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

# Workspace Email Preferences

> Read and change which Tuco notification emails a workspace sends, using that workspace's API key.

<Note>
  Controls which Tuco emails go out for one workspace. Use the **workspace** API key
  (`tuco_…`). Agencies changing this across many workspaces at once should use
  [Agency Email Preferences](/api-reference/endpoint/agency-email-preferences) instead.
</Note>

## Endpoint

* **Method**: `POST` to change, `GET` to read
* **Path**: `/api/email-preferences`
* **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx`

## Email types

| Type | Covers |
| - | - |
| `campaign` | Campaign progress and completion summaries |
| `reply` | Inbound reply alerts. Also carries `mode` |
| `billing` | Invoices, payment failures, plan changes |
| `system_error` | Platform errors affecting your workspace |
| `line_health` | Retained for compatibility — line-down emails are controlled by each line's **Line Down Notifications** toggle, not here |

`reply.mode` is one of `all`, `positive_only`, `debounce_5min` (default) or
`daily_digest`.

## Read

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

```json theme={null}
{
  "success": true,
  "preferences": {
    "line_health": { "enabled": true },
    "campaign": { "enabled": true },
    "reply": { "enabled": true, "mode": "debounce_5min" },
    "billing": { "enabled": true },
    "system_error": { "enabled": true }
  }
}
```

## Change

Send only what you want to change — everything else is preserved.

```bash theme={null}
curl https://app.tuco.ai/api/email-preferences \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "campaign": { "enabled": false },
      "reply": { "enabled": true, "mode": "daily_digest" }
    }
  }'
```

The response is the full merged preference object.

## Error responses

| Status | When |
| - | - |
| `400` | `preferences` missing or not an object, an unknown email type, or an invalid `reply.mode` |
| `401` | Missing or invalid key |
| `403` | An agency key (`tucoagency_…`) was used — this is a per-workspace setting |


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