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

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Subscription topics and sections

> How preferences are modeled as topics in sections, each with a default state and optional channel routing, and which API reads and writes each part.

Preferences are subscription topics grouped into sections.

Each topic carries a default state and optional per-channel routing. You define the model in the [Preferences Editor](https://www.courier.com/docs/recipients/preferences/preferences-editor.md). You read and write a user's choices through the User Preferences API.

For how these pieces combine into a delivery decision, see [How preferences resolve](https://www.courier.com/docs/recipients/preferences/overview.md).

## The model

A preference is an **override on a topic's default**. A user falls back to the default until they make a choice. Courier then stores an override on that topic.

* **Subscription topic** is a category users control independently, such as marketing or product updates. Each topic has an ID (a TypeID prefixed `pt_`, for example `pt_01j9x8a2c4e6g8k0m2p4r6t8w0`), a default state, and a section. Templates map to a topic, so every send respects the user's choice.
* **Section** groups related topics under a heading and controls which channels users can adjust for the topics inside it. Section IDs are TypeIDs prefixed `ps_`.
* **Default state** is `OPTED_IN`, `OPTED_OUT`, or `REQUIRED`. It seeds every user's status until they override it. `REQUIRED` can't be overridden. See [how these resolve](https://www.courier.com/docs/recipients/preferences/overview.md#status-precedence).
* **Custom routing** is the set of channels a user picked for a topic: `direct_message`, `email`, `inbox`, `push`, `sms`, `webhook`. Courier stores them in `custom_routing` and applies them only when `has_custom_routing` is true.
* **Topic data** is arbitrary metadata you attach to a topic through the API, useful for filtering topics or driving a custom preference UI. It's API-only.

A user's stored override has three parts:

* `status`, either `OPTED_IN` or `OPTED_OUT`. These are the only two values a user can set.
* `custom_routing`, with its `has_custom_routing` flag.
* `topic_id`, the topic the override applies to.

On reads, `status` can also come back as `REQUIRED`. The API falls back to the topic default when the user has no override of their own, and Courier rejects a write that tries to opt a user out of a required topic.

## The API surface

Two API layers touch preferences. The **User Preferences API** reads and writes one user's choices. The **Workspace Preferences API** manages the topic and section catalog that those choices reference.

### User preferences

| Path | Purpose |
| - | - |
| [`GET /users/{user_id}/preferences`](https://www.courier.com/docs/api-reference/user-preferences/get-users-preferences) | List a user's preferences. |
| [`PUT /users/{user_id}/preferences`](https://www.courier.com/docs/api-reference/user-preferences/replace-user-preferences-in-bulk) | Replace a user's entire override set (bulk, atomic). |
| [`POST /users/{user_id}/preferences`](https://www.courier.com/docs/api-reference/user-preferences/update-user-preferences-in-bulk) | Additively update preferences without touching others (bulk, partial). |
| [`GET /users/{user_id}/preferences/{topic_id}`](https://www.courier.com/docs/api-reference/user-preferences/get-user-subscription-topic) | Get one topic's preference. |
| [`PUT /users/{user_id}/preferences/{topic_id}`](https://www.courier.com/docs/api-reference/user-preferences/update-or-create-user-preferences-for-a-subscription-topic) | Create or update one topic's preference. |
| [`DELETE /users/{user_id}/preferences/{topic_id}`](https://www.courier.com/docs/api-reference/user-preferences/delete-user-subscription-topic) | Reset one topic to its default. |

Every endpoint accepts an optional `tenant_id` query parameter to scope preferences to one tenant. Both bulk endpoints accept up to **50 topics per request**. No endpoint updates many users at once, so an import across your user base means one bulk call per user. For worked examples, see [Manage preferences via API](https://www.courier.com/docs/recipients/preferences/api.md).

### Reading current state

[`GET /users/{user_id}/preferences`](https://www.courier.com/docs/api-reference/user-preferences/get-users-preferences) returns a row for **every** topic in every section, not only the topics the user has touched. Each row carries the topic's `default_status` plus an effective `status`. The effective `status` is the user's override when one exists, and the topic default otherwise:

```json theme={null}
{
  "paging": {
    "cursor": null,
    "more": false
  },
  "items": [
    {
      "topic_id": "pt_01j9x8a2c4e6g8k0m2p4r6t8w0",
      "topic_name": "Product updates",
      "section_id": "ps_01j9x8a2c4e6g8k0m2p4r6t8w1",
      "section_name": "Notifications",
      "status": "OPTED_IN",
      "default_status": "OPTED_IN",
      "has_custom_routing": true,
      "custom_routing": ["email", "push"]
    }
  ]
}
```

Two things about this response:

* **`status` is effective, not stored.** A topic the user never touched still returns a `status`, copied from `default_status`. A `REQUIRED` topic therefore reads back as `"status": "REQUIRED"`. Branch on `default_status` to know whether the user chose anything.
* **Paging isn't implemented.** `more` is always `false` and no cursor is returned, so a single call gives you every topic.

The read endpoint reports the **topic-level** `default_status`, even when you pass a `tenant_id`. Courier applies tenant default preferences when a message sends, and doesn't surface them here. See [how preferences resolve](https://www.courier.com/docs/recipients/preferences/overview.md).

### Topic and section catalog

The Workspace Preferences API manages the topics and sections themselves. List a section's topics with [`GET /preferences/sections/{section_id}/topics`](https://www.courier.com/docs/api-reference/preference-topics/list-topics-in-section). Create, retrieve, replace, or archive individual topics and sections under `/preferences/sections`. Most teams define these in the [Preferences Editor](https://www.courier.com/docs/recipients/preferences/preferences-editor.md) instead of by hand.

## Digest schedules

A digest holds a topic's notifications and delivers them together on a schedule, so a busy topic becomes one daily or weekly summary. Each subscription topic can have one: a digest template, the schedules users pick from, and optional categories that split event types.

While a user is on a digest schedule, their notifications for the topic show `DIGESTED` in the logs until the schedule releases them as one message. Users on **Instant** get each notification right away. A user's choice is `digest_schedule_id` on their topic preference.

A schedule that collected nothing sends nothing. Turn on **Trigger empty** (`trigger_empty` on the topic's `digest`) to send anyway, for a digest that renders data your own system supplies.

[Send a daily digest](https://www.courier.com/docs/guides/send-a-daily-digest.md) sets one up in the editor and over the API. For count- or time-based batching inside a journey, use the [Batch node](https://www.courier.com/docs/journeys/nodes/batch.md).

## Audit trail

Courier records a history of preference changes. In the dashboard, open [Directory → Users](https://app.courier.com/directory/users) and select a user. You see their subscription topics, current status, and a log of when each preference changed and who changed it.

Through the API, [`GET /preferences/logs`](https://www.courier.com/docs/api-reference/preference-topics/list-preference-changes) returns the change history for one user or the whole environment, and each change also arrives as a `preferences:user:updated` [webhook event](https://www.courier.com/docs/monitor/webhooks/events.md#preferencesuserupdated). To read the history or keep another system in sync, see [Track preference changes](https://www.courier.com/docs/recipients/preferences/api.md#track-preference-changes).

That history is per user. Your own team's changes to the configuration land in the workspace [audit trail](https://www.courier.com/docs/workspaces/audit-trail.md) instead, including a topic created or deleted, its channels changed, and its default status changed.

## FAQ

> [accordion] Is there a bulk preferences endpoint?
>
> Two bulk endpoints exist, both per user. [`PUT /users/{user_id}/preferences`](https://www.courier.com/docs/api-reference/user-preferences/replace-user-preferences-in-bulk) replaces a user's full override set atomically. [`POST /users/{user_id}/preferences`](https://www.courier.com/docs/api-reference/user-preferences/update-user-preferences-in-bulk) updates topics additively. Each accepts up to 50 topics. No endpoint updates multiple users in one call, so a large import runs one bulk call per user.

> [accordion] Can I set a digest schedule through the API?
>
> A topic's schedules are part of its `digest` object on topic create and replace, and a user's choice is `digest_schedule_id` on their topic preference. You can also configure schedules in the [Preferences Editor](https://app.courier.com/~/test/platform/preferences), and users can pick theirs in the preference center. See [Send a daily digest](https://www.courier.com/docs/guides/send-a-daily-digest.md).

> [accordion] Is there a webhook for preference changes?
>
> The `preferences:user:updated` [webhook event](https://www.courier.com/docs/monitor/webhooks/events.md#preferencesuserupdated) fires each time a user opts in, opts out, or changes a topic's channels, on the hosted page, through an unsubscribe link, or through the API. To catch up on changes your endpoint missed, read [`GET /preferences/logs`](https://www.courier.com/docs/api-reference/preference-topics/list-preference-changes).

> [accordion] Where do topic IDs come from?
>
> You create topics in the [Preferences Editor](https://app.courier.com/~/test/platform/preferences) or the Workspace Preferences API, and each carries a TypeID prefixed `pt_`. Reference that `topic_id` when mapping templates and when reading or writing user preferences.
