Agency Email Preferences
curl --request POST \
--url https://app.tuco.ai/api/agency/email-preferences \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.tuco.ai/api/agency/email-preferences"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.tuco.ai/api/agency/email-preferences', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.tuco.ai/api/agency/email-preferences",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/agency/email-preferences"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.tuco.ai/api/agency/email-preferences")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/agency/email-preferences")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyAgency
Agency Email Preferences
Turn Tuco’s notification emails (reply alerts, billing and error notices) off or back on across every workspace in your agency, or in one, in one call.
POST
/
api
/
agency
/
email-preferences
Agency Email Preferences
curl --request POST \
--url https://app.tuco.ai/api/agency/email-preferences \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.tuco.ai/api/agency/email-preferences"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.tuco.ai/api/agency/email-preferences', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.tuco.ai/api/agency/email-preferences",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/agency/email-preferences"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.tuco.ai/api/agency/email-preferences")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/agency/email-preferences")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyYour clients live inside your sub-workspaces. This stops Tuco emailing them
directly — reply alerts, billing notices, error notices — across the whole
group, or in one workspace, or for one email type.
Endpoint
- Method:
POST(read the current state withGETon the same path) - Path:
/api/agency/email-preferences - Auth:
Authorization: Bearer tucoagency_xxxxxxxxxxxxx(agency key)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | yes | false silences, true re-enables. No default — a body-less POST is rejected rather than guessed |
types | string[] | no | Omitted = all five. One or more of line_health, campaign, reply, billing, system_error |
workspaceId | string | no | Limit to one sub-account. Omitted = every workspace in the agency |
Silence everything, everywhere
curl https://app.tuco.ai/api/agency/email-preferences \
-H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'
{
"agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx",
"enabled": false,
"types": ["line_health", "campaign", "reply", "billing", "system_error"],
"workspacesUpdated": 4,
"membersUpdated": 11,
"workspaces": [
{ "clerkOrgId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "name": "Acme Roofing", "members": 3 }
]
}
Narrower changes
# Only reply alerts, only in one workspace
-d '{"enabled": false, "types": ["reply"], "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT"}'
# Put billing notices back on everywhere
-d '{"enabled": true, "types": ["billing"]}'
What it does and does not touch
- Preferences are per member, per workspace. The call writes every member of every targeted workspace, including members who had no stored preference and were therefore on the default (everything on).
- Settings are merged, not replaced. Turning
replyoff keeps your existingreply.mode; turning other types off leavesreplyalone. - Your own agency account is not affected. Silencing your clients does not silence you.
line_healthis accepted for completeness, but line-down and recovery emails are governed by each line’s own Line Down Notifications toggle, not by this preference. Turningline_healthoff here will not stop them.
Reading the current state
curl https://app.tuco.ai/api/agency/email-preferences \
-H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx"
{
"agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx",
"emailTypes": ["line_health", "campaign", "reply", "billing", "system_error"],
"workspaces": [
{
"clerkOrgId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT",
"name": "Acme Roofing",
"membersWithPreferences": 3,
"anyEmailsEnabled": false,
"members": [{ "userId": "user_…", "preferences": { "reply": { "enabled": false } } }]
}
]
}
membersWithPreferences: 0 has nobody on a stored preference, so
everyone there is on the defaults — anyEmailsEnabled is true.
Add ?workspaceId=org_… to read one workspace.
Error responses
| Status | Code | When |
|---|---|---|
400 | ENABLED_REQUIRED | enabled missing or not a boolean |
400 | INVALID_TYPES | types empty, not an array, or naming an unknown type |
401 | UNAUTHORIZED | Missing, unknown, revoked or expired key |
403 | AGENCY_KEY_REQUIRED | A workspace key (tuco_…) was used |
403 | NOT_YOUR_WORKSPACE | workspaceId is not in your agency |
403 | NOT_AN_AGENCY | The account behind the key is not an agency |