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 off (or back on) across every workspace in your agency, 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 — campaign summaries, reply alerts, billing 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 campaign summaries back on everywhere
-d '{"enabled": true, "types": ["campaign"]}'
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": { "campaign": { "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 |