> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agency Email Preferences

> Turn Tuco's notification emails off (or back on) across every workspace in your agency, in one call.

<Note>
  Your 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.
</Note>

## Endpoint

* **Method**: `POST` (read the current state with `GET` on the same path)
* **Path**: `/api/agency/email-preferences`
* **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys))

## 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

```bash theme={null}
curl https://app.tuco.ai/api/agency/email-preferences \
  -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

```json theme={null}
{
  "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

```bash theme={null}
# 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 `reply` off keeps your existing
  `reply.mode`; turning other types off leaves `reply` alone.
* **Your own agency account is not affected.** Silencing your clients does not
  silence you.
* `line_health` is accepted for completeness, but line-down and recovery emails are
  governed by each line's own **Line Down Notifications** toggle, not by this
  preference. Turning `line_health` off here will not stop them.

## Reading the current state

```bash theme={null}
curl https://app.tuco.ai/api/agency/email-preferences \
  -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx"
```

```json theme={null}
{
  "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 } } }]
    }
  ]
}
```

A workspace with `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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.