# Courier

> Courier is one API for email, SMS, push, chat, and in-app inbox, sending through the notification providers you already use. It adds templates, routing, preferences, and multi-step journeys, so your application makes one request instead of integrating each channel.

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

# Delete an Audience
Source: https://www.courier.com/docs/api-reference/audiences/delete-an-audience

/openapi-specs/openapi.documented.yml delete /audiences/{audience_id}
Deletes an audience permanently, so update any caller sending to it by audience id first. Those sends fail once the audience is gone.



# Get an Audience
Source: https://www.courier.com/docs/api-reference/audiences/get-an-audience

/openapi-specs/openapi.documented.yml get /audiences/{audience_id}
Returns one audience with its name, description, and the filter and AND or OR operator that decide which users belong to it.



# List all Audiences
Source: https://www.courier.com/docs/api-reference/audiences/list-all-audiences

/openapi-specs/openapi.documented.yml get /audiences
Returns the audiences in the workspace with paging. Audiences are filter-based groups that recalculate as user profiles change.



# List Audience members
Source: https://www.courier.com/docs/api-reference/audiences/list-audience-members

/openapi-specs/openapi.documented.yml get /audiences/{audience_id}/members
Returns the users currently matching an audience filter, with paging. Membership is recalculated, so results shift as profiles change.



# Update an Audience
Source: https://www.courier.com/docs/api-reference/audiences/update-an-audience

/openapi-specs/openapi.documented.yml put /audiences/{audience_id}
Creates or replaces an audience from a filter and an AND or OR operator. Membership recalculates automatically as profiles change.



# Get an Audit Event
Source: https://www.courier.com/docs/api-reference/audit-events/get-an-audit-event

/openapi-specs/openapi.documented.yml get /audit-events/{audit-event-id}
Returns one audit event by id, including the actor who performed it, the target they changed, the source, the event type, and a timestamp.



# List Audit Events
Source: https://www.courier.com/docs/api-reference/audit-events/list-audit-events

/openapi-specs/openapi.documented.yml get /audit-events
Returns the workspace's audit event log with cursor paging. Each event records the actor, target, source, type, and timestamp of a change.



# Create a JWT
Source: https://www.courier.com/docs/api-reference/authentication/create-a-jwt

/openapi-specs/openapi.documented.yml post /auth/issue-token
Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply the scope and an expires_in duration, both required.



# Invoke an ad hoc Automation
Source: https://www.courier.com/docs/api-reference/automations/invoke-an-ad-hoc-automation

/openapi-specs/openapi.documented.yml post /automations/invoke
Runs a series of automation steps supplied inline, without a saved template, and returns a runId.



# Invoke an Automation
Source: https://www.courier.com/docs/api-reference/automations/invoke-an-automation

/openapi-specs/openapi.documented.yml post /automations/{templateId}/invoke
Starts an automation run from a saved template for one recipient, with optional data and profile, and returns a runId.



# List Automation runs
Source: https://www.courier.com/docs/api-reference/automations/list-automation-runs

/openapi-specs/openapi.documented.yml get /automations/runs
List runs of the workspace's v2 Automations, newest first, filtered by status, Template, or date range and paged by cursor. Journey (v3) runs are listed by `GET /journeys/runs` instead — the two surfaces never return each other's runs. Runs are retained for 95 days.



# List Automations
Source: https://www.courier.com/docs/api-reference/automations/list-automations

/openapi-specs/openapi.documented.yml get /automations
Lists the workspace's saved automation templates, each with its id and a cursor for paging to the next page of results.



# List steps for an Automation run
Source: https://www.courier.com/docs/api-reference/automations/list-steps-for-an-automation-run

/openapi-specs/openapi.documented.yml get /automations/runs/{id}/steps
List the per-step state of one Automation run, in full — this endpoint is not paginated. `message_id` is present on send steps that produced a message; follow it to `GET /messages/{message_id}` for delivery status. A send to a List or an Audience yields one `message_id` for the request, not one per recipient.



# Create a new Brand
Source: https://www.courier.com/docs/api-reference/brands/create-a-new-brand

/openapi-specs/openapi.documented.yml post /brands
Creates a brand from a name and settings, including primary and secondary colors. Brands supply the logo, colors, and styling that templates render with.



# Delete a Brand
Source: https://www.courier.com/docs/api-reference/brands/delete-a-brand

/openapi-specs/openapi.documented.yml delete /brands/{brand_id}
Deletes a brand by id. Reassign any template or tenant that references it before deleting to keep their styling intact.



# Get a Brand
Source: https://www.courier.com/docs/api-reference/brands/get-a-brand

/openapi-specs/openapi.documented.yml get /brands/{brand_id}
Returns one brand by id, including its colors, logo and styling settings, Handlebars snippets, and published version.



# List Brands
Source: https://www.courier.com/docs/api-reference/brands/list-brands

/openapi-specs/openapi.documented.yml get /brands
Lists the workspace's brands. Every entry carries its name, styling settings, snippets, and published version.



# Replace a Brand
Source: https://www.courier.com/docs/api-reference/brands/replace-a-brand

/openapi-specs/openapi.documented.yml put /brands/{brand_id}
Replaces a brand with the values you supply, so send the complete settings and snippets rather than only the fields you want changed.



# Archive Broadcast
Source: https://www.courier.com/docs/api-reference/broadcasts/archive-broadcast

/openapi-specs/openapi.documented.yml delete /broadcasts/{broadcastId}
Archive a broadcast. This is a soft delete — the archived broadcast is returned and no longer appears in list results.



# Cancel Broadcast schedule
Source: https://www.courier.com/docs/api-reference/broadcasts/cancel-broadcast-schedule

/openapi-specs/openapi.documented.yml post /broadcasts/{broadcastId}/cancel
Cancel a broadcast's pending schedule, returning it to the draft state. Only valid for a scheduled broadcast.



# Create Broadcast
Source: https://www.courier.com/docs/api-reference/broadcasts/create-broadcast

/openapi-specs/openapi.documented.yml post /broadcasts
Create a broadcast. Provisions a private notification template for the broadcast and returns the new broadcast in the draft state. Exactly one channel is required.



# Duplicate Broadcast
Source: https://www.courier.com/docs/api-reference/broadcasts/duplicate-broadcast

/openapi-specs/openapi.documented.yml post /broadcasts/{broadcastId}/duplicate
Duplicate a broadcast (and its template) into a new draft named "{source name} (copy)".



# Get Broadcast
Source: https://www.courier.com/docs/api-reference/broadcasts/get-broadcast

/openapi-specs/openapi.documented.yml get /broadcasts/{broadcastId}
Retrieve a broadcast by ID. Archived broadcasts return 404.



# Get Broadcast content
Source: https://www.courier.com/docs/api-reference/broadcasts/get-broadcast-content

/openapi-specs/openapi.documented.yml get /broadcasts/{broadcastId}/content
Retrieve the broadcast's content — the elemental content of its private notification template. Defaults to the working draft, since broadcast content is authored as a draft until the broadcast is sent.



# List Broadcasts
Source: https://www.courier.com/docs/api-reference/broadcasts/list-broadcasts

/openapi-specs/openapi.documented.yml get /broadcasts
List broadcasts in your workspace. Cursor-paginated; returns broadcasts newest-first.



# Schedule Broadcast
Source: https://www.courier.com/docs/api-reference/broadcasts/schedule-broadcast

/openapi-specs/openapi.documented.yml post /broadcasts/{broadcastId}/schedule
Schedule a broadcast for a future send to a list or audience. Publishes the broadcast template first. Not allowed once the broadcast is sending or sent. For an immediate send use POST /broadcasts/{broadcastId}/send.



# Send Broadcast
Source: https://www.courier.com/docs/api-reference/broadcasts/send-broadcast

/openapi-specs/openapi.documented.yml post /broadcasts/{broadcastId}/send
Send a broadcast immediately to a list or audience. Publishes the broadcast template first. Not allowed once the broadcast is sending or sent.



# Update Broadcast
Source: https://www.courier.com/docs/api-reference/broadcasts/update-broadcast

/openapi-specs/openapi.documented.yml put /broadcasts/{broadcastId}
Update a broadcast's name. Content is edited via the broadcast's notification template, not this endpoint.



# Update Broadcast content
Source: https://www.courier.com/docs/api-reference/broadcasts/update-broadcast-content

/openapi-specs/openapi.documented.yml put /broadcasts/{broadcastId}/content
Author the broadcast's content by replacing the draft elemental content of its private notification template. The draft is published automatically when the broadcast is sent or scheduled.



# Add users
Source: https://www.courier.com/docs/api-reference/bulk/add-users

/openapi-specs/openapi.documented.yml post /bulk/{job_id}
Ingest user data into a Bulk Job. 

**Important**: For email-based bulk jobs, each user must include `profile.email` 
for provider routing to work correctly. The `to.email` field is not sufficient 
for email provider routing.




# Create a bulk job
Source: https://www.courier.com/docs/api-reference/bulk/create-a-bulk-job

/openapi-specs/openapi.documented.yml post /bulk
Creates a new bulk job for sending messages to multiple recipients.

**Required**: `message.event` (event ID or notification ID)

**Optional (V2 format)**: `message.template` (notification ID) or `message.content` (Elemental content) 
can be provided to override the notification associated with the event.




# Get a job
Source: https://www.courier.com/docs/api-reference/bulk/get-a-job

/openapi-specs/openapi.documented.yml get /bulk/{job_id}
Returns a bulk job's message definition, its status — CREATED, PROCESSING, COMPLETED, or ERROR — and running counts of users received, messages enqueued, and failures. Poll it to follow a job through to completion.



# Get users
Source: https://www.courier.com/docs/api-reference/bulk/get-users

/openapi-specs/openapi.documented.yml get /bulk/{job_id}/users
Returns the users ingested into a bulk job with paging, each carrying the status Courier recorded for it and the id of the message it produced.



# Run a job
Source: https://www.courier.com/docs/api-reference/bulk/run-a-job

/openapi-specs/openapi.documented.yml post /bulk/{job_id}/run
Starts processing a bulk job, sending to every user ingested into it. Returns 204 immediately; the job runs asynchronously, so poll the job to watch its status and counts.



# Add a token to a user
Source: https://www.courier.com/docs/api-reference/device-tokens/add-a-token-to-a-user

/openapi-specs/openapi.documented.yml put /users/{user_id}/tokens/{token}
Registers one device token for a user against a provider key, overwriting the token if it already exists. Push sends resolve tokens per user.



# Add multiple tokens to user
Source: https://www.courier.com/docs/api-reference/device-tokens/add-multiple-tokens-to-user

/openapi-specs/openapi.documented.yml put /users/{user_id}/tokens
Registers several device tokens for a user in one call, overwriting any stored token with a matching value.



# Delete user token
Source: https://www.courier.com/docs/api-reference/device-tokens/delete-user-token

/openapi-specs/openapi.documented.yml delete /users/{user_id}/tokens/{token}
Deletes one device token for a user, addressed by the token value, so push sends no longer target that device.



# Get a token
Source: https://www.courier.com/docs/api-reference/device-tokens/get-a-token

/openapi-specs/openapi.documented.yml get /users/{user_id}/tokens/{token}
Returns one device token with its provider key, status and status reason, expiry date, and any properties stored alongside it.



# List tokens
Source: https://www.courier.com/docs/api-reference/device-tokens/list-tokens

/openapi-specs/openapi.documented.yml get /users/{user_id}/tokens
Returns every device token registered for a user, each with its provider key, status, and expiry date.



# Update a token
Source: https://www.courier.com/docs/api-reference/device-tokens/update-a-token

/openapi-specs/openapi.documented.yml patch /users/{user_id}/tokens/{token}
Applies a JSON Patch to a device token, changing its status, expiry, or properties without re-registering it.



# Delete a topic's digest
Source: https://www.courier.com/docs/api-reference/digests/delete-a-topics-digest

/openapi-specs/openapi.documented.yml delete /preferences/sections/{section_id}/topics/{topic_id}/digest
Turn off a topic's digest, leaving the topic itself in place. The template is unlinked and the digest's schedules are removed along with their delivery rules. Equivalent to sending `digest: null` on a topic replace.



# List digest instances
Source: https://www.courier.com/docs/api-reference/digests/list-digest-instances

/openapi-specs/openapi.documented.yml get /digests/schedules/{schedule_id}/instances
Returns the digest instances for a schedule, one per user, with cursor paging. Use it to see what has accumulated before a digest releases.



# Release a digest early
Source: https://www.courier.com/docs/api-reference/digests/release-a-digest-early

/openapi-specs/openapi.documented.yml post /digests/schedules/{schedule_id}/trigger
Send a digest now instead of waiting for its scheduled time, so your users get what they have collected so far right away.



# Release a recipient's digest
Source: https://www.courier.com/docs/api-reference/digests/release-a-recipients-digest

/openapi-specs/openapi.documented.yml post /preferences/sections/{section_id}/topics/{topic_id}/digest/release
Send one recipient's held digest now, instead of waiting for its schedule. Use it to preview what a digest will look like, or to let someone flush their own.

Keyed on the topic because that is how a held digest is stored: one per recipient per topic, with the schedule recorded on it rather than part of its identity. To flush every recipient on a schedule instead, use `POST /digests/schedules/{schedule_id}/trigger`.



# Archive a Journey
Source: https://www.courier.com/docs/api-reference/journeys/archive-a-journey

/openapi-specs/openapi.documented.yml delete /journeys/{templateId}
Archives a journey so it can no longer be invoked. Runs already in flight continue to completion, so archiving never strands a user mid-sequence.



# Archive a Journey-scoped Notification Template
Source: https://www.courier.com/docs/api-reference/journeys/archive-a-journey-scoped-notification-template

/openapi-specs/openapi.documented.yml delete /journeys/{templateId}/templates/{notificationId}
Archives one journey's notification template, preventing further sends. Detach any send node referencing it beforehand.



# Cancel Journey runs
Source: https://www.courier.com/docs/api-reference/journeys/cancel-journey-runs

/openapi-specs/openapi.documented.yml post /journeys/cancel
Cancels in-flight journey runs, either every run sharing a cancelation token or one run by id. Use it to stop a sequence when the event resolves.



# Create a Journey
Source: https://www.courier.com/docs/api-reference/journeys/create-a-journey

/openapi-specs/openapi.documented.yml post /journeys
Creates a journey from a set of nodes, in draft state unless you pass a published state. Send nodes cannot be included until their templates exist.



# Create a Notification Template scoped to a Journey
Source: https://www.courier.com/docs/api-reference/journeys/create-a-notification-template-scoped-to-a-journey

/openapi-specs/openapi.documented.yml post /journeys/{templateId}/templates
Create a notification template scoped to this journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to publish on create.

The content tree must contain exactly one channel block whose `channel` matches the `channel` on the request — a journey-scoped template carries a single channel. Top-level elements, or a block for a different channel, return `400`. The template designer renders only the channel block matching the tab it draws, so content stored without one cannot be opened. An empty `elements` array is accepted.



# Fetch a Journey by id
Source: https://www.courier.com/docs/api-reference/journeys/fetch-a-journey-by-id

/openapi-specs/openapi.documented.yml get /journeys/{templateId}
Fetch a journey by id. Pass `?version=draft` (default `published`) to retrieve the working draft, or `?version=vN` to retrieve a historical version.



# Fetch a Journey run
Source: https://www.courier.com/docs/api-reference/journeys/fetch-a-journey-run

/openapi-specs/openapi.documented.yml get /journeys/runs/{run_id}
Fetch one Journey run by id. Returns `404` for an unknown run, a run belonging to another workspace, a run past the 95-day retention window, or an Automation run id — the same body in every case, so the response never reveals whether a run exists elsewhere.



# Fetch a Journey-scoped Notification Template by id
Source: https://www.courier.com/docs/api-reference/journeys/fetch-a-journey-scoped-notification-template-by-id

/openapi-specs/openapi.documented.yml get /journeys/{templateId}/templates/{notificationId}
Returns a journey's own notification template with its name, brand, subscription topic, and content. Defaults to the published version.



# Fetch the content of a Journey-scoped Notification Template
Source: https://www.courier.com/docs/api-reference/journeys/fetch-the-content-of-a-journey-scoped-notification-template

/openapi-specs/openapi.documented.yml get /journeys/{templateId}/templates/{notificationId}/content
Returns the Elemental elements and version of a journey-scoped template's content. Compare versions to see what changed between publishes.



# Invoke a Journey
Source: https://www.courier.com/docs/api-reference/journeys/invoke-a-journey

/openapi-specs/openapi.documented.yml post /journeys/{templateId}/invoke
Starts a journey run for one user and returns a runId. Runs execute asynchronously, so the response arrives before any message is sent.



# List Journey runs
Source: https://www.courier.com/docs/api-reference/journeys/list-journey-runs

/openapi-specs/openapi.documented.yml get /journeys/runs
List runs of the workspace's Journeys, newest first, filtered by status, Journey, or date range and paged by cursor. Runs of v2 Automations are listed by `GET /automations/runs` instead — the two surfaces never return each other's runs. Runs are retained for 95 days.



# List Journeys
Source: https://www.courier.com/docs/api-reference/journeys/list-journeys

/openapi-specs/openapi.documented.yml get /journeys
Lists the workspace's journeys, each carrying a name, state, and enabled flag. Paged by cursor.



# List Notification Templates scoped to a Journey
Source: https://www.courier.com/docs/api-reference/journeys/list-notification-templates-scoped-to-a-journey

/openapi-specs/openapi.documented.yml get /journeys/{templateId}/templates
List notification templates scoped to this journey. Journey-scoped notification templates can only be referenced from `send` nodes within the same journey.



# List steps for a Journey run
Source: https://www.courier.com/docs/api-reference/journeys/list-steps-for-a-journey-run

/openapi-specs/openapi.documented.yml get /journeys/runs/{run_id}/steps
List the per-node state of one Journey run, in full — this endpoint is not paginated. Each step's `node_id` is the id of the node in the published Journey, so a step maps directly onto the Journey graph. `message_id` is present on send steps that produced a message; follow it to `GET /messages/{message_id}` for delivery status.



# List versions of a Journey
Source: https://www.courier.com/docs/api-reference/journeys/list-versions-of-a-journey

/openapi-specs/openapi.documented.yml get /journeys/{templateId}/versions
Lists a journey's published versions, most recent first, so you have a version id to roll back to. Paged by cursor.



# List versions of a Journey-scoped Notification Template
Source: https://www.courier.com/docs/api-reference/journeys/list-versions-of-a-journey-scoped-notification-template

/openapi-specs/openapi.documented.yml get /journeys/{templateId}/templates/{notificationId}/versions
Lists the published versions of a template that belongs to a journey, most recent first. Paged by cursor.



# Publish a Journey
Source: https://www.courier.com/docs/api-reference/journeys/publish-a-journey

/openapi-specs/openapi.documented.yml post /journeys/{templateId}/publish
Publishes a journey's current draft as a new version, making it live for new runs. Pass a version instead to roll back to an earlier one.



# Publish a Journey-scoped Notification Template
Source: https://www.courier.com/docs/api-reference/journeys/publish-a-journey-scoped-notification-template

/openapi-specs/openapi.documented.yml post /journeys/{templateId}/templates/{notificationId}/publish
Publishes a journey-scoped template's draft as a new version. Pass a version instead to roll back the template to an earlier publish.



# Replace a Journey
Source: https://www.courier.com/docs/api-reference/journeys/replace-a-journey

/openapi-specs/openapi.documented.yml put /journeys/{templateId}
Replaces a journey's working draft, leaving the published version live until you publish. Reach for this when editing a journey already running.



# Replace a Journey-scoped Notification Template
Source: https://www.courier.com/docs/api-reference/journeys/replace-a-journey-scoped-notification-template

/openapi-specs/openapi.documented.yml put /journeys/{templateId}/templates/{notificationId}
Replaces the draft content of one journey's notification template. Publish it before send nodes referencing it render the change.



# Replace a locale of a Journey-scoped Notification Template
Source: https://www.courier.com/docs/api-reference/journeys/replace-a-locale-of-a-journey-scoped-notification-template

/openapi-specs/openapi.documented.yml put /journeys/{templateId}/templates/{notificationId}/locales/{localeId}
Set locale-specific content overrides for a journey-scoped notification template. Each element override must reference an existing element by ID.



# Replace the content of a Journey-scoped Notification Template
Source: https://www.courier.com/docs/api-reference/journeys/replace-the-content-of-a-journey-scoped-notification-template

/openapi-specs/openapi.documented.yml put /journeys/{templateId}/templates/{notificationId}/content
Replace the elemental content of a journey-scoped notification template. Overwrites all elements in the template draft with the provided content.



# Add subscribers to a List
Source: https://www.courier.com/docs/api-reference/lists/add-subscribers-to-a-list

/openapi-specs/openapi.documented.yml post /lists/{list_id}/subscriptions
Subscribes additional users to the list, without modifying existing subscriptions. If the list does not exist, it will be automatically created.



# Delete a List
Source: https://www.courier.com/docs/api-reference/lists/delete-a-list

/openapi-specs/openapi.documented.yml delete /lists/{list_id}
Deletes a list, halting sends that target it. A previously deleted list can be brought back with the companion restore endpoint.



# Get a List
Source: https://www.courier.com/docs/api-reference/lists/get-a-list

/openapi-specs/openapi.documented.yml get /lists/{list_id}
Returns one list by id with its name and created and updated timestamps. Fetch its subscribers separately with the subscriptions endpoint.



# List Lists
Source: https://www.courier.com/docs/api-reference/lists/list-lists

/openapi-specs/openapi.documented.yml get /lists
Returns the workspace's lists, filterable by a pattern to fetch a subset such as every regional list. Paged by cursor.



# List subscriptions for a List
Source: https://www.courier.com/docs/api-reference/lists/list-subscriptions-for-a-list

/openapi-specs/openapi.documented.yml get /lists/{list_id}/subscriptions
Returns the users subscribed to a list with paging, each with the preferences recorded for that subscription.



# Restore a List
Source: https://www.courier.com/docs/api-reference/lists/restore-a-list

/openapi-specs/openapi.documented.yml put /lists/{list_id}/restore
Restores a previously deleted list along with its subscribers, so a list removed by mistake can be brought back rather than rebuilt.



# Subscribe a user Profile to a List
Source: https://www.courier.com/docs/api-reference/lists/subscribe-a-user-profile-to-a-list

/openapi-specs/openapi.documented.yml put /lists/{list_id}/subscriptions/{user_id}
Subscribes one user to a list, creating the list if it does not yet exist. Optional preferences apply to this subscription only.



# Subscribe users to a List
Source: https://www.courier.com/docs/api-reference/lists/subscribe-users-to-a-list

/openapi-specs/openapi.documented.yml put /lists/{list_id}/subscriptions
Subscribes the users to the list, overwriting existing subscriptions. If the list does not exist, it will be automatically created.



# Unsubscribe a user Profile from a List
Source: https://www.courier.com/docs/api-reference/lists/unsubscribe-a-user-profile-from-a-list

/openapi-specs/openapi.documented.yml delete /lists/{list_id}/subscriptions/{user_id}
Removes one user's subscription to a list, addressed by list id and user id. The user's profile and other subscriptions are separate resources.



# Update a List
Source: https://www.courier.com/docs/api-reference/lists/update-a-list

/openapi-specs/openapi.documented.yml put /lists/{list_id}
Creates or replaces a list from a name and preferences. Subscribers are managed through the separate subscriptions endpoints.



# Archive message
Source: https://www.courier.com/docs/api-reference/messages/archive-message

/openapi-specs/openapi.documented.yml put /requests/{request_id}/archive
Archives a send request by its request id. Use it to remove test sends or superseded requests from the message list without deleting them.



# Cancel message
Source: https://www.courier.com/docs/api-reference/messages/cancel-message

/openapi-specs/openapi.documented.yml post /messages/{message_id}/cancel
Cancels a message that is still in the delivery pipeline and returns the message record with its resulting canceled or failed status.



# Get message
Source: https://www.courier.com/docs/api-reference/messages/get-message

/openapi-specs/openapi.documented.yml get /messages/{message_id}
Returns a sent message's status, recipient, event, and per-provider delivery detail, with timestamps for enqueued, sent, delivered, opened, and clicked.



# Get message content
Source: https://www.courier.com/docs/api-reference/messages/get-message-content

/openapi-specs/openapi.documented.yml get /messages/{message_id}/output
Returns the rendered content Courier delivered for a message, broken out per channel, to confirm what the recipient received.



# Get message history
Source: https://www.courier.com/docs/api-reference/messages/get-message-history

/openapi-specs/openapi.documented.yml get /messages/{message_id}/history
Returns the ordered event history for a sent message, one entry per status transition with its timestamp.



# List messages
Source: https://www.courier.com/docs/api-reference/messages/list-messages

/openapi-specs/openapi.documented.yml get /messages
Returns previously sent messages, most recent first, each carrying its status, recipient, channel, and provider. Paged by cursor.



# Resend message
Source: https://www.courier.com/docs/api-reference/messages/resend-message

/openapi-specs/openapi.documented.yml post /messages/{message_id}/resend
Resends a previously sent message to the same recipient and content, returning a new messageId. The original send request is not modified.



# Archive a Preference Section
Source: https://www.courier.com/docs/api-reference/preference-topics/archive-a-preference-section

/openapi-specs/openapi.documented.yml delete /preferences/sections/{section_id}
Archive a workspace preference. The workspace preference must be empty: delete its topics first, otherwise the request fails with 409.



# Archive Topic in Section
Source: https://www.courier.com/docs/api-reference/preference-topics/archive-topic-in-section

/openapi-specs/openapi.documented.yml delete /preferences/sections/{section_id}/topics/{topic_id}
Archives a subscription topic and removes it from its workspace preference, addressed by section id and topic id.



# Create a Preference Section
Source: https://www.courier.com/docs/api-reference/preference-topics/create-a-preference-section

/openapi-specs/openapi.documented.yml post /preferences/sections
Creates a workspace preference and returns its generated id. Add subscription topics to it afterwards with the topics endpoint.



# Create Topic in Section
Source: https://www.courier.com/docs/api-reference/preference-topics/create-topic-in-section

/openapi-specs/openapi.documented.yml post /preferences/sections/{section_id}/topics
Creates a subscription topic inside a workspace preference. The default status sets whether users start opted in, opted out, or required.



# Get a Preference Section
Source: https://www.courier.com/docs/api-reference/preference-topics/get-a-preference-section

/openapi-specs/openapi.documented.yml get /preferences/sections/{section_id}
Returns one workspace preference by id, including its subscription topics, routing options, and custom routing flag.



# Get Topic in Section
Source: https://www.courier.com/docs/api-reference/preference-topics/get-topic-in-section

/openapi-specs/openapi.documented.yml get /preferences/sections/{section_id}/topics/{topic_id}
Returns one subscription topic with its default status, routing options, allowed preferences, and unsubscribe header setting.



# List preference changes
Source: https://www.courier.com/docs/api-reference/preference-topics/list-preference-changes

/openapi-specs/openapi.documented.yml get /preferences/logs
Returns the history of preference changes in this environment, newest first. Each entry records one change a user made to one subscription topic, and carries the value before it where there was one. Supply user_id to read a single user's history instead of the whole environment.



# List Preference Sections
Source: https://www.courier.com/docs/api-reference/preference-topics/list-preference-sections

/openapi-specs/openapi.documented.yml get /preferences/sections
Returns the workspace's preferences, each embedding its subscription topics, routing options, and whether custom routing is allowed.



# List Topics in Section
Source: https://www.courier.com/docs/api-reference/preference-topics/list-topics-in-section

/openapi-specs/openapi.documented.yml get /preferences/sections/{section_id}/topics
Returns the subscription topics inside a workspace preference, each with its default status and routing options.



# Publish Preferences page
Source: https://www.courier.com/docs/api-reference/preference-topics/publish-preferences-page

/openapi-specs/openapi.documented.yml post /preferences/publish
Publishes the workspace preference page, snapshotting every preference and topic, and returns the page id and a preview URL.



# Replace a Preference Section
Source: https://www.courier.com/docs/api-reference/preference-topics/replace-a-preference-section

/openapi-specs/openapi.documented.yml put /preferences/sections/{section_id}
Replace a workspace preference. Full document replacement; missing optional fields are cleared. Topics attached to the workspace preference are unaffected.



# Replace Topic in Section
Source: https://www.courier.com/docs/api-reference/preference-topics/replace-topic-in-section

/openapi-specs/openapi.documented.yml put /preferences/sections/{section_id}/topics/{topic_id}
Replace a topic within a workspace preference. Full document replacement; missing optional fields are cleared. Same 404 rules as GET.



# Archive Device Set
Source: https://www.courier.com/docs/api-reference/previews/archive-device-set

/openapi-specs/openapi.documented.yml delete /previews/device-sets/{deviceSetId}
Archive a device set. This is a soft delete — the archived set is returned and no longer appears in list results. Runs already created against it keep their own copy of the device list and are unaffected. The Courier-provided default set cannot be archived and returns 409.



# Create Device Set
Source: https://www.courier.com/docs/api-reference/previews/create-device-set

/openapi-specs/openapi.documented.yml post /previews/device-sets
Create a named, reusable set of preview devices. Every id must be one listed by `GET /previews/devices`; any other is a 422.



# Create Preview Run
Source: https://www.courier.com/docs/api-reference/previews/create-preview-run

/openapi-specs/openapi.documented.yml post /notifications/{id}/previews/runs
Render this template's email content on each of the requested devices.

Returns as soon as the run exists and its render is queued — the screenshots are produced asynchronously. Poll `GET /notifications/{id}/previews/runs/{previewRunId}` until every result reaches a terminal status.

Name the devices either with `device_set_id`, for a saved set, or with `device_ids`, for a one-off list. Exactly one of the two is required. Inline `device_ids` must be ids listed by `GET /previews/devices`; any other id is a 422, refused before the run exists or is billed.

A template that does not exist is a 404. One that exists but cannot be previewed — not a Design Studio template, no email channel, or no such `template_version` — is a 422, also refused before the run exists or is billed.

Preview runs are a metered add-on. A workspace without it, or with its billing suspended, receives a 402.



# Get Device Set
Source: https://www.courier.com/docs/api-reference/previews/get-device-set

/openapi-specs/openapi.documented.yml get /previews/device-sets/{deviceSetId}
Retrieve a preview set by ID. Archived sets return 404.



# Get Preview Run
Source: https://www.courier.com/docs/api-reference/previews/get-preview-run

/openapi-specs/openapi.documented.yml get /notifications/{id}/previews/runs/{previewRunId}
Retrieve one of this template's preview runs together with its per-device results.

A run is only readable under the template it previewed: under any other template it is a 404, the same as a run that does not exist.

`thumbnail_url` and `screenshot_url` are short-lived signed URLs, re-signed on every read. Fetch them now rather than storing them. Both are null until Courier's own copy of the image exists, which is what `status: COMPLETED` on a result means.



# List Device Sets
Source: https://www.courier.com/docs/api-reference/previews/list-device-sets

/openapi-specs/openapi.documented.yml get /previews/device-sets
List the workspace's preview sets. Archived sets are not returned.



# List Preview Devices
Source: https://www.courier.com/docs/api-reference/previews/list-preview-devices

/openapi-specs/openapi.documented.yml get /previews/devices
List the devices a preview can be rendered on. Reference data, identical for every workspace — these ids are what a device set is built from and what a run reports results for.



# List Preview Runs
Source: https://www.courier.com/docs/api-reference/previews/list-preview-runs

/openapi-specs/openapi.documented.yml get /notifications/{id}/previews/runs
List this template's preview runs, newest first. Cursor-paginated.

A template that does not exist is a 404, the same as every other `/notifications/{id}` route.



# Update Device Set
Source: https://www.courier.com/docs/api-reference/previews/update-device-set

/openapi-specs/openapi.documented.yml put /previews/device-sets/{deviceSetId}
Replace a device set. This is a full replace, not a patch — both the name and the device list are always written. The Courier-provided default set cannot be changed and returns 409.



# Create a Provider
Source: https://www.courier.com/docs/api-reference/providers/create-a-provider

/openapi-specs/openapi.documented.yml post /providers
Configures a provider integration from a Courier provider key and its settings. Check the catalog endpoint for the schema each provider expects.



# Delete a Provider
Source: https://www.courier.com/docs/api-reference/providers/delete-a-provider

/openapi-specs/openapi.documented.yml delete /providers/{id}
Deletes a provider configuration, which fails while routing strategies or templates still reference it. Update those references first.



# Get a Provider
Source: https://www.courier.com/docs/api-reference/providers/get-a-provider

/openapi-specs/openapi.documented.yml get /providers/{id}
Returns one configured provider by id, including its channel, provider key, alias, title, and current settings.



# List available Provider types
Source: https://www.courier.com/docs/api-reference/providers/list-available-provider-types

/openapi-specs/openapi.documented.yml get /providers/catalog
Returns the provider types Courier supports, each with a display name, description, and the configuration fields it requires.



# List Providers
Source: https://www.courier.com/docs/api-reference/providers/list-providers

/openapi-specs/openapi.documented.yml get /providers
Lists the provider integrations configured in the workspace, one entry per channel and provider key with its alias and settings.



# Patch a Provider
Source: https://www.courier.com/docs/api-reference/providers/patch-a-provider

/openapi-specs/openapi.documented.yml patch /providers/{id}
Applies JSON Patch (RFC 6902) operations to a provider configuration and keeps every field the operations don't touch. Paths address the provider as it is returned: /title, /alias and /settings/<key>. The operations apply in order, and if one fails, nothing is saved.



# Update a Provider
Source: https://www.courier.com/docs/api-reference/providers/update-a-provider

/openapi-specs/openapi.documented.yml put /providers/{id}
Replaces a provider's configuration in full, clearing any field you omit rather than merging it. Send the complete settings object.



# Archive Routing Strategy
Source: https://www.courier.com/docs/api-reference/routing-strategies/archive-routing-strategy

/openapi-specs/openapi.documented.yml delete /routing-strategies/{id}
Archive a routing strategy. The strategy must not have associated notification templates. Unlink all templates before archiving.



# Create Routing Strategy
Source: https://www.courier.com/docs/api-reference/routing-strategies/create-routing-strategy

/openapi-specs/openapi.documented.yml post /routing-strategies
Create a routing strategy. Requires a name and routing configuration at minimum. Channels and providers default to empty if omitted.



# Get Routing Strategy
Source: https://www.courier.com/docs/api-reference/routing-strategies/get-routing-strategy

/openapi-specs/openapi.documented.yml get /routing-strategies/{id}
Returns one routing strategy by id with its name, tags, channels, and the routing rules that decide provider order and fallback.



# List notifications for a Routing Strategy
Source: https://www.courier.com/docs/api-reference/routing-strategies/list-notifications-for-a-routing-strategy

/openapi-specs/openapi.documented.yml get /routing-strategies/{id}/notifications
Returns the notification templates using a routing strategy, with paging. Check this before changing a strategy that templates depend on.



# List Routing Strategies
Source: https://www.courier.com/docs/api-reference/routing-strategies/list-routing-strategies

/openapi-specs/openapi.documented.yml get /routing-strategies
List routing strategies in your workspace. Returns metadata only (no routing/channels/providers content). Use GET /routing-strategies/{id} for full details.



# Replace Routing Strategy
Source: https://www.courier.com/docs/api-reference/routing-strategies/replace-routing-strategy

/openapi-specs/openapi.documented.yml put /routing-strategies/{id}
Replace a routing strategy. Full document replacement; the caller must send the complete desired state. Missing optional fields are cleared.



# Send a message
Source: https://www.courier.com/docs/api-reference/send/send-a-message

/openapi-specs/openapi.documented.yml post /send
Sends a message to one or more recipients and returns a requestId. Courier routes it to email, SMS, push, chat, or in-app based on your rules. Use the returned requestId to look up delivery status via the Messages API.



# Archive Notification Template
Source: https://www.courier.com/docs/api-reference/templates/archive-notification-template

/openapi-specs/openapi.documented.yml delete /notifications/{id}
Archives a notification template, preventing new sends from referencing it. The template stays retrievable for its version history.



# Cancel submission
Source: https://www.courier.com/docs/api-reference/templates/cancel-submission

/openapi-specs/openapi.documented.yml delete /notifications/{id}/{submissionId}/checks
Cancels a pending template submission, withdrawing it from the approval workflow. The template stays in draft and can be resubmitted later.



# Create Notification Template
Source: https://www.courier.com/docs/api-reference/templates/create-notification-template

/openapi-specs/openapi.documented.yml post /notifications
Create a notification template. Requires all fields in the notification object. Templates are created in draft state by default.

Content must place its elements inside a channel block — `{ "type": "channel", "channel": "email", "elements": [...] }` — or the request returns `400`. The template designer renders only the channel block matching the tab it draws, so content stored without one cannot be opened. An empty `elements` array is accepted, and the requirement applies to creation only: `PUT /notifications/{id}` still accepts unwrapped content. Note this endpoint takes versioned content only — the `{ title, body }` shorthand accepted by `/send` is rejected here with an `invalid_request_error` on `notification.content.version`.



# Get Notification Content
Source: https://www.courier.com/docs/api-reference/templates/get-notification-content

/openapi-specs/openapi.documented.yml get /notifications/{id}/content
Returns a template's content and checksum. V2 templates return Elemental elements, while V1 templates return blocks and channels instead.



# Get Notification Template
Source: https://www.courier.com/docs/api-reference/templates/get-notification-template

/openapi-specs/openapi.documented.yml get /notifications/{id}
Retrieve a notification template by ID. Returns the published version by default. Pass version=draft to retrieve an unpublished template.



# Get Notification Template Metrics
Source: https://www.courier.com/docs/api-reference/templates/get-notification-template-metrics

/openapi-specs/openapi.documented.yml get /notifications/{id}/metrics
Fetch the delivery funnel for one Notification Template as a time series — sent, delivered, opened, clicked, errors, and undeliverable — broken out per provider and channel inside each bucket. Sum the entries in a bucket for its totals; there is no bucket-level total.

Choose the window absolutely with `start` and `end`, or relatively with `lookback` (an ISO 8601 duration). `start` and `end` take precedence when both are supplied, and a request carrying neither defaults to `lookback=P30D`. The window is snapped outwards onto the `granularity` grid so every bucket it overlaps is returned whole, and the snapped boundaries come back as `start` and `end` — align a chart on those rather than on what was requested. Every boundary is UTC; there is no timezone support.

Every bucket in the window is returned, including the quiet ones, whose `data` array is empty, so a series is directly plottable with no gap filling client-side. An unknown template id returns `200` with an all-empty series rather than `404`, and messages sent without a Notification Template never appear here.

Available in the US region only.



# Get submission checks
Source: https://www.courier.com/docs/api-reference/templates/get-submission-checks

/openapi-specs/openapi.documented.yml get /notifications/{id}/{submissionId}/checks
Returns the approval checks recorded for a template submission, each with its pass or fail result.



# List Notification Template Versions
Source: https://www.courier.com/docs/api-reference/templates/list-notification-template-versions

/openapi-specs/openapi.documented.yml get /notifications/{id}/versions
Returns a notification template's published versions, most recent first, for comparison or rollback. Paged.



# List Notification Templates
Source: https://www.courier.com/docs/api-reference/templates/list-notification-templates

/openapi-specs/openapi.documented.yml get /notifications
Lists the workspace's notification templates. Each carries a name, tags, brand, routing, and its draft or published state.



# Publish Notification Template
Source: https://www.courier.com/docs/api-reference/templates/publish-notification-template

/openapi-specs/openapi.documented.yml post /notifications/{id}/publish
Publish a notification template. Publishes the current draft by default. Pass a version in the request body to publish a specific historical version.



# Replace Notification Content
Source: https://www.courier.com/docs/api-reference/templates/replace-notification-content

/openapi-specs/openapi.documented.yml put /notifications/{id}/content
Replaces all Elemental content in a template, overwriting every existing element. Supported for V2 templates only, not V1 blocks and channels.



# Replace Notification Element
Source: https://www.courier.com/docs/api-reference/templates/replace-notification-element

/openapi-specs/openapi.documented.yml put /notifications/{id}/elements/{elementId}
Replaces one Elemental element in a template, addressed by its element id. Supported for V2 templates only, not V1 blocks and channels.



# Replace Notification Locale
Source: https://www.courier.com/docs/api-reference/templates/replace-notification-locale

/openapi-specs/openapi.documented.yml put /notifications/{id}/locales/{localeId}
Sets locale-specific content overrides for a template. Each override must reference an element that already exists in the default content.



# Replace Notification Template
Source: https://www.courier.com/docs/api-reference/templates/replace-notification-template

/openapi-specs/openapi.documented.yml put /notifications/{id}
Replaces a notification template in full, so send every field rather than only the ones you want changed. Publish separately to make it live.



# Replace submission checks
Source: https://www.courier.com/docs/api-reference/templates/replace-submission-checks

/openapi-specs/openapi.documented.yml put /notifications/{id}/{submissionId}/checks
Replaces the approval checks on a template submission with the complete set supplied in the request body.



# Add a user to a Tenant
Source: https://www.courier.com/docs/api-reference/tenant-memberships/add-a-user-to-a-tenant

/openapi-specs/openapi.documented.yml put /users/{user_id}/tenants/{tenant_id}
Adds a user to one tenant, optionally with a tenant-specific profile that overrides their workspace profile for sends in that tenant.



# Add a user to multiple Tenants
Source: https://www.courier.com/docs/api-reference/tenant-memberships/add-a-user-to-multiple-tenants

/openapi-specs/openapi.documented.yml put /users/{user_id}/tenants
Adds a user to several tenants in one call, each optionally with a per-tenant profile that overrides their workspace profile.



# List a user's Tenants
Source: https://www.courier.com/docs/api-reference/tenant-memberships/list-a-users-tenants

/openapi-specs/openapi.documented.yml get /users/{user_id}/tenants
Returns the tenants a user belongs to, with cursor paging. A user can belong to many tenants, each with its own profile and preferences.



# Remove a user from all Tenants
Source: https://www.courier.com/docs/api-reference/tenant-memberships/remove-a-user-from-all-tenants

/openapi-specs/openapi.documented.yml delete /users/{user_id}/tenants
Removes a user from every tenant they belong to in one call. Their workspace-level profile is a separate resource.



# Remove user from a Tenant
Source: https://www.courier.com/docs/api-reference/tenant-memberships/remove-user-from-a-tenant

/openapi-specs/openapi.documented.yml delete /users/{user_id}/tenants/{tenant_id}
Removes a user from one tenant. Their other tenant memberships and workspace profile are managed through separate endpoints.



# Create or update a Tenant Template
Source: https://www.courier.com/docs/api-reference/tenant-templates/create-or-update-a-tenant-template

/openapi-specs/openapi.documented.yml put /tenants/{tenant_id}/templates/{template_id}
Creates or updates a notification template scoped to one tenant, letting a tenant override the content the workspace template would send.

This is an upsert: it creates when the tenant has no template under `template_id`, and updates when it does. On the create half, content must place its elements inside a channel block — `{ "type": "channel", "channel": "email", "elements": [...] }` — or the request returns `400`. The template designer renders only the channel block matching the tab it draws, so content stored without one cannot be opened. An empty `elements` array is accepted, as is the `{ title, body }` shorthand, which has no elements to wrap. Updates are not checked, so tenant templates already stored without a wrapper stay editable.



# Delete a Tenant Template
Source: https://www.courier.com/docs/api-reference/tenant-templates/delete-a-tenant-template

/openapi-specs/openapi.documented.yml delete /tenants/{tenant_id}/templates/{template_id}
Deletes a tenant's notification template by id. Sends for that tenant then use the workspace template registered under the same id.



# Get a Template in Tenant
Source: https://www.courier.com/docs/api-reference/tenant-templates/get-a-template-in-tenant

/openapi-specs/openapi.documented.yml get /tenants/{tenant_id}/templates/{template_id}
Returns a tenant's notification template with its content, version, and created, updated, and published timestamps.



# Get a Template version
Source: https://www.courier.com/docs/api-reference/tenant-templates/get-a-template-version

/openapi-specs/openapi.documented.yml get /tenants/{tenant_id}/templates/{template_id}/versions/{version}
Returns one version of a tenant template, addressed by version number or by latest, with its content and publish timestamp.



# List Templates in Tenant
Source: https://www.courier.com/docs/api-reference/tenant-templates/list-templates-in-tenant

/openapi-specs/openapi.documented.yml get /tenants/{tenant_id}/templates
Lists a tenant's notification templates, each carrying its version and published timestamp. Paged.



# Publish a Tenant Template
Source: https://www.courier.com/docs/api-reference/tenant-templates/publish-a-tenant-template

/openapi-specs/openapi.documented.yml post /tenants/{tenant_id}/templates/{template_id}/publish
Publishes a version of a tenant's notification template, making it the content that tenant's sends render from until you publish another.



# Create or replace a Tenant
Source: https://www.courier.com/docs/api-reference/tenants/create-or-replace-a-tenant

/openapi-specs/openapi.documented.yml put /tenants/{tenant_id}
Creates or replaces a tenant from a name, parent, brand, properties, and default preferences supplied in the request body.



# Create or replace default Preferences for Topic
Source: https://www.courier.com/docs/api-reference/tenants/create-or-replace-default-preferences-for-topic

/openapi-specs/openapi.documented.yml put /tenants/{tenant_id}/default_preferences/items/{topic_id}
Sets a tenant's default opt-in status for one subscription topic, which applies to every member unless a user sets their own override.



# Delete a Tenant
Source: https://www.courier.com/docs/api-reference/tenants/delete-a-tenant

/openapi-specs/openapi.documented.yml delete /tenants/{tenant_id}
Deletes a tenant. Its members' workspace-level profiles and preferences live outside the tenant and are managed separately.



# Get a Tenant
Source: https://www.courier.com/docs/api-reference/tenants/get-a-tenant

/openapi-specs/openapi.documented.yml get /tenants/{tenant_id}
Returns one tenant with its name, parent tenant id, default preferences, properties, and the user profile applied to its members.



# Get users in Tenant
Source: https://www.courier.com/docs/api-reference/tenants/get-users-in-tenant

/openapi-specs/openapi.documented.yml get /tenants/{tenant_id}/users
Returns the users belonging to a tenant with cursor paging. Use it to see who a tenant-scoped send will reach.



# List Tenants
Source: https://www.courier.com/docs/api-reference/tenants/list-tenants

/openapi-specs/openapi.documented.yml get /tenants
Lists the workspace's tenants, each carrying a name, parent tenant, properties, and default preferences. Paged.



# Remove default Preferences for Topic
Source: https://www.courier.com/docs/api-reference/tenants/remove-default-preferences-for-topic

/openapi-specs/openapi.documented.yml delete /tenants/{tenant_id}/default_preferences/items/{topic_id}
Removes a tenant's default preference for one subscription topic, addressed by tenant id and topic id.



# Track an event
Source: https://www.courier.com/docs/api-reference/track-events/track-an-event

/openapi-specs/openapi.documented.yml post /inbound/courier
Records an inbound event that can trigger a journey. Requires an event name, a messageId you generate, a type, and a properties object.



# Get a Translation
Source: https://www.courier.com/docs/api-reference/translations/get-a-translation

/openapi-specs/openapi.documented.yml get /translations/{domain}/{locale}
Returns the translation strings stored for one domain and locale, for use in localized notification content.



# Update Translations by locale
Source: https://www.courier.com/docs/api-reference/translations/update-translations-by-locale

/openapi-specs/openapi.documented.yml put /translations/{domain}/{locale}
Uploads the translation strings for one domain and locale. Courier uses them to render localized content for recipients in that locale.



# Delete user Subscription Topic
Source: https://www.courier.com/docs/api-reference/user-preferences/delete-user-subscription-topic

/openapi-specs/openapi.documented.yml delete /users/{user_id}/preferences/{topic_id}
Removes a user's override for one subscription topic, resetting it to the effective default from the tenant or workspace.



# Get user Subscription Topic
Source: https://www.courier.com/docs/api-reference/user-preferences/get-user-subscription-topic

/openapi-specs/openapi.documented.yml get /users/{user_id}/preferences/{topic_id}
Returns a user's opt-in status and channel choices for one subscription topic, or the effective default if they have set no override.



# Get user's Preferences
Source: https://www.courier.com/docs/api-reference/user-preferences/get-users-preferences

/openapi-specs/openapi.documented.yml get /users/{user_id}/preferences
Returns a user's preference overrides with paging, one entry per subscription topic they have set a choice for.



# Replace user Preferences in bulk
Source: https://www.courier.com/docs/api-reference/user-preferences/replace-user-preferences-in-bulk

/openapi-specs/openapi.documented.yml put /users/{user_id}/preferences
Replaces a user's entire set of preference overrides. Any topic you leave out is reset to its default, so send the full set rather than a subset.



# Update or create user Preferences for a Subscription Topic
Source: https://www.courier.com/docs/api-reference/user-preferences/update-or-create-user-preferences-for-a-subscription-topic

/openapi-specs/openapi.documented.yml put /users/{user_id}/preferences/{topic_id}
Sets a user's opt-in status and channel choices for one subscription topic, overriding the tenant default for that topic only.



# Update user Preferences in bulk
Source: https://www.courier.com/docs/api-reference/user-preferences/update-user-preferences-in-bulk

/openapi-specs/openapi.documented.yml post /users/{user_id}/preferences
Adds or updates a user's preferences for several subscription topics at once. Topics you leave out keep whatever they were set to before.



# Create a Profile
Source: https://www.courier.com/docs/api-reference/user-profiles/create-a-profile

/openapi-specs/openapi.documented.yml post /profiles/{user_id}
Merges the supplied values into a user's profile, creating it if absent and leaving any key you omit untouched. Prefer this for everyday writes.



# Delete a Profile
Source: https://www.courier.com/docs/api-reference/user-profiles/delete-a-profile

/openapi-specs/openapi.documented.yml delete /profiles/{user_id}
Deletes a user's profile and stored contact details. List subscriptions and preferences are separate resources, so remove those too if required.



# Delete List subscriptions
Source: https://www.courier.com/docs/api-reference/user-profiles/delete-list-subscriptions

/openapi-specs/openapi.documented.yml delete /profiles/{user_id}/lists
Removes every list subscription for a user at once. Their profile and preferences are untouched, so this only affects list-targeted sends.



# Get a Profile
Source: https://www.courier.com/docs/api-reference/user-profiles/get-a-profile

/openapi-specs/openapi.documented.yml get /profiles/{user_id}
Returns a user's stored profile and preferences, including the email address, phone number, and push tokens Courier can reach them on.



# Get List subscriptions
Source: https://www.courier.com/docs/api-reference/user-profiles/get-list-subscriptions

/openapi-specs/openapi.documented.yml get /profiles/{user_id}/lists
Returns the lists a user is subscribed to, with paging. Use it to check what a recipient will receive before sending to a list.



# Replace a Profile
Source: https://www.courier.com/docs/api-reference/user-profiles/replace-a-profile

/openapi-specs/openapi.documented.yml put /profiles/{user_id}
Overwrites a user profile in full, removing any key absent from the request body. Use the patch endpoint when changing a single field.



# Subscribe to one or more Lists
Source: https://www.courier.com/docs/api-reference/user-profiles/subscribe-to-one-or-more-lists

/openapi-specs/openapi.documented.yml post /profiles/{user_id}/lists
Subscribes a user to one or more lists, creating any list that does not yet exist. Optional preferences apply to each subscription.



# Update a Profile
Source: https://www.courier.com/docs/api-reference/user-profiles/update-a-profile

/openapi-specs/openapi.documented.yml patch /profiles/{user_id}
Applies a JSON Patch to a user profile, adding, removing, or replacing individual fields without sending the whole object.



# Broadcasts
Source: https://www.courier.com/docs/broadcasts/overview

Send one message to a whole list or audience, now or on a schedule.

A broadcast is one message to a whole list or audience, sent now or on a schedule.

You design the content once, pick who receives it, and send. Use a broadcast for one-off sends: newsletters, product launches, and policy updates.

A broadcast is those two things together: content written the way a [Template
DOC](/docs/design/templates/overview) is written, addressed to a [list or audience
DOC](/docs/recipients/lists-and-audiences/overview).

## Which one to use

Broadcasts and [journeys
DOC](/docs/journeys/overview) both send to many people, and the difference is what starts the send.

| | Broadcasts | Journeys |
| - | - | - |
| Shape | One message to a group | Per-user flow, single or multi-step |
| Trigger | You send it, now or scheduled | A user event or API call |
| Recipients | A list or an audience | Users entering the flow |
| Best for | Newsletters, promotions, announcements | Onboarding, receipts, digests, re-engagement |

Sending the same message to a group at a chosen moment is a broadcast. A user's action that should send a message or start a sequence is a journey.

## How it works

### From draft to sent

A broadcast moves through three states:

* **Draft**: created but not yet sent or scheduled.
* **Scheduled**: queued for a set time. You can reschedule or cancel, but the content is locked. To change the message, cancel, edit, and schedule again.
* **Sent**: delivered, with [performance metrics
  DOC](/docs/monitor/analytics#broadcasts).

Each broadcast sends on a **single channel**. To reach the same group elsewhere, create a separate broadcast. Recipients are a [list
DOC](/docs/recipients/lists-and-audiences/lists) you curate by hand, or an [audience
DOC](/docs/recipients/lists-and-audiences/audiences) Courier keeps current from rules.

### Its content

You write a broadcast's content in the same editor a [Template
DOC](/docs/design/templates/overview) uses, and it is stored as the same [Elemental
DOC](/docs/design/elemental/overview) document. Variables resolve from each recipient's profile, so one broadcast reads differently for every person.

Build a broadcast in the console, or drive the whole flow through the [Broadcasts API](/docs/api-reference/broadcasts/create-broadcast): create, write content, then send or schedule.

## FAQ

> **Is there an API to send a Broadcast?**
>
> [Create Broadcast](/docs/api-reference/broadcasts/create-broadcast) creates one, [Update Broadcast content](/docs/api-reference/broadcasts/update-broadcast-content) writes the content, and [Send Broadcast](/docs/api-reference/broadcasts/send-broadcast) or `/schedule` delivers it. You can also skip Broadcasts and send to a `list_id` or `audience_id` through the [Send API
> DOC](/docs/send/overview).

> **Should I send to a List or an Audience?**
>
> Use a list for a group you curate by hand, and an audience for a rule-based segment Courier keeps current as profiles change. Either works as recipients.


# Send a broadcast
Source: https://www.courier.com/docs/broadcasts/send

Create, schedule, and send a broadcast from the console or the API.

A Broadcast sends one message to a whole List or Audience, now or on a schedule.

## Send from the console

**1. Create the Broadcast**

In the console, open **Broadcasts** under **Orchestration** and select **Add broadcast**. Name it and pick a channel. Each Broadcast sends on one channel.

![The Add a new broadcast modal: a Name field and channel options for Email, SMS, and In-App](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/broadcast-add-new-broadcast.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=1f127c70480698f1f941834ffe55d65a)

**2. Design the content**

Drag blocks onto the canvas, the same editor as a Template. Variables resolve from each recipient's Profile.

![The broadcast design editor: the blocks panel on the left, the email canvas in the center, and Email styles on the right](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/broadcast-create-design-editor.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=418e672fdb6bcc1625e7828c97280c7f)

**3. Choose recipients**

Open **Recipients** and pick a [List
DOC](/docs/recipients/lists-and-audiences/lists) you curate by hand, or an [Audience
DOC](/docs/recipients/lists-and-audiences/audiences) Courier keeps current from rules.

![The broadcast Recipients dropdown open, listing lists and audiences alongside the send-time fields](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/broadcast-recipients-dropdown.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=c249ec837329c452a82313f34d5cb1fb)

**4. Send or schedule**

Send now, or schedule a date, time, and timezone. A scheduled Broadcast locks its content. To change the message, cancel, edit, and schedule again.

![The broadcast send panel with Scheduled selected, showing date, time, and timezone](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/broadcast-schedule-details.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=f19098c8935951e6578f1989ca7f6cc7)

**5. Check performance**

After it sends, the [**Performance** tab
DOC](/docs/monitor/analytics#broadcasts) reports delivery, open, click, and error rates, plus a per-recipient log.

![The Performance tab for a sent broadcast](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/broadcast-performance.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=de242699501487e48013e642be593f69)

## Send with the API

**1. Create the Broadcast**

[Create Broadcast](/docs/api-reference/broadcasts/create-broadcast) takes a name and one channel, and returns the Broadcast ID. `channel` is one of `email`, `sms`, `push`, `inbox`, `slack`, or `msteams`.

```javascript Node.js highlight={3} theme={null}
const broadcast = await client.broadcasts.create({
  name: 'March product update',
  channel: 'email',
});
```

```python Python highlight={3} theme={null}
broadcast = client.broadcasts.create(
    name="March product update",
    channel="email",
)
```

```bash cURL highlight={5} theme={null}
curl --request POST \
  --url https://api.courier.com/broadcasts \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "name": "March product update", "channel": "email" }'
```

```ruby Ruby theme={null}
broadcast = courier.broadcasts.create(name: "March product update", channel: "email")
```

```go Go highlight={4} theme={null}
broadcast, err := client.Broadcasts.New(context.TODO(), courier.BroadcastNewParams{
	CreateBroadcastRequest: courier.CreateBroadcastRequestParam{
		Name:    "March product update",
		Channel: "email",
	},
})
```

```java Java highlight={3} theme={null}
CreateBroadcastRequest params = CreateBroadcastRequest.builder()
    .name("March product update")
    .channel(CreateBroadcastRequest.Channel.EMAIL)
    .build();
Broadcast broadcast = client.broadcasts().create(params);
```

```php PHP highlight={3} theme={null}
$broadcast = $client->broadcasts->create(
  name: 'March product update',
  channel: 'email',
);
```

```csharp C# highlight={4} theme={null}
BroadcastCreateParams parameters = new()
{
    Name = "March product update",
    Channel = "email",
};

var broadcast = await client.Broadcasts.Create(parameters);
```

```bash CLI highlight={4} theme={null}
courier broadcasts create \
  --api-key "$COURIER_API_KEY" \
  --name "March product update" \
  --channel email
```

**2. Write the content**

[Update Broadcast content](/docs/api-reference/broadcasts/update-broadcast-content) takes the same Elemental document a Template uses.

```javascript Node.js theme={null}
await client.broadcasts.putContent('YOUR_BROADCAST_ID', {
  content: {
    version: '2022-01-01',
    elements: [{ type: 'text', content: 'Here is what shipped in March.' }],
  },
});
```

```python Python theme={null}
client.broadcasts.put_content(
    broadcast_id="YOUR_BROADCAST_ID",
    content={
        "version": "2022-01-01",
        "elements": [{"type": "text", "content": "Here is what shipped in March."}],
    },
)
```

```bash cURL theme={null}
curl --request PUT \
  --url https://api.courier.com/broadcasts/YOUR_BROADCAST_ID/content \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "content": {
      "version": "2022-01-01",
      "elements": [{ "type": "text", "content": "Here is what shipped in March." }]
    }
  }'
```

```ruby Ruby theme={null}
courier.broadcasts.put_content(
  "YOUR_BROADCAST_ID",
  content: {elements: [{type: "text", content: "Here is what shipped in March."}], version: "2022-01-01"}
)
```

```go Go theme={null}
// Elemental nodes carry no typed content field, so set it as an extra field.
textNode := shared.ElementalTextNodeWithTypeParam{Type: "text"}
textNode.SetExtraFields(map[string]any{"content": "Here is what shipped in March."})

_, err := client.Broadcasts.PutContent(
	context.TODO(),
	"YOUR_BROADCAST_ID",
	courier.BroadcastPutContentParams{
		NotificationContentPutRequest: courier.NotificationContentPutRequestParam{
			Content: courier.NotificationContentPutRequestContentParam{
				Elements: []shared.ElementalNodeUnionParam{{
					OfElementalTextNodeWithType: &textNode,
				}},
				Version: courier.String("2022-01-01"),
			},
		},
	},
)
```

```java Java theme={null}
BroadcastPutContentParams params = BroadcastPutContentParams.builder()
    .broadcastId("YOUR_BROADCAST_ID")
    .notificationContentPutRequest(NotificationContentPutRequest.builder()
        .content(NotificationContentPutRequest.Content.builder()
            .addElement(ElementalTextNodeWithType.builder()
                .type(ElementalTextNodeWithType.Type.TEXT)
                .putAdditionalProperty("content", JsonValue.from("Here is what shipped in March."))
                .build())
            .version("2022-01-01")
            .build())
        .build())
    .build();
client.broadcasts().putContent(params);
```

```php PHP theme={null}
$client->broadcasts->putContent(
  'YOUR_BROADCAST_ID',
  content: ['elements' => [['type' => 'text', 'content' => 'Here is what shipped in March.']], 'version' => '2022-01-01'],
);
```

```csharp C# theme={null}
BroadcastPutContentParams parameters = new()
{
    BroadcastID = "YOUR_BROADCAST_ID",
    Content = new()
    {
        // Elemental nodes expose no typed content property, so build the node from raw JSON.
        Elements =
        [
            ElementalTextNodeWithType.FromRawUnchecked(
                JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                { "type": "text", "content": "Here is what shipped in March." }
                """)),
        ],
        Version = "2022-01-01",
    },
};

await client.Broadcasts.PutContent(parameters);
```

```bash CLI theme={null}
courier broadcasts put-content \
  --api-key "$COURIER_API_KEY" \
  --broadcast-id YOUR_BROADCAST_ID \
  --content '{"version":"2022-01-01","elements":[{"type":"text","content":"Here is what shipped in March."}]}'
```

**3. Send it**

[Send Broadcast](/docs/api-reference/broadcasts/send-broadcast) targets a List or an Audience and sends immediately.

```javascript Node.js theme={null}
await client.broadcasts.send('YOUR_BROADCAST_ID', {
  recipient_type: 'list',
  recipient_id: 'acme-corp.beta-testers',
});
```

```python Python theme={null}
client.broadcasts.send(
    broadcast_id="YOUR_BROADCAST_ID",
    recipient_type="list",
    recipient_id="acme-corp.beta-testers",
)
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.courier.com/broadcasts/YOUR_BROADCAST_ID/send \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "recipient_type": "list", "recipient_id": "acme-corp.beta-testers" }'
```

```ruby Ruby theme={null}
courier.broadcasts.send_(
  "YOUR_BROADCAST_ID",
  recipient_type: "list",
  recipient_id: "acme-corp.beta-testers"
)
```

```go Go theme={null}
_, err := client.Broadcasts.Send(
	context.TODO(),
	"YOUR_BROADCAST_ID",
	courier.BroadcastSendParams{
		SendBroadcastRequest: courier.SendBroadcastRequestParam{
			RecipientType: "list",
			RecipientID:   "acme-corp.beta-testers",
		},
	},
)
```

```java Java theme={null}
BroadcastSendParams params = BroadcastSendParams.builder()
    .broadcastId("YOUR_BROADCAST_ID")
    .sendBroadcastRequest(SendBroadcastRequest.builder()
        .recipientType(SendBroadcastRequest.RecipientType.LIST)
        .recipientId("acme-corp.beta-testers")
        .build())
    .build();
client.broadcasts().send(params);
```

```php PHP theme={null}
$client->broadcasts->send(
  'YOUR_BROADCAST_ID',
  recipientType: 'list',
  recipientID: 'acme-corp.beta-testers',
);
```

```csharp C# theme={null}
BroadcastSendParams parameters = new()
{
    BroadcastID = "YOUR_BROADCAST_ID",
    RecipientType = "list",
    RecipientID = "acme-corp.beta-testers",
};

await client.Broadcasts.Send(parameters);
```

```bash CLI theme={null}
courier broadcasts send \
  --api-key "$COURIER_API_KEY" \
  --broadcast-id YOUR_BROADCAST_ID \
  --recipient-type list \
  --recipient-id acme-corp.beta-testers
```

**4. Or schedule it**

[Schedule Broadcast](/docs/api-reference/broadcasts/schedule-broadcast) takes a wall-clock `scheduled_to` with no offset, so the zone comes from `timezone`.

```javascript Node.js highlight={4} theme={null}
await client.broadcasts.schedule('YOUR_BROADCAST_ID', {
  recipient_type: 'audience',
  recipient_id: 'active-business-users',
  scheduled_to: '2026-07-21T20:00:00',
  timezone: 'America/New_York',
});
```

```python Python highlight={5} theme={null}
client.broadcasts.schedule(
    broadcast_id="YOUR_BROADCAST_ID",
    recipient_type="audience",
    recipient_id="active-business-users",
    scheduled_to="2026-07-21T20:00:00",
    timezone="America/New_York",
)
```

```bash cURL highlight={8} theme={null}
curl --request POST \
  --url https://api.courier.com/broadcasts/YOUR_BROADCAST_ID/schedule \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "recipient_type": "audience",
    "recipient_id": "active-business-users",
    "scheduled_to": "2026-07-21T20:00:00",
    "timezone": "America/New_York"
  }'
```

```ruby Ruby highlight={5} theme={null}
courier.broadcasts.schedule(
  "YOUR_BROADCAST_ID",
  recipient_type: "audience",
  recipient_id: "active-business-users",
  scheduled_to: "2026-07-21T20:00:00",
  timezone: "America/New_York"
)
```

```go Go highlight={8} theme={null}
_, err := client.Broadcasts.Schedule(
	context.TODO(),
	"YOUR_BROADCAST_ID",
	courier.BroadcastScheduleParams{
		ScheduleBroadcastRequest: courier.ScheduleBroadcastRequestParam{
			RecipientType: "audience",
			RecipientID:   "active-business-users",
			ScheduledTo:   "2026-07-21T20:00:00",
			Timezone:      courier.String("America/New_York"),
		},
	},
)
```

```java Java highlight={6} theme={null}
BroadcastScheduleParams params = BroadcastScheduleParams.builder()
    .broadcastId("YOUR_BROADCAST_ID")
    .scheduleBroadcastRequest(ScheduleBroadcastRequest.builder()
        .recipientType(ScheduleBroadcastRequest.RecipientType.AUDIENCE)
        .recipientId("active-business-users")
        .scheduledTo("2026-07-21T20:00:00")
        .timezone("America/New_York")
        .build())
    .build();
client.broadcasts().schedule(params);
```

```php PHP highlight={5} theme={null}
$client->broadcasts->schedule(
  'YOUR_BROADCAST_ID',
  recipientType: 'audience',
  recipientID: 'active-business-users',
  scheduledTo: '2026-07-21T20:00:00',
  timezone: 'America/New_York',
);
```

```csharp C# highlight={6} theme={null}
BroadcastScheduleParams parameters = new()
{
    BroadcastID = "YOUR_BROADCAST_ID",
    RecipientType = "audience",
    RecipientID = "active-business-users",
    ScheduledTo = "2026-07-21T20:00:00",
    Timezone = "America/New_York",
};

await client.Broadcasts.Schedule(parameters);
```

```bash CLI highlight={6} theme={null}
courier broadcasts schedule \
  --api-key "$COURIER_API_KEY" \
  --broadcast-id YOUR_BROADCAST_ID \
  --recipient-type audience \
  --recipient-id active-business-users \
  --scheduled-to "2026-07-21T20:00:00" \
  --timezone America/New_York
```

[Cancel Broadcast schedule](/docs/api-reference/broadcasts/cancel-broadcast-schedule) cancels a scheduled send, and [Duplicate Broadcast](/docs/api-reference/broadcasts/duplicate-broadcast) copies one for a repeat.


# Brands
Source: https://www.courier.com/docs/design/brands

Apply one logo, color set, header, and footer across every template you send.

A brand is the visual appearance Courier applies to your notifications: logo, colors, header, footer, and custom styling.

Attach a brand to a template and every send inherits it, so styling stays consistent. Brands cover white-labeling, multiple product identities, and per-tenant styling.

## How it works

### The brand object

A brand's `settings` hold the stored configuration:

| Path | What it holds |
| - | - |
| `settings.colors` | `primary` and `secondary`, plus any extra key you add. The designer offers `tertiary`. |
| `settings.email.header` | `barColor`, and `logo.image` with an optional `logo.href` |
| `settings.email.footer` | `markdown`, `inheritDefault`, and a `social` URL for `facebook`, `instagram`, `linkedin`, `medium`, or `twitter` |
| `settings.email.head` | `content`, injected into the email's `<head>` |
| `settings.email.templateOverride` | A custom MJML or Handlebars template, with its own background colors |
| `settings.inapp` | In-app styling: colors, icons, placement, border radius, font family |

A brand ID is prefixed `bnd_`. Legacy brands may use a slug like `default`.

Every workspace has a **default brand** that can't be deleted. Every email uses it unless you disable brands in template settings. It is also the fallback when a send enables brands without naming one.

Manage brands through the [Brands API](/docs/api-reference/brands/list-brands) or the [console](https://app.courier.com/content/brands).

### Brand variables in a template

At render time Courier flattens the brand into the `brand` namespace, **without** the `settings` level:

| Variable | Resolves to |
| - | - |
| `brand.id` | The brand's ID |
| `brand.colors.primary`, `.secondary`, `.tertiary` | The brand's colors |
| `brand.email.header.barColor` | The header bar color |
| `brand.email.header.logo.image`, `.logo.href` | The logo image and the link it wraps |
| `brand.email.backgroundColor`, `.blocksBackgroundColor`, `.footerBackgroundColor` | Layout colors from the active template override |
| `brand.social.facebook`, `.instagram`, `.linkedin`, `.medium`, `.twitter` | Each social URL. A network with no URL set is absent. |
| `brand.inapp` | The in-app settings |

Write it double-braced, so `{{brand.colors.primary}}` in template content, or `{{var "brand.colors.primary"}}` inside a brand's own MJML/Handlebars template. See [variables
DOC](/docs/design/templates/variables).

### Brand designer

The brand designer is the visual editor for a brand's logo, colors, header, and footer. It also takes a custom MJML/Handlebars template, so you can define the exact header and footer markup.

![The brand designer: brand logo and primary, secondary, and tertiary colors on the left, the head, header, and footer editors in the middle, and social URLs on the right](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/brand-designer.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=f4266505e6dc078f069075640b362f29)

### Brand snippets

> [!NOTE]
>
> **Brand snippets are legacy and not recommended for new work.** They are a **Snippets** tab on the older brand designer that stores reusable Handlebars fragments on a brand. The new brand designer doesn't carry them forward, and they aren't being developed further. Existing snippets keep rendering. For shared content in new templates, use the brand's header, footer, and **Head** editors, or a template override.

### CSS class names

Courier puts a class on every part of a rendered email. Restyle any of them from the brand's **Head** editor.

Every rule takes the same shape: a `c--` class, a `*`, and `!important`.

```html theme={null}
<mj-style>
  .c--block-text * {
    font-family: Georgia, serif !important;
  }
</mj-style>
```

Both are load-bearing. The class sits on a wrapper, so `*` reaches the text inside it, and MJML's inline styles beat a plain stylesheet.

| Target | Classes |
| - | - |
| Layout | `c--email-body`, `c--email-content`, `c--email-header`, `c--email-footer`, `c--social` |
| Blocks | `c--block`, and one of `c--block-text`, `c--block-image`, `c--block-action`, `c--block-list`, `c--block-quote`, `c--block-divider`, `c--block-markdown`, `c--block-template`, `c--block-columns` |
| Text | `c--text-text`, `c--text-h1`, `c--text-h2`, `c--text-h3`, `c--text-subtext`, `c--text-quote` |

### Email domain white-labeling

Sending from your own domain is configured on the **email provider integration**, not on the brand. Set your verified sending domain and From address on the provider (SendGrid, SES, and so on). Courier enforces the allowed domain at send time.

A branded **link and open tracking** domain is a separate setup, a CNAME to Courier's tracking infrastructure. See [tracking
DOC](/docs/monitor/tracking#custom-tracking-domain).

### Applying a brand to a send

Courier picks the brand in this order:

1. The `brand_id` on the send message.
2. The template's configured default brand, if brands are enabled on it.
3. The workspace default brand.

Override the brand per channel with `channels.<channel>.brand_id`. In multi-tenant apps, a [tenant
DOC](/docs/tenants/context) can carry a default brand, so sends in that tenant's context pick it up automatically.

## FAQ

> **How do I send from my own domain?**
>
> Set a verified sending domain and From address on your email provider integration. The brand controls visual styling only. A branded tracking domain is a separate CNAME setup.

> **What CSS classes can I target?**
>
> Layout classes like `c--email-body` and `c--email-footer`, `c--block` with a per-type variant such as `c--block-text`, and text classes from `c--text-text` to `c--text-h3`. Write `.c--block-text * { ... !important }`. The `*` reaches the text inside the wrapper, and `!important` beats the compiler's inline styles.

> **How do I brand notifications per tenant?**
>
> Give each tenant a brand and set it as the tenant's default, or pass `brand_id` on the send. Sends in a tenant's context pick up its brand automatically.


# Elemental control flow
Source: https://www.courier.com/docs/design/elemental/control-flow

Use if, loop, ref, and channels on any element to show, repeat, reuse, or target content.

Elemental has four control flow properties:

* **`if`** - Conditionally render elements based on data or conditions
* **`loop`** - Repeat elements for each item in an array
* **`ref`** - Reference elements to check their visibility or properties
* **`channels`** - Show elements only on specific channels

All four are optional, available on every element, and can be combined on the same element.

> [!NOTE]
>
> Control flow properties are evaluated at render time using Handlebars expressions. You can read `message.data`, `message.to.data`, and other message context.

## If

The `if` property renders an element only when a Handlebars expression is truthy. Otherwise the element is skipped.

**When to use:**

* Show different content based on user type, subscription status, or feature flags
* Display elements only when certain data exists
* Create personalized experiences based on user context
* Hide elements that aren't relevant to the current recipient

**Applies to**: All Elemental elements

**Basic Example**

```json Elemental highlight={4} theme={null}
{
  "type": "text",
  "content": "Welcome, premium member!",
  "if": "data.user_tier === 'premium'"
}
```

```javascript Node.js highlight={12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Welcome, premium member!",
          if: "data.user_tier === 'premium'",
        },
      ],
    },
  },
});
```

```python Python highlight={12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "text",
            "content": "Welcome, premium member!",
            "if": "data.user_tier === 'premium'",
          },
        ],
      },
    },
)
```

```bash cURL highlight={15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "text",
              "content": "Welcome, premium member!",
              "if": "data.user_tier === '\''premium'\''"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Welcome, premium member!",
          if: "data.user_tier === 'premium'"
        }
      ]
    }
  }
)
```

```go Go highlight={8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Welcome, premium member!",
      "if": "data.user_tier === 'premium'"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={10} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "text",
                    "content", "Welcome, premium member!",
                    "if", "data.user_tier === 'premium'")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'text',
          'content' => 'Welcome, premium member!',
          'if' => 'data.user_tier === \'premium\'',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "text",
                  "content": "Welcome, premium member!",
                  "if": "data.user_tier === 'premium'"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "Welcome, premium member!", "if": "data.user_tier === '\''premium'\''"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com and show the discount line only for premium users.
```

**Realistic Examples**

**Conditional welcome message based on user type:**

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Welcome back, {{first_name}}!",
      "if": "data.is_returning_user"
    },
    {
      "type": "text",
      "content": "Welcome to {{company_name}}, {{first_name}}!",
      "if": "!data.is_returning_user"
    },
    {
      "type": "action",
      "content": "Upgrade to Premium",
      "href": "https://example.com/upgrade",
      "if": "data.user_tier !== 'premium'"
    }
  ]
}
```

**Show elements only when data exists:**

```json theme={null}
{
  "type": "group",
  "if": "data.items && data.items.length > 0",
  "elements": [
    {
      "type": "text",
      "content": "Your order contains {{data.items.length}} item(s)"
    }
  ]
}
```

**Structured conditions**

The `if` field also accepts a **structured condition array**: one or more condition groups evaluated at render time. The element renders if **any** group matches, so groups are OR'd together. Within a group, conditions combine using the group's `logical_operator`.

**Supported property namespaces** (dot-paths only):

| Namespace | Description | Example |
| - | - | - |
| `data.*` | Values from the send `data` payload | `data.order_total` |
| `profile.*` | Recipient profile fields | `profile.plan` |
| `refs.*` | Visibility of another element by its `ref` | `refs.promo_banner.visible` |

**Supported operators:**

| Operator | Type | `value` required |
| - | - | - |
| `equals`, `not_equals` | binary | yes |
| `greater_than`, `less_than`, `greater_than_or_equals`, `less_than_or_equals` | binary | yes |
| `contains`, `not_contains` | binary | yes |
| `is_empty`, `is_not_empty` | unary | no |

**Design Studio labels these operators in prose, and three don't match their JSON key.** The
editor builds the same object either way. This is the mapping:

| Editor reads | JSON key |
| - | - |
| doesn't equal | `not_equals` |
| is at least | `greater_than_or_equals` |
| is at most | `less_than_or_equals` |

The other seven read as their key: equals, is greater than, is less than, contains, doesn't
contain, is empty, isn't empty.

**A condition group always holds at least one condition, and `if` always holds at least one group.**
Delete a group's last condition and the group goes with it. Delete the last group and the `if`
field is removed rather than left as `[]`. To express "no conditions," omit `if`: an element
whose `if` is `[]` is malformed.

**Single group (all conditions AND'd):**

```json theme={null}
{
  "type": "text",
  "content": "You qualify for the enterprise plan.",
  "if": [
    {
      "logical_operator": "and",
      "conditions": [
        { "property": "data.account_type", "operator": "equals", "value": "enterprise" },
        { "property": "profile.email_verified", "operator": "equals", "value": "true" }
      ]
    }
  ]
}
```

**Multiple groups (OR between groups):**

```json theme={null}
{
  "type": "text",
  "content": "Upgrade available!",
  "if": [
    {
      "logical_operator": "and",
      "conditions": [{ "property": "data.plan", "operator": "equals", "value": "free" }]
    },
    {
      "logical_operator": "and",
      "conditions": [{ "property": "data.plan", "operator": "equals", "value": "starter" }]
    }
  ]
}
```

**Unary operator (no `value` needed):**

```json theme={null}
{
  "type": "text",
  "content": "No promo code applied.",
  "if": [
    {
      "logical_operator": "and",
      "conditions": [{ "property": "data.promo_code", "operator": "is_empty" }]
    }
  ]
}
```

**Using `refs` to check element visibility:**

```json theme={null}
{
  "type": "text",
  "content": "Here is what you unlocked:",
  "if": [
    {
      "logical_operator": "and",
      "conditions": [{ "property": "refs.promo_block.visible", "operator": "equals", "value": "true" }]
    }
  ]
}
```

> [!NOTE]
>
> String `if` and structured `if` are mutually exclusive on the same element. Use one or the other. String expressions remain fully supported.

## Ref

The `ref` property names an element so other elements can reference it. A referenced element exposes its properties plus `visible`, which says whether it rendered.

**When to use:**

* Check if another element was rendered before showing related content
* Create dependencies between elements
* Build complex conditional logic based on element visibility
* Access element properties from other elements

**Applies to**: All Elemental elements

**Note**: An element can only reference elements defined earlier in the `elements` array.

**Basic Example**

```json Elemental highlight={4,9} theme={null}
{
  "type": "text",
  "content": "Hello, {{first_name}}",
  "ref": "greeting"
},
{
  "type": "text",
  "content": "This shows if greeting is visible",
  "if": "refs.greeting.visible"
}
```

```javascript Node.js highlight={12,17} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Hello, {{first_name}}",
          ref: "greeting",
        },
        {
          type: "text",
          content: "This shows if greeting is visible",
          if: "refs.greeting.visible",
        },
      ],
    },
  },
});
```

```python Python highlight={12,17} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "text",
            "content": "Hello, {{first_name}}",
            "ref": "greeting",
          },
          {
            "type": "text",
            "content": "This shows if greeting is visible",
            "if": "refs.greeting.visible",
          },
        ],
      },
    },
)
```

```bash cURL highlight={15,20} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "text",
              "content": "Hello, {{first_name}}",
              "ref": "greeting"
            },
            {
              "type": "text",
              "content": "This shows if greeting is visible",
              "if": "refs.greeting.visible"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={12,17} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Hello, {{first_name}}",
          ref: "greeting"
        },
        {
          type: "text",
          content: "This shows if greeting is visible",
          if: "refs.greeting.visible"
        }
      ]
    }
  }
)
```

```go Go highlight={8,13} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Hello, {{first_name}}",
      "ref": "greeting"
    },
    {
      "type": "text",
      "content": "This shows if greeting is visible",
      "if": "refs.greeting.visible"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={10,14} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "text",
                    "content", "Hello, {{first_name}}",
                    "ref", "greeting"),
                  java.util.Map.of(
                    "type", "text",
                    "content", "This shows if greeting is visible",
                    "if", "refs.greeting.visible")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={12,17} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'text',
          'content' => 'Hello, {{first_name}}',
          'ref' => 'greeting',
        ],
        [
          'type' => 'text',
          'content' => 'This shows if greeting is visible',
          'if' => 'refs.greeting.visible',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={15,20} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "text",
                  "content": "Hello, {{first_name}}",
                  "ref": "greeting"
                },
                {
                  "type": "text",
                  "content": "This shows if greeting is visible",
                  "if": "refs.greeting.visible"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "Hello, {{first_name}}", "ref": "greeting"}, {"type": "text", "content": "This shows if greeting is visible", "if": "refs.greeting.visible"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com that reuses an earlier element by reference.
```

**Realistic Example**

**Show follow-up content only if initial element is visible:**

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Special offer for premium members!",
      "ref": "premium_offer",
      "if": "data.user_tier === 'premium'"
    },
    {
      "type": "action",
      "content": "Claim Offer",
      "href": "https://example.com/claim",
      "if": "refs.premium_offer.visible"
    }
  ]
}
```

## Loop

The `loop` property renders an element multiple times, once for each item in an iterable data source (typically an array).

**When to use:**

* Display lists of products, orders, notifications, or other array data
* Create dynamic content that adapts to variable-length data
* Build repeating patterns like product cards or notification items
* Iterate over nested data structures

**Applies to**: All Elemental elements

**Loop variables:**

* `$.item` - The current item in the iteration
* `$.index` - The zero-based index of the current iteration

**Basic Example**

```json Elemental highlight={4} theme={null}
{
  "type": "text",
  "content": "* {{$.item.name}} - {{$.item.price}}",
  "loop": "data.products"
}
```

```javascript Node.js highlight={12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "* {{$.item.name}} - {{$.item.price}}",
          loop: "data.products",
        },
      ],
    },
    data: {
      products: [
        { name: "Notebook", price: 12.5 },
        { name: "Pen", price: 3 },
      ],
    },
  },
});
```

```python Python highlight={12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "text",
            "content": "* {{$.item.name}} - {{$.item.price}}",
            "loop": "data.products",
          },
        ],
      },
      "data": {
        "products": [
          {"name": "Notebook", "price": 12.5},
          {"name": "Pen", "price": 3},
        ],
      },
    },
)
```

```bash cURL highlight={15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "text",
              "content": "* {{$.item.name}} - {{$.item.price}}",
              "loop": "data.products"
            }
          ]
        },
        "data": {
          "products": [
            { "name": "Notebook", "price": 12.5 },
            { "name": "Pen", "price": 3 }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "* {{$.item.name}} - {{$.item.price}}",
          loop: "data.products"
        }
      ]
    },
    data: {
      products: [
        { name: "Notebook", price: 12.5 },
        { name: "Pen", price: 3 }
      ]
    }
  }
)
```

```go Go highlight={8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "* {{$.item.name}} - {{$.item.price}}",
      "loop": "data.products"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
		Data: map[string]any{
			"products": []any{
				map[string]any{"name": "Notebook", "price": 12.5},
				map[string]any{"name": "Pen", "price": 3},
			},
		},
	},
})
```

```java Java highlight={10} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "text",
                    "content", "* {{$.item.name}} - {{$.item.price}}",
                    "loop", "data.products")))))
        .data(JsonValue.from(java.util.Map.of(
                "products", java.util.List.of(
                  java.util.Map.of("name", "Notebook", "price", 12.5),
                  java.util.Map.of("name", "Pen", "price", 3)))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'text',
          'content' => '* {{$.item.name}} - {{$.item.price}}',
          'loop' => 'data.products',
        ],
      ],
    ],
    'data' => [
      'products' => [
        ['name' => 'Notebook', 'price' => 12.5],
        ['name' => 'Pen', 'price' => 3],
      ],
    ],
  ],
);
```

```csharp C# highlight={15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "text",
                  "content": "* {{$.item.name}} - {{$.item.price}}",
                  "loop": "data.products"
                }
              ]
            }
            """)),
        Data = new Dictionary<string, JsonElement>()
        {
            { "products", JsonSerializer.SerializeToElement(new[]
                {
                    new { name = "Notebook", price = 12.5 },
                    new { name = "Pen", price = 3 },
                })
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "* {{$.item.name}} - {{$.item.price}}", "loop": "data.products"}]}' \
  --message.data '{"products": [{"name": "Notebook", "price": 12.5}, {"name": "Pen", "price": 3}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com listing the two products in data.products, one line per item.
```

**Realistic Examples**

**Product list with nested data:**

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "group",
      "loop": "data.products",
      "elements": [
        {
          "type": "text",
          "content": "{{$.item.name}}",
          "text_style": "h2"
        },
        {
          "type": "text",
          "content": "Price: {{$.item.price}}"
        },
        {
          "type": "image",
          "src": "{{$.item.image_url}}",
          "alt_text": "{{$.item.name}}"
        },
        {
          "type": "action",
          "content": "View Details",
          "href": "https://example.com/products/{{$.item.id}}"
        },
        {
          "type": "divider"
        }
      ]
    }
  ]
}
```

**Using `$.index` for item numbering:**

> [!TIP]
>
> To show a 1-based item number, pass `$.index` to the `add` [Handlebars helper
> DOC](/docs/design/templates/variables):
>
> ```handlebars theme={null}
> Item {{add $.index 1}}: {{$.item.name}}
> ```
>
> This outputs "Item 1", "Item 2", and so on, instead of starting at zero.

```json theme={null}
{
  "type": "text",
  "content": "Item {{add $.index 1}}: {{$.item.name}} - {{$.item.price}}",
  "loop": "data.products"
}
```

## Channels

The `channels` property renders an element only on the channels you list. Use it to show different content on email, SMS, push, and other channels.

**When to use:**

* Show detailed content in email, concise content in SMS
* Display channel-specific formatting or elements
* Customize content per channel while maintaining a single template
* Hide elements that don't work well on certain channels

**Applies to**: All Elemental elements

**Valid channels**: `email`, `push`, `direct_message`, `sms`, or provider-specific channels like `slack`, `discord`, etc.

> [!NOTE]
>
> For a fully different content structure per channel, use [Channel elements
> DOC](/docs/design/elemental/elements/channel).

**Basic Example**

```json Elemental highlight={4} theme={null}
{
  "type": "text",
  "content": "This only appears in email and push",
  "channels": ["email", "push"]
}
```

```javascript Node.js highlight={12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "This only appears in email and push",
          channels: [
            "email",
            "push",
          ],
        },
      ],
    },
  },
});
```

```python Python highlight={12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "text",
            "content": "This only appears in email and push",
            "channels": [
              "email",
              "push",
            ],
          },
        ],
      },
    },
)
```

```bash cURL highlight={15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "text",
              "content": "This only appears in email and push",
              "channels": [
                "email",
                "push"
              ]
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "This only appears in email and push",
          channels: [
            "email",
            "push"
          ]
        }
      ]
    }
  }
)
```

```go Go highlight={8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "This only appears in email and push",
      "channels": [
        "email",
        "push"
      ]
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={10} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "text",
                    "content", "This only appears in email and push",
                    "channels", java.util.List.of(
                      "email",
                      "push"))))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'text',
          'content' => 'This only appears in email and push',
          'channels' => [
            'email',
            'push',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "text",
                  "content": "This only appears in email and push",
                  "channels": [
                    "email",
                    "push"
                  ]
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "This only appears in email and push", "channels": ["email", "push"]}]}'
```

```text MCP theme={null}
With Courier MCP, send an email and a push to sarah@acme-corp.com, showing the footer on email only.
```

**Realistic Examples**

**Channel-specific content:**

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Your order #{{order_number}} has shipped! Track it here: {{tracking_url}}",
      "channels": ["email"]
    },
    {
      "type": "text",
      "content": "Order {{order_number}} shipped. Track: {{tracking_url}}",
      "channels": ["sms"]
    },
    {
      "type": "text",
      "content": "Your order has shipped!",
      "channels": ["push"]
    }
  ]
}
```

**Hide complex elements on SMS:**

```json theme={null}
{
  "type": "columns",
  "channels": ["email"],
  "elements": [
    {
      "type": "column",
      "width": "50%",
      "elements": [
        {
          "type": "image",
          "src": "{{product_image}}"
        }
      ]
    },
    {
      "type": "column",
      "width": "50%",
      "elements": [
        {
          "type": "text",
          "content": "{{product_name}}"
        }
      ]
    }
  ]
}
```

**Combining Control Flow Properties**

You can combine multiple control flow properties on the same element:

```json theme={null}
{
  "type": "text",
  "content": "Premium feature available!",
  "if": "data.user_tier === 'premium'",
  "channels": ["email", "push"],
  "ref": "premium_notice"
}
```

**Evaluation order:**

1. `channels` - Element must match current channel
2. `if` - Condition must evaluate to truthy
3. `loop` - Element is repeated for each item (if present)
4. `ref` - Element is registered for reference (if present)

### Best practices

* **Use `if` for conditional content**: Show/hide elements based on data or user context
* **Use `loop` with `group`**: Wrap looped elements in a group for better organization
* **Reference order matters**: Elements must be defined before they're referenced
* **Test with real data**: Control flow expressions are evaluated at render time, so test with realistic data structures
* **Combine with locales**: Use control flow with [localization
  DOC](/docs/design/elemental/locales) for fully dynamic, multi-language notifications
* **Channel considerations**: some elements (like columns) may not render well on all channels


# Elemental action element
Source: https://www.courier.com/docs/design/elemental/elements/action

Add a button or link with a label, href, and style, rendered per channel.

The action element adds a clickable action to your notification. It renders as a button or a link, depending on the channel and styling options you choose. The type value is `"action"`.

**When to use:**

* Add call-to-action buttons (e.g., "Sign Up", "View Order", "Confirm Email")
* Create clickable links within notifications
* Provide interactive elements that direct users to specific URLs

**Basic example**

```json Elemental theme={null}
{
  "type": "action",
  "content": "Click me",
  "href": "https://example.com"
}
```

```javascript Node.js highlight={9-13} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "action",
          content: "Click me",
          href: "https://example.com",
        },
      ],
    },
  },
});
```

```python Python highlight={9-13} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "action",
            "content": "Click me",
            "href": "https://example.com",
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-16} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "action",
              "content": "Click me",
              "href": "https://example.com"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-13} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "action",
          content: "Click me",
          href: "https://example.com"
        }
      ]
    }
  }
)
```

```go Go highlight={5-9} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "action",
      "content": "Click me",
      "href": "https://example.com"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-10} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "action",
                    "content", "Click me",
                    "href", "https://example.com")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-13} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'action',
          'content' => 'Click me',
          'href' => 'https://example.com',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-16} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "action",
                  "content": "Click me",
                  "href": "https://example.com"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "action", "content": "Click me", "href": "https://example.com"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com with a button linking to our dashboard.
```

**Fields**

**content** `string` *required*

The label displayed on the button or link.

**href** `string` *required*

The target URL of the action. Clicking it sends the user to this URL.

**action\_id** `string`

A unique identifier for the action when it is executed. Useful for tracking and analytics.

**align** `string`

The alignment of the action button. One of `"center"`, `"left"`, `"right"`, or `"full"`. Defaults to `"center"`.

**background\_color** `string`

The background color of the action button. Any valid CSS color value (e.g., `"#007bff"`, `"rgb(0, 123, 255)"`).

**style** `string`

The visual style of the action. Defaults to `"button"`.

* `"button"`: a filled button. `background_color` is the fill.
* `"secondary"`: an outlined button. `background_color` is the border and the label.
* `"tertiary"`: the quietest button. `background_color` is the label.
* `"link"`: inline text rather than a button, and the only style that draws no button chrome.

`background_color` is a fill only for `"button"`. Sending white with `"secondary"` asks for a white border and a white label, not a white button.

**disable\_tracking** `boolean`

When true, the action's `href` isn't rewritten for click-through tracking, even when click-through tracking is enabled for the workspace.

**locales** `object`

Translations of `content` and `href`, keyed by locale code. See [Template translations
DOC](/docs/design/elemental/locales).

**Examples and variants**

**Styles**

The default style renders a filled button:

```json theme={null}
{
  "type": "action",
  "content": "Get Started",
  "href": "https://example.com/start",
  "style": "button"
}
```

`"link"` renders inline text instead:

```json theme={null}
{
  "type": "action",
  "content": "Learn more",
  "href": "https://example.com/docs",
  "style": "link"
}
```

Each channel draws these as closely as its medium allows, so the three button styles are a hierarchy rather than a fixed set of pixels:

| | Email | Inbox | Slack |
| - | - | - | - |
| `"button"` | filled | plain, hairline edge | button |
| `"secondary"` | outlined | outlined | button, Slack's `primary` style |
| `"tertiary"` | underlined | solid fill | button, Slack's `danger` style |
| `"link"` | inline link | inline link | `mrkdwn` link |

The Inbox reads the three buttons as a volume control rather than as email's fill, outline, and rule. `"button"` is the quiet default it has always drawn, and `"tertiary"` is the solid one.

**Styled button**

Customize the button appearance with colors and alignment:

```json theme={null}
{
  "type": "action",
  "content": "Sign Up Now",
  "href": "https://example.com/signup",
  "style": "button",
  "background_color": "#007bff",
  "align": "center"
}
```

**With localization**

Localize action content and URLs:

```json theme={null}
{
  "type": "action",
  "content": "View Dashboard",
  "href": "https://app.example.com/dashboard",
  "locales": {
    "es": {
      "content": "Ver Panel",
      "href": "https://app.example.com/es/dashboard"
    },
    "fr": {
      "content": "Voir le Tableau de Bord",
      "href": "https://app.example.com/fr/dashboard"
    }
  }
}
```

**With conditional logic**

Show different actions based on conditions:

```json theme={null}
{
  "type": "action",
  "content": "Upgrade Account",
  "href": "https://example.com/upgrade",
  "if": "{{user.plan}} === 'free'"
}
```

**Channel support**

Action elements are supported across all channels:

* **Email**: filled, outlined, or underlined, following `style`
* **Push**: a clickable action button
* **SMS**: a clickable link
* **Inbox**: an interactive button whose weight follows `style`


# Elemental channel element
Source: https://www.courier.com/docs/design/elemental/elements/channel

Set different content per channel inside one document, and override that channel's routing.

The channel element sets content per channel. Send a detailed message on email and a shorter one on push. The type value is `"channel"`.

**When to use:**

* Provide channel-specific content (different content for email vs push vs SMS)
* Use raw channel data for provider-specific formats (MJML for email, Slack blocks, etc.)
* Create channel-specific layouts and structures

> [!NOTE]
>
> Channel elements are only valid at the top level and can't be nested. If one appears at the top level, every sibling must also be a channel element.

> [!TIP]
>
> **Alternative**: most elements support a `channels` property that shows a single element on chosen channels only. See [Control flow
> DOC](/docs/design/elemental/control-flow#channels).

**Basic example**

```json Elemental theme={null}
{
  "type": "channel",
  "channel": "email",
  "elements": [
    {
      "type": "meta",
      "title": "My Subject"
    },
    {
      "type": "text",
      "content": "My email body"
    }
  ]
}
```

```javascript Node.js highlight={9-22} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "channel",
          channel: "email",
          elements: [
            {
              type: "meta",
              title: "My Subject",
            },
            {
              type: "text",
              content: "My email body",
            },
          ],
        },
      ],
    },
  },
});
```

```python Python highlight={9-22} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "channel",
            "channel": "email",
            "elements": [
              {
                "type": "meta",
                "title": "My Subject",
              },
              {
                "type": "text",
                "content": "My email body",
              },
            ],
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-25} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "channel",
              "channel": "email",
              "elements": [
                {
                  "type": "meta",
                  "title": "My Subject"
                },
                {
                  "type": "text",
                  "content": "My email body"
                }
              ]
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-22} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "channel",
          channel: "email",
          elements: [
            {
              type: "meta",
              title: "My Subject"
            },
            {
              type: "text",
              content: "My email body"
            }
          ]
        }
      ]
    }
  }
)
```

```go Go highlight={5-18} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [
        {
          "type": "meta",
          "title": "My Subject"
        },
        {
          "type": "text",
          "content": "My email body"
        }
      ]
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "channel",
                    "channel", "email",
                    "elements", java.util.List.of(
                      java.util.Map.of(
                        "type", "meta",
                        "title", "My Subject"),
                      java.util.Map.of(
                        "type", "text",
                        "content", "My email body")))))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-22} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'channel',
          'channel' => 'email',
          'elements' => [
            [
              'type' => 'meta',
              'title' => 'My Subject',
            ],
            [
              'type' => 'text',
              'content' => 'My email body',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-25} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "channel",
                  "channel": "email",
                  "elements": [
                    {
                      "type": "meta",
                      "title": "My Subject"
                    },
                    {
                      "type": "text",
                      "content": "My email body"
                    }
                  ]
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "channel", "channel": "email", "elements": [{"type": "meta", "title": "My Subject"}, {"type": "text", "content": "My email body"}]}]}'
```

```text MCP theme={null}
With Courier MCP, send an email and an SMS to sarah@acme-corp.com with different content on each channel.
```

**Fields**

**channel** `string` *required*

The channel the contents of this element should be applied to. Can be:

* Standard channels: `"email"`, `"push"`, `"direct_message"`, `"sms"`
* Provider names: `"slack"`, `"discord"`, `"teams"`, etc.
* `"default"` - applies to all channels not explicitly specified

**elements** `CourierElement[]`

An array of Elemental elements to apply to the channel. If `raw` hasn't been specified, `elements` is required.

**raw** `object`

Raw data to apply to the channel. Use channel-specific formats like MJML for email, Slack blocks, or webhook payloads. If `elements` hasn't been specified, `raw` is required.

**font\_family** `string`

The CSS `font-family` stack to apply to the rendered email. Only valid when `channel` is `"email"`. Use the exact `fontFamily` value from the [font catalog
DOC](/docs/design/elemental/fonts#font-catalog). Google Fonts are loaded automatically. Defaults to `Helvetica, Arial, sans-serif` if omitted.

```json theme={null}
{
  "type": "channel",
  "channel": "email",
  "font_family": "Roboto, Arial, sans-serif",
  "elements": [...]
}
```

**Examples and variants**

**Using elements**

Provide different Elemental content per channel:

```json theme={null}
{
  "type": "channel",
  "channel": "email",
  "elements": [
    {
      "type": "meta",
      "title": "Order Confirmation"
    },
    {
      "type": "text",
      "content": "Your order #{{order_id}} has been confirmed. We'll send you tracking information once your order ships."
    },
    {
      "type": "action",
      "content": "View Order",
      "href": "https://app.example.com/orders/{{order_id}}"
    }
  ]
},
{
  "type": "channel",
  "channel": "push",
  "elements": [
    {
      "type": "meta",
      "title": "Order Confirmed"
    },
    {
      "type": "text",
      "content": "Order #{{order_id}} confirmed"
    }
  ]
}
```

**Using raw data**

Use raw channel data for provider-specific formats.

Email with MJML:

```json theme={null}
{
  "type": "channel",
  "channel": "email",
  "raw": {
    "subject": "Order Confirmation",
    "html": "<mjml><mj-body><mj-section><mj-column><mj-text>Your order has been confirmed!</mj-text></mj-column></mj-section></mj-body></mjml>",
    "text": "Your order has been confirmed!",
    "transformers": ["handlebars", "mjml"]
  }
}
```

Slack:

```json theme={null}
{
  "type": "channel",
  "channel": "slack",
  "raw": {
    "text": "Hello World!",
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "Your order has been confirmed!"
        }
      }
    ]
  }
}
```

Webhook:

```json theme={null}
{
  "type": "channel",
  "channel": "webhook",
  "raw": {
    "payload": {
      "body": {
        "event": "order.confirmed",
        "order_id": "{{order_id}}",
        "timestamp": "{{timestamp}}"
      }
    }
  }
}
```

**Default channel**

Use `"default"` to provide content for all channels not explicitly specified:

```json theme={null}
{
  "type": "channel",
  "channel": "email",
  "elements": [
    {
      "type": "text",
      "content": "Detailed email content here"
    }
  ]
},
{
  "type": "channel",
  "channel": "default",
  "elements": [
    {
      "type": "text",
      "content": "Content for push, SMS, and other channels"
    }
  ]
}
```

**Channel-specific considerations**

**Email**

* Supports full Elemental elements or raw HTML/MJML
* Can use `raw.subject` for email subject line
* Supports `transformers` array for templating engines

**Push**

* Typically uses `meta.title` for notification title
* Content should be concise due to character limits
* Supports action buttons via action elements

**SMS**

* Very limited character count
* Best for short, essential messages
* No rich formatting support

**Direct message (Slack, Discord, Teams, etc.)**

* Provider-specific formats via `raw` property
* Can use provider-specific block structures
* Supports rich interactive elements per provider


# Elemental columns element
Source: https://www.courier.com/docs/design/elemental/elements/columns

Lay out content side by side in columns with their own width and styling.

The columns element holds a row of columns for side-by-side content. Each column can set its own styling, width, and content. The type value is `"columns"`, and each child must be a `"column"` element.

**When to use:**

* Create side-by-side layouts (e.g., product images with descriptions)
* Build responsive multi-column grids
* Organize content in structured layouts
* Display data in tabular-like formats

> [!NOTE]
>
> **Email client compatibility**: column styling uses MJML patterns. Borders and border radius render correctly in most modern email clients and degrade gracefully in older ones. The `gap` property inserts spacer columns between content columns to get the spacing right.

**Basic example**

```json Elemental theme={null}
{
  "type": "columns",
  "elements": [
    {
      "type": "column",
      "width": "50%",
      "elements": [
        {
          "type": "image",
          "src": "https://example.com/product.png"
        }
      ]
    },
    {
      "type": "column",
      "width": "50%",
      "elements": [
        {
          "type": "text",
          "content": "Product Name",
          "text_style": "h2"
        },
        {
          "type": "text",
          "content": "$99.99"
        }
      ]
    }
  ]
}
```

```javascript Node.js highlight={9-38} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "columns",
          elements: [
            {
              type: "column",
              width: "50%",
              elements: [
                {
                  type: "image",
                  src: "https://example.com/product.png",
                },
              ],
            },
            {
              type: "column",
              width: "50%",
              elements: [
                {
                  type: "text",
                  content: "Product Name",
                  text_style: "h2",
                },
                {
                  type: "text",
                  content: "$99.99",
                },
              ],
            },
          ],
        },
      ],
    },
  },
});
```

```python Python highlight={9-38} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "columns",
            "elements": [
              {
                "type": "column",
                "width": "50%",
                "elements": [
                  {
                    "type": "image",
                    "src": "https://example.com/product.png",
                  },
                ],
              },
              {
                "type": "column",
                "width": "50%",
                "elements": [
                  {
                    "type": "text",
                    "content": "Product Name",
                    "text_style": "h2",
                  },
                  {
                    "type": "text",
                    "content": "$99.99",
                  },
                ],
              },
            ],
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-41} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "columns",
              "elements": [
                {
                  "type": "column",
                  "width": "50%",
                  "elements": [
                    {
                      "type": "image",
                      "src": "https://example.com/product.png"
                    }
                  ]
                },
                {
                  "type": "column",
                  "width": "50%",
                  "elements": [
                    {
                      "type": "text",
                      "content": "Product Name",
                      "text_style": "h2"
                    },
                    {
                      "type": "text",
                      "content": "$99.99"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-38} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "columns",
          elements: [
            {
              type: "column",
              width: "50%",
              elements: [
                {
                  type: "image",
                  src: "https://example.com/product.png"
                }
              ]
            },
            {
              type: "column",
              width: "50%",
              elements: [
                {
                  type: "text",
                  content: "Product Name",
                  text_style: "h2"
                },
                {
                  type: "text",
                  content: "$99.99"
                }
              ]
            }
          ]
        }
      ]
    }
  }
)
```

```go Go highlight={5-34} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "columns",
      "elements": [
        {
          "type": "column",
          "width": "50%",
          "elements": [
            {
              "type": "image",
              "src": "https://example.com/product.png"
            }
          ]
        },
        {
          "type": "column",
          "width": "50%",
          "elements": [
            {
              "type": "text",
              "content": "Product Name",
              "text_style": "h2"
            },
            {
              "type": "text",
              "content": "$99.99"
            }
          ]
        }
      ]
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-27} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "columns",
                    "elements", java.util.List.of(
                      java.util.Map.of(
                        "type", "column",
                        "width", "50%",
                        "elements", java.util.List.of(
                          java.util.Map.of(
                            "type", "image",
                            "src", "https://example.com/product.png"))),
                      java.util.Map.of(
                        "type", "column",
                        "width", "50%",
                        "elements", java.util.List.of(
                          java.util.Map.of(
                            "type", "text",
                            "content", "Product Name",
                            "text_style", "h2"),
                          java.util.Map.of(
                            "type", "text",
                            "content", "$99.99")))))))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-38} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'columns',
          'elements' => [
            [
              'type' => 'column',
              'width' => '50%',
              'elements' => [
                [
                  'type' => 'image',
                  'src' => 'https://example.com/product.png',
                ],
              ],
            ],
            [
              'type' => 'column',
              'width' => '50%',
              'elements' => [
                [
                  'type' => 'text',
                  'content' => 'Product Name',
                  'text_style' => 'h2',
                ],
                [
                  'type' => 'text',
                  'content' => '$99.99',
                ],
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-41} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "columns",
                  "elements": [
                    {
                      "type": "column",
                      "width": "50%",
                      "elements": [
                        {
                          "type": "image",
                          "src": "https://example.com/product.png"
                        }
                      ]
                    },
                    {
                      "type": "column",
                      "width": "50%",
                      "elements": [
                        {
                          "type": "text",
                          "content": "Product Name",
                          "text_style": "h2"
                        },
                        {
                          "type": "text",
                          "content": "$99.99"
                        }
                      ]
                    }
                  ]
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "columns", "elements": [{"type": "column", "width": "50%", "elements": [{"type": "image", "src": "https://example.com/product.png"}]}, {"type": "column", "width": "50%", "elements": [{"type": "text", "content": "Product Name", "text_style": "h2"}, {"type": "text", "content": "$99.99"}]}]}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com laid out in two columns.
```

**Columns element fields**

**elements** `CourierColumn[]` *required*

An array of column elements. Each must be of type `"column"`. See the **Column element** section below.

**background\_color** `string`

Background color for the columns container. Any valid CSS color value (e.g., `"#f5f5f5"`, `"rgb(245,245,245)"`).

**border\_width** `string`

Border width for the columns container (e.g., `"1px"`, `"2px"`).

**border\_color** `string`

Border color for the columns container (e.g., `"#cccccc"`, `"rgb(204,204,204)"`).

**border\_radius** `string`

Border radius for rounded corners on the container (e.g., `"5px"`, `"10px"`).

**gap** `string`

Spacing between columns. Automatically inserts spacer columns with exact width (e.g., `"10px"`, `"15px"`).

**padding** `string`

Inner padding for the columns container. CSS shorthand works (e.g., `"10px"`, `"20px 10px"`).

**vertical\_align** `string`

Alignment of columns within the row. One of `"top"`, `"middle"`, or `"bottom"`. Defaults to `"top"`.

**Column element**

Each child in a columns element's `elements` array must be of type `column`. Each one can set its own styling and width.

**type** `string` *required*

Must be `"column"`.

**elements** `CourierElement[]` *required*

The content blocks inside this column. Any Elemental elements (text, image, action, etc.).

**width** `string`

The width of the column. Can be:

* Percentage: `"50%"`, `"33.33%"`
* Fixed: `"200px"`, `"300px"`
* Auto: `"auto"` (takes remaining space)

**background\_color** `string`

Hex code or CSS color for the column background (e.g., `"#F4F7FF"`, `"rgb(244,247,255)"`).

**border\_width** `string`

Border width for this specific column (e.g., `"1px"`, `"2px"`).

**border\_color** `string`

Border color for this specific column (e.g., `"#cccccc"`, `"rgb(204,204,204)"`).

**border\_radius** `string`

Border radius for rounded corners on this column (e.g., `"5px"`, `"10px"`).

**padding** `string`

CSS padding shorthand for the column (e.g., `"10px"`, `"20px 10px"`).

**vertical\_align** `string`

Overrides the parent's vertical alignment for this column. One of `"top"`, `"middle"`, or `"bottom"`.

**Examples and variants**

**Two-column layout**

Basic sidebar and main content layout:

```json theme={null}
{
  "type": "columns",
  "elements": [
    {
      "type": "column",
      "width": "30%",
      "background_color": "#F4F7FF",
      "padding": "20px",
      "elements": [
        {
          "type": "image",
          "src": "https://example.com/avatar.png",
          "width": "50px"
        },
        {
          "type": "text",
          "content": "User Profile",
          "text_style": "subtext"
        }
      ]
    },
    {
      "type": "column",
      "width": "70%",
      "padding": "20px",
      "elements": [
        {
          "type": "text",
          "content": "Welcome to the platform!",
          "text_style": "h2"
        },
        {
          "type": "text",
          "content": "We are excited to have you here. Your account is now active."
        },
        {
          "type": "action",
          "content": "Get Started",
          "href": "https://example.com/start",
          "style": "button"
        }
      ]
    }
  ]
}
```

**Equal-width columns**

Three equal columns with middle vertical alignment:

```json theme={null}
{
  "type": "columns",
  "vertical_align": "middle",
  "gap": "15px",
  "elements": [
    {
      "type": "column",
      "width": "33.33%",
      "elements": [
        {
          "type": "text",
          "content": "Column 1",
          "text_style": "h3"
        },
        {
          "type": "text",
          "content": "Content for first column"
        }
      ]
    },
    {
      "type": "column",
      "width": "33.33%",
      "elements": [
        {
          "type": "text",
          "content": "Column 2",
          "text_style": "h3"
        },
        {
          "type": "text",
          "content": "Content for second column"
        }
      ]
    },
    {
      "type": "column",
      "width": "33.33%",
      "elements": [
        {
          "type": "text",
          "content": "Column 3",
          "text_style": "h3"
        },
        {
          "type": "text",
          "content": "Content for third column"
        }
      ]
    }
  ]
}
```

**Styled container with borders**

Columns container with styling:

```json theme={null}
{
  "type": "columns",
  "padding": "20px",
  "background_color": "#f5f5f5",
  "border_width": "2px",
  "border_color": "#cccccc",
  "border_radius": "8px",
  "gap": "15px",
  "elements": [
    {
      "type": "column",
      "width": "50%",
      "elements": [
        {
          "type": "text",
          "content": "Left Column"
        }
      ]
    },
    {
      "type": "column",
      "width": "50%",
      "elements": [
        {
          "type": "text",
          "content": "Right Column"
        }
      ]
    }
  ]
}
```

**Product card layout**

Complete product card with image and details:

```json theme={null}
{
  "type": "columns",
  "padding": "25px",
  "background_color": "#ffffff",
  "border_width": "1px",
  "border_color": "#e0e0e0",
  "border_radius": "12px",
  "gap": "20px",
  "vertical_align": "middle",
  "elements": [
    {
      "type": "column",
      "width": "40%",
      "border_width": "1px",
      "border_color": "#4CAF50",
      "border_radius": "8px",
      "padding": "20px",
      "background_color": "#f1f8f4",
      "elements": [
        {
          "type": "image",
          "src": "https://example.com/product-image.jpg",
          "href": "https://example.com/product",
          "width": "100%"
        }
      ]
    },
    {
      "type": "column",
      "width": "60%",
      "elements": [
        {
          "type": "text",
          "content": "**Premium Product Name**",
          "text_style": "h2"
        },
        {
          "type": "text",
          "content": "High-quality product with exceptional features. Perfect for everyday use."
        },
        {
          "type": "text",
          "content": "**$149.99**",
          "bold": true
        },
        {
          "type": "action",
          "content": "Add to Cart",
          "href": "https://example.com/cart",
          "background_color": "#4CAF50",
          "style": "button"
        }
      ]
    }
  ]
}
```

**Channel support**

* **Email**: Full support with MJML rendering for maximum compatibility
* **Push**: Limited support. Columns may render as stacked content
* **SMS**: Not supported. Use single-column layouts
* **Inbox**: Full support with responsive behavior


# Elemental comment element
Source: https://www.courier.com/docs/design/elemental/elements/comment

Add notes to a template that never render in the output, for documenting the document.

The comment element holds notes that never render in the output. Use it to document templates, leave notes for teammates, or label sections. The type value is `"comment"`.

**When to use:**

* Document complex template logic
* Add notes for other developers
* Organize and label sections of your template
* Include metadata that shouldn't appear in notifications

> [!NOTE]
>
> Comments are ignored at render time and never appear in the output, on any channel.

**Basic example**

```json Elemental theme={null}
{
  "type": "comment",
  "comment": "This is a comment that will not be rendered in the output"
}
```

```javascript Node.js highlight={9-12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "comment",
          comment: "This is a comment that will not be rendered in the output",
        },
      ],
    },
  },
});
```

```python Python highlight={9-12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "comment",
            "comment": "This is a comment that will not be rendered in the output",
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "comment",
              "comment": "This is a comment that will not be rendered in the output"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "comment",
          comment: "This is a comment that will not be rendered in the output"
        }
      ]
    }
  }
)
```

```go Go highlight={5-8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "comment",
      "comment": "This is a comment that will not be rendered in the output"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "comment",
                    "comment", "This is a comment that will not be rendered in the output")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'comment',
          'comment' => 'This is a comment that will not be rendered in the output',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "comment",
                  "comment": "This is a comment that will not be rendered in the output"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "comment", "comment": "This is a comment that will not be rendered in the output"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com and leave a comment element noting who owns the copy.
```

**Fields**

**comment** `string`

The comment text. It isn't rendered in the output.

**object** `any`

An optional object alongside the comment. Holds metadata, structured notes, or other context that isn't rendered.

**Examples and variants**

**Simple comment**

Add a basic text comment:

```json theme={null}
{
  "type": "comment",
  "comment": "This section handles order confirmations"
}
```

**Comment with metadata**

Include structured data with your comment:

```json theme={null}
{
  "type": "comment",
  "comment": "A/B test variant A - shows promotional content",
  "object": {
    "test_id": "promo_ab_test",
    "variant": "A",
    "author": "team-marketing",
    "last_updated": "2024-01-15"
  }
}
```

**Organizing template sections**

Use comments to organize and label different sections:

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "comment",
      "comment": "=== HEADER SECTION ==="
    },
    {
      "type": "meta",
      "title": "Order Confirmation"
    },
    {
      "type": "image",
      "src": "https://example.com/logo.png"
    },
    {
      "type": "comment",
      "comment": "=== MAIN CONTENT ==="
    },
    {
      "type": "text",
      "content": "Your order has been confirmed!"
    },
    {
      "type": "comment",
      "comment": "=== FOOTER SECTION ==="
    },
    {
      "type": "text",
      "content": "Questions? Contact support@acme-corp.com"
    }
  ]
}
```


# Elemental divider element
Source: https://www.courier.com/docs/design/elemental/elements/divider

Render a horizontal rule between content sections, with color and spacing.

The divider element renders a horizontal rule between elements. Use it to separate content sections. The type value is `"divider"`.

**When to use:**

* Separate distinct sections of content
* Create visual breaks between related items
* Improve readability in long notifications
* Organize grouped content visually

**Basic example**

```json Elemental theme={null}
{
  "type": "divider",
  "color": "#800080"
}
```

```javascript Node.js highlight={9-12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "divider",
          color: "#800080",
        },
      ],
    },
  },
});
```

```python Python highlight={9-12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "divider",
            "color": "#800080",
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "divider",
              "color": "#800080"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "divider",
          color: "#800080"
        }
      ]
    }
  }
)
```

```go Go highlight={5-8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "divider",
      "color": "#800080"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "divider",
                    "color", "#800080")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'divider',
          'color' => '#800080',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "divider",
                  "color": "#800080"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "divider", "color": "#800080"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com with a divider between two sections.
```

**Fields**

**color** `string`

The CSS color of the divider line. Any valid CSS color value (e.g., `"#e0e0e0"`, `"rgb(224, 224, 224)"`, `"gray"`). Defaults to a standard gray.

**border\_width** `string`

Border width in pixels for the divider line (e.g., `"1px"`, `"2px"`).

**padding** `string`

Padding around the divider. Any valid CSS padding value (e.g., `"10px"`, `"20px 10px"`).

**channels** `string[]`

An array of channel names. The divider renders only for the listed channels. See [Control flow
DOC](/docs/design/elemental/control-flow#channels).

**Examples and variants**

**Basic divider**

Simple divider with default styling:

```json theme={null}
{
  "type": "divider"
}
```

**Styled divider**

Divider with custom color:

```json theme={null}
{
  "type": "divider",
  "color": "#800080"
}
```

**Thick divider**

Divider with custom width:

```json theme={null}
{
  "type": "divider",
  "color": "#007bff",
  "border_width": "3px"
}
```

**Divider with padding**

Divider with spacing:

```json theme={null}
{
  "type": "divider",
  "color": "#e0e0e0",
  "padding": "20px 0"
}
```

**Section separator**

Using dividers to separate content sections:

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Order Summary",
      "text_style": "h2"
    },
    {
      "type": "text",
      "content": "Item 1: $29.99"
    },
    {
      "type": "text",
      "content": "Item 2: $49.99"
    },
    {
      "type": "divider",
      "color": "#cccccc"
    },
    {
      "type": "text",
      "content": "Total: $79.98",
      "bold": true
    }
  ]
}
```

**Channel support**

* **Email**: ✅ Full support with styling
* **Push**: ⚠️ Limited support (may render as plain text or be ignored)
* **SMS**: ❌ Not supported (dividers aren't rendered)
* **Inbox**: ✅ Full support with styling


# Elemental group element
Source: https://www.courier.com/docs/design/elemental/elements/group

Wrap several elements so one if or loop condition applies to all of them.

The group element wraps multiple elements into one unit. Combine it with `if` or `loop` to render or repeat the whole set at once. The type value is `"group"`.

**When to use:**

* Apply conditional logic to multiple elements at once
* Loop over multiple elements together
* Organize related elements into logical sections
* Create reusable element blocks

**Basic example**

```json Elemental theme={null}
{
  "type": "group",
  "elements": [
    {
      "type": "text",
      "content": "Welcome!"
    },
    {
      "type": "action",
      "content": "Get Started",
      "href": "https://example.com/start"
    }
  ]
}
```

```javascript Node.js highlight={9-22} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "group",
          elements: [
            {
              type: "text",
              content: "Welcome!",
            },
            {
              type: "action",
              content: "Get Started",
              href: "https://example.com/start",
            },
          ],
        },
      ],
    },
  },
});
```

```python Python highlight={9-22} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "group",
            "elements": [
              {
                "type": "text",
                "content": "Welcome!",
              },
              {
                "type": "action",
                "content": "Get Started",
                "href": "https://example.com/start",
              },
            ],
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-25} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "group",
              "elements": [
                {
                  "type": "text",
                  "content": "Welcome!"
                },
                {
                  "type": "action",
                  "content": "Get Started",
                  "href": "https://example.com/start"
                }
              ]
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-22} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "group",
          elements: [
            {
              type: "text",
              content: "Welcome!"
            },
            {
              type: "action",
              content: "Get Started",
              href: "https://example.com/start"
            }
          ]
        }
      ]
    }
  }
)
```

```go Go highlight={5-18} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "group",
      "elements": [
        {
          "type": "text",
          "content": "Welcome!"
        },
        {
          "type": "action",
          "content": "Get Started",
          "href": "https://example.com/start"
        }
      ]
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "group",
                    "elements", java.util.List.of(
                      java.util.Map.of(
                        "type", "text",
                        "content", "Welcome!"),
                      java.util.Map.of(
                        "type", "action",
                        "content", "Get Started",
                        "href", "https://example.com/start")))))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-22} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'group',
          'elements' => [
            [
              'type' => 'text',
              'content' => 'Welcome!',
            ],
            [
              'type' => 'action',
              'content' => 'Get Started',
              'href' => 'https://example.com/start',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-25} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "group",
                  "elements": [
                    {
                      "type": "text",
                      "content": "Welcome!"
                    },
                    {
                      "type": "action",
                      "content": "Get Started",
                      "href": "https://example.com/start"
                    }
                  ]
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "group", "elements": [{"type": "text", "content": "Welcome!"}, {"type": "action", "content": "Get Started", "href": "https://example.com/start"}]}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com with a grouped heading and button block.
```

**Fields**

**elements** `CourierElement[]` *required*

An array of Elemental elements. They render together as one unit.

**if** `string | object[]`

A condition that determines whether the whole group renders. Accepts a string expression or a structured condition array. See [Control flow
DOC](/docs/design/elemental/control-flow#if).

**loop** `string`

An expression that repeats the whole group. See [Control flow
DOC](/docs/design/elemental/control-flow#loop).

**ref** `string`

A reference identifier for the group. See [Control flow
DOC](/docs/design/elemental/control-flow#ref).

**channels** `string[]`

An array of channel names. The group renders only for the listed channels. See [Control flow
DOC](/docs/design/elemental/control-flow#channels).

**Examples and variants**

**Conditional group**

Show or hide multiple elements based on a condition:

```json theme={null}
{
  "type": "group",
  "if": "{{user.plan}} === 'premium'",
  "elements": [
    {
      "type": "text",
      "content": "**Premium Features**",
      "text_style": "h2"
    },
    {
      "type": "text",
      "content": "You have access to all premium features!"
    },
    {
      "type": "action",
      "content": "Explore Features",
      "href": "https://example.com/premium"
    }
  ]
}
```

**Looping group**

Repeat a group of elements for each item in an array:

```json theme={null}
{
  "type": "group",
  "loop": "data.products",
  "elements": [
    {
      "type": "text",
      "content": "# {{$.item.name}}",
      "text_style": "h2"
    },
    {
      "type": "divider"
    },
    {
      "type": "text",
      "content": "Description: {{$.item.description}}"
    },
    {
      "type": "text",
      "content": "Price: ${{$.item.price}}",
      "bold": true
    },
    {
      "type": "action",
      "content": "View Product",
      "href": "https://example.com/products/{{$.item.id}}"
    }
  ]
}
```

**Nested groups**

Group elements within groups for complex structures:

```json theme={null}
{
  "type": "group",
  "if": "{{order.items.length}} > 0",
  "elements": [
    {
      "type": "text",
      "content": "Order Items",
      "text_style": "h2"
    },
    {
      "type": "group",
      "loop": "data.order.items",
      "elements": [
        {
          "type": "text",
          "content": "{{$.item.name}} - ${{$.item.price}}"
        }
      ]
    },
    {
      "type": "text",
      "content": "Total: ${{order.total}}",
      "bold": true
    }
  ]
}
```


# Elemental HTML element
Source: https://www.courier.com/docs/design/elemental/elements/html

Embed raw HTML when no other element produces the structure you need.

The HTML element embeds raw HTML in your notification. Use it when the other Elemental elements can't produce the structure or styling you need. It renders on email only. The type value is `"html"`.

**When to use:**

* Custom HTML structures (tables, complex layouts)
* HTML that requires specific formatting not available in Elemental elements
* Legacy HTML content that needs to be preserved
* Custom styling that requires direct HTML/CSS

**Basic example**

```json Elemental theme={null}
{
  "type": "html",
  "content": "<h1>Hello, <strong>World!</strong></h1>"
}
```

```javascript Node.js highlight={9-12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "html",
          content: "<h1>Hello, <strong>World!</strong></h1>",
        },
      ],
    },
  },
});
```

```python Python highlight={9-12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "html",
            "content": "<h1>Hello, <strong>World!</strong></h1>",
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "html",
              "content": "<h1>Hello, <strong>World!</strong></h1>"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "html",
          content: "<h1>Hello, <strong>World!</strong></h1>"
        }
      ]
    }
  }
)
```

```go Go highlight={5-8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "html",
      "content": "<h1>Hello, <strong>World!</strong></h1>"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "html",
                    "content", "<h1>Hello, <strong>World!</strong></h1>")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'html',
          'content' => '<h1>Hello, <strong>World!</strong></h1>',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "html",
                  "content": "<h1>Hello, <strong>World!</strong></h1>"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "html", "content": "<h1>Hello, <strong>World!</strong></h1>"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com with a raw HTML block.
```

**Fields**

**content** `string` *required*

The raw HTML. Any valid HTML markup, including CSS styles.

**locales** `object`

Translations of `content`, keyed by locale code. See [Template translations
DOC](/docs/design/elemental/locales).

**channels** `string[]`

An array of channel names. The HTML element renders only for the listed channels. See [Control flow
DOC](/docs/design/elemental/control-flow#channels).

**Examples and variants**

**Simple HTML**

Basic HTML content:

```json theme={null}
{
  "type": "html",
  "content": "<h1>Hello, <strong>World!</strong></h1>"
}
```

**HTML table**

Create custom HTML tables:

```json theme={null}
{
  "type": "html",
  "content": "<table style='width: 100%; border-collapse: collapse;'><tr><th style='border: 1px solid #ddd; padding: 8px;'>Item</th><th style='border: 1px solid #ddd; padding: 8px;'>Price</th></tr><tr><td style='border: 1px solid #ddd; padding: 8px;'>Product A</td><td style='border: 1px solid #ddd; padding: 8px;'>$99.99</td></tr></table>"
}
```

**HTML with Handlebars**

Use Handlebars variables in HTML:

```json theme={null}
{
  "type": "html",
  "content": "<div><h2>Order #{{order_id}}</h2><p>Total: ${{order_total}}</p></div>"
}
```

**HTML with localization**

Localize HTML content:

```json theme={null}
{
  "type": "html",
  "content": "<h1>Welcome!</h1>",
  "locales": {
    "es": {
      "content": "<h1>¡Bienvenido!</h1>"
    },
    "fr": {
      "content": "<h1>Bienvenue!</h1>"
    }
  }
}
```

**Channel-specific HTML**

Only render HTML for email:

```json theme={null}
{
  "type": "html",
  "channels": ["email"],
  "content": "<div style='background: #f5f5f5; padding: 20px;'>Email-only HTML content</div>"
}
```

### Best practices

* **Use sparingly**: prefer standard Elemental elements for cross-channel compatibility
* **Test thoroughly**: HTML rendering varies across email clients.
* **Use inline styles**: email clients often strip `<style>` tags, so use inline CSS
* **Keep it simple**: complex HTML may not render correctly in all email clients

**Channel support**

* **Email**: ✅ Full support
* **Push**: ❌ Not supported
* **SMS**: ❌ Not supported
* **Inbox**: ❌ Not supported


# Elemental image element
Source: https://www.courier.com/docs/design/elemental/elements/image

Embed an image with width, alignment, alt text, and an optional link.

The image element embeds an image in your notification. Images can be aligned, sized, linked, and given alt text. The type value is `"image"`.

**When to use:**

* Display logos, product images, or illustrations
* Add visual elements to enhance notifications
* Create clickable image banners
* Include user avatars or profile pictures

**Basic example**

```json Elemental theme={null}
{
  "type": "image",
  "src": "https://example.com/logo.png"
}
```

```javascript Node.js highlight={9-12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "image",
          src: "https://example.com/logo.png",
        },
      ],
    },
  },
});
```

```python Python highlight={9-12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "image",
            "src": "https://example.com/logo.png",
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "image",
              "src": "https://example.com/logo.png"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "image",
          src: "https://example.com/logo.png"
        }
      ]
    }
  }
)
```

```go Go highlight={5-8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "image",
      "src": "https://example.com/logo.png"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "image",
                    "src", "https://example.com/logo.png")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'image',
          'src' => 'https://example.com/logo.png',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "image",
                  "src": "https://example.com/logo.png"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "image", "src": "https://example.com/logo.png"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com with our logo image at the top.
```

**Fields**

**src** `string` *required*

The image URL. Must be publicly accessible.

**alt\_text** `string`

Alternate text for the image. Screen readers use it, and it displays when the image can't load.

**href** `string`

A URL to open when the image is clicked.

**width** `string`

CSS width for the image. Can be:

* Fixed: `"200px"`, `"300px"`
* Percentage: `"50%"`, `"100%"`
* Auto: `"auto"`

**align** `string`

The alignment of the image. One of `"center"`, `"left"`, `"right"`, or `"full"`. Defaults to `"center"`.

**border\_color** `string`

CSS border color applied to the image (e.g., `"#ccc"`).

**border\_size** `string`

CSS border width applied to the image (e.g., `"1px"`).

**padding** `string`

CSS padding applied around the image (e.g., `"10px"`).

**locales** `object`

Translations of `src` (image URL) and `href` (link URL), keyed by locale code. `alt_text` stays in the default language. See [Template translations
DOC](/docs/design/elemental/locales).

**channels** `string[]`

An array of channel names. The image renders only for the listed channels. See [Control flow
DOC](/docs/design/elemental/control-flow#channels).

**Examples and variants**

**Basic image**

Simple image with alt text:

```json theme={null}
{
  "type": "image",
  "src": "https://example.com/logo.png",
  "alt_text": "Company Logo"
}
```

**Clickable image**

Image that links to a URL:

```json theme={null}
{
  "type": "image",
  "src": "https://example.com/banner.jpg",
  "alt_text": "Special Offer",
  "href": "https://example.com/sale",
  "width": "100%"
}
```

**Sized and aligned image**

Control image size and alignment:

```json theme={null}
{
  "type": "image",
  "src": "https://example.com/product.png",
  "alt_text": "Product Image",
  "width": "200px",
  "align": "center"
}
```

**Localized image**

Use different images for different locales:

```json theme={null}
{
  "type": "image",
  "src": "https://example.com/welcome-en.png",
  "alt_text": "Welcome",
  "href": "https://example.com/dashboard",
  "locales": {
    "es": {
      "src": "https://example.com/welcome-es.png",
      "href": "https://example.com/es/dashboard"
    },
    "fr": {
      "src": "https://example.com/welcome-fr.png",
      "href": "https://example.com/fr/dashboard"
    }
  }
}
```

**Channel-specific image**

Show different images per channel:

```json theme={null}
{
  "type": "image",
  "channels": ["email"],
  "src": "https://example.com/email-banner.jpg",
  "alt_text": "Email Banner",
  "width": "100%"
},
{
  "type": "image",
  "channels": ["push"],
  "src": "https://example.com/push-icon.png",
  "alt_text": "Notification Icon"
}
```

**Full-width banner**

Full-width banner image:

```json theme={null}
{
  "type": "image",
  "src": "https://example.com/banner.jpg",
  "alt_text": "Promotional Banner",
  "href": "https://example.com/promo",
  "width": "100%",
  "align": "full"
}
```

**Channel support**

* **Email**: ✅ Full support with alignment, sizing, and linking
* **Push**: ✅ Supported (typically as notification icon or banner)
* **SMS**: ❌ Not supported (text-only channel)
* **Inbox**: ✅ Full support


# Elemental Jsonnet element
Source: https://www.courier.com/docs/design/elemental/elements/jsonnet

Generate Elemental content at render time with a Jsonnet template.

The Jsonnet element embeds a Jsonnet template in your Elemental document. Jsonnet is a data templating language that generates JSON, so it suits structured content built programmatically. The type value is `"jsonnet"`.

**When to use:**

* Generate dynamic JSON structures based on data
* Create reusable template logic with functions and variables
* Build complex nested objects programmatically
* Avoid repetitive JSON structures

> [!NOTE]
>
> Jsonnet is an advanced feature and requires knowing its syntax. For simple content, use [Text elements
> DOC](/docs/design/elemental/elements/text) with Handlebars variables instead.

**Basic example**

```json Elemental theme={null}
{
  "type": "jsonnet",
  "template": "local person(name, age) = { name: name, age: age, greeting: \"Hello \" + name + \"!\" }; { user: person(\"Sarah Bennett\", 30) }"
}
```

```javascript Node.js highlight={9-12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "jsonnet",
          template: "local person(name, age) = { name: name, age: age, greeting: \"Hello \" + name + \"!\" }; { user: person(\"Sarah Bennett\", 30) }",
        },
      ],
    },
  },
});
```

```python Python highlight={9-12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "jsonnet",
            "template": "local person(name, age) = { name: name, age: age, greeting: \"Hello \" + name + \"!\" }; { user: person(\"Sarah Bennett\", 30) }",
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "jsonnet",
              "template": "local person(name, age) = { name: name, age: age, greeting: \"Hello \" + name + \"!\" }; { user: person(\"Sarah Bennett\", 30) }"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "jsonnet",
          template: "local person(name, age) = { name: name, age: age, greeting: \"Hello \" + name + \"!\" }; { user: person(\"Sarah Bennett\", 30) }"
        }
      ]
    }
  }
)
```

```go Go highlight={5-8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "jsonnet",
      "template": "local person(name, age) = { name: name, age: age, greeting: \"Hello \" + name + \"!\" }; { user: person(\"Sarah Bennett\", 30) }"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "jsonnet",
                    "template", "local person(name, age) = { name: name, age: age, greeting: \"Hello \" + name + \"!\" }; { user: person(\"Sarah Bennett\", 30) }")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'jsonnet',
          'template' => 'local person(name, age) = { name: name, age: age, greeting: "Hello " + name + "!" }; { user: person("Sarah Bennett", 30) }',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "jsonnet",
                  "template": "local person(name, age) = { name: name, age: age, greeting: \"Hello \" + name + \"!\" }; { user: person(\"Sarah Bennett\", 30) }"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "jsonnet", "template": "local person(name, age) = { name: name, age: age, greeting: \"Hello \" + name + \"!\" }; { user: person(\"Sarah Bennett\", 30) }"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com whose content is generated by a jsonnet element.
```

**Fields**

**template** `string` *required*

The Jsonnet template code. A string of valid Jsonnet, evaluated to produce JSON. The template reaches message data through Jsonnet's standard variable access.

**channels** `string[]`

An array of channel names. The Jsonnet element renders only for the listed channels. See [Control flow
DOC](/docs/design/elemental/control-flow#channels).

**Jsonnet language basics**

Jsonnet extends JSON with:

* **Variables**: `local name = "Sarah Bennett";`
* **Functions**: `local greet(name) = "Hello " + name;`
* **Object composition**: Merge objects with `+`
* **Conditionals**: `if condition then value1 else value2`
* **Loops**: `[x * 2 for x in [1, 2, 3]]`
* **Imports**: `local lib = import "lib.jsonnet";`

> [!NOTE]
>
> For complete Jsonnet language documentation, see the [official Jsonnet documentation](https://jsonnet.org/).

**Examples and variants**

**Simple object generation**

Generate a simple JSON object:

```json theme={null}
{
  "type": "jsonnet",
  "template": "{ message: \"Welcome!\", timestamp: \"2024-01-15\" }"
}
```

**Output:**

```json theme={null}
{
  "message": "Welcome!",
  "timestamp": "2024-01-15"
}
```

**Using functions**

Create reusable functions:

```json theme={null}
{
  "type": "jsonnet",
  "template": "local formatPrice(amount) = \"$\" + std.toString(amount); { price: formatPrice(99.99), discount: formatPrice(49.99) }"
}
```

**Output:**

```json theme={null}
{
  "price": "$99.99",
  "discount": "$49.99"
}
```

**Conditional content**

Generate different content based on conditions:

```json theme={null}
{
  "type": "jsonnet",
  "template": "local isPremium = true; { tier: if isPremium then \"premium\" else \"basic\", features: if isPremium then [\"feature1\", \"feature2\", \"feature3\"] else [\"feature1\"] }"
}
```

**Output:**

```json theme={null}
{
  "tier": "premium",
  "features": ["feature1", "feature2", "feature3"]
}
```

**Complex nested structures**

Build complex nested objects:

```json theme={null}
{
  "type": "jsonnet",
  "template": "local user(name, email) = { profile: { name: name, email: email }, settings: { notifications: true } }; { users: [user(\"Sarah Bennett\", \"sarah@acme-corp.com\"), user(\"Kai Turner\", \"kai@acme-corp.com\")] }"
}
```

**Output:**

```json theme={null}
{
  "users": [
    {
      "profile": {
        "name": "Sarah Bennett",
        "email": "sarah@acme-corp.com"
      },
      "settings": {
        "notifications": true
      }
    },
    {
      "profile": {
        "name": "Kai Turner",
        "email": "kai@acme-corp.com"
      },
      "settings": {
        "notifications": true
      }
    }
  ]
}
```

> [!WARNING]
>
> Jsonnet templates are evaluated at render time. A syntax or runtime error fails the whole notification render. Test your templates before deploying.

**Channel support**

* **Email**: ✅ Full support
* **Push**: ✅ Supported (JSON output can be used in push payloads)
* **SMS**: ⚠️ Limited support (JSON output may need to be stringified)
* **Inbox**: ✅ Full support

**Additional resources**

* [Jsonnet Language Documentation](https://jsonnet.org/)
* [Jsonnet Tutorial](https://jsonnet.org/learning/tutorial.html)
* [Jsonnet Standard Library](https://jsonnet.org/ref/stdlib.html)


# Elemental list element
Source: https://www.courier.com/docs/design/elemental/elements/list

Render ordered or unordered lists, nested up to five levels, from your data.

The list element renders an ordered (numbered) or unordered (bulleted) list. Lists nest up to 5 levels deep. Parent and nested lists can each use their own loop. The type value is `"list"`, and each child must be a `"list-item"` element.

**When to use:**

* Display ordered sequences (steps, rankings)
* Show unordered items (features, benefits, options)
* Create nested hierarchical structures
* Display dynamic lists from data (products, items, etc.)

**Basic example**

```json Elemental theme={null}
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "First item" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Second item" }
      ]
    }
  ]
}
```

```javascript Node.js highlight={9-32} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "list",
          list_type: "unordered",
          elements: [
            {
              type: "list-item",
              elements: [
                {
                  type: "string",
                  content: "First item",
                },
              ],
            },
            {
              type: "list-item",
              elements: [
                {
                  type: "string",
                  content: "Second item",
                },
              ],
            },
          ],
        },
      ],
    },
  },
});
```

```python Python highlight={9-32} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "list",
            "list_type": "unordered",
            "elements": [
              {
                "type": "list-item",
                "elements": [
                  {
                    "type": "string",
                    "content": "First item",
                  },
                ],
              },
              {
                "type": "list-item",
                "elements": [
                  {
                    "type": "string",
                    "content": "Second item",
                  },
                ],
              },
            ],
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-35} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "list",
              "list_type": "unordered",
              "elements": [
                {
                  "type": "list-item",
                  "elements": [
                    {
                      "type": "string",
                      "content": "First item"
                    }
                  ]
                },
                {
                  "type": "list-item",
                  "elements": [
                    {
                      "type": "string",
                      "content": "Second item"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-32} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "list",
          list_type: "unordered",
          elements: [
            {
              type: "list-item",
              elements: [
                {
                  type: "string",
                  content: "First item"
                }
              ]
            },
            {
              type: "list-item",
              elements: [
                {
                  type: "string",
                  content: "Second item"
                }
              ]
            }
          ]
        }
      ]
    }
  }
)
```

```go Go highlight={5-28} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "list",
      "list_type": "unordered",
      "elements": [
        {
          "type": "list-item",
          "elements": [
            {
              "type": "string",
              "content": "First item"
            }
          ]
        },
        {
          "type": "list-item",
          "elements": [
            {
              "type": "string",
              "content": "Second item"
            }
          ]
        }
      ]
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-22} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "list",
                    "list_type", "unordered",
                    "elements", java.util.List.of(
                      java.util.Map.of(
                        "type", "list-item",
                        "elements", java.util.List.of(
                          java.util.Map.of(
                            "type", "string",
                            "content", "First item"))),
                      java.util.Map.of(
                        "type", "list-item",
                        "elements", java.util.List.of(
                          java.util.Map.of(
                            "type", "string",
                            "content", "Second item")))))))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-32} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'list',
          'list_type' => 'unordered',
          'elements' => [
            [
              'type' => 'list-item',
              'elements' => [
                [
                  'type' => 'string',
                  'content' => 'First item',
                ],
              ],
            ],
            [
              'type' => 'list-item',
              'elements' => [
                [
                  'type' => 'string',
                  'content' => 'Second item',
                ],
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-35} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "list",
                  "list_type": "unordered",
                  "elements": [
                    {
                      "type": "list-item",
                      "elements": [
                        {
                          "type": "string",
                          "content": "First item"
                        }
                      ]
                    },
                    {
                      "type": "list-item",
                      "elements": [
                        {
                          "type": "string",
                          "content": "Second item"
                        }
                      ]
                    }
                  ]
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "list", "list_type": "unordered", "elements": [{"type": "list-item", "elements": [{"type": "string", "content": "First item"}]}, {"type": "list-item", "elements": [{"type": "string", "content": "Second item"}]}]}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com listing every item in their order.
```

**Fields**

**list\_type** `string` *required*

One of `"ordered"` (numbered) or `"unordered"` (bulleted).

**elements** `ListItemElement[]` *required*

An array of list item elements. Each must be of type `"list-item"`. See the **List item fields** section below.

**imgSrc** `string`

Renders bullets as a custom image, for unordered lists only. The image URL becomes the bullet.

**imgHref** `string`

URL for the bullet image, if used. Makes the bullet image clickable.

**loop** `string`

An expression that generates the list from data. See [Control flow
DOC](/docs/design/elemental/control-flow#loop).

**if** `string | object[]`

A condition that determines whether the list renders. Accepts a string expression or a structured condition array. See [Control flow
DOC](/docs/design/elemental/control-flow#if).

**channels** `string[]`

An array of channel names. The list renders only for the listed channels. See [Control flow
DOC](/docs/design/elemental/control-flow#channels).

**List item fields**

Each item in the `elements` array must be a list item element with the following properties:

**type** `string` *required*

Must be `"list-item"`.

**elements** `CourierElement[]` *required*

Content of the list item. Can include:

* `string` elements for text
* `link` elements for clickable links
* `img` elements for inline images
* Nested `list` elements for sub-lists

**background\_color** `string`

Background color for the list item. Any valid CSS color value.

**loop** `string`

An expression that repeats the list item. See [Control flow
DOC](/docs/design/elemental/control-flow#loop).

**if** `string | object[]`

A condition that determines whether the list item renders. Accepts a string expression or a structured condition array. See [Control flow
DOC](/docs/design/elemental/control-flow#if).

**Examples and variants**

**Unordered list**

Simple bulleted list:

```json theme={null}
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Feature 1" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Feature 2" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Feature 3" }
      ]
    }
  ]
}
```

**Ordered list**

Numbered list:

```json theme={null}
{
  "type": "list",
  "list_type": "ordered",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Step 1: Sign up" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Step 2: Verify email" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Step 3: Get started" }
      ]
    }
  ]
}
```

**Nested lists**

Nest a list inside a list item:

```json theme={null}
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Fruits" },
        {
          "type": "list",
          "list_type": "ordered",
          "elements": [
            {
              "type": "list-item",
              "elements": [
                { "type": "string", "content": "Apple" }
              ]
            },
            {
              "type": "list-item",
              "elements": [
                { "type": "string", "content": "Banana" }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Vegetables" },
        {
          "type": "list",
          "list_type": "ordered",
          "elements": [
            {
              "type": "list-item",
              "elements": [
                { "type": "string", "content": "Carrot" }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

**List items with links**

Include clickable links in list items:

```json theme={null}
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "View our " },
        { "type": "link", "content": "documentation", "href": "https://example.com/docs" },
        { "type": "string", "content": " for more info" }
      ]
    }
  ]
}
```

**Dynamic lists with loops**

Generate lists from data:

```json theme={null}
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "loop": "data.products",
      "elements": [
        { "type": "string", "content": "{{$.item.name}} - ${{$.item.price}}" }
      ]
    }
  ]
}
```

**Nested dynamic lists**

Dynamic lists with nested loops:

```json theme={null}
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "loop": "data.categories",
      "elements": [
        { "type": "string", "content": "{{$.item.name}}" },
        {
          "type": "list",
          "list_type": "ordered",
          "elements": [
            {
              "type": "list-item",
              "loop": "$.item.products",
              "elements": [
                { "type": "string", "content": "{{$.item}}" }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

**Custom bullet images**

Use custom images for bullets:

```json theme={null}
{
  "type": "list",
  "list_type": "unordered",
  "imgSrc": "https://example.com/custom-bullet.png",
  "imgHref": "https://example.com",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Item with custom bullet" }
      ]
    }
  ]
}
```

> [!NOTE]
>
> Nested lists can use a different list type (ordered/unordered) than their parent.

**Channel support**

* **Email**: ✅ Full support with proper list rendering
* **Push**: ✅ Supported (may render as plain text in some cases)
* **SMS**: ⚠️ Limited support (may render as plain text)
* **Inbox**: ✅ Full support


# Elemental meta element
Source: https://www.courier.com/docs/design/elemental/elements/meta

Set the title, which becomes the email subject and push title.

The meta element describes the notification for the channel or provider rendering it. Its `title` field becomes the title on channels that support one, such as email subject lines and push titles. The type value is `"meta"`.

**When to use:**

* Set email subject lines
* Set push notification titles
* Provide channel-specific titles
* Include metadata for notification processing

**Basic example**

```json Elemental theme={null}
{
  "type": "meta",
  "title": "Thank you for signing up!"
}
```

```javascript Node.js highlight={9-12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "meta",
          title: "Thank you for signing up!",
        },
      ],
    },
  },
});
```

```python Python highlight={9-12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "meta",
            "title": "Thank you for signing up!",
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "meta",
              "title": "Thank you for signing up!"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "meta",
          title: "Thank you for signing up!"
        }
      ]
    }
  }
)
```

```go Go highlight={5-8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "meta",
      "title": "Thank you for signing up!"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "meta",
                    "title", "Thank you for signing up!")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'meta',
          'title' => 'Thank you for signing up!',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "meta",
                  "title": "Thank you for signing up!"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "meta", "title": "Thank you for signing up!"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com and set its subject line with a meta element.
```

**Fields**

**title** `string`

The title to be displayed by supported channels:

* **Email**: Used as the email subject line
* **Push**: Used as the push notification title
* **Inbox**: Used as the notification title

Supports Handlebars variables.

**locales** `object`

Translations of `title`, keyed by locale code such as `es` or `fr`. See [Template translations
DOC](/docs/design/elemental/locales).

**channels** `string[]`

An array of channel names. The meta element applies only to the listed channels. See [Control flow
DOC](/docs/design/elemental/control-flow#channels).

**Examples and variants**

**Basic title**

Simple title for email subject or push notification:

```json theme={null}
{
  "type": "meta",
  "title": "Thank you for signing up!"
}
```

**Dynamic title with Handlebars**

Use variables in the title:

```json theme={null}
{
  "type": "meta",
  "title": "Hello, {{first_name}} {{last_name}}"
}
```

The variables come from `message.data` (e.g., `data.first_name`, `data.last_name`).

**Channel-specific titles**

Different titles for different channels:

```json theme={null}
{
  "type": "meta",
  "channels": ["email"],
  "title": "Order Confirmation - Check Your Email"
},
{
  "type": "meta",
  "channels": ["push"],
  "title": "Order Confirmed!"
},
{
  "type": "meta",
  "channels": ["sms"],
  "title": "Order #{{order_id}} confirmed"
}
```

**Localized titles**

Localize titles for different languages:

```json theme={null}
{
  "type": "meta",
  "title": "Welcome!",
  "locales": {
    "es": {
      "title": "¡Bienvenido!"
    },
    "fr": {
      "title": "Bienvenue!"
    },
    "de": {
      "title": "Willkommen!"
    }
  }
}
```

**Combined dynamic and localized**

Use both Handlebars and localization:

```json theme={null}
{
  "type": "meta",
  "title": "Order #{{order_id}} Confirmed",
  "locales": {
    "es": {
      "title": "Pedido #{{order_id}} Confirmado"
    },
    "fr": {
      "title": "Commande #{{order_id}} Confirmée"
    }
  }
}
```

**Multiple meta elements**

Use multiple meta elements for different purposes:

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "meta",
      "channels": ["email"],
      "title": "Your Weekly Newsletter"
    },
    {
      "type": "meta",
      "channels": ["push"],
      "title": "New Newsletter Available"
    },
    {
      "type": "text",
      "content": "Check out this week's updates..."
    }
  ]
}
```

**Channel usage**

**Email**: the `title` field becomes the email subject line.

**Push notifications**: the `title` field becomes the push notification title. Keep it concise, typically 40-60 characters.

**SMS**: meta elements are typically unused, since SMS has no title or subject.

**Inbox**: the `title` field becomes the notification title in the inbox.


# Elemental quote element
Source: https://www.courier.com/docs/design/elemental/elements/quote

Render a quote block for testimonials or callouts, with border, color, and text styles.

The quote element renders a quote block for testimonials or text you want to stand out. Style it with borders, colors, and text styles. The type value is `"quote"`.

**When to use:**

* Display testimonials or customer reviews
* Highlight important quotes or statements
* Emphasize key information
* Create visually distinct text blocks

**Basic example**

```json Elemental theme={null}
{
  "type": "quote",
  "content": "The future belongs to those who believe in the beauty of their dreams"
}
```

```javascript Node.js highlight={9-12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "quote",
          content: "The future belongs to those who believe in the beauty of their dreams",
        },
      ],
    },
  },
});
```

```python Python highlight={9-12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "quote",
            "content": "The future belongs to those who believe in the beauty of their dreams",
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "quote",
              "content": "The future belongs to those who believe in the beauty of their dreams"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "quote",
          content: "The future belongs to those who believe in the beauty of their dreams"
        }
      ]
    }
  }
)
```

```go Go highlight={5-8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "quote",
      "content": "The future belongs to those who believe in the beauty of their dreams"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "quote",
                    "content", "The future belongs to those who believe in the beauty of their dreams")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'quote',
          'content' => 'The future belongs to those who believe in the beauty of their dreams',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "quote",
                  "content": "The future belongs to those who believe in the beauty of their dreams"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "quote", "content": "The future belongs to those who believe in the beauty of their dreams"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com with a quoted callout.
```

**Fields**

**content** `string` *required*

The text of the quote. Supports Handlebars variables.

**align** `string`

Alignment of the quote. One of `"center"`, `"left"`, `"right"`, or `"full"`. Defaults to `"left"`.

**border\_color** `string`

CSS border color for the quote block. Any valid CSS color value (e.g., `"#007bff"`, `"rgb(0, 123, 255)"`).

**text\_style** `string`

Text style for the quote. One of `"text"`, `"h1"`, `"h2"`, or `"subtext"`. Defaults to `"text"`.

**locales** `object`

Translations of `content`, keyed by locale code. See [Template translations
DOC](/docs/design/elemental/locales).

**channels** `string[]`

An array of channel names. The quote renders only for the listed channels. See [Control flow
DOC](/docs/design/elemental/control-flow#channels).

**Examples and variants**

**Basic quote**

Simple quote block:

```json theme={null}
{
  "type": "quote",
  "content": "The future belongs to those who believe in the beauty of their dreams"
}
```

**Styled quote**

Quote with border and styling:

```json theme={null}
{
  "type": "quote",
  "content": "Customer satisfaction is our top priority",
  "border_color": "#007bff",
  "text_style": "h2",
  "align": "center"
}
```

**Quote with Handlebars**

Dynamic quote content:

```json theme={null}
{
  "type": "quote",
  "content": "{{customer_name}} said: \"{{testimonial}}\""
}
```

**Localized quote**

Quote with translations:

```json theme={null}
{
  "type": "quote",
  "content": "Quality is not an act, it is a habit",
  "locales": {
    "es": {
      "content": "La calidad no es un acto, es un hábito"
    },
    "fr": {
      "content": "La qualité n'est pas un acte, c'est une habitude"
    }
  }
}
```

**Testimonial quote**

Quote styled as a testimonial:

```json theme={null}
{
  "type": "quote",
  "content": "\"This product changed my life!\" - {{customer_name}}",
  "border_color": "#4CAF50",
  "text_style": "h2",
  "align": "center"
}
```

**Channel support**

* **Email**: ✅ Full support with styling and borders
* **Push**: ✅ Supported (may render as plain text in some cases)
* **SMS**: ⚠️ Limited support (may render as plain text)
* **Inbox**: ✅ Full support


# Elemental text element
Source: https://www.courier.com/docs/design/elemental/elements/text

Render body text with formatting, styles, and inline links or images.

The text element renders a body of text. It supports formatting and styling, and can contain inline text content elements (string, link, img). The type value is `"text"`.

**When to use:**

* Display body text, paragraphs, and descriptions
* Create headings and subheadings
* Show formatted text with styling (bold, italic, colors)
* Include inline links and images within text
* Display dynamic content with Handlebars variables

**Basic example**

```json Elemental theme={null}
{
  "type": "text",
  "content": "Thanks for signing up!"
}
```

```javascript Node.js highlight={9-12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Thanks for signing up!",
        },
      ],
    },
  },
});
```

```python Python highlight={9-12} theme={null}
response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "text",
            "content": "Thanks for signing up!",
          },
        ],
      },
    },
)
```

```bash cURL highlight={12-15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "text",
              "content": "Thanks for signing up!"
            }
          ]
        }
      }
    }'
```

```ruby Ruby highlight={9-12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Thanks for signing up!"
        }
      ]
    }
  }
)
```

```go Go highlight={5-8} theme={null}
// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Thanks for signing up!"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
```

```java Java highlight={7-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "text",
                    "content", "Thanks for signing up!")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'text',
          'content' => 'Thanks for signing up!',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={12-15} theme={null}
// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "text",
                  "content": "Thanks for signing up!"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "Thanks for signing up!"}]}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com with a text element that greets them by name.
```

**Fields**

**content** `string`

The text content displayed in the notification. Either this field or the `elements` field must be specified. Supports Handlebars variables.

**elements** `TextContentElement[]`

An array of Text Content Elements (string, link, img). Either this field or `content` must be specified, or both. When both are present, `elements` takes precedence and `content` is ignored. See the **Text content elements** section below.

**align** `string`

Text alignment. One of `"left"`, `"center"`, or `"right"`. Defaults to `"left"`.

**text\_style** `string`

Renders the text as a heading level. One of `"text"`, `"h1"`, `"h2"`, or `"subtext"`. Defaults to `"text"`.

**color** `string`

The text color. Any valid CSS color value (e.g., `"#007bff"`, `"rgb(0, 123, 255)"`).

**bold** `boolean`

Apply bold formatting to the text.

**italic** `boolean`

Apply italic formatting to the text.

**strikethrough** `boolean`

Apply a strikethrough to the text.

**underline** `boolean`

Apply an underline to the text.

**locales** `object`

Translations of this text, keyed by locale code. An entry can hold `content` (a string), `elements` (an array of inline nodes), or both, and [text node resolution
DOC](/docs/design/elemental/locales#text-node-resolution) shows which one renders. To translate a link's `href` or an image's `src` inside the text, put translated nodes in the entry's `elements`.

**channels** `string[]`

An array of channel names. The text renders only for the listed channels. See [Control flow
DOC](/docs/design/elemental/control-flow#channels).

**Examples and variants**

**Basic text**

Simple text content:

```json theme={null}
{
  "type": "text",
  "content": "Thanks for signing up!"
}
```

**Text with Handlebars**

Dynamic text with variables:

```json theme={null}
{
  "type": "text",
  "content": "This is a notification I sent to {{first_name}}"
}
```

Variables come from `message.data` (e.g., `data.first_name`).

**Styled text**

Text with formatting:

```json theme={null}
{
  "type": "text",
  "content": "Important Notice",
  "text_style": "h2",
  "bold": true,
  "color": "#007bff",
  "align": "center"
}
```

**Localized text**

Text with translations using the `content` string format:

```json theme={null}
{
  "type": "text",
  "content": "This is a notification I sent to {{first_name}}",
  "locales": {
    "es": {
      "content": "Esta es una notificación que envié a {{first_name}}"
    },
    "fr": {
      "content": "Ceci est une notification que j'ai envoyée à {{first_name}}"
    }
  }
}
```

**Localized text with structured elements**

When your text node uses the `elements` array, provide locale translations as `elements` arrays to preserve inline formatting across languages:

```json theme={null}
{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Your order " },
    { "type": "string", "content": "#{{order.id}}", "bold": true },
    { "type": "string", "content": " has been confirmed." }
  ],
  "locales": {
    "fr": {
      "elements": [
        { "type": "string", "content": "Votre commande " },
        { "type": "string", "content": "#{{order.id}}", "bold": true },
        { "type": "string", "content": " a été confirmée." }
      ]
    }
  }
}
```

**When both `content` and `elements` are present**

If a text node includes both `content` and `elements`, only `elements` is used. Choose one format per node.

> [!NOTE]
>
> If a text node uses `elements` but a locale only provides `content`, Courier wraps that string into a single-element array for backward compatibility. Rendering still works, but any inline formatting is lost. Provide `elements` in your locale translations to keep it. See [text node resolution
> DOC](/docs/design/elemental/locales#text-node-resolution) for the full table.

**Heading styles**

Use text as headings:

```json theme={null}
{
  "type": "text",
  "content": "Welcome to Our Platform",
  "text_style": "h1"
},
{
  "type": "text",
  "content": "Get started in minutes",
  "text_style": "subtext"
}
```

**Text content elements**

The text element can contain an array of text content elements instead of, or in addition to, the `content` field. These sub-elements build inline text with links, images, and formatted strings.

> [!NOTE]
>
> Text content elements (string, link, img) must be children of a text element. They can't stand alone as top-level elements.

**String element**

Renders a simple string. Behaves like default text, but formats inline within a text element.

**Fields:**

**type** `string` *required*

Must be `"string"`.

**content** `string` *required*

The text content displayed in the notification.

**align** `string`

Text alignment. One of `"left"`, `"center"`, or `"right"`.

**text\_style** `string`

Renders the text as a heading level. One of `"text"`, `"h1"`, `"h2"`, or `"subtext"`.

**color** `string`

The text color. Any valid CSS color value.

**bold** `boolean`

Apply bold formatting to the text.

**italic** `boolean`

Apply italic formatting to the text.

**strikethrough** `boolean`

Apply a strikethrough to the text.

**underline** `boolean`

Apply an underline to the text.

**locales** `object`

Translations of `content`, keyed by locale code, for content you pass inline to a send. In a stored template, translate the [text element
DOC](/docs/design/elemental/locales#formatted-text) instead.

**Link element**

Renders a clickable link within a body of text.

**Fields:**

**type** `string` *required*

Must be `"link"`.

**content** `string` *required*

The text content of the link (the clickable text).

**href** `string`

The address to link to. When provided, the link becomes clickable.

**disable\_tracking** `boolean`

Disable click tracking for the link. By default, Courier tracks link clicks.

**align** `string`

Text alignment. One of `"left"`, `"center"`, or `"right"`.

**text\_style** `string`

Renders the text as a heading level. One of `"text"`, `"h1"`, `"h2"`, or `"subtext"`.

**color** `string`

The text color. Any valid CSS color value.

**bold** `boolean`

Apply bold formatting to the text.

**italic** `boolean`

Apply italic formatting to the text.

**strikethrough** `boolean`

Apply a strikethrough to the text.

**underline** `boolean`

Apply an underline to the text.

**locales** `object`

Translations of `content` and `href`, keyed by locale code, for content you pass inline to a send. In a stored template, translate the [text element
DOC](/docs/design/elemental/locales#formatted-text) instead.

**Img element**

Renders an image inline within a body of text.

**Fields:**

**type** `string` *required*

Must be `"img"`.

**src** `string` *required*

The source address of the image. Must be a publicly accessible URL.

**alt\_text** `string`

Text used for screen readers and displayed on mouse hover. Important for accessibility.

**width** `string`

How wide the image renders. Any valid CSS width value (e.g., `"50px"`, `"100%"`).

**href** `string`

An address to link to. Makes the image clickable.

**disable\_tracking** `boolean`

Disable click tracking for the link (if `href` is provided).

**align** `string`

Text alignment. One of `"left"`, `"center"`, or `"right"`.

**text\_style** `string`

Renders the text as a heading level. One of `"text"`, `"h1"`, `"h2"`, or `"subtext"`.

**color** `string`

The text color, for any text overlay.

**bold** `boolean`

Apply bold formatting (for any text overlay).

**italic** `boolean`

Apply italic formatting (for any text overlay).

**strikethrough** `boolean`

Apply a strikethrough (for any text overlay).

**underline** `boolean`

Apply an underline (for any text overlay).

**locales** `object`

Translations of `src` and `href`, keyed by locale code, for content you pass inline to a send. In a stored template, translate the [text element
DOC](/docs/design/elemental/locales#formatted-text) instead.

**Text with inline links**

Combine strings and links:

```json theme={null}
{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Hey! " },
    { "type": "link", "content": "Check out this site.", "href": "https://www.example.com" },
    { "type": "string", "content": " It's awesome!" }
  ]
}
```

**Text with inline images**

Include images within text:

```json theme={null}
{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Check out this emoji: " },
    { "type": "img", "src": "https://emoji.com/cool-emoji", "width": "20px", "alt_text": "Cool emoji" },
    { "type": "string", "content": " Pretty cool, right?" }
  ]
}
```

**Rich formatted text**

Mix strings, links, and formatting:

```json theme={null}
{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Welcome, ", "bold": true },
    { "type": "string", "content": "{{user_name}}", "bold": true, "color": "#007bff" },
    { "type": "string", "content": "! Visit our " },
    { "type": "link", "content": "documentation", "href": "https://docs.example.com", "bold": true },
    { "type": "string", "content": " to get started." }
  ]
}
```

**Channel support**

* **Email**: ✅ Full support with all formatting options
* **Push**: ✅ Supported (formatting may be limited)
* **SMS**: ⚠️ Limited support (plain text only)
* **Inbox**: ✅ Full support with rich formatting

### Best practices

* **Use `content` for simple text**: plain text needs nothing more
* **Use `elements` for rich formatting**: inline links, images, or mixed styling
* **Avoid specifying both**: `elements` takes precedence and `content` is ignored. Pick one format per node
* **Match locale format to root format**: if your text node uses `elements`, provide `elements` in your locales. A `content`-only locale works but loses inline formatting
* **Keep text concise**: long paragraphs are hard to read, especially in email
* **Use headings appropriately**: use `text_style` for a proper heading hierarchy


# Email template fonts
Source: https://www.courier.com/docs/design/elemental/fonts

Set an email font in Design Studio or with font_family, and see how clients load it.

Pick a font for an email template in Design Studio, or set `font_family` in Elemental.

Both write the same field, so the editor and the API always show the same font.

Your font applies to all text in the email: headings, body copy, lists, and button labels. For Google Fonts, Courier also adds the stylesheet import to the email's head, so you never host font files or add tags yourself. Fonts are an email channel setting, so SMS, push, and in-app content aren't affected.

## Set a font

### In Design Studio

Open a template's email channel in [Design Studio
DOC](/docs/design/templates/design-studio). The **Email styles** panel sits in the right sidebar, below **Background color** and **Content body color**:

1. **Font** sets the email's font. All 70 catalog fonts are listed, each with a preview.
2. **Font fallback** sets the font used when the recipient's email client doesn't support your choice. The list holds the 10 [web-safe fonts](#web-safe-fonts), which render everywhere. Arial, Verdana, and Georgia are the safest picks.

The editor renders your content in the selected font as you work. The font saves with the template, so it appears in version history.

### In Elemental

Add a `font_family` field to your `type: "channel"`, `channel: "email"` element. It belongs on the channel element, not on the top-level content object.

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "font_family": "Roboto, Arial, sans-serif",
      "elements": [
        {
          "type": "meta",
          "title": "Welcome to Courier"
        },
        {
          "type": "text",
          "content": "Thanks for signing up, {{name}}!"
        }
      ]
    }
  ]
}
```

The value is a CSS font stack: your chosen font first, then the fallback. Use the exact `fontFamily` string from the [font catalog](#font-catalog) below. Courier matches on the first font in the stack, so `'Roboto', sans-serif` still resolves, but the canonical value is safest.

## How font loading works

* **Web-safe fonts** are already on the recipient's device. Nothing loads, and they render the same in every email client.
* **Google Fonts** load through an `@import` rule that Courier injects into the email's head at send time. The recipient's email client fetches the stylesheet if it supports that rule. See [Email Client Support](#email-client-support) for which ones do.
* **No font set** falls back to `Helvetica, Arial, sans-serif`. If your [brand
  DOC](/docs/design/brands) uses a custom MJML template that defines its own font, leaving `font_family` unset keeps the brand's font.

## Font catalog

Courier supports 70 fonts: 10 web-safe fonts and 60 Google Fonts. Use the `fontFamily` value as-is for the `font_family` property in your Elemental content.

### Web-safe fonts

These fonts ship with most operating systems, so nothing loads externally and every email client renders them the same. They are also the options in the **Font fallback** picker in Design Studio. See [Web Fonts vs Email-Safe Fonts
DOC](/docs/design/templates/html-email) for email client compatibility.

| Name | `fontFamily` value |
| - | - |
| Arial | `Arial, sans-serif` |
| Courier New | `'Courier New', Courier, monospace` |
| Georgia | `Georgia, serif` |
| Helvetica | `Helvetica, Arial, sans-serif` |
| Impact | `Impact, Charcoal, sans-serif` |
| Palatino | `Palatino Linotype, Book Antiqua, Palatino, serif` |
| Tahoma | `Tahoma, Geneva, sans-serif` |
| Times New Roman | `'Times New Roman', Times, serif` |
| Trebuchet MS | `'Trebuchet MS', Helvetica, sans-serif` |
| Verdana | `Verdana, Geneva, sans-serif` |

### Google Fonts

Courier adds the stylesheet import automatically. Every stack ends in a web-safe fallback, so clients without web font support render the next font in the stack.

> **Sans-serif (34 fonts)**
>
> | Name | `fontFamily` value |
> | - | - |
> | Archivo | `Archivo, Arial, sans-serif` |
> | Atkinson Hyperlegible | `'Atkinson Hyperlegible', Arial, sans-serif` |
> | Barlow | `Barlow, Arial, sans-serif` |
> | Bricolage Grotesque | `'Bricolage Grotesque', Arial, sans-serif` |
> | Cabin | `Cabin, Arial, sans-serif` |
> | DM Sans | `'DM Sans', Arial, sans-serif` |
> | Exo 2 | `'Exo 2', Arial, sans-serif` |
> | Figtree | `Figtree, Arial, sans-serif` |
> | IBM Plex Sans | `'IBM Plex Sans', Arial, sans-serif` |
> | Inter | `Inter, Arial, sans-serif` |
> | Josefin Sans | `'Josefin Sans', Arial, sans-serif` |
> | Karla | `Karla, Arial, sans-serif` |
> | Lato | `Lato, Arial, sans-serif` |
> | Lexend | `Lexend, Arial, sans-serif` |
> | Manrope | `Manrope, Arial, sans-serif` |
> | Montserrat | `Montserrat, Arial, sans-serif` |
> | Nunito Sans | `'Nunito Sans', Arial, sans-serif` |
> | Open Sans | `'Open Sans', Arial, sans-serif` |
> | Oswald | `Oswald, Arial, sans-serif` |
> | Overpass | `Overpass, Arial, sans-serif` |
> | Poppins | `Poppins, Arial, sans-serif` |
> | PT Sans | `'PT Sans', Arial, sans-serif` |
> | Quicksand | `Quicksand, Arial, sans-serif` |
> | Raleway | `Raleway, Arial, sans-serif` |
> | Red Hat Display | `'Red Hat Display', Arial, sans-serif` |
> | Roboto | `Roboto, Arial, sans-serif` |
> | Roboto Condensed | `'Roboto Condensed', Arial, sans-serif` |
> | Rubik | `Rubik, Arial, sans-serif` |
> | Sora | `Sora, Arial, sans-serif` |
> | Source Sans 3 | `'Source Sans 3', Arial, sans-serif` |
> | Space Grotesk | `'Space Grotesk', Arial, sans-serif` |
> | Syne | `Syne, Arial, sans-serif` |
> | Ubuntu | `Ubuntu, Arial, sans-serif` |
> | Work Sans | `'Work Sans', Arial, sans-serif` |

> **Serif (13 fonts)**
>
> | Name | `fontFamily` value |
> | - | - |
> | Arvo | `Arvo, Georgia, serif` |
> | Cormorant | `Cormorant, Georgia, serif` |
> | Crimson Pro | `'Crimson Pro', Georgia, serif` |
> | DM Serif Display | `'DM Serif Display', Georgia, serif` |
> | Fraunces | `Fraunces, Georgia, serif` |
> | Libre Baskerville | `'Libre Baskerville', Georgia, serif` |
> | Literata | `Literata, Georgia, serif` |
> | Lora | `Lora, Georgia, serif` |
> | Merriweather | `Merriweather, Georgia, serif` |
> | Playfair Display | `'Playfair Display', Georgia, serif` |
> | Roboto Slab | `'Roboto Slab', Georgia, serif` |
> | Vollkorn | `Vollkorn, Georgia, serif` |
> | Zilla Slab | `'Zilla Slab', Georgia, serif` |

> **Display (5 fonts)**
>
> | Name | `fontFamily` value |
> | - | - |
> | Abril Fatface | `'Abril Fatface', Georgia, serif` |
> | Bebas Neue | `'Bebas Neue', Arial, sans-serif` |
> | Comfortaa | `Comfortaa, Arial, sans-serif` |
> | Pacifico | `Pacifico, Arial, sans-serif` |
> | Righteous | `Righteous, Arial, sans-serif` |

> **Monospace (5 fonts)**
>
> | Name | `fontFamily` value |
> | - | - |
> | Fira Mono | `'Fira Mono', 'Courier New', monospace` |
> | IBM Plex Mono | `'IBM Plex Mono', 'Courier New', monospace` |
> | Inconsolata | `Inconsolata, 'Courier New', monospace` |
> | Roboto Mono | `'Roboto Mono', 'Courier New', monospace` |
> | Space Mono | `'Space Mono', 'Courier New', monospace` |

> **Handwriting (3 fonts)**
>
> | Name | `fontFamily` value |
> | - | - |
> | Caveat | `Caveat, Arial, sans-serif` |
> | Dancing Script | `'Dancing Script', Arial, sans-serif` |
> | Sacramento | `Sacramento, Georgia, serif` |

## Email client support

Each email client decides whether to honor the `@import` rule that loads a Google Font. Clients that don't support it strip the import and use your fallback font instead. The table covers Google Fonts only, since web-safe fonts need no loading.

| Email Client | Google Fonts |
| - | - |
| Apple Mail (macOS) | Supported |
| Apple Mail (iOS) | Supported |
| HEY webmail | Supported |
| Gmail (web, Android, iOS) | Not supported |
| Outlook for Windows | Not supported |
| Outlook for Mac (16.80 and later) | Not supported |
| Outlook.com and Outlook mobile | Not supported |
| Thunderbird (78.5 and later) | Not supported |
| Yahoo Mail | Not supported |
| AOL Mail | Not supported |

With `font_family: "Roboto, Arial, sans-serif"`, Apple Mail renders Roboto and Gmail renders Arial. Support data is from [Can I Email](https://www.caniemail.com/features/css-at-import/), checked July 2026.

> [!NOTE]
>
> Outlook for Windows is the exception: it reads the `@import` rule but ignores remotely hosted fonts, so text can drop to Times New Roman instead of the next font in your stack. Pick a web-safe font for a template most of your recipients open there.

> [!TIP]
>
> Always end a font stack with a web-safe font. Every catalog value already does, and the **Font fallback** picker handles it in Design Studio. This only matters when you write a stack by hand.

## FAQ

> **Can I use a font that isn't in the catalog, like our brand font?**
>
> You can pass any CSS font stack through `font_family`, and Courier applies it as the email's `font-family`. Only the 70 catalog fonts get a stylesheet import, so an off-catalog font renders only for recipients who already have it installed. You can't upload or self-host a font file. For a font you need loaded, choose one from the catalog.

> **Can I use different fonts for different parts of the email?**
>
> The font is set once per email channel and applies to all text in that email, including button labels. To mix typefaces, vary weight and size on individual blocks.

> **Why does my email render in the fallback font instead of the font I chose?**
>
> The recipient opened it in a client without web font support, most likely Gmail or Outlook for Windows. That's intended: the client uses the next font in the stack. Open the same email in Apple Mail to confirm your font applies. In Outlook for Windows, text can land on Times New Roman rather than your fallback.

> **[Elemental Overview](/docs/design/elemental/overview)**
>
> Build email content with Elemental markup

> **[Channel Element](/docs/design/elemental/elements/channel)**
>
> The channel element and its fields

> **[CSS Classnames](/docs/design/brands#css-class-names)**
>
> Custom CSS for email template blocks

> **[Email Safe Formatting](/docs/design/templates/html-email)**
>
> HTML and CSS for cross-client rendering


# Template translations
Source: https://www.courier.com/docs/design/elemental/locales

Localize a template by syncing translations from your translation tool over the API, or with AI in Design Studio. Each recipient gets their language.

A template holds your content once, in your default language, and carries a translation of each piece of it for every language you support. Courier sends each recipient the version in their language.

## How it works

1. **You write the template in your default language.** Each element (the subject line, a paragraph, a button) gets an `id`.
2. **You add translations, one locale at a time.** Each element stores its translations in a `locales` map, keyed by a locale code such as `es` or `fr`. Get them from your translators or a translation tool such as Lokalise, Crowdin, or Phrase and [write them back through the API](#translate-a-template-with-the-api), or generate them with [AI Translation in Design Studio](#translate-in-design-studio).
3. **Courier picks the translation at send time.** It reads the recipient's locale and swaps in the matching text, element by element. An element with no translation for that locale sends in the default language.

Here's one element with Spanish and French translations:

```json theme={null}
{
  "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p",
  "type": "text",
  "content": "Order {{order_number}} is confirmed.",
  "locales": {
    "es": { "content": "El pedido {{order_number}} está confirmado." },
    "fr": { "content": "La commande {{order_number}} est confirmée." }
  }
}
```

Each locale stores only the fields it translates, usually the text, so a layout change carries into every language. The same `locales` map also works on content you pass inline to a send in `message.content`.

Short strings you reuse across many templates, like a common button label, can instead live in your [workspace translation strings](#workspace-translation-strings), one `.po` file per locale, rendered with `{{t}}`.

## How Courier picks a locale

Courier takes the recipient's locale from `message.to.locale` on the send, or from the `locale` stored on their [profile
DOC](/docs/recipients/overview) when the send doesn't set one. With neither, the default content sends.

Locale codes match exactly, including case. A template translated as `es` serves recipients whose locale is `es`, and a recipient set to `es-MX` or `ES` gets the default content. Design Studio names locales in lowercase, such as `es` or `es-mx`, so store the same form on your profiles.

Sends use the published template, so translations reach recipients once you publish.

## Translate a template with the API

Translating a template through the API takes six steps. The translating itself happens outside Courier, in whatever tool or process you use, and every other step is one call:

| Step | Call | Result |
| - | - | - |
| [1. Create the template](#1-create-the-template) | [Create Notification Template](/docs/api-reference/templates/create-notification-template) | A draft template, with an `id` on every element |
| [2. Export the strings](#2-export-the-strings) | [Get Notification Content](/docs/api-reference/templates/get-notification-content) | Each element's `id`, default text, and `checksum` |
| [3. Translate the strings](#3-translate-the-strings) | None, in your own tool | A translation per element `id`, per locale |
| [4. Write a locale back](#4-write-a-locale-back) | [Replace Notification Locale](/docs/api-reference/templates/replace-notification-locale) | One locale's translations stored on the draft |
| [5. Publish](#5-publish) | [Publish Notification Template](/docs/api-reference/templates/publish-notification-template) | The translations go live |
| [6. Send it](#6-send-it) | [Send a message](/docs/api-reference/send/send-a-message) | Each recipient gets their locale |

For a template that already exists, start at step 2. When the default text changes later, export again and translate only the strings whose checksum changed.

### 1. Create the template

[Create Notification Template](/docs/api-reference/templates/create-notification-template) takes your default content and returns the template ID as `id` (`nt_01kx4h2jdafq8bk9aftxak4b40` in the later steps). Courier also gives every element an `id`, which is how translations find their element. You can set your own instead, such as `"id": "subject"`, as long as each one is unique in the template. Elements also accept a `locales` map here if you already have translations.

The `brand`, `subscription`, and `routing` IDs below are placeholders. Set `brand` and `subscription` to `null` if you don't use them, and set `routing.strategy_id` to one of your [routing strategies
DOC](/docs/send/routing-strategies). Content created without a `scope` field, like this example, reads the send's `data` at the root, so the body uses `{{order_number}}` rather than `{{data.order_number}}`.

```javascript Node.js highlight={8,16-17} theme={null}
const notificationTemplateResponse = await client.notifications.create({
  notification: {
    name: 'Order Confirmation',
    tags: ['orders'],
    brand: { id: 'bnd_01kx4mrd0pfzw8wt7pn7p2fzag' },
    subscription: { topic_id: 'pt_01kx4h2jdafq8bk9a26x0kvd1t' },
    routing: { strategy_id: 'rs_01kx4h2jdafq8bk9amzvy6hbv0' },
    content: {
      version: '2022-01-01',
      elements: [
        {
          type: 'channel',
          channel: 'email',
          elements: [
            { type: 'meta', title: 'Order confirmed' },
            { type: 'text', content: 'Order {{order_number}} is confirmed.' },
            { type: 'action', content: 'View order', href: 'https://app.acme-corp.com/orders' },
          ],
        },
      ],
    },
  },
  state: 'DRAFT',
});
```

```python Python highlight={8,16-17} theme={null}
notification_template_response = client.notifications.create(
    notification={
        "name": "Order Confirmation",
        "tags": ["orders"],
        "brand": {"id": "bnd_01kx4mrd0pfzw8wt7pn7p2fzag"},
        "subscription": {"topic_id": "pt_01kx4h2jdafq8bk9a26x0kvd1t"},
        "routing": {"strategy_id": "rs_01kx4h2jdafq8bk9amzvy6hbv0"},
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "channel",
                    "channel": "email",
                    "elements": [
                        {"type": "meta", "title": "Order confirmed"},
                        {"type": "text", "content": "Order {{order_number}} is confirmed."},
                        {"type": "action", "content": "View order", "href": "https://app.acme-corp.com/orders"},
                    ],
                }
            ],
        },
    },
    state="DRAFT",
)
```

```bash cURL highlight={12,20-21} theme={null}
curl --request POST \
  --url https://api.courier.com/notifications \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "notification": {
      "name": "Order Confirmation",
      "tags": ["orders"],
      "brand": { "id": "bnd_01kx4mrd0pfzw8wt7pn7p2fzag" },
      "subscription": { "topic_id": "pt_01kx4h2jdafq8bk9a26x0kvd1t" },
      "routing": { "strategy_id": "rs_01kx4h2jdafq8bk9amzvy6hbv0" },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "channel",
            "channel": "email",
            "elements": [
              { "type": "meta", "title": "Order confirmed" },
              { "type": "text", "content": "Order {{order_number}} is confirmed." },
              { "type": "action", "content": "View order", "href": "https://app.acme-corp.com/orders" }
            ]
          }
        ]
      }
    },
    "state": "DRAFT"
  }'
```

```ruby Ruby highlight={8,16-17} theme={null}
notification_template_response = courier.notifications.create(
  notification: {
    name: "Order Confirmation",
    tags: ["orders"],
    brand: {id: "bnd_01kx4mrd0pfzw8wt7pn7p2fzag"},
    subscription: {topic_id: "pt_01kx4h2jdafq8bk9a26x0kvd1t"},
    routing: {strategy_id: "rs_01kx4h2jdafq8bk9amzvy6hbv0"},
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "channel",
          channel: "email",
          elements: [
            {type: "meta", title: "Order confirmed"},
            {type: "text", content: "Order {{order_number}} is confirmed."},
            {type: "action", content: "View order", href: "https://app.acme-corp.com/orders"}
          ]
        }
      ]
    }
  },
  state: "DRAFT"
)
```

```go Go highlight={1,9-10,23} theme={null}
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [
        { "type": "meta", "title": "Order confirmed" },
        { "type": "text", "content": "Order {{order_number}} is confirmed." },
        { "type": "action", "content": "View order", "href": "https://app.acme-corp.com/orders" }
      ]
    }
  ]
}`))

notificationTemplateResponse, err := client.Notifications.New(context.TODO(), courier.NotificationNewParams{
	NotificationTemplateCreateRequest: courier.NotificationTemplateCreateRequestParam{
		Notification: courier.NotificationTemplateWritePayloadParam{
			NotificationTemplatePayloadParam: courier.NotificationTemplatePayloadParam{
				Brand: courier.NotificationTemplatePayloadBrandParam{
					ID: "bnd_01kx4mrd0pfzw8wt7pn7p2fzag",
				},
				Content: content,
				Name:    "Order Confirmation",
				Routing: courier.NotificationTemplatePayloadRoutingParam{
					StrategyID: "rs_01kx4h2jdafq8bk9amzvy6hbv0",
				},
				Subscription: courier.NotificationTemplatePayloadSubscriptionParam{
					TopicID: "pt_01kx4h2jdafq8bk9a26x0kvd1t",
				},
				Tags: []string{"orders"},
			},
		},
	},
})
```

```java Java highlight={6,12-13} theme={null}
NotificationTemplateCreateRequest params = NotificationTemplateCreateRequest.builder()
    .notification(NotificationTemplateWritePayload.builder()
        .brand(NotificationTemplatePayload.Brand.builder()
            .id("bnd_01kx4mrd0pfzw8wt7pn7p2fzag")
            .build())
        .content(ElementalContent.builder()
            .addElement(ElementalChannelNodeWithType.builder()
                .type(ElementalChannelNodeWithType.Type.CHANNEL)
                .channel("email")
                .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                    java.util.Map.of("type", "meta", "title", "Order confirmed"),
                    java.util.Map.of("type", "text", "content", "Order {{order_number}} is confirmed."),
                    java.util.Map.of("type", "action", "content", "View order", "href", "https://app.acme-corp.com/orders"))))
                .build())
            .version("2022-01-01")
            .build())
        .name("Order Confirmation")
        .routing(NotificationTemplatePayload.Routing.builder()
            .strategyId("rs_01kx4h2jdafq8bk9amzvy6hbv0")
            .build())
        .subscription(NotificationTemplatePayload.Subscription.builder()
            .topicId("pt_01kx4h2jdafq8bk9a26x0kvd1t")
            .build())
        .addTag("orders")
        .build())
    .build();
NotificationTemplateResponse notificationTemplateResponse = client.notifications().create(params);
```

```php PHP highlight={8,16-17} theme={null}
$notificationTemplateResponse = $client->notifications->create(
  notification: [
    'name' => 'Order Confirmation',
    'tags' => ['orders'],
    'brand' => ['id' => 'bnd_01kx4mrd0pfzw8wt7pn7p2fzag'],
    'subscription' => ['topicID' => 'pt_01kx4h2jdafq8bk9a26x0kvd1t'],
    'routing' => ['strategyID' => 'rs_01kx4h2jdafq8bk9amzvy6hbv0'],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'channel',
          'channel' => 'email',
          'elements' => [
            ['type' => 'meta', 'title' => 'Order confirmed'],
            ['type' => 'text', 'content' => 'Order {{order_number}} is confirmed.'],
            ['type' => 'action', 'content' => 'View order', 'href' => 'https://app.acme-corp.com/orders'],
          ],
        ],
      ],
    ],
  ],
  state: 'DRAFT',
);
```

```csharp C# highlight={17-18} theme={null}
NotificationCreateParams parameters = new()
{
    Notification = new()
    {
        Brand = new("bnd_01kx4mrd0pfzw8wt7pn7p2fzag"),
        Content = new()
        {
            Elements =
            [
                ElementalChannelNodeWithType.FromRawUnchecked(
                    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                    {
                      "type": "channel",
                      "channel": "email",
                      "elements": [
                        { "type": "meta", "title": "Order confirmed" },
                        { "type": "text", "content": "Order {{order_number}} is confirmed." },
                        { "type": "action", "content": "View order", "href": "https://app.acme-corp.com/orders" }
                      ]
                    }
                    """)),
            ],
            Version = "2022-01-01",
        },
        Name = "Order Confirmation",
        Routing = new("rs_01kx4h2jdafq8bk9amzvy6hbv0"),
        Subscription = new("pt_01kx4h2jdafq8bk9a26x0kvd1t"),
        Tags = ["orders"],
    },
};

var notificationTemplateResponse = await client.Notifications.Create(parameters);
```

```bash CLI highlight={3} theme={null}
courier notifications create \
  --api-key "$COURIER_API_KEY" \
  --notification "{name: Order Confirmation, tags: [orders], brand: {id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag}, subscription: {topic_id: pt_01kx4h2jdafq8bk9a26x0kvd1t}, routing: {strategy_id: rs_01kx4h2jdafq8bk9amzvy6hbv0}, content: {version: '2022-01-01', elements: [{type: channel, channel: email, elements: [{type: meta, title: Order confirmed}, {type: text, content: 'Order {{order_number}} is confirmed.'}, {type: action, content: View order, href: 'https://app.acme-corp.com/orders'}]}]}}" \
  --state DRAFT
```

```text MCP theme={null}
With Courier MCP, create a draft email template called Order Confirmation with the subject "Order confirmed", the body "Order {{order_number}} is confirmed.", and a View order button linking to https://app.acme-corp.com/orders.
```

### 2. Export the strings

[Get Notification Content](/docs/api-reference/templates/get-notification-content) returns every element with its `id`, its default text, a `checksum`, and any translations already stored. Pass `version=draft` to read unpublished work. Without it you get the published version, and a template that has never been published returns `404`. Templates from the Classic Designer (Legacy) return `blocks` and `channels` instead of `elements`. This workflow is for Elemental templates.

```javascript Node.js highlight={2} theme={null}
const content = await client.notifications.retrieveContent('nt_01kx4h2jdafq8bk9aftxak4b40', {
  version: 'draft',
});
```

```python Python highlight={3} theme={null}
content = client.notifications.retrieve_content(
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
    version="draft",
)
```

```bash cURL highlight={2} theme={null}
curl --request GET \
  --url "https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40/content?version=draft" \
  --header "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
content = courier.notifications.retrieve_content("nt_01kx4h2jdafq8bk9aftxak4b40", version: "draft")
```

```go Go highlight={5} theme={null}
content, err := client.Notifications.GetContent(
	context.TODO(),
	"nt_01kx4h2jdafq8bk9aftxak4b40",
	courier.NotificationGetContentParams{
		Version: courier.String("draft"),
	},
)
```

```java Java highlight={4} theme={null}
var content = client.notifications().retrieveContent(
    NotificationRetrieveContentParams.builder()
        .id("nt_01kx4h2jdafq8bk9aftxak4b40")
        .version("draft")
        .build());
```

```php PHP highlight={3} theme={null}
$content = $client->notifications->retrieveContent(
  'nt_01kx4h2jdafq8bk9aftxak4b40',
  version: 'draft',
);
```

```csharp C# highlight={3} theme={null}
var content = await client.Notifications.RetrieveContent(
    "nt_01kx4h2jdafq8bk9aftxak4b40",
    new() { Version = "draft" }
);
```

```bash CLI highlight={4} theme={null}
courier notifications retrieve-content \
  --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40 \
  --version draft
```

```text MCP theme={null}
With Courier MCP, show me the draft content of template nt_01kx4h2jdafq8bk9aftxak4b40 with its translations.
```

The response is the template's element tree, with an `id` and a `checksum` on every element:

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "id": "elem_01kx4h2jdafq8bk9b07z4mq2wd",
      "type": "channel",
      "channel": "email",
      "checksum": "055792c3ddaec6cf26ced79a10394b15",
      "elements": [
        {
          "id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n",
          "type": "meta",
          "title": "Order confirmed",
          "checksum": "ec7fc20765b50a8b3fbacdaf6b4167db"
        },
        {
          "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p",
          "type": "text",
          "content": "Order {{order_number}} is confirmed.",
          "checksum": "5114903fee322b18acf679bab5de55c1"
        },
        {
          "id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e",
          "type": "action",
          "content": "View order",
          "href": "https://app.acme-corp.com/orders",
          "checksum": "88d1f1c314280c172aaaad3be5311caf"
        }
      ]
    }
  ]
}
```

**Checksums tell you what needs re-translating.** An element's `checksum` changes when its own content changes, and a container's changes when anything inside it does. Adding or editing translations leaves it alone, and each translation carries its own `checksum` inside `locales`. Store each string's element `id` and `checksum` when you export. On the next export, a changed checksum means new source text to translate, a new `id` is a new string, and a missing `id` needs nothing. Export with `version=draft` each time.

### 3. Translate the strings

The export is a tree, so walk into every `elements` array and skip the `locales` maps. From each element, take its text: `title` on `meta`, and `content` on `text`, `action`, `quote`, and `html`. Each channel holds its own copy of the content, so a template that sends email and inbox has two of each string. A text element built from inline nodes (bold, links) needs its translation written back as nodes, covered in [formatted text](#formatted-text).

Hand the strings, keyed by element `id`, to whoever translates them: your own translators, or a translation tool such as Lokalise, Crowdin, or Phrase. Add a note on what each string is so translators have context, and ask them to keep `{{variables}}` exactly as written.

What you send out is a list of strings:

```json theme={null}
[
  { "id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n", "field": "title", "text": "Order confirmed", "checksum": "ec7fc20765b50a8b3fbacdaf6b4167db", "note": "Email subject" },
  { "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p", "field": "content", "text": "Order {{order_number}} is confirmed.", "checksum": "5114903fee322b18acf679bab5de55c1", "note": "Email body" },
  { "id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e", "field": "content", "text": "View order", "checksum": "88d1f1c314280c172aaaad3be5311caf", "note": "Button label" }
]
```

What comes back is the same list with the translation for each locale:

```json theme={null}
[
  { "id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n", "field": "title", "es": "Pedido confirmado" },
  { "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p", "field": "content", "es": "El pedido {{order_number}} está confirmado." },
  { "id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e", "field": "content", "es": "Ver pedido" }
]
```

The file format is up to you and your tool. Courier only needs each translation matched to its element `id` and field in the next step.

### 4. Write a locale back

[Replace Notification Locale](/docs/api-reference/templates/replace-notification-locale) sets one locale's translations. Turn what came back into one request per locale: each entry names an element by `id` and carries its translated fields. Add any localized links yourself, like the Spanish `href` for the button below. The fields an element accepts depend on its type (see [which fields a locale can override](#which-fields-a-locale-can-override)).

```javascript Node.js highlight={4-6} theme={null}
await client.notifications.putLocale('es', {
  id: 'nt_01kx4h2jdafq8bk9aftxak4b40',
  elements: [
    { id: 'elem_01kx4h2jdafq8bk9b0a8x3rt5n', title: 'Pedido confirmado' },
    { id: 'elem_01kx4h2jdafq8bk9b0d2c6yv9p', content: 'El pedido {{order_number}} está confirmado.' },
    { id: 'elem_01kx4h2jdafq8bk9b0g5k7hs1e', content: 'Ver pedido', href: 'https://app.acme-corp.com/es/orders' },
  ],
});
```

```python Python highlight={5-7} theme={null}
client.notifications.put_locale(
    locale_id="es",
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
    elements=[
        {"id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n", "title": "Pedido confirmado"},
        {"id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p", "content": "El pedido {{order_number}} está confirmado."},
        {"id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e", "content": "Ver pedido", "href": "https://app.acme-corp.com/es/orders"},
    ],
)
```

```bash cURL highlight={7-9} theme={null}
curl --request PUT \
  --url https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40/locales/es \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "elements": [
      { "id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n", "title": "Pedido confirmado" },
      { "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p", "content": "El pedido {{order_number}} está confirmado." },
      { "id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e", "content": "Ver pedido", "href": "https://app.acme-corp.com/es/orders" }
    ]
  }'
```

```ruby Ruby highlight={5-7} theme={null}
courier.notifications.put_locale(
  "es",
  id: "nt_01kx4h2jdafq8bk9aftxak4b40",
  elements: [
    {id: "elem_01kx4h2jdafq8bk9b0a8x3rt5n", title: "Pedido confirmado"},
    {id: "elem_01kx4h2jdafq8bk9b0d2c6yv9p", content: "El pedido {{order_number}} está confirmado."},
    {id: "elem_01kx4h2jdafq8bk9b0g5k7hs1e", content: "Ver pedido", href: "https://app.acme-corp.com/es/orders"}
  ]
)
```

```go Go highlight={9-11} theme={null}
_, err := client.Notifications.PutLocale(
	context.TODO(),
	"es",
	courier.NotificationPutLocaleParams{
		ID: "nt_01kx4h2jdafq8bk9aftxak4b40",
		NotificationLocalePutRequest: courier.NotificationLocalePutRequestParam{
			// Translated fields vary by element type, so they go in ExtraFields.
			Elements: []courier.NotificationLocalePutRequestElementParam{
				{ID: "elem_01kx4h2jdafq8bk9b0a8x3rt5n", ExtraFields: map[string]any{"title": "Pedido confirmado"}},
				{ID: "elem_01kx4h2jdafq8bk9b0d2c6yv9p", ExtraFields: map[string]any{"content": "El pedido {{order_number}} está confirmado."}},
				{ID: "elem_01kx4h2jdafq8bk9b0g5k7hs1e", ExtraFields: map[string]any{"content": "Ver pedido", "href": "https://app.acme-corp.com/es/orders"}},
			},
		},
	},
)
```

```java Java highlight={7,11,15} theme={null}
// Translated fields vary by element type, so they go in as additional properties.
NotificationPutLocaleParams params = NotificationPutLocaleParams.builder()
    .id("nt_01kx4h2jdafq8bk9aftxak4b40")
    .localeId("es")
    .notificationLocalePutRequest(NotificationLocalePutRequest.builder()
        .addElement(NotificationLocalePutRequest.Element.builder()
            .id("elem_01kx4h2jdafq8bk9b0a8x3rt5n")
            .putAdditionalProperty("title", JsonValue.from("Pedido confirmado"))
            .build())
        .addElement(NotificationLocalePutRequest.Element.builder()
            .id("elem_01kx4h2jdafq8bk9b0d2c6yv9p")
            .putAdditionalProperty("content", JsonValue.from("El pedido {{order_number}} está confirmado."))
            .build())
        .addElement(NotificationLocalePutRequest.Element.builder()
            .id("elem_01kx4h2jdafq8bk9b0g5k7hs1e")
            .putAdditionalProperty("content", JsonValue.from("Ver pedido"))
            .putAdditionalProperty("href", JsonValue.from("https://app.acme-corp.com/es/orders"))
            .build())
        .build())
    .build();
client.notifications().putLocale(params);
```

```php PHP highlight={5-7} theme={null}
$client->notifications->putLocale(
  'es',
  id: 'nt_01kx4h2jdafq8bk9aftxak4b40',
  elements: [
    ['id' => 'elem_01kx4h2jdafq8bk9b0a8x3rt5n', 'title' => 'Pedido confirmado'],
    ['id' => 'elem_01kx4h2jdafq8bk9b0d2c6yv9p', 'content' => 'El pedido {{order_number}} está confirmado.'],
    ['id' => 'elem_01kx4h2jdafq8bk9b0g5k7hs1e', 'content' => 'Ver pedido', 'href' => 'https://app.acme-corp.com/es/orders'],
  ],
);
```

```csharp C# highlight={12-14} theme={null}
// Translated fields vary by element type, so each entry is built from raw JSON.
static Element Entry(string json) =>
    Element.FromRawUnchecked(JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(json)!);

await client.Notifications.PutLocale(
    "es",
    new()
    {
        ID = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Elements =
        [
            Entry("""{ "id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n", "title": "Pedido confirmado" }"""),
            Entry("""{ "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p", "content": "El pedido {{order_number}} está confirmado." }"""),
            Entry("""{ "id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e", "content": "Ver pedido", "href": "https://app.acme-corp.com/es/orders" }"""),
        ],
    }
);
```

```bash CLI highlight={5-7} theme={null}
courier notifications put-locale \
  --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40 \
  --locale-id es \
  --element "{id: elem_01kx4h2jdafq8bk9b0a8x3rt5n, title: Pedido confirmado}" \
  --element "{id: elem_01kx4h2jdafq8bk9b0d2c6yv9p, content: 'El pedido {{order_number}} está confirmado.'}" \
  --element "{id: elem_01kx4h2jdafq8bk9b0g5k7hs1e, content: Ver pedido, href: 'https://app.acme-corp.com/es/orders'}"
```

```text MCP theme={null}
With Courier MCP, add a Spanish (es) translation to template nt_01kx4h2jdafq8bk9aftxak4b40: subject "Pedido confirmado", body "El pedido {{order_number}} está confirmado.", and a "Ver pedido" button linking to https://app.acme-corp.com/es/orders.
```

The write merges into what's there. It touches only the locale in the path and only the elements you list, so your default content and every other language stay as they are. Within an element, each field you send replaces that field's translation and the fields you leave out keep theirs. That means you can send a translation tool's changes for a handful of strings without re-sending the rest. Leave untranslated strings out, and they send in the default language.

Every `id` must exist in the template. An unknown `id` returns a `400` that lists each one, and nothing is written.

### 5. Publish

Writes land on the draft by default. Publish with [Publish Notification Template](/docs/api-reference/templates/publish-notification-template) once the translations are in, or pass `"state": "PUBLISHED"` on the locale write to publish in the same call. Publishing releases everything on the draft, including edits other than yours.

```javascript Node.js theme={null}
await client.notifications.publish('nt_01kx4h2jdafq8bk9aftxak4b40');
```

```python Python theme={null}
client.notifications.publish(
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
)
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40/publish \
  --header "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
courier.notifications.publish("nt_01kx4h2jdafq8bk9aftxak4b40")
```

```go Go theme={null}
err := client.Notifications.Publish(
	context.TODO(),
	"nt_01kx4h2jdafq8bk9aftxak4b40",
	courier.NotificationPublishParams{},
)
```

```java Java theme={null}
client.notifications().publish("nt_01kx4h2jdafq8bk9aftxak4b40");
```

```php PHP theme={null}
$client->notifications->publish('nt_01kx4h2jdafq8bk9aftxak4b40');
```

```csharp C# theme={null}
NotificationPublishParams parameters = new() { ID = "nt_01kx4h2jdafq8bk9aftxak4b40" };

await client.Notifications.Publish(parameters);
```

```bash CLI theme={null}
courier notifications publish \
  --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, publish template nt_01kx4h2jdafq8bk9aftxak4b40.
```

### 6. Send it

Send the template as usual. Set `locale` on the recipient, or store it on their profile so every send picks it up.

```javascript Node.js highlight={3} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123', locale: 'es' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { order_number: '1042' },
  },
});
```

```python Python highlight={3} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123", "locale": "es"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"order_number": "1042"},
    }
)
```

```bash cURL highlight={7} theme={null}
curl --request POST \
  --url https://api.courier.com/send \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "message": {
      "to": { "user_id": "user_123", "locale": "es" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "order_number": "1042" }
    }
  }'
```

```ruby Ruby highlight={3} theme={null}
response = courier.send_.message(
  message: {
    to: {user_id: "user_123", locale: "es"},
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {order_number: "1042"}
  }
)
```

```go Go highlight={6} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
				Locale: courier.String("es"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data:     map[string]any{"order_number": "1042"},
	},
})
```

```java Java highlight={5} theme={null}
SendMessageResponse response = client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder()
            .userId("user_123")
            .locale("es")
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(SendMessageParams.Message.Data.builder()
            .putAdditionalProperty("order_number", JsonValue.from("1042"))
            .build())
        .build())
    .build());
```

```php PHP highlight={3} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123', 'locale' => 'es'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['order_number' => '1042'],
  ],
);
```

```csharp C# highlight={5} theme={null}
var response = await client.Send.Message(new SendMessageParams
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123", Locale = "es" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "order_number", JsonSerializer.SerializeToElement("1042") },
        },
    },
});
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123", "locale": "es"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"order_number": "1042"}'
```

```text MCP theme={null}
With Courier MCP, set the locale on user_123's profile to es, then send template nt_01kx4h2jdafq8bk9aftxak4b40 to user_123 with order number 1042.
```

`user_123` gets "Pedido confirmado" with the Spanish body and button. Check the rendered message in [message logs
DOC](/docs/monitor/overview) or with [Get message content](/docs/api-reference/messages/get-message-content).

## Translate in Design Studio

[Design Studio
DOC](/docs/design/templates/design-studio) translates a template for you. Open the template, select the globe icon, and add a language. With **Translate with AI** checked, which is the default, Courier translates every string, including subject lines, headings, body copy, and button text.

Review the result in a two-column view, with the default on the left and the translation on the right, and edit any string. When you change the default content, Courier marks translations that may be out of date, and you can re-translate them one at a time or all together. Publish the template to send the translations.

AI Translation runs on AI credits, which you can buy on the **Business** or **Enterprise** plan. Each translation request costs **2.5 credits** plus token overages, from the same balance as [AI journey nodes
DOC](/docs/journeys/nodes/ai#billing). A long template can take more than one request per locale.

Translations made in Design Studio and through the API are the same `locales` data, so you can use both on one template.

## Other ways to write translations

* **Replace all content.** [Replace Notification Content](/docs/api-reference/templates/replace-notification-content) writes the whole element tree, translations included. Read the draft with `version=draft`, remove every `checksum` (on elements and inside `locales`), and keep each element's `id` and `locales`. Templates translated in Design Studio also carry keys starting with an underscore, such as `_sourceHash`, inside `locales`. Remove those too, because the write rejects them. An element sent without an `id` gets a new one, and content sent without `locales` has no translations.
* **Replace one element.** [Replace Notification Element](/docs/api-reference/templates/replace-notification-element) replaces a single element, so include its `locales` in the body to keep them. For translation work, the locale endpoint above is the better fit.
* **Remove a locale.** The locale endpoint adds and updates. To remove a language, read the draft, delete that code from each element's `locales`, and write the content back with [Replace Notification Content](/docs/api-reference/templates/replace-notification-content) as above.
* **Journey templates.** A template that belongs to a journey has the same calls under the journey, with the same bodies: [Fetch the content of a Journey-scoped Notification Template](/docs/api-reference/journeys/fetch-the-content-of-a-journey-scoped-notification-template) to export, [Replace a locale of a Journey-scoped Notification Template](/docs/api-reference/journeys/replace-a-locale-of-a-journey-scoped-notification-template) to write a locale, and [Publish a Journey-scoped Notification Template](/docs/api-reference/journeys/publish-a-journey-scoped-notification-template) to publish.

## Which fields a locale can override

The fields a locale entry accepts depend on the element type:

| Field | Element types | Use it for |
| - | - | - |
| `content` | `text`, `action`, `quote`, `html` | Body copy and button labels |
| `title` | `meta` | Email subject lines and push titles |
| `href` | `action`, `image` | Language-specific links |
| `src` | `image` | Images with text baked in |
| `raw` | `channel` | Provider-native overrides, such as a translated `subject` or a whole translated `html` body |
| `elements` | `text` (inline nodes); `list-item` (inline nodes or a nested list); `channel`, `group`, `column` (full nodes); `columns` (column nodes); `list` (list-item nodes) | Nested content, such as formatted text |

`divider`, `jsonnet`, `partial`, and `comment` elements take no locale entry. A field the element type doesn't accept returns a `400` naming it.

Sending `elements` or `raw` in a locale replaces that field's whole value for the element, so include everything each time.

### Formatted text

A text element can hold its copy as a `content` string or as an `elements` array of inline nodes (string, link, img). Give a formatted element its translations as `elements` too, so bold, italic, and links carry into every language:

```json theme={null}
{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Your order " },
    { "type": "string", "content": "#{{order_number}}", "bold": true },
    { "type": "string", "content": " is " },
    { "type": "string", "content": "confirmed", "bold": true },
    { "type": "string", "content": "." }
  ],
  "locales": {
    "fr": {
      "elements": [
        { "type": "string", "content": "Votre commande " },
        { "type": "string", "content": "#{{order_number}}", "bold": true },
        { "type": "string", "content": " est " },
        { "type": "string", "content": "confirmée", "bold": true },
        { "type": "string", "content": "." }
      ]
    },
    "es": {
      "content": "Tu pedido #{{order_number}} está confirmado."
    }
  }
}
```

### Text node resolution

A locale can use either format. Courier uses the locale field that matches the element's own format, and falls back to the other:

| Element has | Locale provides | Renders |
| - | - | - |
| `elements` | `elements`, with or without `content` | The locale's array |
| `elements` | `content` only | The locale's string as a single plain node, without the original formatting |
| `content` only | `content`, with or without `elements` | The locale's string |
| `content` only | `elements` only | The locale's array |

## Workspace translation strings

Workspace translations hold short strings reused across templates, like button labels and common phrases. They're keyed by locale and rendered with the `{{t}}` Handlebars helper. Manage them with [Update Translations by locale](/docs/api-reference/translations/update-translations-by-locale) and reference a string with `{{t "welcome_headline"}}`. Use this for a shared glossary, and per-locale template content for the body of a notification.

* **The payload is a `.po` file**, the gettext format most translation tools already export. Send the file as the raw request body with `Content-Type: text/plain`.
* **`domain` is always `default`.** Any other value returns a `400`.
* **Read them back with [Get a Translation](/docs/api-reference/translations/get-a-translation)**, which returns the stored `.po` content, to compare what's live with what your translation system holds.

Upload a locale's file like this:

```bash theme={null}
curl --request PUT \
  --url https://api.courier.com/translations/default/es \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: text/plain" \
  --data-binary @es.po
```

**`{{t}}` renders from the recipient's locale.** A send renders a `{{t}}` string only when the recipient has a locale with an uploaded `.po` file. With no locale, or a locale that has no file, the message fails with `translate helper: Could not find translations`. A key missing from an uploaded file renders as the key itself.

Translations are per workspace. A customer who needs different wording from a [tenant
DOC](/docs/tenants/overview) needs a different template.

## Related docs

> **[Manage templates with the API](/docs/design/templates/api)**
>
> Create, read, update, and publish templates.

> **[Elemental](/docs/design/elemental/overview)**
>
> The content format every element and locale lives in.


# Elemental
Source: https://www.courier.com/docs/design/elemental/overview

The JSON format behind every template, and the elements Courier renders on each channel.

You compose a notification from a list of elements. Courier renders each one for email, push, SMS, inbox, and direct message.

A document has two top-level fields, and a send passes it as `message.content`:

```json theme={null}
{
  "message": {
    "to": { "email": "sarah@acme-corp.com" },
    "content": {
      "version": "2022-01-01",
      "elements": [
        // CourierElement[]
      ]
    }
  }
}
```

**version** `string` *required*

The Elemental format version. The only supported value is `"2022-01-01"`.

**elements** `CourierElement[]` *required*

The elements that make up the notification. Every type is documented below.

**Two ways to write content**

**ElementalContentSugar** is a shorthand for simple notifications. Pass `title` and `body` instead of a full element tree, and omit `version` and `elements`. Courier converts it to full Elemental internally: `title` becomes a `meta` element, `body` becomes a `text` element.

```javascript Node.js highlight={5-6} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { email: "sarah@acme-corp.com" },
    content: {
      title: "Welcome!",
      body: "Thanks for signing up, {{name}}",
    },
    data: { name: "Sarah Bennett" },
  },
});
```

```python Python highlight={5-6} theme={null}
response = client.send.message(
    message={
        "to": {"email": "sarah@acme-corp.com"},
        "content": {
            "title": "Welcome!",
            "body": "Thanks for signing up, {{name}}",
        },
        "data": {"name": "Sarah Bennett"},
    },
)
```

```bash cURL highlight={8-9} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "email": "sarah@acme-corp.com" },
      "content": {
        "title": "Welcome!",
        "body": "Thanks for signing up, {{name}}"
      },
      "data": { "name": "Sarah Bennett" }
    }
  }'
```

```ruby Ruby highlight={5-6} theme={null}
response = courier.send_.message(
  message: {
    to: { email: "sarah@acme-corp.com" },
    content: {
      title: "Welcome!",
      body: "Thanks for signing up, {{name}}"
    },
    data: { name: "Sarah Bennett" }
  }
)
```

```go Go highlight={10-11} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{
			OfElementalContentSugar: &shared.ElementalContentSugarParam{
				Title: "Welcome!",
				Body:  "Thanks for signing up, {{name}}",
			},
		},
		Data: map[string]any{"name": "Sarah Bennett"},
	},
})
```

```java Java highlight={5-6} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
            "title", "Welcome!",
            "body", "Thanks for signing up, {{name}}")))
        .data(JsonValue.from(java.util.Map.of("name", "Sarah Bennett")))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={5-6} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['email' => 'sarah@acme-corp.com'],
    'content' => [
      'title' => 'Welcome!',
      'body' => 'Thanks for signing up, {{name}}',
    ],
    'data' => ['name' => 'Sarah Bennett'],
  ],
);
```

```csharp C# highlight={8-9} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = new ElementalContentSugar()
        {
            Title = "Welcome!",
            Body = "Thanks for signing up, {{name}}",
        },
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") }
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"title": "Welcome!", "body": "Thanks for signing up, {{name}}"}' \
  --message.data '{"name": "Sarah Bennett"}'
```

```text MCP theme={null}
With Courier MCP, send an email to sarah@acme-corp.com with the title Welcome and a short thank-you body.
```

Use the sugar format for a title and body with no conditionals, loops, or layout. Use **full Elemental** for everything else: multi-channel customization, columns and groups, `if`/`loop`/`ref`, locales, and styling.

**Element nesting**

Elemental is a tree. The root `elements` array holds elements, and the container types hold their own `elements` arrays:

* `group`: conditions and loops
* `channel`: channel-specific content
* `columns`: holds `column` elements
* `list`: holds `list-item` elements

Nesting makes conditional groups, per-channel branches, and multi-column layouts possible.

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [
        { "type": "meta", "title": "Order Confirmation" },
        {
          "type": "group",
          "if": "data.items.length > 0",
          "elements": [
            {
              "type": "columns",
              "elements": [
                {
                  "type": "column",
                  "width": "50%",
                  "elements": [{ "type": "image", "src": "{{item.image}}" }]
                },
                {
                  "type": "column",
                  "width": "50%",
                  "elements": [{ "type": "text", "content": "{{item.name}}" }]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

**Common properties**

Every element has a required `type` string. Each section below gives its value, for example `"text"` for the text element.

Most elements also accept these shared properties:

* `channels`: an array of channel names. The element renders only for the listed channels.
* `if`: a condition that controls whether the element renders. Accepts a string expression or a [structured condition array
  DOC](/docs/design/elemental/control-flow#if).
* `loop`: an expression that repeats the element for each item in an array.
* `ref`: a reference identifier for the element.

[Control flow properties
DOC](/docs/design/elemental/control-flow) below covers all four. Many elements also accept a `locales` object for multi-language content, covered in [Template translations
DOC](/docs/design/elemental/locales). Where a property is central to an element, such as `if` and `loop` on group and list, it is listed in that element's fields below.

Text fields support [Handlebars
DOC](/docs/design/templates/variables) variables. They resolve against `message.data`, for example `data.first_name`.

## The elements

| Element | Use it to |
| - | - |
| [`text`&#xA;DOC](/docs/design/elemental/elements/text) | Format copy: bold, italic, links, alignment, colour. |
| [`action`&#xA;DOC](/docs/design/elemental/elements/action) | Add a button or a link. |
| [`channel`&#xA;DOC](/docs/design/elemental/elements/channel) | Wrap content for one channel, and override its routing. |
| [`meta`&#xA;DOC](/docs/design/elemental/elements/meta) | Set the subject line and other metadata. |
| [`image`&#xA;DOC](/docs/design/elemental/elements/image) | Place an image, sized, aligned, optionally a link. |
| [`divider`&#xA;DOC](/docs/design/elemental/elements/divider) | Draw a horizontal rule. |
| [`group`&#xA;DOC](/docs/design/elemental/elements/group) | Nest elements so one control-flow rule covers them all. |
| [`columns`&#xA;DOC](/docs/design/elemental/elements/columns) | Lay elements side by side. |
| [`list`&#xA;DOC](/docs/design/elemental/elements/list) | Render repeating items from your data. |
| [`quote`&#xA;DOC](/docs/design/elemental/elements/quote) | Call out a passage. |
| [`comment`&#xA;DOC](/docs/design/elemental/elements/comment) | Leave an internal remark that never renders. |
| [`html`&#xA;DOC](/docs/design/elemental/elements/html) | Embed raw HTML for email. |
| [`jsonnet`&#xA;DOC](/docs/design/elemental/elements/jsonnet) | Generate content programmatically. |

Every element also takes `if`, `loop`, `ref`, and `channels`. Those four are documented once, in [control flow
DOC](/docs/design/elemental/control-flow).

## Sending a document and storing one differ

A send takes the document above as `message.content` and renders it for every channel it routes to.

**Storing the same document on a Template needs its top-level elements wrapped in a `channel` element.** A send accepts a bare element list. The write API doesn't, and its rejection names a schema path rather than the rule you broke. [Templates API
DOC](/docs/design/templates/api) covers the round trip.


# Tenant Templates API
Source: https://www.courier.com/docs/design/embedded-designer/api

Read, write, publish, and version a tenant's templates with the endpoints Courier Create uses.

Courier Create reads and writes through these endpoints, so anything the editor does you can script.

```bash theme={null}
curl --request GET \
  --url https://api.courier.com/tenants/acme-corp/templates \
  --header "Authorization: Bearer $COURIER_API_KEY"
```

## Authentication

Two credentials reach these endpoints, and which one you use depends on where the code runs.

Your server uses the API key, as above. The browser uses a JWT scoped to one Tenant, which
is the same token `TemplateProvider` takes. Issue it with

[Create a JWT](/docs/api-reference/authentication/create-a-jwt)

and scope it as
[Overview
DOC](/docs/design/embedded-designer/overview#scopes) lists.

**Never send the API key from a browser.** It carries the whole workspace, not one Tenant,
so a customer holding it can read and write every other customer's Templates.

## Endpoints

| Operation | Method and path |
| - | - |
| List a Tenant's Templates | [List Templates in Tenant](/docs/api-reference/tenant-templates/list-templates-in-tenant) |
| Read one Template | [Get a Template in Tenant](/docs/api-reference/tenant-templates/get-a-template-in-tenant) |
| Create or replace a draft | [Create or update a Tenant Template](/docs/api-reference/tenant-templates/create-or-update-a-tenant-template) |
| Delete a Template | [Delete a Tenant Template](/docs/api-reference/tenant-templates/delete-a-tenant-template) |
| Publish the draft | [Publish a Tenant Template](/docs/api-reference/tenant-templates/publish-a-tenant-template) |
| Read one version | [Get a Template version](/docs/api-reference/tenant-templates/get-a-template-version) |

A `PUT` replaces the draft rather than merging into it, so send the whole document. Reading
first and writing back a modified copy is the safe order.

## Publishing is a separate call

A write leaves a draft. A draft doesn't send, so a customer who edits and closes the tab
has changed nothing a recipient will see. Publishing is what promotes it.

```bash theme={null}
curl --request POST \
  --url https://api.courier.com/tenants/acme-corp/templates/nt_01kx4h2jdafq8bk9aftxak4b40/publish \
  --header "Authorization: Bearer $COURIER_API_KEY"
```

The editor publishes for the customer through its own button, or through
`useTemplateActions` when you hide it. See
[Template editor
DOC](/docs/design/embedded-designer/template-editor#publish-from-your-own-button).

## Versions

Publishing keeps the previous published document, and

[Get a Template version](/docs/api-reference/tenant-templates/get-a-template-version)

reads one back by version. Use it to show a customer what changed, or to restore a document
by writing an older version back with a `PUT`.

## Common responses

| Status | Meaning |
| - | - |
| `200` | The read or write succeeded. |
| `204` | The delete succeeded and returned no body. |
| `400` | The document failed validation. An Elemental document has to be wrapped in a channel element to be stored. |
| `401` | The credential is missing, malformed, or expired. |
| `403` | The credential is valid but its scope doesn't cover this Tenant or this operation. |
| `404` | No Template with that id in this Tenant. |

`401` and `403` separate cleanly. A `401` means fix the token. A `403` means the token works
but was scoped too narrowly, usually a missing `brand` scope or a `tenant` in the scope that
doesn't match the path.

## Tenant Templates aren't workspace Templates

These two live in different places and neither endpoint reaches the other.

| | Tenant Template | Workspace Template |
| - | - | - |
| Belongs to | One Tenant | The workspace |
| Path | `/tenants/{tenant_id}/templates/...` | `/notifications/...` |
| Edited by | Your customer, in Courier Create | Your team, in Design Studio |
| Documented in | This page | [Templates API&#xA;DOC](/docs/design/templates/api) |

A Template your customer writes in Courier Create doesn't appear in the workspace Template
list, and a workspace Template isn't editable through these endpoints. Sending to a Tenant
resolves that Tenant's own Template.

## Verify

List the Tenant's Templates, write a draft with a `PUT`, then read it back. Publish it and
read it again. The published document is what a send to that Tenant now resolves.

## FAQ

> **Why does my edit not reach recipients?**
>
> A write leaves a draft. Call the publish endpoint, or publish from the editor, before a
> send resolves the new document.

> **What separates a 401 from a 403 here?**
>
> A `401` means the credential is missing, malformed, or expired. A `403` means the
> credential is valid but too narrowly scoped, usually a missing `brand` scope or a
> `tenant` scope that doesn't match the path.

> **Do these endpoints reach my workspace Templates?**
>
> Tenant Templates and workspace Templates are separate. Workspace Templates live under
> `/notifications` and are documented in the [Templates API
> DOC](/docs/design/templates/api).

> **Can a browser call these endpoints directly?**
>
> A browser can call them with a Tenant-scoped JWT. The API key stays on your server,
> because it carries the whole workspace rather than one Tenant.


# Courier Create brand editor
Source: https://www.courier.com/docs/design/embedded-designer/brand-editor

Let a tenant edit its logo, colors, and email footer with BrandEditor and BrandProvider.

`BrandEditor` edits one Tenant's logo, colors, and email footer. `BrandProvider` carries its auth.

```jsx theme={null}
import "@trycourier/react-designer/styles.css";
import { BrandProvider, BrandEditor } from "@trycourier/react-designer";

function Branding({ token }) {
  return (
    <BrandProvider tenantId="acme-corp" token={token}>
      <BrandEditor />
    </BrandProvider>
  );
}
```

`BrandProvider` takes no `templateId`. A Brand belongs to the Tenant rather than to one
Template, so every Template that Tenant sends picks the same Brand up.

## Scope the token for a Brand

The Brand scopes are separate from the Template scopes, and a token carrying only Template
scopes can't write a Brand.

| Scope | Grants |
| - | - |
| `tenant:<id>:brand:read` | Read one Tenant's Brand |
| `tenant:<id>:brand:write` | Write it |
| `tenants:brand:read` / `:write` | Brands across every Tenant |

Include both `read` and `write` for an editor a customer can save from. See
[Overview
DOC](/docs/design/embedded-designer/overview#scopes) for the full list and
the mint flow.

**A missing Brand scope fails at save, not at mount.** The editor renders, the customer
edits, and the write is rejected. Scope the token before you ship rather than after a
customer reports it.

## Run both editors together

Two arrangements do this, and they differ in how much control you get.

`brandEditor` on `TemplateEditor` shows the Brand editor beside the content editor, inside
the Template provider. `brandProps` passes options through to it.

```jsx theme={null}
<TemplateProvider templateId={templateId} tenantId="acme-corp" token={token}>
  <TemplateEditor brandEditor brandProps={{ hidePublish: true }} />
</TemplateProvider>
```

Mounting `BrandProvider` separately gives the Brand its own page or dialog. Each provider
creates its own store, so a Brand editor mounted this way holds state independent of the
Template editor.

Either way the token needs the Brand scopes. Adding `brandEditor` to a Template editor does
not widen the token.

## Publish from your own button

`hidePublish` removes the built-in control, and `useBrandActions` exposes the actions
behind it.

```jsx theme={null}
import { useBrandActions } from "@trycourier/react-designer";

function PublishBrandButton() {
  const { publishBrand } = useBrandActions();
  return <button onClick={() => publishBrand()}>Publish brand</button>;
}
```

The hook also returns `saveBrand` for an explicit save, and `getTemplate`. Call it inside
`BrandProvider`, or inside the `TemplateProvider` when the Brand editor is mounted through
`brandEditor`.

Publishing a Brand is its own call. Publishing a Template doesn't publish the Brand beside
it, so a customer who changes both has two things to publish.

## Theme the editor

`theme` takes a theme object or a class name, and `colorScheme` selects `light` or `dark`.

```jsx theme={null}
<BrandEditor theme={{ background: "#ffffff", primary: "#0f62fe" }} colorScheme="light" />
```

Import `@trycourier/react-designer/styles.css` once in your app. Without it the editor
renders unstyled.

## Provider props

`BrandProvider` takes auth and identity only.

| Property | Type | Required | Description |
| - | - | - | - |
| `tenantId` | string | Yes | The Tenant whose Brand is edited. |
| `token` | string | Yes | JWT carrying the Brand scopes. Issue it server-side. |
| `apiUrl` | string | No | Override the API base URL. |

## Editor props

| Property | Type | Default | Description |
| - | - | - | - |
| `autoSave` | boolean | `true` | Save Brand changes automatically. |
| `autoSaveDebounce` | number | `500` | Milliseconds to wait before an auto-save. |
| `colorScheme` | `"light" \| "dark"` | None | Force a color scheme. |
| `disableVariablesAutocomplete` | boolean | `false` | Let customers type any variable name. |
| `hidePublish` | boolean | `false` | Hide the built-in Publish button. |
| `templateEditor` | boolean | None | Show the template editor beside the Brand editor. The mirror of `brandEditor`. |
| `theme` | `Theme` or class name | None | Style the editor. |
| `value` | `BrandEditorFormValues` | None | Initial Brand values. |
| `variables` | `Record<string, unknown>` | None | Variables offered to autocomplete in footer content. |
| `variableValidation` | `VariableValidationConfig` | None | Restrict allowed variable names. |

## Verify

Render the page, change the logo or a color, and wait for the save message. Publish, then
open [Brands](https://app.courier.com/designer/brands) and confirm
the Tenant's Brand carries the change. Send that Tenant a Template and confirm the email
picks the Brand up.

## Troubleshooting

| Symptom | Cause |
| - | - |
| The editor renders, saves are rejected | The token has Template scopes but no `brand` scopes. |
| The editor renders unstyled | `@trycourier/react-designer/styles.css` was never imported. |
| A published Template still shows the old Brand | The Brand was never published. Publishing a Template doesn't publish the Brand. |
| `useBrandActions` does nothing | The component calling it sits outside both providers. |

## FAQ

> **Can a customer edit only their Brand?**
>
> Mount `BrandProvider` with `BrandEditor` and issue a token carrying just the Brand
> scopes. No Template scopes are needed.

> **Why is the Brand editor rejecting saves?**
>
> The token is missing `tenant:<id>:brand:write`. The editor renders normally either way,
> and the missing scope only shows up when the customer tries to save.

> **Does publishing a Template publish the Brand too?**
>
> Publishing is per resource. A customer who edits both has two publishes to make, and
> `publishBrand` from `useBrandActions` is the Brand one.

> **Does BrandProvider need a templateId?**
>
> A Brand belongs to the Tenant rather than to a Template, so `BrandProvider` takes
> `tenantId` and `token` only.


# Courier Create
Source: https://www.courier.com/docs/design/embedded-designer/overview

Embed the template and brand editors in your React app so customers design their own messages.

Courier Create is a template and brand editor you mount in your React app.

Your customers design and publish their [Tenant's
DOC](/docs/tenants/overview) notifications without leaving your product.

Two editors, each wrapped by a provider that handles auth and state:

* **`TemplateProvider`** wraps **`TemplateEditor`** for content.
* **`BrandProvider`** wraps **`BrandEditor`** for logo, colors, and footer.

Everything they write is a Tenant-scoped Template, separate from your workspace Templates, which you manage with the [Templates API
DOC](/docs/design/templates/api). Email is fully supported.

> **[Template editor](/docs/design/embedded-designer/template-editor)**
>
> Mount it, restrict channels, switch templates, offer variables, publish.

> **[Brand editor](/docs/design/embedded-designer/brand-editor)**
>
> Logo, colors, and footer, with their own scopes.

> **[Tenant Templates API](/docs/design/embedded-designer/api)**
>
> The endpoints both editors write through.

## Install the package

Requires React 18.2.0 or newer.

```bash theme={null}
npm install @trycourier/react-designer
```

```jsx theme={null}
import "@trycourier/react-designer/styles.css";
import { TemplateProvider, TemplateEditor } from "@trycourier/react-designer";
```

Import the stylesheet once in your app. An editor mounted without it renders unstyled,
which reads as a broken layout rather than a missing import.

## Issue a scoped token

The editor runs in the browser, so it authenticates with a JWT, never your API key. Issue one from your backend with [Create a JWT](/docs/api-reference/authentication/create-a-jwt), scoped to the Tenant the customer may edit:

[Authenticate users
DOC](/docs/in-app/authenticate-users) is the source of truth for the mint-and-sign-in flow. The scopes below are the designer's own, and they differ from the Inbox scopes documented there.

```javascript Node.js theme={null}
const { token } = await client.auth.issueToken({
  scope: "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write",
  expires_in: "30 days",
});
```

```python Python theme={null}
response = client.auth.issue_token(
    scope="user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write",
    expires_in="30 days",
)
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.courier.com/auth/issue-token \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "scope": "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write",
    "expires_in": "30 days"
  }'
```

```ruby Ruby theme={null}
response = courier.auth.issue_token(
  scope: "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write",
  expires_in: "30 days"
)
```

```go Go theme={null}
response, err := client.Auth.IssueToken(context.TODO(), courier.AuthIssueTokenParams{
  Scope:     "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write",
  ExpiresIn: "30 days",
})
```

```java Java theme={null}
AuthIssueTokenParams params = AuthIssueTokenParams.builder()
    .scope("user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write")
    .expiresIn("30 days")
    .build();

var response = client.auth().issueToken(params);
```

```php PHP theme={null}
$response = $client->auth->issueToken(
    scope: 'user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write',
    expiresIn: '30 days',
);
```

```csharp C# theme={null}
var response = await client.Auth.IssueToken(new AuthIssueTokenParams
{
    Scope = "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write",
    ExpiresIn = "30 days"
});
```

```bash CLI theme={null}
courier auth issue-token \
  --scope "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write" \
  --expires-in "30 days"
```

```text MCP theme={null}
With Courier MCP, issue a 30-day token for user_123 that can read and write acme-corp's templates.
```

### Scopes

Scope a token to one Tenant so a customer edits only their own. Plural forms grant workspace-wide access.

| Scope | Grants |
| - | - |
| `tenant:<id>:read` | Read one Tenant |
| `tenant:<id>:notifications:read` / `:write` | That Tenant's Templates |
| `tenant:<id>:brand:read` / `:write` | That Tenant's Brand |
| `tenants:read` | All Tenants |
| `tenants:notifications:read` / `:write` | Templates across Tenants |
| `tenants:brand:read` / `:write` | Brands across Tenants |

The per-Tenant Template scope is `notifications`, plural. Always include a `user_id:<id>` scope.

**A scope that is too narrow fails at save, not at mount.** A token with Template scopes and
no Brand scopes renders a Brand editor, and the write fails when the customer tries to save.

## Verify

Mount the editor and confirm it renders. A blank editor means the provider created a new
draft. Publish a change, then open the Tenant's Template in Courier and confirm it reflects
what the customer wrote.

## FAQ

> **What scopes does the token need?**
>
> A `user_id:<id>` scope, plus `tenant:<id>:notifications:read` and `:write` for Templates, and `tenant:<id>:brand:read` / `:write` if you show the brand editor.

> **Is my API key exposed in the browser?**
>
> The API key stays on your backend as long as you issue the JWT there and pass only
> that token to the component. A browser holding the key itself would have access to
> your whole workspace.

> **Can I embed only the brand editor?**
>
> Mount `BrandProvider` with `BrandEditor` and a token scoped to the Brand. See
> [Brand editor
> DOC](/docs/design/embedded-designer/brand-editor).

> **Which channels can my customers edit?**
>
> Email is fully supported. Pass `routing` to limit which channels appear, as
> [Template editor
> DOC](/docs/design/embedded-designer/template-editor#restrict-the-channels) describes.


# Courier Create template editor
Source: https://www.courier.com/docs/design/embedded-designer/template-editor

Mount TemplateEditor, scope its token, restrict channels, theme it, and publish from your button.

`TemplateProvider` carries auth and template state. `TemplateEditor` renders the editing surface.

```jsx theme={null}
import "@trycourier/react-designer/styles.css";
import { TemplateProvider, TemplateEditor } from "@trycourier/react-designer";

function Designer({ token }) {
  return (
    <TemplateProvider
      templateId="nt_01kx4h2jdafq8bk9aftxak4b40"
      tenantId="acme-corp"
      token={token}
    >
      <TemplateEditor routing={{ method: "single", channels: ["email"] }} />
    </TemplateProvider>
  );
}
```

The provider creates the Template when `templateId` doesn't resolve to one, so a first
render shows an empty editor rather than an error. Issue the `token` from your backend as
[Overview
DOC](/docs/design/embedded-designer/overview#issue-a-scoped-token)
describes.

## Restrict the channels

`routing.channels` decides which channel tabs appear. Unlisted channels are hidden from the
customer.

```jsx theme={null}
<TemplateEditor routing={{ method: "all", channels: ["email", "inbox"] }} />
```

Hiding a channel doesn't restrict what the stored Template may contain. A channel your
customer can't see can still be present in content written through the API.

There is also a bare `channels` prop. It is deprecated in favour of `routing.channels` and
scheduled for removal, so pass `routing`. When both are set, `routing.channels` wins.

## Switch templates

Change `templateId` and the provider loads the new Template. The prop sits in an effect
dependency, so no remount or `key` is needed.

```jsx theme={null}
const [templateId, setTemplateId] = useState("nt_01kx4h2jdafq8bk9aftxak4b40");

<TemplateProvider templateId={templateId} tenantId="acme-corp" token={token}>
  <TemplateEditor />
</TemplateProvider>
```

Auto-save runs against the Template that was mounted, so let a pending save settle before
switching. With the default debounce that is 500ms after the last keystroke.

## Publish from your own button

`hidePublish` removes the built-in control. `useTemplateActions` exposes the same action,
so your own button does the same work.

```jsx theme={null}
import { useTemplateActions } from "@trycourier/react-designer";

function PublishButton() {
  const { publishTemplate } = useTemplateActions();
  return <button onClick={() => publishTemplate()}>Publish</button>;
}
```

Call the hook inside the provider. A component rendered outside it has no template state to
act on.

## Control when writes happen

Auto-save is on, debounced 500ms. Turn it off to write on your own schedule.

```jsx theme={null}
<TemplateEditor autoSave={false} />
```

`readOnly` makes the editor read-only across every channel. It disables editing, toolbar
actions, block insertion, drag and drop, and auto-save, which makes it the prop to reach for
when a customer may view a Template but not change it.

## Offer variables

`variables` populates the autocomplete a customer sees after typing `{{`.

```jsx theme={null}
<TemplateEditor variables={{ user: { first_name: "Sarah" }, order: { id: "1234" } }} />
```

**Leaving `variables` unset disables every variable feature.** The toolbar button is hidden,
and typing `{{` creates no variable chip. Pass `variables` to turn autocomplete on.

Two props change how strict that autocomplete is:

* `disableVariablesAutocomplete` drops the dropdown and lets a customer type any name.
* `variableValidation` restricts which names are allowed and says what happens when one
  fails.

`sampleData` is separate. It validates the data path on a loop, and warns when the path
matches no key or doesn't resolve to an array.

## Theme the editor

`theme` takes a theme object or a class name. `colorScheme` selects `light` or `dark`.

```jsx theme={null}
<TemplateEditor theme={{ background: "#ffffff", primary: "#0f62fe" }} colorScheme="dark" />
```

Import `@trycourier/react-designer/styles.css` once in your app. Without it the editor
renders unstyled, which reads as a broken layout rather than a missing import.

## Render inside a modal

The editor is a regular element, so your own dialog can hold it. Two things about the
surrounding app matter.

Give the container a height. The editor fills its parent, and a dialog that sizes to its
content gives it nothing to fill.

**Set `renderToaster` to `false` when your app already renders a Sonner `<Toaster />`.**
The provider renders its own by default, and two on one page means every save message
appears twice.

```jsx theme={null}
<TemplateProvider
  templateId={templateId}
  tenantId="acme-corp"
  token={token}
  renderToaster={false}
>
  <TemplateEditor />
</TemplateProvider>
```

Keep the provider mounted while the dialog is open. Unmounting it discards template state,
so the next open refetches.

## Provider props

`TemplateProvider` holds auth, identity, and the options that outlive a single editor.

| Property | Type | Required | Description |
| - | - | - | - |
| `templateId` | string | Yes | The Template to edit. Created when it doesn't exist. Changing it loads another Template. |
| `tenantId` | string | Yes | The Tenant the Template belongs to. |
| `token` | string | Yes | JWT authorizing the requests. Issue it server-side, because a browser holding your API key has access to the whole workspace. |
| `apiUrl` | string | No | Override the API base URL. |
| `uploadImage` | `UploadImageFunction` | No | Replace the default image upload. Takes a `Blob`, a `File`, or an `ImageUploadConfig`. |
| `variables` | `Record<string, unknown>` | No | Variables offered to autocomplete. |
| `disableVariablesAutocomplete` | boolean | No | Let customers type any variable name. |
| `variableValidation` | `VariableValidationConfig` | No | Restrict allowed variable names and set the failure behavior. |
| `sampleData` | `Record<string, unknown>` | No | Payload used to validate loop data paths. |
| `renderToaster` | boolean | No | Render the bundled Sonner `<Toaster />`. Defaults to `true`. |

## Editor props

| Property | Type | Default | Description |
| - | - | - | - |
| `autoSave` | boolean | `true` | Save changes automatically. |
| `autoSaveDebounce` | number | `500` | Milliseconds to wait before an auto-save. |
| `brandEditor` | boolean | `false` | Show the brand editor beside the template editor. |
| `brandProps` | `BrandEditorProps` | None | Options passed to that brand editor. |
| `colorScheme` | `"light" \| "dark"` | None | Force a color scheme. |
| `disableVariablesAutocomplete` | boolean | `false` | Let customers type any variable name. |
| `hidePublish` | boolean | `false` | Hide the built-in Publish button. |
| `onChange` | `(value: ElementalContent) => void` | None | Fires when content changes. |
| `readOnly` | boolean | `false` | Make every channel read-only and stop auto-save. |
| `routing` | `MessageRouting` | All channels | Restrict which channel tabs appear. |
| `sampleData` | `Record<string, unknown>` | None | Validate loop data paths against this payload. |
| `theme` | `Theme` or class name | None | Style the editor. |
| `value` | `ElementalContent` | `null` | Initial content. |
| `variables` | `Record<string, unknown>` | None | Variables offered to autocomplete. Unset disables variables entirely. |
| `variableValidation` | `VariableValidationConfig` | None | Restrict allowed variable names. |
| `channels` | `ChannelType[]` | None | Deprecated. Use `routing.channels`. |

## Verify

Render the page and confirm the editor appears. Type into a block, wait for the save
message, then open [Templates](https://app.courier.com/content/templates)
and confirm the Tenant's Template carries the change.

## Troubleshooting

| Symptom | Cause |
| - | - |
| The editor renders unstyled | `@trycourier/react-designer/styles.css` was never imported. |
| The editor has no height | The parent sizes to its content. The editor fills its parent. |
| No variable button, and `{{` does nothing | `variables` is unset, which disables the whole feature. |
| Every save message appears twice | Your app renders a Sonner `<Toaster />` too. Set `renderToaster` to `false`. |
| Edits never persist | `autoSave` is `false` with nothing calling a save, or `readOnly` is `true`. |
| A brand change is rejected while content saves | The token carries `notifications` scopes but no `brand` scopes. |
| `useTemplateActions` has no template | The component calling it sits outside `TemplateProvider`. |

## FAQ

> **How do I switch the customer to a different template?**
>
> Change the `templateId` prop on `TemplateProvider`. The prop sits in an effect
> dependency, so the provider loads the new Template without a remount.

> **Why is there no variable button in the toolbar?**
>
> The `variables` prop is unset. Leaving it undefined disables every variable feature,
> including the `{{` autocomplete.

> **Can the editor run inside a dialog?**
>
> A dialog can hold the editor. Give the container an explicit height, and set
> `renderToaster` to `false` if your app already renders a Sonner `<Toaster />`.

> **Should I use channels or routing.channels?**
>
> Pass `routing.channels`. The bare `channels` prop is deprecated and scheduled for
> removal, and `routing.channels` takes priority when both are set.


# Design notifications
Source: https://www.courier.com/docs/design/overview

Templates, brands, and the Elemental format that defines what a notification says and looks like.

A notification's design lives in a template: what it says, how it looks, and how it changes per channel.

![Design Studio: the channel rail and blocks panel on the left, the canvas in the center, and the styles panel on the right](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/design-studio.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=51850c52555d0647e10435c5d0bc6ef2)

## How it works

[Templates
DOC](/docs/design/templates/overview) hold the content and the channel, routing, and brand settings around it. Your team builds one in the [Design Studio
DOC](/docs/design/templates/design-studio) or over the [Templates API
DOC](/docs/design/templates/api).

[Brands
DOC](/docs/design/brands) hold the logo, colors, and footer that a template applies, so a styling change lands everywhere at once rather than template by template.

[Elemental
DOC](/docs/design/elemental/overview) is the JSON format underneath. The visual editor writes it for you, and the API takes it directly, so a template is the same object either way.

## When your customers design their own

White-label and multi-tenant products often need each customer writing their own messages, not your team writing them all.

The [Embedded Designer
DOC](/docs/design/embedded-designer/overview) mounts the same editor inside your React app. What a customer builds there belongs to their [tenant
DOC](/docs/tenants/overview) rather than to your workspace.


# Manage templates with the API
Source: https://www.courier.com/docs/design/templates/api

Create, read, update, and publish templates over the REST API with an nt_ ID and a draft lifecycle.

> [!NOTE]
>
> [How templates work
> DOC](/docs/design/templates/overview) explains the draft/publish model.

Manage templates over the API so they live in code and move through Git review. Each carries an `nt_` ID and a draft/published lifecycle.

## Prerequisites

* [A Courier API key](https://app.courier.com/settings/api-keys)
* [The Elemental content format
  DOC](/docs/design/elemental/overview)

## Create a template

[Create Notification Template](/docs/api-reference/templates/create-notification-template) returns a new template in the `DRAFT` state:

```javascript Node.js theme={null}
const notificationTemplateResponse = await client.notifications.create({
  notification: {
    name: 'Welcome Email',
    tags: ['onboarding', 'welcome'],
    brand: { id: 'bnd_01kx4mrd0pfzw8wt7pn7p2fzag' },
    subscription: { topic_id: 'pt_01kx4h2jdafq8bk9a26x0kvd1t' },
    routing: { strategy_id: 'rs_01kx4h2jdafq8bk9amzvy6hbv0' },
    content: {
      version: '2022-01-01',
      elements: [
        {
          type: 'channel',
          channel: 'email',
          elements: [{ type: 'text', content: 'Welcome aboard, {{name}}.' }],
        },
      ],
    },
  },
  state: 'DRAFT',
});
```

```python Python theme={null}
notification_template_response = client.notifications.create(
    notification={
        "name": "Welcome Email",
        "tags": ["onboarding", "welcome"],
        "brand": {"id": "bnd_01kx4mrd0pfzw8wt7pn7p2fzag"},
        "subscription": {"topic_id": "pt_01kx4h2jdafq8bk9a26x0kvd1t"},
        "routing": {"strategy_id": "rs_01kx4h2jdafq8bk9amzvy6hbv0"},
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "channel",
                    "channel": "email",
                    "elements": [{"type": "text", "content": "Welcome aboard, {{name}}."}],
                }
            ],
        },
    },
    state="DRAFT",
)
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.courier.com/notifications \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "notification": {
      "name": "Welcome Email",
      "tags": ["onboarding", "welcome"],
      "brand": { "id": "bnd_01kx4mrd0pfzw8wt7pn7p2fzag" },
      "subscription": { "topic_id": "pt_01kx4h2jdafq8bk9a26x0kvd1t" },
      "routing": { "strategy_id": "rs_01kx4h2jdafq8bk9amzvy6hbv0" },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "channel",
            "channel": "email",
            "elements": [{ "type": "text", "content": "Welcome aboard, {{name}}." }]
          }
        ]
      }
    },
    "state": "DRAFT"
  }'
```

```ruby Ruby theme={null}
notification_template_response = courier.notifications.create(
  notification: {
    brand: {id: "bnd_01kx4mrd0pfzw8wt7pn7p2fzag"},
    content: {elements: [{type: "channel", channel: "email", elements: [{type: "text", content: "Welcome aboard, {{name}}."}]}], version: "2022-01-01"},
    name: "Welcome Email",
    routing: {strategy_id: "rs_01kx4h2jdafq8bk9amzvy6hbv0"},
    subscription: {topic_id: "pt_01kx4h2jdafq8bk9a26x0kvd1t"},
    tags: ["onboarding", "welcome"]
  }
)
```

```go Go theme={null}
// The typed elemental model has no field for a channel's child elements, so pass the content as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [{ "type": "text", "content": "Welcome aboard, {{name}}." }]
    }
  ]
}`))

notificationTemplateResponse, err := client.Notifications.New(context.TODO(), courier.NotificationNewParams{
	NotificationTemplateCreateRequest: courier.NotificationTemplateCreateRequestParam{
		Notification: courier.NotificationTemplateWritePayloadParam{
			NotificationTemplatePayloadParam: courier.NotificationTemplatePayloadParam{
				Brand: courier.NotificationTemplatePayloadBrandParam{
					ID: "bnd_01kx4mrd0pfzw8wt7pn7p2fzag",
				},
				Content: content,
				Name:    "Welcome Email",
				Routing: courier.NotificationTemplatePayloadRoutingParam{
					StrategyID: "rs_01kx4h2jdafq8bk9amzvy6hbv0",
				},
				Subscription: courier.NotificationTemplatePayloadSubscriptionParam{
					TopicID: "pt_01kx4h2jdafq8bk9a26x0kvd1t",
				},
				Tags: []string{"onboarding", "welcome"},
			},
		},
	},
})
```

```java Java theme={null}
NotificationTemplateCreateRequest params = NotificationTemplateCreateRequest.builder()
    .notification(NotificationTemplateWritePayload.builder()
        .brand(NotificationTemplatePayload.Brand.builder()
            .id("bnd_01kx4mrd0pfzw8wt7pn7p2fzag")
            .build())
        .content(ElementalContent.builder()
            // The channel builder has no addElement, so its children go in as an additional property.
            .addElement(ElementalChannelNodeWithType.builder()
                .type(ElementalChannelNodeWithType.Type.CHANNEL)
                .channel("email")
                .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                    java.util.Map.of("type", "text", "content", "Welcome aboard, {{name}}."))))
                .build())
            .version("2022-01-01")
            .build())
        .name("Welcome Email")
        .routing(NotificationTemplatePayload.Routing.builder()
            .strategyId("rs_01kx4h2jdafq8bk9amzvy6hbv0")
            .build())
        .subscription(NotificationTemplatePayload.Subscription.builder()
            .topicId("pt_01kx4h2jdafq8bk9a26x0kvd1t")
            .build())
        .addTag("onboarding")
        .addTag("welcome")
        .build())
    .build();
NotificationTemplateResponse notificationTemplateResponse = client.notifications().create(params);
```

```php PHP theme={null}
$notificationTemplateResponse = $client->notifications->create(
  notification: [
    'brand' => ['id' => 'bnd_01kx4mrd0pfzw8wt7pn7p2fzag'],
    'content' => ['elements' => [['type' => 'channel']], 'version' => '2022-01-01'],
    'name' => 'Welcome Email',
    'routing' => ['strategyID' => 'rs_01kx4h2jdafq8bk9amzvy6hbv0'],
    'subscription' => ['topicID' => 'pt_01kx4h2jdafq8bk9a26x0kvd1t'],
    'tags' => ['onboarding', 'welcome'],
  ],
  state: 'DRAFT',
);
```

```csharp C# theme={null}
NotificationCreateParams parameters = new()
{
    Notification = new()
    {
        Brand = new("bnd_01kx4mrd0pfzw8wt7pn7p2fzag"),
        Content = new()
        {
            // Elemental nodes expose no typed content property, so build the node from raw JSON.
        Elements =
        [
            ElementalChannelNodeWithType.FromRawUnchecked(
                JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                {
                  "type": "channel",
                  "channel": "email",
                  "elements": [{ "type": "text", "content": "Welcome aboard, {{name}}." }]
                }
                """)),
        ],
            Version = "2022-01-01",
        },
        Name = "Welcome Email",
        Routing = new("rs_01kx4h2jdafq8bk9amzvy6hbv0"),
        Subscription = new("pt_01kx4h2jdafq8bk9a26x0kvd1t"),
        Tags = ["onboarding", "welcome"],
    },
};

var notificationTemplateResponse = await client.Notifications.Create(parameters);
```

```bash CLI theme={null}
courier notifications create \
  --api-key "$COURIER_API_KEY" \
  --notification "{brand: {id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag}, content: {elements: [{type: channel, channel: email, elements: [{type: text, content: 'Welcome aboard, {{name}}.'}]}], version: '2022-01-01'}, name: Welcome Email, routing: {strategy_id: rs_01kx4h2jdafq8bk9amzvy6hbv0}, subscription: {topic_id: pt_01kx4h2jdafq8bk9a26x0kvd1t}, tags: [onboarding, welcome]}"
```

```text MCP theme={null}
With Courier MCP, create a draft template called Welcome Email tagged onboarding.
```

### Content needs a channel to live in

Every element belongs inside a `channel` block. Content whose elements sit at the
top level is rejected at creation:

```json theme={null}
{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "inbox",
      "elements": [{ "type": "text", "content": "Your order shipped." }]
    }
  ]
}
```

The channel block is what the [Design Studio
DOC](/docs/design/templates/design-studio)
renders when someone opens the template, so content without one is stored but
opens as an empty document. A `meta` element may sit at the top level alongside
the channel blocks. A template with no elements at all is fine: it is one nobody
has written yet.

Only creation is checked. Templates already saved without a channel block still
send, and are left alone.

## Read a template

[Get Notification Template](/docs/api-reference/templates/get-notification-template) returns the template, defaulting to the published version. Pass `?version=draft` (or a version like `v001`) to read another:

```javascript Node.js theme={null}
const notificationTemplateResponse = await client.notifications.retrieve('nt_01kx4h2jdafq8bk9aftxak4b40');
```

```python Python theme={null}
notification_template_response = client.notifications.retrieve(
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
)
```

```bash cURL theme={null}
curl --request GET \
  --url https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40 \
  --header "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
notification_template_response = courier.notifications.retrieve("nt_01kx4h2jdafq8bk9aftxak4b40")
```

```go Go theme={null}
notificationTemplateResponse, err := client.Notifications.Get(
	context.TODO(),
	"nt_01kx4h2jdafq8bk9aftxak4b40",
	courier.NotificationGetParams{},
)
```

```java Java theme={null}
NotificationTemplateResponse notificationTemplateResponse = client.notifications().retrieve("nt_01kx4h2jdafq8bk9aftxak4b40");
```

```php PHP theme={null}
$notificationTemplateResponse = $client->notifications->retrieve('nt_01kx4h2jdafq8bk9aftxak4b40');
```

```csharp C# theme={null}
NotificationRetrieveParams parameters = new() { ID = "nt_01kx4h2jdafq8bk9aftxak4b40" };

var notificationTemplateResponse = await client.Notifications.Retrieve(parameters);
```

```bash CLI theme={null}
courier notifications retrieve \
  --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, show me the published version of my welcome email template.
```

## Update content: the round-trip contract

Template content is read and written through a separate content endpoint. [Get Notification Content](/docs/api-reference/templates/get-notification-content) returns one of two shapes: the **Elemental** form (`{ version, elements }`, where every element carries a read-only `checksum` and a translated element carries its translations in `locales`) or, for legacy templates, the **blocks and channels** form (`{ blocks, channels, checksum }`).

> [!WARNING]
>
> **PUT accepts Elemental only, and it replaces all content.**\\
>
> [Replace Notification Content](/docs/api-reference/templates/replace-notification-content) takes the `{ version, elements }` tree inside a `content` object. Read the draft with `?version=draft`, change the elements, and remove every `checksum` at any depth, because the write rejects them. Templates translated in Design Studio also carry keys starting with an underscore, such as `_sourceHash`, inside `locales`. Remove those too. Keep each element's `id` and `locales`: an element sent without an `id` gets a new one, and one sent without `locales` loses its translations.

This example writes content to a template with no translations yet. To change only a template's translations, write one locale at a time with [Replace Notification Locale](/docs/api-reference/templates/replace-notification-locale), which leaves the default content and other locales as they are. See [template translations
DOC](/docs/design/elemental/locales).

```javascript Node.js theme={null}
const notificationContentMutationResponse = await client.notifications.putContent('nt_01kx4h2jdafq8bk9aftxak4b40', {
  content: {
    version: '2022-01-01',
    elements: [
      {
        type: 'channel',
        channel: 'email',
        elements: [{ type: 'text', content: 'Welcome aboard, {{name}}.' }],
      },
    ],
  },
  state: 'DRAFT',
});
```

```python Python theme={null}
notification_content_mutation_response = client.notifications.put_content(
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
    content={
        "version": "2022-01-01",
        "elements": [
            {
                "type": "channel",
                "channel": "email",
                "elements": [{"type": "text", "content": "Welcome aboard, {{name}}."}],
            }
        ],
    },
    state="DRAFT",
)
```

```bash cURL theme={null}
curl --request PUT \
  --url https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40/content \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "content": {
      "version": "2022-01-01",
      "elements": [
        {
          "type": "channel",
          "channel": "email",
          "elements": [{ "type": "text", "content": "Welcome aboard, {{name}}." }]
        }
      ]
    },
    "state": "DRAFT"
  }'
```

```ruby Ruby theme={null}
notification_content_mutation_response = courier.notifications.put_content(
  "nt_01kx4h2jdafq8bk9aftxak4b40",
  content: {elements: [{type: "channel", channel: "email", elements: [{type: "text", content: "Welcome aboard, {{name}}."}]}], version: "2022-01-01"}
)
```

```go Go theme={null}
notificationContentMutationResponse, err := client.Notifications.PutContent(
	context.TODO(),
	"nt_01kx4h2jdafq8bk9aftxak4b40",
	courier.NotificationPutContentParams{
		NotificationContentPutRequest: courier.NotificationContentPutRequestParam{
			// The typed elemental model has no field for a channel's child elements, so pass the content as raw JSON.
			Content: param.Override[courier.NotificationContentPutRequestContentParam](json.RawMessage(`{
			  "version": "2022-01-01",
			  "elements": [
			    {
			      "type": "channel",
			      "channel": "email",
			      "elements": [{ "type": "text", "content": "Welcome aboard, {{name}}." }]
			    }
			  ]
			}`)),
		},
	},
)
```

```java Java theme={null}
NotificationPutContentParams params = NotificationPutContentParams.builder()
    .id("nt_01kx4h2jdafq8bk9aftxak4b40")
    .notificationContentPutRequest(NotificationContentPutRequest.builder()
        .content(NotificationContentPutRequest.Content.builder()
            // The channel builder has no addElement, so its children go in as an additional property.
            .addElement(ElementalChannelNodeWithType.builder()
                .type(ElementalChannelNodeWithType.Type.CHANNEL)
                .channel("email")
                .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                    java.util.Map.of("type", "text", "content", "Welcome aboard, {{name}}."))))
                .build())
            .version("2022-01-01")
            .build())
        .build())
    .build();
NotificationContentMutationResponse notificationContentMutationResponse = client.notifications().putContent(params);
```

```php PHP theme={null}
$notificationContentMutationResponse = $client->notifications->putContent(
  'nt_01kx4h2jdafq8bk9aftxak4b40',
  content: ['elements' => [['type' => 'channel', 'channel' => 'email', 'elements' => [['type' => 'text', 'content' => 'Welcome aboard, {{name}}.']]]], 'version' => '2022-01-01'],
  state: NotificationTemplateState::DRAFT,
);
```

```csharp C# theme={null}
NotificationPutContentParams parameters = new()
{
    ID = "nt_01kx4h2jdafq8bk9aftxak4b40",
    Content = new()
    {
        Elements = [new ElementalChannelNodeWithType() { Type = ElementalChannelNodeWithTypeIntersectionMember1Type.Channel }],
        Version = "2022-01-01",
    },
};

var notificationContentMutationResponse = await client.Notifications.PutContent(parameters);
```

```bash CLI theme={null}
courier notifications put-content \
  --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40 \
  --content "{elements: [{type: channel, channel: email, elements: [{type: text, content: 'Welcome aboard, {{name}}.'}]}], version: '2022-01-01'}"
```

```text MCP theme={null}
With Courier MCP, replace the draft content of my welcome email template with this Elemental document.
```

## Publish

A `PUT` writes the draft. [Publish Notification Template](/docs/api-reference/templates/publish-notification-template) makes it the active version. You can also publish a historical version to roll back.

```javascript Node.js theme={null}
await client.notifications.publish('nt_01kx4h2jdafq8bk9aftxak4b40');
```

```python Python theme={null}
client.notifications.publish(
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
)
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40/publish \
  --header "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
result = courier.notifications.publish("nt_01kx4h2jdafq8bk9aftxak4b40")
```

```go Go theme={null}
err := client.Notifications.Publish(
	context.TODO(),
	"nt_01kx4h2jdafq8bk9aftxak4b40",
	courier.NotificationPublishParams{},
)
```

```java Java theme={null}
client.notifications().publish("nt_01kx4h2jdafq8bk9aftxak4b40");
```

```php PHP theme={null}
$result = $client->notifications->publish('nt_01kx4h2jdafq8bk9aftxak4b40');
```

```csharp C# theme={null}
NotificationPublishParams parameters = new() { ID = "nt_01kx4h2jdafq8bk9aftxak4b40" };

await client.Notifications.Publish(parameters);
```

```bash CLI theme={null}
courier notifications publish \
  --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, publish my welcome email template.
```

## Aliases

An alias is a name you choose that stands in for a template's `nt_` ID on a send. Your code keeps a readable reference while the template behind it changes. You assign one in the template's **settings**, under **Alias**, or with `notification.alias` on [Create Notification Template](/docs/api-reference/templates/create-notification-template) and [Replace Notification Template](/docs/api-reference/templates/replace-notification-template). A string sets the alias, `null` clears it, and leaving the field out keeps the existing alias. Claiming an alias another template already holds returns `409`.

[Send it by ID or alias
DOC](/docs/design/templates/overview#send-it-by-id-or-alias) has the rules and an example.

## Read a template's metrics

[Get Notification Template Metrics](/docs/api-reference/templates/get-notification-template-metrics) returns one template's sends, deliveries, opens, clicks, errors, and undeliverables over time, broken out per provider and channel. [Template metrics
DOC](/docs/monitor/template-metrics) covers the window, granularity, and plan caps.

## Preview a template on email clients

[Create Preview Run](/docs/api-reference/previews/create-preview-run) renders a template's email on real clients and returns a screenshot of each. [Device Preview
DOC](/docs/design/templates/device-preview#run-a-preview-with-the-api) covers device sets, timing, and reading the results.

## Approval workflow

If your team gates publishing behind review, enable the approval workflow. Submitting a draft for review happens in the console, which puts the template in a read-only submission state. Over the API you then manage the submission's **checks**: read them with [Get submission checks](/docs/api-reference/templates/get-submission-checks), resolve or fail them with `PUT`, and cancel the submission with `DELETE`. Creating the submission itself happens in the console.

## Manage Templates as code

**1. Export a template to Elemental**

[Elemental
DOC](/docs/design/elemental/overview) is the JSON format Courier uses for template content, so it is what you version-control. Read a template's content with [Get Notification Content](/docs/api-reference/templates/get-notification-content) and commit the `{ version, elements }` JSON to your repo as the source of truth for the template.

**2. Version-control the content**

With the Elemental JSON in your repo, review template changes in a pull request like any other code. Apply an approved change back to Courier with [Replace Notification Content](/docs/api-reference/templates/replace-notification-content). Remove the read-only `checksum` fields and any `locales` key that starts with an underscore, and keep each element's `id` and `locales` before you PUT, and see [the round-trip contract](#update-content-the-round-trip-contract) for the rest.

**3. Manage templates from the CLI**

The Courier CLI maps to the same template operations, so you can script create, update, publish, and version listing in CI:

```bash theme={null}
# Create a template from an Elemental file
courier notifications create --api-key "$COURIER_API_KEY" \
  --notification "$(cat welcome-email.json)"

# Update its content from the versioned file
courier notifications put-content --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40 --content "$(cat welcome-email.content.json)"

# Publish, and list versions to confirm
courier notifications publish --api-key "$COURIER_API_KEY" --id nt_01kx4h2jdafq8bk9aftxak4b40
courier notifications list-versions --api-key "$COURIER_API_KEY" --id nt_01kx4h2jdafq8bk9aftxak4b40
```

The full verb set is `list`, `create`, `retrieve`, `replace`, `archive`, `list-versions`, `publish`, `duplicate`, `retrieve-content`, `put-content`, `put-element`, and `put-locale`.

**4. Manage templates from an AI agent**

The same operations are available as Courier [MCP
DOC](/docs/resources/mcp) tools (`create_notification`, `put_notification_content`, `publish_notification`, `list_notification_versions`), so an AI agent can create and update templates in your workspace. Connect the MCP server once and drive template changes from your agent.

**5. Verify the round-trip**

Export a template, change a value in the JSON, write it back with `put-content`, and publish. Confirm the change renders in a test send, then run `list-versions` and confirm your publish created a new version.

## Endpoints

Every operation on a workspace Template. Names and reference links are generated from the
OpenAPI spec, so this table can't drift from what the API serves.

| Operation | Method and path |
| - | - |
| List Templates | [List Notification Templates](/docs/api-reference/templates/list-notification-templates) |
| Read one | [Get Notification Template](/docs/api-reference/templates/get-notification-template) |
| Replace one | [Replace Notification Template](/docs/api-reference/templates/replace-notification-template) |
| Archive one | [Archive Notification Template](/docs/api-reference/templates/archive-notification-template) |
| List versions | [List Notification Template Versions](/docs/api-reference/templates/list-notification-template-versions) |
| Publish | [Publish Notification Template](/docs/api-reference/templates/publish-notification-template) |
| Read content | [Get Notification Content](/docs/api-reference/templates/get-notification-content) |
| Replace content | [Replace Notification Content](/docs/api-reference/templates/replace-notification-content) |
| Replace one element | [Replace Notification Element](/docs/api-reference/templates/replace-notification-element) |
| Replace a locale | [Replace Notification Locale](/docs/api-reference/templates/replace-notification-locale) |
| Read submission checks | [Get submission checks](/docs/api-reference/templates/get-submission-checks) |
| Replace submission checks | [Replace submission checks](/docs/api-reference/templates/replace-submission-checks) |
| Cancel a submission | [Cancel submission](/docs/api-reference/templates/cancel-submission) |
| Read metrics | [Get Notification Template Metrics](/docs/api-reference/templates/get-notification-template-metrics) |

## Response codes

| Status | Meaning |
| - | - |
| `200` | The read or write succeeded. |
| `201` | The Template was created. |
| `204` | The write succeeded and returned no body. |
| `400` | The document failed validation. Content stored on a Template needs its top-level elements wrapped in a channel element. |
| `402` | The workspace's plan doesn't include this operation. |
| `404` | No Template with that id, or no such version. |
| `409` | The write conflicts with the Template's current state, such as publishing what is already published. |
| `429` | Rate limited. Retry after the interval the response names. |
| `503` | Temporarily unavailable. Retry with backoff. |

## Where three related things live

These come up while working with this API and each is documented once, elsewhere:

* **Filling variables at send time.** Pass `data` on the send and the Template resolves it. [Variables
  DOC](/docs/design/templates/variables) covers the syntax, scope, and the helpers.
* **Raw HTML for email.** [HTML email
  DOC](/docs/design/templates/html-email) covers sending a full HTML document and what a provider does with it.
* **Workspace against Tenant Templates.** These endpoints reach workspace Templates only. A Tenant's own Templates live under `/tenants/{tenant_id}/templates` and are documented in [Tenant Templates API
  DOC](/docs/design/embedded-designer/api).

## Verify

Retrieve the template without a `version` parameter and confirm your published change is live, then send it to a test recipient and confirm it renders in [message logs
DOC](/docs/monitor/overview).


# Design Studio block settings
Source: https://www.courier.com/docs/design/templates/blocks

Every setting on each Design Studio block, with its type and default.

Select a block on the canvas and its settings open in the right panel. This page is the reference for what each one exposes.

Padding, border, and color values are pixels or CSS color strings unless a row says otherwise. Add and arrange blocks in [Design Studio
DOC](/docs/design/templates/design-studio).

## Heading and text

**These are one settings surface.** A heading is a text block with a heading level. Both take the same attributes and the same defaults.

| Setting | Type | Default |
| - | - | - |
| `paddingVertical` | number | `6` |
| `paddingHorizontal` | number | `0` |
| `backgroundColor` | color | `transparent` |
| `borderWidth` | number | `0` |
| `borderColor` | color | `transparent` |
| `textAlign` | `left`, `center`, `right`, `justify` | `left` |
| `fontSize` | number or null | `null` |
| `lineHeight` | number or null | `null` |

**`null` on `fontSize` or `lineHeight` means inherit, not zero.** The block falls back to the document base, then to the tier preset, and the value isn't written into Elemental at all. Setting either to `0` or clearing it reads as inherit too, so there is no way to express "no line height".

## Button

| Setting | Type | Default |
| - | - | - |
| `label` | string | `Enter text` |
| `link` | string | empty |
| `alignment` | `left`, `center`, `right` | `center` |
| `actionStyle` | `button`, `secondary`, `tertiary`, `link` | `button` |
| `backgroundColor` | color | `#0085FF` |
| `textColor` | color | `#ffffff` |
| `borderColor` | color | `transparent` |
| `borderRadius` | number | `0` |
| `paddingVertical` | number | `8` |
| `paddingHorizontal` | number | `16` |
| `fontSize` | number or null | `null` |
| `fontWeight` | `normal`, `bold` | `normal` |
| `fontStyle` | `normal`, `italic` | `normal` |
| `isUnderline` | boolean | `false` |
| `isStrike` | boolean | `false` |
| `disableTracking` | boolean | `false` |

`disableTracking` stops Courier rewriting the button's URL for click tracking. Turn it on for a link that must reach the destination unmodified, and accept that clicks on it stop being recorded. See [tracking
DOC](/docs/monitor/tracking).

`actionStyle` names how the action renders, and the four values mean different things per channel. Inbox in particular applies no colours of its own, so the style name is the whole contract there.

## Divider and Spacer

**One block with a `variant` switch, which is why they share a table.** The defaults differ, and that is the point. A divider draws a visible line. A spacer reserves height and draws nothing.

| Setting | Type | Divider default | Spacer default |
| - | - | - | - |
| `variant` | `divider`, `spacer` | `divider` | `spacer` |
| `padding` | number | `6` | `24` |
| `color` | color | `#000000` | `transparent` |
| `size` | number | `1` | `1` |
| `radius` | number | `0` | `0` |

A spacer is a transparent divider with more padding. Setting a spacer's `color` makes it a divider in everything but name.

## Image

| Setting | Type | Default |
| - | - | - |
| `sourcePath` | string | empty |
| `link` | string | empty |
| `alt` | string | empty |
| `alignment` | `left`, `center`, `right` | `center` |
| `width` | number | `1` |
| `borderWidth` | number | `0` |
| `borderColor` | color | `transparent` |

Give every image an `alt`. An email client that blocks images shows that text instead, which for many readers is the only version of the message they see.

## List

| Setting | Type | Default |
| - | - | - |
| `listType` | `ordered`, `unordered` | `unordered` |
| `paddingVertical` | number | `6` |
| `paddingHorizontal` | number | `0` |
| `fontSize` | number or null | `null` |
| `lineHeight` | number or null | `null` |
| `loop` | string | empty |

`loop` is the data path the list repeats over, and it is what turns one list item into one per array entry at send time. See [control flow
DOC](/docs/design/elemental/control-flow#loop).

## Column

A Column block holds cells, and each cell has its own settings.

| Column setting | Type | Default |
| - | - | - |
| `columnsCount` | number, 1 to 4 | `2` |
| `paddingHorizontal` | number | `0` |
| `paddingVertical` | number | `0` |
| `backgroundColor` | color | `transparent` |
| `borderWidth` | number | `0` |
| `borderRadius` | number | `0` |
| `borderColor` | color | `transparent` |

| Cell setting | Type | Default |
| - | - | - |
| `paddingHorizontal` | number | `6` |
| `paddingVertical` | number | `6` |
| `backgroundColor` | color | `transparent` |
| `borderWidth` | number | `0` |
| `borderRadius` | number | `0` |
| `borderColor` | color | `transparent` |

The cells carry padding by default and the column doesn't, so spacing between columns comes from the cells unless you change it.

## Blockquote

| Setting | Type | Default |
| - | - | - |
| `paddingHorizontal` | number | `20` |
| `paddingVertical` | number | `4` |
| `backgroundColor` | color | `transparent` |
| `borderLeftWidth` | number | `2` |
| `borderColor` | color | `#e0e0e0` |
| `fontSize` | number or null | `null` |
| `lineHeight` | number or null | `null` |

A blockquote is the one block styled by a left border rather than a full one, so `borderLeftWidth` replaces `borderWidth` here.

## HTML

| Setting | Type | Default |
| - | - | - |
| `code` | string | an HTML comment |

Raw HTML for email, when no other block expresses what you need. [The html element
DOC](/docs/design/elemental/elements/html) covers what a provider does with it, and [HTML email
DOC](/docs/design/templates/html-email) covers bringing a whole document in.

## Jsonnet

| Setting | Type | Default |
| - | - | - |
| `template` | string | a starter template |

Generates content programmatically. See [the jsonnet element
DOC](/docs/design/elemental/elements/jsonnet).


# Classic Designer (Legacy)
Source: https://www.courier.com/docs/design/templates/classic-designer

The previous template editor, still sending, with no new templates built in it.

Classic Designer is the block-based editor that came before [Design Studio
DOC](/docs/design/templates/design-studio). It is no longer the editor new templates are built in.

## Existing templates keep sending

Nothing changes for a template built in Classic Designer. It stays in your workspace, it keeps its id and its alias, and it keeps sending on the same channels. There is no deadline to move it and no migration step to run.

## Which editor a template uses

Open the template in [Templates](https://app.courier.com/content/templates). The console labels the two editors **Design Studio v2** and **Design Studio Classic**, and the one that opens is the one the template was built in.

The template id doesn't tell you. Both editors produce `nt_` ids, so a template's id says nothing about which editor owns it.

## New templates

Build new templates in [Design Studio
DOC](/docs/design/templates/design-studio). It covers the same channels, adds the block set documented in [block settings
DOC](/docs/design/templates/blocks), and its templates are addressed by the same [id and alias
DOC](/docs/design/templates/template-settings).


# Data mapping for push and inbox
Source: https://www.courier.com/docs/design/templates/data-mapping

Choose which send data fields reach a delivered push or inbox message.

Data mapping decides which of a send's `data` fields reach the delivered push or inbox message.

> [!NOTE]
>
> **You probably don't need this page.** Data mapping applies only to **legacy block-based templates**, the ones built in the older designer. On anything else, your whole `data` object already reaches the device:
>
> * A template built in [Design Studio
>   DOC](/docs/design/templates/design-studio) passes `data` through automatically. Its push and inbox settings still show a **Data mapping** editor, but Courier doesn't evaluate it. The mapping is skipped and the full `data` object is used.
> * A send with inline `content` and no template needs no mapping at all.
>
> If your fields aren't arriving and the template was built in Design Studio, data mapping isn't the cause. See [variables
> DOC](/docs/design/templates/variables) and check the payload in [Logs](https://app.courier.com/logs).

That leaves the legacy case. A block-based template's push or inbox channel renders `data` into variables only unless mapping is on. The push data bag then carries only Courier's tracking keys, and your own fields never leave the send.

## Turn data mapping on

Open the template in the [console](https://app.courier.com/content/templates), then the channel's settings, and go to the **Data Mapping** tab. It appears for push and inbox channels only. Enable it and write a mapping that builds the data object from the incoming request.

![A push channel settings modal with Data Mapping selected, showing the Enabled toggle and a mapping editor that maps the incoming request to the push data payload](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/data-mapping.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=242c4d23f11a9fc6c50f83b6de00a4ed)

The push channel settings modal with the Data Mapping tab selected, showing the toggle and the mapping editor.

Pass the whole `data` object through:

```jsonnet theme={null}
{
  data: request("data"),
}
```

Or name the fields, and mix in values from elsewhere on the request:

```jsonnet theme={null}
{
  data: {
    order_id: request("data.order_id"),
    email: request("profile.email"),
    screen: "order-detail",
  },
}
```

`request()` reads from the send request. The paths are `data`, `profile`, `recipient`, `event`, `brand`, and `message`. Courier evaluates the mapping at send time. Jsonnet is the default processing mode.

## How mapping settings behave

* **Mapping stays as you set it.** Courier seeds the default when a channel is created and doesn't change it afterward.
* **A provider override carries your fields either way.** A [provider override
  DOC](/docs/send/overrides#how-overrides-work) bypasses rendering, so it sends your fields whether or not the template maps anything.

## FAQ

> **My data is not reaching the device. What do I check?**
>
> Check which designer built the template first. A Design Studio template, and a send with inline `content`, already pass `data` through. Look at the payload you sent and at your variable paths, not at mapping. Only a legacy block-based template needs **Data Mapping** turned on in its push or inbox channel settings.

> **I turned Data Mapping on in Design Studio and nothing changed. Why?**
>
> Because the template's content is Elemental, Courier skips the mapping and uses the full `data` object. The editor is a leftover surface on that channel's settings, so there is nothing to configure. Your fields are already being passed through.

> **Does data mapping affect email or SMS?**
>
> Only push and inbox have a data payload for it to fill. Email and SMS render `data` into content through variables.

> **Can I set a mapping over the API?**
>
> Not on its own. Data mapping is a channel setting on the template, so it travels with the template. For a per-send payload, set the fields in a [provider override
> DOC](/docs/send/overrides#how-overrides-work) instead.


# Design Studio
Source: https://www.courier.com/docs/design/templates/design-studio

The visual template editor: canvas, per-channel content, blocks, variables, preview, and publish.

You write a notification here rather than in code, and a product manager can edit the wording after you ship it. One template holds every channel the message goes out on, each with its own content.

![Design Studio: the channel rail and blocks panel on the left, the canvas in the center, and the styles panel on the right](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/design-studio.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=51850c52555d0647e10435c5d0bc6ef2)

## Design a template

**1. Create a Template**

Open [Templates](https://app.courier.com/content/templates), select **Add template**, and choose **Design Studio v2**. Name it and create it.

> [!NOTE]
>
> This page documents **Design Studio v2**. The other editor in the console is [Classic Designer
> DOC](/docs/design/templates/classic-designer).

**2. Pick a channel and its routing**

Select the **Email** channel tab to activate it. Open the **routing selector** in the toolbar to choose which Provider delivers it. Routing configurations are reusable across Templates, so a change applies everywhere. See [routing
DOC](/docs/send/routing).

**3. Add content**

Drag blocks onto the canvas: **Text** for the message, **Button** for the call to action, plus **Heading**, **Image**, **Divider**, and **Spacer**. Select a block to edit it inline. Use the settings panel for alignment, size, and color. Courier auto-saves.

![The template editor: channel rail and blocks on the left, canvas in the center, styles panel on the right](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/design-studio.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=51850c52555d0647e10435c5d0bc6ef2)

**4. Insert a variable**

Type `{{` to open the variable picker, or select the variable icon in the block toolbar. Variables are **double-braced**:

* `{{profile.name}}` for a Profile field
* `{{data.invite_url}}` for send data
* `{{tenant.name}}` and `{{tenant.properties.tier}}` for the [tenant
  DOC](/docs/tenants/context) on the send
* `{{urls.preferences}}` and `{{urls.unsubscribe}}` for the built-in links

Every variable needs its namespace prefix. A bare `{{invite_url}}` doesn't fall back to `data`, so the editor marks it invalid. See [variables
DOC](/docs/design/templates/variables).

**5. Build per-channel variants**

Switch channel tabs to build variants for SMS, push, in-app, and chat. Each channel gets an editor built for its format. Courier adapts shared content to each channel's requirements.

**6. Add translations**

To send the template in more than one language, select the globe icon and pick a language. With **Translate with AI** checked, Courier translates every string, and you review each one next to the default. See [template translations
DOC](/docs/design/elemental/locales#translate-in-design-studio).

**7. Preview and send a test**

Select **Preview & Test**, create a test event, then fill the `data` and `profile` objects with values matching your variables:

```json theme={null}
{
  "data": { "invite_url": "https://www.acme-corp.com/invite" },
  "profile": { "email": "sarah@acme-corp.com", "name": "Sarah Bennett" }
}
```

The preview renders every channel variant with your data. A variable still showing as raw `{{...}}` means the path doesn't match your test event. **Send Test** delivers a live copy to yourself, so you catch broken links before publishing.

**8. Apply a Brand and publish**

Optionally apply a [Brand
DOC](/docs/design/brands) from the toolbar for a consistent logo, colors, header, and footer. Then select **Publish**. Edits stay in the draft until you publish.

Copy the Template ID from the top of the editor.

## Layout

Three areas, left to right:

1. **Channel tabs** switch between Email, SMS, Push, In-App, Slack, and MS Teams.
2. **Canvas** is where you drag blocks and edit content.
3. **Settings** holds the selected block's options.

The toolbar carries the Brand selector, routing selector, version history, the globe icon for [translations
DOC](/docs/design/elemental/locales#translate-in-design-studio), **Preview & Test**, and [template settings
DOC](/docs/design/templates/template-settings) (name, alias, subscription Topic, message tags).

## Channels

Not every block works on every channel.

| Channel | Blocks | Notes |
| - | - | - |
| **Email** | All | Full HTML, images, HTML blocks, Brand header and footer, and custom [fonts&#xA;DOC](/docs/design/elemental/fonts) |
| **SMS** | Text only | No formatting. Variables work. Carrier character limits apply. |
| **Push** | Text only | Title and body. Length limits vary by platform. |
| **In-App** | Text only | Renders in the [Courier Inbox&#xA;DOC](/docs/in-app/overview). |
| **Slack** | Subset | |
| **Microsoft Teams** | Subset | |

## Available blocks

| Block | What it does | Notes |
| - | - | - |
| **Heading** | Large text for titles and section headers | Choose the heading level (H1, H2, H3). A heading is a text block with a heading level, so it also supports variables and alignment. |
| **Text** | Paragraphs of body copy | Rich formatting (bold, italic, links, lists) on email. Variables work on every channel, with plain text on SMS, push, and Inbox. |
| **Image** | Embeds an image | Set the image URL (or a variable), alt text for accessibility, an optional link, and width or alignment. |
| **Button** | Clickable call-to-action button | See [Buttons](#buttons) for label, link, and style settings. |
| **Spacer** | Adds vertical space between blocks | Adjust the height in the block settings. |
| **Divider** | Horizontal line between sections | Set color, thickness, and corner radius in the block settings. |
| **List** | Bulleted or numbered list | See [Lists](#lists) for ordered vs. unordered types and looping over a data array. |
| **Column** | Multi-column layout | See [Columns](#columns) for column count and per-cell styling. |
| **HTML** | Raw HTML for custom markup | See [HTML](#html) for inline blocks and whole-email HTML. |
| **Blockquote** | Quoted or highlighted text for testimonials and pull quotes | Not in the default sidebar yet. Add it from the slash menu or when it is enabled for your workspace. |

## Adding blocks

**1. Select a channel**

Pick a channel from the left sidebar.

**2. Drag a block onto the canvas**

Drag a block from the block sidebar to the spot you want.

**3. Reorder as needed**

Drag blocks up or down to reorder them.

![Block sidebar in Design Studio](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-toolbar.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=0f42bd934972e032d090696d5d9151e1)

Block Sidebar

## Block settings

Click a block and its settings open in the right panel, varying by block type. [Block settings
DOC](/docs/design/templates/blocks) is the reference for every setting each block exposes, with its default. Settings may include:

* **Frame**: padding and margin.
* **Border**: border style and radius.
* **Alignment**: text and content alignment.
* **Colors**: background and text colors.

![Block settings panel](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-block-settings.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=33e2ee15ca27989548d1416b39663b6f)

Block Settings

## Copying and removing blocks

When you select a block, action icons appear:

* **Copy**: duplicate the block directly below.
* **Delete**: remove the block from the canvas.

![Copy and delete block actions](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-block-remove.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=6096682fa0009caedbe187006ef74c76)

Block Actions

## Buttons

Select a button block to open its settings:

* **Label**: text on the button. [Variables
  DOC](/docs/design/templates/variables) work here (e.g. `View {{data.product_name}}`).
* **Link URL**: where the button goes. Variables work here too.
* **Alignment**: left, center, or right.
* **Background color**: button fill color.
* **Border radius**: corner rounding.
* **Border size**: outline thickness.
* **Padding**: space around the button.

![Button block in Design Studio](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-button-new.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=707b04750dd7aa5bf88dcf06466bb8de)

Button Block

## Lists

Select a List block to open its settings:

* **Type**: toggle between **Unordered** (bulleted) and **Ordered** (numbered).
* **Padding**: horizontal and vertical padding in pixels.
* **Loop on**: repeat the list for each item in a data array (see below).

![List block settings panel showing type, padding, and loop on toggle](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-list-settings.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=6437015ed04ab696c3b2e4500f197b99)

List Settings

### Looping over data

The **Loop on** toggle repeats the list for each item in a data array you send on the [Send API](/docs/api-reference/send/send-a-message) call.

**1. Enable Loop on**

Select the List block and turn on **Loop on**.

**2. Set the data path**

Enter a **Data path** pointing to an array in your `data` payload (e.g. `data.order_items`). The path must start with `data.`.

**3. Reference the current item**

In list item text, reference fields on the current item as `{{$.item.name}}` and `{{$.item.price}}`.

Given this Send API payload:

```json Send request lines highlight={6-10} theme={null}
{
  "message": {
    "to": { "user_id": "user_123" },
    "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    "data": {
      "order_items": [
        { "name": "Wireless Mouse", "quantity": 1, "price": "$29.99" },
        { "name": "USB-C Hub", "quantity": 2, "price": "$44.99" },
        { "name": "Laptop Stand", "quantity": 1, "price": "$59.99" }
      ]
    }
  }
}
```

Set the data path to `data.order_items`, then use `{{$.item.name}}`, `{{$.item.quantity}}`, and `{{$.item.price}}` in your list item text. Courier expands the list at send time, one item per array entry.

![Preview showing expanded list items from a looped data array](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-list-preview.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=0710eecbb4f0989c9125b9d7892cd73e)

List Loop Preview

A data path must start with `data.` and point to an array. Design Studio validates it against your [test event
DOC](/docs/design/templates/overview) data, so you catch mismatches before sending.

At render time, Courier's [loop evaluation
DOC](/docs/design/elemental/control-flow#loop) expands every iteration into one list block, so spacing and formatting stay consistent. For loop logic the List block doesn't support (nested loops, conditional items, custom markup), use an [HTML block](#html) with raw Handlebars.

## Columns

A column block starts as a two-column row with equal widths. Each cell is an independent container that accepts any block type, including nested columns.

Select the column block to configure it:

* **Columns count**: choose 1, 2, 3, or 4 columns.
* **Frame**: horizontal and vertical padding (pixels) and background color for each cell.
* **Border**: width, radius, and color for each cell.
* **Conditions**: show or hide the block based on profile or data values.

Frame and border settings apply per cell, so you can style each column independently.

![Column layout settings panel in Design Studio](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-column-cell-settings.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=d5b464554089afd831e5868f508e27de)

Column Layout Settings

Columns render differently per channel:

| Channel | Behavior |
| - | - |
| **Email** | Full multi-column layout using MJML for maximum email client compatibility |
| **Push** | Columns stack vertically (single-column fallback) |
| **SMS** | Not applicable. Content renders as plain text |
| **In-App (Inbox)** | Full support with responsive behavior |

Mobile email clients usually stack columns vertically, so keep to 2 or 3 columns and write content that reads well both side by side and stacked.

## HTML

HTML gives you full control of your markup for custom tables, tracking pixels, or porting an existing HTML email into Courier. There are two ways to use it.

| Your goal | Use | How |
| - | - | - |
| Add one custom section alongside drag-and-drop blocks | Inline HTML block | Add an HTML block in Design Studio |
| Bring an existing full HTML email into Courier | Whole-email HTML | Set `raw.html` on the email channel |
| Add HTML to a template programmatically (API) | Either | A `type: "html"` element inside a channel for a section, or `raw.html` on the email channel for a full document |

### Add an inline HTML block

The HTML block gives you a code editor in the right panel. Enter standard HTML (like `<div>`, `<table>`, or `<img>`) and inline CSS. Your changes appear in the canvas preview as you type.

![HTML block in Design Studio](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-custom-code-new.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=357dd49ae1e721e8f9c8d58d5c24f85e)

HTML Block

**An inline HTML block is a fragment, not a full page.** Leave out `<!DOCTYPE html>`, `<html>`, `<head>`, and `<body>`, because Courier composes your markup alongside the other blocks. For a full document, use [whole-email HTML](#send-a-full-html-email).

The expand icon in the editor's top-right corner opens a larger window.

### Variables and Handlebars

HTML blocks support [variables
DOC](/docs/design/templates/variables) in `{{variable}}` syntax and every [Handlebars helper
DOC](/docs/design/templates/variables), including `{{#if}}` for conditionals and `{{#each}}` for arrays. Inside an inline HTML block, Handlebars resolve automatically, with no transformer to configure.

This is the place for helper expressions. A rich-text block turns `{{` into a variable chip, so a helper call typed there is flagged invalid. An HTML block takes raw Handlebars as written.

```handlebars theme={null}
<ul>
{{#each data.items}}
  <li>{{this.name}}: {{this.price}}</li>
{{/each}}
</ul>
```

Use this for loop structures beyond the [List block's Loop on feature](#lists), such as nested loops or fully custom markup.

![Handlebars and variables in HTML block](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-custom-code-rendered-handlebars.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=7d58900f29fddd2f5da8cd1165c44a67)

Handlebars Example

Variables and Handlebars expressions resolve on send, so [preview mode
DOC](/docs/design/templates/overview) shows the raw syntax rather than sample values.

### Send a full HTML email

To use a complete HTML document, put it on the email [channel
DOC](/docs/design/elemental/elements/channel) node's `raw.html`. Declare the `handlebars` transformer so your `{{variables}}` resolve. The `meta` title sets the subject line, and `raw.html` replaces that channel's rendered body.

```json theme={null}
{
  "content": {
    "version": "2022-01-01",
    "elements": [
      {
        "type": "channel",
        "channel": "email",
        "elements": [
          { "type": "meta", "title": "Your order confirmation" }
        ],
        "raw": {
          "transformers": ["handlebars"],
          "html": "<!DOCTYPE html><html><body><h1>Hi {{name}}</h1><p>Your order shipped.</p></body></html>"
        }
      }
    ]
  }
}
```

This shape works with [Create Notification Template](/docs/api-reference/templates/create-notification-template) and [Replace Notification Content](/docs/api-reference/templates/replace-notification-content), and renders your markup as written.

> [!NOTE]
>
> To add an inline HTML block over the API, put a `type: "html"` element inside the channel's `elements`. [Create Notification Template](/docs/api-reference/templates/create-notification-template) and [Replace Notification Content](/docs/api-reference/templates/replace-notification-content) both accept it. Use it for a fragment, and `raw.html` for a full document.


# Device Preview for email
Source: https://www.courier.com/docs/design/templates/device-preview

Render a template on real email clients and devices, from the editor or the API, and get a screenshot of each.

Device Preview renders your template on real email clients and returns a screenshot from each one. Every screenshot comes from the real app, such as Outlook on Windows, not a simulation.

You can run a preview two ways:

* **[In the editor](#run-a-preview-in-the-editor):** check a template while you design it. Pick a set of clients in Design Studio, run the preview, and fix what breaks before you publish.
* **[With the API](#run-a-preview-with-the-api):** run the same previews from code. An AI agent can preview a template, review the screenshots, and fix what it finds. You can also show the screenshots in your own product, such as next to an email editor your customers use.

Both share the same target sets and history, so a run started from either one shows up in the editor.

![A Device Preview run showing one email rendered on Apple Mail, Gmail, and Outlook, in light and dark mode](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/device-preview-run.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=3a72245c94a9f299aadc73e35df2e628)

A Device Preview run across desktop, mobile, and webmail clients

***

## Run a preview in the editor

Open a template in [Design Studio
DOC](/docs/design/templates/design-studio) and click the **device** icon in the toolbar. Previews render whatever is in the editor right now, including unpublished changes.

Choose a **target set**, the group of clients you want to render on. Every workspace starts with **Courier Recommended**, an 8-client set spanning desktop, mobile, and webmail in both light and dark mode. Build your own from the [full catalog](#supported-clients).

If your template is [localized
DOC](/docs/design/elemental/locales), choose which translation to render. Set test values for any variables, such as `profile.name`.

> [!NOTE]
>
> A variable without a test value renders as nothing, so a greeting reads "Hi , your order has shipped." That's the most common reason a preview looks broken when the template is fine.

Click **Run preview**. Screenshots load as they return, and a full run takes 10 to 120 seconds. Outlook clients are often the last to come back.

### Review the results

Click a screenshot to open it full size, then use the arrows to move through the run. Download any screenshot from the results page.

### Find past runs

Click **Preview history** for past runs, including runs started from the API. Each shows when it ran, how many clients it covered, and which template version it rendered.

Use it to see whether a rendering problem is new or shipped several versions ago.

### Build a target set

Create your own target sets to focus on the variations you care about. You might keep one for Outlook versions, another for dark mode across mobile, and a third for the clients most of your users are on.

Open the **Targets** dropdown and click **Create new set**. Name it, filter the catalog by **Mobile**, **Web**, or **Application**, then add the clients you want. Use the pencil icon to edit a set later.

Sets are shared with your workspace and scoped to the [environment
DOC](/docs/workspaces/environments) you're in. The API calls them device sets, and calls each client a device.

***

## Run a preview with the API

The API runs the same previews as the editor: start a run on a template, check it until every device has reported, then download the screenshots.

The template must be a Design Studio template with an email channel. Runs use the API key's environment, the same way target sets do.

### Start a run

List your device sets with [List Device Sets](/docs/api-reference/previews/list-device-sets) and take the `id` of the set named **Courier Recommended**. Every workspace has one, with its own ID in each environment, so look it up by name:

```json theme={null}
{
  "results": [
    {
      "id": "pvs_01m0g557g5f6fsvbzx13fnk5p3",
      "name": "Courier Recommended",
      "device_ids": [
        "pvd_0rk8bz6ywhbydvhfh6xv0bw8ep",
        "pvd_36m3f6jvvdb5ntjg4ktpwekqws",
        "pvd_6qa25njzggbbbs4kf8azs92qn4",
        "pvd_02h2ecnn2rbgy9x1eptdr0py9z",
        "pvd_5yvs8k8jv9axkv5xsptpd51mvg",
        "pvd_4khhpethbyarsb5z4a354t8er8",
        "pvd_60wzmxv9cjbrbr87w8d7rmrdv9",
        "pvd_4s7rvnng7hbjn8eca8npw4b9pq"
      ],
      "created_at": "2026-08-20T17:58:00.453Z",
      "updated_at": "2026-08-20T17:58:00.453Z"
    }
  ]
}
```

Start the run with [Create Preview Run](/docs/api-reference/previews/create-preview-run). Send an `Idempotency-Key` so a retried request returns the same run instead of starting a second one. Use a new key for each run: a repeated key within 25 hours returns the earlier run.

Pass test values in `data`:

* `data.profile` fills `{{profile.*}}` variables, such as `{{profile.name}}`.
* `data.tenant` fills `{{tenant.*}}` variables, such as `{{tenant.name}}`.
* Every other key fills your template's own data variables, such as `order_id`.

```javascript Node.js theme={null}
const run = await client.notifications.previews.runs.create("nt_01m3d2j79dfk1th1a2r7h494ye", {
  device_set_id: "pvs_01m0g557g5f6fsvbzx13fnk5p3",
  data: {
    profile: { name: "Sarah Bennett", email: "sarah@acme-corp.com" },
    tenant: { name: "Acme Corp" },
    order_id: "ORD-1234",
  },
  "Idempotency-Key": "preview-order-shipped-001",
});

console.log(run.id, run.status); // "pvr_...", "PENDING"
```

```python Python theme={null}
run = client.notifications.previews.runs.create(
    id="nt_01m3d2j79dfk1th1a2r7h494ye",
    device_set_id="pvs_01m0g557g5f6fsvbzx13fnk5p3",
    data={
        "profile": {"name": "Sarah Bennett", "email": "sarah@acme-corp.com"},
        "tenant": {"name": "Acme Corp"},
        "order_id": "ORD-1234",
    },
    idempotency_key="preview-order-shipped-001",
)

print(run.id, run.status)  # "pvr_...", "PENDING"
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/notifications/nt_01m3d2j79dfk1th1a2r7h494ye/previews/runs \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: preview-order-shipped-001" \
  -d '{
    "device_set_id": "pvs_01m0g557g5f6fsvbzx13fnk5p3",
    "data": {
      "profile": { "name": "Sarah Bennett", "email": "sarah@acme-corp.com" },
      "tenant": { "name": "Acme Corp" },
      "order_id": "ORD-1234"
    }
  }'
```

```ruby Ruby theme={null}
run = courier.notifications.previews.runs.create(
  "nt_01m3d2j79dfk1th1a2r7h494ye",
  device_set_id: "pvs_01m0g557g5f6fsvbzx13fnk5p3",
  data: {
    profile: {name: "Sarah Bennett", email: "sarah@acme-corp.com"},
    tenant: {name: "Acme Corp"},
    order_id: "ORD-1234"
  },
  idempotency_key: "preview-order-shipped-001"
)
```

```go Go theme={null}
run, err := client.Notifications.Previews.Runs.New(
	context.TODO(),
	"nt_01m3d2j79dfk1th1a2r7h494ye",
	courier.NotificationPreviewRunNewParams{
		CreatePreviewRunRequest: courier.CreatePreviewRunRequestParam{
			DeviceSetID: courier.String("pvs_01m0g557g5f6fsvbzx13fnk5p3"),
			Data: map[string]any{
				"profile":  map[string]any{"name": "Sarah Bennett", "email": "sarah@acme-corp.com"},
				"tenant":   map[string]any{"name": "Acme Corp"},
				"order_id": "ORD-1234",
			},
		},
		IdempotencyKey: courier.String("preview-order-shipped-001"),
	},
)
```

```java Java theme={null}
RunCreateParams params = RunCreateParams.builder()
    .id("nt_01m3d2j79dfk1th1a2r7h494ye")
    .idempotencyKey("preview-order-shipped-001")
    .createPreviewRunRequest(CreatePreviewRunRequest.builder()
        .deviceSetId("pvs_01m0g557g5f6fsvbzx13fnk5p3")
        .data(CreatePreviewRunRequest.Data.builder()
            .putAdditionalProperty("profile", JsonValue.from(java.util.Map.of(
                "name", "Sarah Bennett", "email", "sarah@acme-corp.com")))
            .putAdditionalProperty("tenant", JsonValue.from(java.util.Map.of("name", "Acme Corp")))
            .putAdditionalProperty("order_id", JsonValue.from("ORD-1234"))
            .build())
        .build())
    .build();
PreviewRun run = client.notifications().previews().runs().create(params);
```

```php PHP theme={null}
$run = $client->notifications->previews->runs->create(
  'nt_01m3d2j79dfk1th1a2r7h494ye',
  deviceSetID: 'pvs_01m0g557g5f6fsvbzx13fnk5p3',
  data: [
    'profile' => ['name' => 'Sarah Bennett', 'email' => 'sarah@acme-corp.com'],
    'tenant' => ['name' => 'Acme Corp'],
    'order_id' => 'ORD-1234',
  ],
  idempotencyKey: 'preview-order-shipped-001',
);
```

```csharp C# theme={null}
var run = await client.Notifications.Previews.Runs.Create(new RunCreateParams
{
    ID = "nt_01m3d2j79dfk1th1a2r7h494ye",
    DeviceSetID = "pvs_01m0g557g5f6fsvbzx13fnk5p3",
    Data = new Dictionary<string, JsonElement>
    {
        { "profile", JsonSerializer.SerializeToElement(new { name = "Sarah Bennett", email = "sarah@acme-corp.com" }) },
        { "tenant", JsonSerializer.SerializeToElement(new { name = "Acme Corp" }) },
        { "order_id", JsonSerializer.SerializeToElement("ORD-1234") },
    },
    IdempotencyKey = "preview-order-shipped-001",
});
```

```bash CLI theme={null}
courier notifications:previews:runs create \
  --api-key "$COURIER_API_KEY" \
  --id nt_01m3d2j79dfk1th1a2r7h494ye \
  --device-set-id pvs_01m0g557g5f6fsvbzx13fnk5p3 \
  --data '{"profile": {"name": "Sarah Bennett", "email": "sarah@acme-corp.com"}, "tenant": {"name": "Acme Corp"}, "order_id": "ORD-1234"}' \
  --idempotency-key preview-order-shipped-001
```

```text MCP theme={null}
With Courier MCP, run a device preview of template nt_01m3d2j79dfk1th1a2r7h494ye on the Courier Recommended set, as Sarah Bennett (sarah@acme-corp.com) at Acme Corp with order ORD-1234.
```

The run comes back right away with status `PENDING` and the devices it will render on:

```json theme={null}
{
  "id": "pvr_01m3d2j8zve8nb25sqfmckfc3g",
  "template_id": "nt_01m3d2j79dfk1th1a2r7h494ye",
  "status": "PENDING",
  "device_ids": [
    "pvd_0rk8bz6ywhbydvhfh6xv0bw8ep",
    "pvd_36m3f6jvvdb5ntjg4ktpwekqws",
    "pvd_6qa25njzggbbbs4kf8azs92qn4",
    "pvd_02h2ecnn2rbgy9x1eptdr0py9z",
    "pvd_5yvs8k8jv9axkv5xsptpd51mvg",
    "pvd_4khhpethbyarsb5z4a354t8er8",
    "pvd_60wzmxv9cjbrbr87w8d7rmrdv9",
    "pvd_4s7rvnng7hbjn8eca8npw4b9pq"
  ],
  "created_at": "2026-09-25T20:02:04.411Z"
}
```

It renders the latest draft unless you pass `template_version`: `published` for the live version, or a published version such as `v002`. A `locale` renders that translation.

### Get the results

A run takes 10 to 120 seconds, and screenshots come back one device at a time. Read the run with [Get Preview Run](/docs/api-reference/previews/get-preview-run) every 10 seconds, for up to 5 minutes.

```javascript Node.js theme={null}
const detail = await client.notifications.previews.runs.retrieve("pvr_01m3d2j8zve8nb25sqfmckfc3g", {
  id: "nt_01m3d2j79dfk1th1a2r7h494ye",
});

console.log(detail.status, detail.results);
```

```python Python theme={null}
detail = client.notifications.previews.runs.retrieve(
    preview_run_id="pvr_01m3d2j8zve8nb25sqfmckfc3g",
    id="nt_01m3d2j79dfk1th1a2r7h494ye",
)

print(detail.status, detail.results)
```

```bash cURL theme={null}
curl https://api.courier.com/notifications/nt_01m3d2j79dfk1th1a2r7h494ye/previews/runs/pvr_01m3d2j8zve8nb25sqfmckfc3g \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
detail = courier.notifications.previews.runs.retrieve(
  "pvr_01m3d2j8zve8nb25sqfmckfc3g",
  id: "nt_01m3d2j79dfk1th1a2r7h494ye"
)
```

```go Go theme={null}
detail, err := client.Notifications.Previews.Runs.Get(
	context.TODO(),
	"pvr_01m3d2j8zve8nb25sqfmckfc3g",
	courier.NotificationPreviewRunGetParams{
		ID: "nt_01m3d2j79dfk1th1a2r7h494ye",
	},
)
```

```java Java theme={null}
RunRetrieveParams params = RunRetrieveParams.builder()
    .id("nt_01m3d2j79dfk1th1a2r7h494ye")
    .previewRunId("pvr_01m3d2j8zve8nb25sqfmckfc3g")
    .build();
PreviewRunDetail detail = client.notifications().previews().runs().retrieve(params);
```

```php PHP theme={null}
$detail = $client->notifications->previews->runs->retrieve(
  'pvr_01m3d2j8zve8nb25sqfmckfc3g',
  id: 'nt_01m3d2j79dfk1th1a2r7h494ye',
);
```

```csharp C# theme={null}
var detail = await client.Notifications.Previews.Runs.Retrieve(new RunRetrieveParams
{
    ID = "nt_01m3d2j79dfk1th1a2r7h494ye",
    PreviewRunID = "pvr_01m3d2j8zve8nb25sqfmckfc3g",
});
```

```bash CLI theme={null}
courier notifications:previews:runs retrieve \
  --api-key "$COURIER_API_KEY" \
  --id nt_01m3d2j79dfk1th1a2r7h494ye \
  --preview-run-id pvr_01m3d2j8zve8nb25sqfmckfc3g
```

```text MCP theme={null}
With Courier MCP, get preview run pvr_01m3d2j8zve8nb25sqfmckfc3g for template nt_01m3d2j79dfk1th1a2r7h494ye and show me each device's screenshot.
```

Each device has its own entry in `results`, in no fixed order, so match entries by `device_id`. A finished device carries a `screenshot_url` and a `thumbnail_url`, and one still rendering has both set to `null`. This run was read partway through, with 2 of its 8 results shown:

```json theme={null}
{
  "id": "pvr_01m3d2j8zve8nb25sqfmckfc3g",
  "template_id": "nt_01m3d2j79dfk1th1a2r7h494ye",
  "template_version": "draft",
  "status": "SUBMITTED",
  "device_ids": [
    "pvd_0rk8bz6ywhbydvhfh6xv0bw8ep",
    "pvd_36m3f6jvvdb5ntjg4ktpwekqws",
    "pvd_6qa25njzggbbbs4kf8azs92qn4",
    "pvd_02h2ecnn2rbgy9x1eptdr0py9z",
    "pvd_5yvs8k8jv9axkv5xsptpd51mvg",
    "pvd_4khhpethbyarsb5z4a354t8er8",
    "pvd_60wzmxv9cjbrbr87w8d7rmrdv9",
    "pvd_4s7rvnng7hbjn8eca8npw4b9pq"
  ],
  "created_at": "2026-09-25T20:02:04.411Z",
  "results": [
    {
      "device_id": "pvd_4khhpethbyarsb5z4a354t8er8",
      "status": "COMPLETED",
      "thumbnail_url": "https://….s3.us-east-1.amazonaws.com/…/thumbnail.png?X-Amz-…",
      "screenshot_url": "https://….s3.us-east-1.amazonaws.com/…/default.png?X-Amz-…"
    },
    {
      "device_id": "pvd_60wzmxv9cjbrbr87w8d7rmrdv9",
      "status": "PROCESSING",
      "thumbnail_url": null,
      "screenshot_url": null
    }
  ]
}
```

The run is done when its `status` is `COMPLETED` or `FAILED`. Each device settles on its own, and one device failing doesn't fail the run:

| Result status | Meaning |
| - | - |
| `PENDING`, `PROCESSING` | Still rendering |
| `COMPLETED` | The screenshot is ready |
| `TIMED_OUT` | The device didn't report in time |
| `UNSUPPORTED` | The device has been retired |
| `FAILED` | The render failed on that device |

This loop checks every 10 seconds for up to 5 minutes, then prints each device's screenshot:

```javascript Node.js theme={null}
const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const deadline = Date.now() + 5 * 60 * 1000;
const read = () => client.notifications.previews.runs.retrieve(run.id, { id: run.template_id });

await wait(10_000);
let detail = await read();
while (!["COMPLETED", "FAILED"].includes(detail.status) && Date.now() < deadline) {
  await wait(10_000);
  detail = await read();
}

for (const result of detail.results) {
  console.log(result.device_id, result.status, result.screenshot_url ?? "");
}
```

```python Python theme={null}
import time

deadline = time.monotonic() + 5 * 60

def read():
    return client.notifications.previews.runs.retrieve(preview_run_id=run.id, id=run.template_id)

time.sleep(10)
detail = read()
while detail.status not in ("COMPLETED", "FAILED") and time.monotonic() < deadline:
    time.sleep(10)
    detail = read()

for result in detail.results:
    print(result.device_id, result.status, result.screenshot_url or "")
```

```bash cURL theme={null}
URL="https://api.courier.com/notifications/nt_01m3d2j79dfk1th1a2r7h494ye/previews/runs/pvr_01m3d2j8zve8nb25sqfmckfc3g"

sleep 10
for attempt in $(seq 1 30); do
  RUN=$(curl -s "$URL" -H "Authorization: Bearer $COURIER_API_KEY")
  STATUS=$(echo "$RUN" | jq -r '.status')
  if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then break; fi
  sleep 10
done

echo "$RUN" | jq -r '.results[] | "\(.device_id) \(.status) \(.screenshot_url // "")"'
```

**Download screenshots when you read the run.** `screenshot_url` and `thumbnail_url` are temporary signed links, so read the run again for fresh ones later. Most screenshots are PNG files, but check each file's `Content-Type` rather than its extension.

### Check email previews with an AI agent

An agent can run a preview, read the screenshots, and fix what it finds. Connect it through the [Courier MCP server
DOC](/docs/resources/mcp) when it works in a chat or code editor, or have it call the API above when it runs in your own code or CI.

With MCP, ask for the preview and the review in one prompt:

```text theme={null}
With Courier MCP, run a device preview of template nt_01m3d2j79dfk1th1a2r7h494ye on the Courier Recommended set, as Sarah Bennett at Acme Corp with order ORD-1234. Check the run every 10 seconds for up to 5 minutes. Review each screenshot and tell me what's broken on each client.
```

Ask it to check for blank gaps from missing variables, copy that doesn't match its section, broken images, Outlook layout breaks, mobile stacking, dark mode contrast, and the subject line.

### Customize the devices

Courier Recommended covers the common clients. To focus on others, list the full catalog with [List Preview Devices](/docs/api-reference/previews/list-preview-devices). Each device has a `pvd_` ID and fields to filter on: `category`, `app`, `platform`, `os`, `os_version`, and `theme`.

For a one-off run, pass `device_ids` instead of `device_set_id`. Send exactly one of the two.

To reuse a list, save it with [Create Device Set](/docs/api-reference/previews/create-device-set). It shows up in the editor's **Targets** dropdown too:

```json theme={null}
{
  "name": "Outlook desktop",
  "device_ids": [
    "pvd_6jftknaab7a55she2qg907nfna",
    "pvd_0f36p8bvkgbynrgt24nh59ajd0",
    "pvd_3j67g4gq17bmyvhddgngpbbjx6",
    "pvd_17j3h8qhx5ajkvxbswyya6zcjn"
  ]
}
```

[Update Device Set](/docs/api-reference/previews/update-device-set) replaces a set's name and devices in full. [Archive Device Set](/docs/api-reference/previews/archive-device-set) archives it, and runs that used it keep their own copy of its devices. Courier Recommended can't be changed, so copy its devices into your own set to adjust them.

### Errors

Courier checks a run request before the run exists, so a rejected request isn't billed.

| Status | When | Message |
| - | - | - |
| `400` | Both or neither of `device_set_id` and `device_ids` | `provide exactly one of device_set_id or device_ids` |
| `400` | A field the request doesn't take, such as `template_id` | `Unrecognized key: "template_id"` |
| `400` | A malformed version, such as `v2` | `template_version: Invalid input` |
| `402` | The previews add-on isn't enabled | `the cross-client previews add-on is required for this workspace` |
| `404` | The template, device set, or run doesn't exist | |
| `409` | Changing or archiving Courier Recommended | `device set … is the Courier default set and cannot be changed or archived` |
| `422` | A device ID that isn't in the catalog | `unknown device id: pvd_…` |
| `422` | A version the template doesn't have | `template … has no version v009` |
| `422` | A template that isn't a Design Studio template | `not a Design Studio template` |

***

## Preview HTML you already have

You don't need to send through Courier to use Device Preview. Bring the HTML email you send from any platform, turn it into a template, and preview it like any other.

**In the editor**, create an email template, open the [HTML editor
DOC](/docs/design/templates/html-email), paste your markup, and run a preview.

**With the API**, create the template with [Create Notification Template](/docs/api-reference/templates/create-notification-template). Put a `meta` element for the subject and an `html` element for the markup inside the email channel. Reference test values by name, such as `{{profile.name}}` and `{{order_id}}`:

```json theme={null}
{
  "notification": {
    "name": "Order shipped",
    "tags": [],
    "brand": null,
    "subscription": null,
    "routing": null,
    "content": {
      "version": "2022-01-01",
      "elements": [
        {
          "type": "channel",
          "channel": "email",
          "elements": [
            { "type": "meta", "title": "Your order has shipped" },
            { "type": "html", "content": "<table role=\"presentation\" width=\"600\"><tr><td>Hi {{profile.name}}, order {{order_id}} is on its way.</td></tr></table>" }
          ]
        }
      ]
    }
  },
  "state": "DRAFT"
}
```

Then [start a run](#start-a-run) on the new template's `id`.

## Pricing

Device Preview is a paid monthly add-on. Enable it in the console under **Settings → Billing**.

Each device in a run is one preview. The add-on comes in three tiers. Each includes a set number of previews per month, and anything beyond that is billed per preview. Included previews reset each month and don't roll over.

| Monthly price | Previews included | Overage per preview |
| -: | -: | -: |
| \$20 | 100 | \$0.20 |
| \$50 | 400 | \$0.15 |
| \$100 | 1,000 | \$0.12 |

## Supported clients

A **client** is one combination of app, device, OS, browser, and color mode. The tables below list the current catalog, and [List Preview Devices](/docs/api-reference/previews/list-preview-devices) always returns the latest one as new devices and OS versions are added.

### Desktop applications

| App | Device | OS | Modes |
| - | - | - | - |
| Apple Mail 16 | Mac | macOS 13 | Light, Dark |
| Outlook 2016 | PC | Windows 10 | Light |
| Outlook 2016 (120 dpi) | PC | Windows 10 | Light |
| Outlook 2019 | PC | Windows 10 | Light |
| Outlook 2019 (120 dpi) | PC | Windows 10 | Light |
| Outlook 2021 | PC | Windows 11 | Light, Dark |
| Outlook 2024 | PC | Windows 11 | Light, Dark |
| Outlook Microsoft 365 | Mac | macOS 13 | Light, Dark |
| Outlook Microsoft 365 | PC | Windows 11 | Light, Dark |
| Outlook Office 365 | PC | Windows 10 | Light, Dark |

### Mobile applications

| App | OS | Devices | Modes |
| - | - | - | - |
| Apple Mail | iOS 16 | iPhone 14, iPhone 14 Pro, iPhone 14 Pro Max | Light, Dark |
| Apple Mail | iOS 17 | iPhone 15, iPhone 15 Plus, iPhone 15 Pro, iPhone 15 Pro Max | Light, Dark |
| Apple Mail | iOS 18 | iPhone 16, iPhone 16 Pro, iPhone 16 Pro Max | Light, Dark |
| Apple Mail | iOS 26 | iPhone 17, iPhone 17 Pro, iPhone 17 Pro Max | Light, Dark |
| Apple Mail | iOS 27 | iPhone 18 Pro | Light, Dark |
| Gmail | iOS 26 | iPhone 16 | Light, Dark |
| Gmail | Android 12 | Pixel 6 | Light, Dark |
| Gmail | Android 13 | Pixel 7 | Light, Dark |
| Gmail | Android 14 | Pixel 8 | Light, Dark |
| Gmail | Android 15 | Pixel 9 | Light, Dark |
| Gmail | Android 16 | Pixel 10 | Light, Dark |
| Outlook | iOS 15 | iPhone 13 | Light, Dark |

### Webmail

| Service | Browsers | OS | Modes |
| - | - | - | - |
| AOL.com | Chrome, Edge, Firefox | Windows 10 | Light, Dark |
| Free.fr | Chrome, Edge, Firefox | Windows 10 | Light, Dark |
| Gmail.com | Chrome, Edge, Firefox | Windows 10 | Light, Dark |
| GMX | Chrome, Edge, Firefox | Windows 10 | Light |
| Libero | Chrome, Edge, Firefox | Windows 10 | Light |
| Microsoft365.com | Chrome, Edge, Firefox | Windows 10 | Light, Dark |
| Outlook.com | Chrome, Edge, Firefox | Windows 10 | Light, Dark |
| T-Online | Chrome, Edge, Firefox | Windows 10 | Light |
| Web.de | Chrome, Edge, Firefox | Windows 10 | Light |
| Yahoo.com | Chrome, Edge, Firefox | Windows 10 | Light, Dark |

## Limits & behavior

* **Each run records the version it rendered.** That's the published version if your draft matches it, or `draft` if the draft has unpublished changes.
* **Preview history is kept for one year.** Runs can't be cancelled or deleted.
* **Screenshots vary by client.** Some show the full inbox, others only the email body.


# Edit email HTML directly
Source: https://www.courier.com/docs/design/templates/html-email

Edit a template's email HTML by hand and format it to render in Gmail, Outlook, and Apple Mail.

> [!NOTE]
>
> [How templates work
> DOC](/docs/design/templates/overview) compares the designer with code.

When the visual designer's blocks aren't enough, edit a template's email HTML directly and format it to render across Gmail, Outlook, and Apple Mail.

## Prerequisites

* [An email template](https://app.courier.com/content/templates)
* Your HTML email markup

## Import and format the HTML

**1. Open the HTML editor**

Open the email template in the designer and click the code icon (`</>`) in the toolbar, then **Start editing**. Courier converts the current blocks to HTML and shows it in the editor.

> [!WARNING]
>
> **Editing HTML is one-directional.**\\
>
> Enabling code editing creates a new version, and switching back to the visual designer discards your HTML changes. Keep a copy of your HTML, or use version history to revert.

**2. Paste and format your HTML**

Paste your markup into the editor. It auto-formats on paste, highlights syntax, and wraps long lines. The email **subject** is edited separately in the subject field above the editor, so it is safe from your body changes.

**3. Add variables and logic**

Use Handlebars in the HTML to personalize each send. Reference the `data` payload (`{{order_id}}`), profile fields (`{{profile.email}}`), and use the full [Handlebars helpers
DOC](/docs/design/templates/variables) for logic and formatting:

```html theme={null}
{{#if premium_user}}
  <div class="premium-banner">Premium Member Benefits</div>
{{/if}}

{{#each items}}
  <tr>
    <td>{{capitalize this.name}}</td>
    <td>{{format this.price style="currency" currency="USD"}}</td>
  </tr>
{{/each}}
```

The preview panel renders your HTML with test data so you can check it before publishing.

**4. Make the HTML email-safe**

Email clients vary widely in their HTML and CSS support. When porting web HTML to email, work through this checklist:

* **Replace flexbox/grid with tables.** Use `<table>`/`<tr>`/`<td>` for layout, with `role="presentation"` on layout tables for accessibility.
* **Move all CSS inline.** External stylesheets and most `<style>` blocks are stripped (Gmail is the exception: it supports `<style>` in the `<head>`).
* **Replace `div` containers with table cells.** Outlook 2019 ignores `max-width` on `<div>`.
* **Set explicit pixel widths.** Percentages are unreliable in nested tables. Use a 600px max-width outer container and keep every section the same width.
* **Use `!important` on class-based styles.** Courier's MJML compiler generates inline styles that win by default, so your custom CSS classes need `!important` to override them (see [CSS class names
  DOC](/docs/design/brands#css-class-names)).
* **Host images externally.** Use absolute URLs. Courier doesn't host images for `src` paths (the exception is [image blocks
  DOC](/docs/design/templates/design-studio)).
* **Add MSO conditionals for Outlook.** Outlook uses Word's rendering engine and needs Outlook-specific table markup.

**5. Add Outlook compatibility**

Outlook 2019 and earlier ignore most CSS beyond basic font, color, margin, padding, and border. Wrap Outlook-specific table structure in MSO conditional comments:

```html theme={null}
<!--[if mso]>
<table role="presentation" width="600" style="width:600px;">
  <tr><td>
<![endif]-->
<table role="presentation" width="100%" style="max-width:600px;">
  <!-- Email content -->
</table>
<!--[if mso]></td></tr></table><![endif]-->
```

For a brand's MJML footer that needs Outlook support, inject the raw table with `<mj-raw>`. If MJML minification is enabled on your workspace, it can strip MSO comments from the compiled output. If your Outlook layout disappears after sending, [contact support](mailto:support@courier.com) to check whether minification is on for your workspace.

**6. Avoid unsupported CSS**

Modern CSS is unsupported or inconsistent in email. Avoid these without a tested fallback: `animation`/`transition` (use GIFs), `position: absolute/fixed`, `flex`/`grid` (use tables), `box-shadow` and `border-radius` (no Outlook), `opacity`, `calc()`, `filter`, pseudo-elements (`:hover`, `:before`), and `object-fit`. Design mobile-first at a 600px max width, since `@media` support is partial.

**7. Preview across clients**

Use the preview panel to check rendering with test data. Then run a [Device Preview
DOC](/docs/design/templates/device-preview) to screenshot the email in Gmail, Outlook, and Apple Mail themselves, in light and dark mode.


# Templates
Source: https://www.courier.com/docs/design/templates/overview

What a template contains, its draft and published versions, and sending it by ID or alias.

A template defines what a notification says, how it looks, and how it behaves across channels.

You build it once, then send it through email, SMS, push, chat, or in-app. A template is Elemental content plus channel, routing, and brand settings. Build it visually in the designer, or as code through the Templates API.

## Which one to use

A template built in the designer and one managed through the API are the same object, and it is [Elemental
DOC](/docs/design/elemental/overview) content either way. The difference is where your team would rather work.

> **[Design a template](/docs/design/templates/design-studio)**
>
> Build it in the visual editor: drag-and-drop blocks, per-channel content, test-data previews, and version history.
>
> Best when PMs, designers, and developers work on content together.

> **[Template API](/docs/design/templates/api)**
>
> Manage it as JSON: create, update, and publish from your codebase, review changes in Git, and test payloads in CI.
>
> Best when templates live in code, or you would rather not click through a UI.

## How it works

Beyond content, a template carries the settings that shape a send:

* **Channels** it can go out on
* Reusable **routing**, primary and fallback
* A **Brand** for consistent styling
* **Conditional logic** to show or hide content by data or preference
* **Variables** that personalize each recipient's version
* **Translations** so each recipient gets their language

See [variables & Handlebars
DOC](/docs/design/templates/variables) for the personalization model, [brands
DOC](/docs/design/brands) for styling, and [template translations
DOC](/docs/design/elemental/locales) for languages.

### Draft, publish, and version history

Editing a template updates its **draft**. Publishing snapshots the draft as the active **version**. A normal send renders the published version, so recipients never see an unfinished edit. Version history lets you compare versions side by side and roll back. A message's log records the version it used, so you can trace a rendering change to a publish.

[Go live
GUIDE](/docs/guides/go-live) covers reviewing a draft before you publish it.

### How a template is performing

Sends, deliveries, opens, clicks, and errors are reported per template, split by channel and provider. [Analytics
DOC](/docs/monitor/analytics) shows them in the Courier app, and [template metrics
DOC](/docs/monitor/template-metrics) returns the same series over the API for your own dashboards.

## Send it by ID or alias

Both paths end the same way. Pass the Template ID and the data its variables need to [Send a message](/docs/api-reference/send/send-a-message):

```javascript Node.js theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { email: 'sarah@acme-corp.com' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { invite_url: 'https://www.acme-corp.com/invite' },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {"email": "sarah@acme-corp.com"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"invite_url": "https://www.acme-corp.com/invite"},
    },
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "email": "sarah@acme-corp.com" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "invite_url": "https://www.acme-corp.com/invite" }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: { email: "sarah@acme-corp.com" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { invite_url: "https://www.acme-corp.com/invite" }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"invite_url": "https://www.acme-corp.com/invite",
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("invite_url", "https://www.acme-corp.com/invite")))
        .build())
    .build();
client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['email' => 'sarah@acme-corp.com'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['invite_url' => 'https://www.acme-corp.com/invite'],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "invite_url", JsonSerializer.SerializeToElement("https://www.acme-corp.com/invite") },
        },
    },
};

await client.Send.Message(parameters);
```

```bash CLI theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"email":"sarah@acme-corp.com"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"invite_url":"https://www.acme-corp.com/invite"}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to sarah@acme-corp.com with the invite URL.
```

That `template` field accepts either form:

| Value | Looks like | Where it comes from |
| - | - | - |
| **Template ID** | `nt_01kx4h2jdafq8bk9aftxak4b40` | Generated by Courier, shown in the template's settings |
| **Alias** | `order-confirmation` | A name you assign, in the template's **settings** under **Alias** or with `notification.alias` over the API |

An alias is the readable name your code keeps while the template behind it changes. You assign one in the template's **settings**, under **Alias**, or with `notification.alias` when you create or replace the template over the API. Setting it to `null` clears it, and leaving it out keeps the existing alias. It then sits exactly where the ID sat, and nothing else about the request changes.

Three rules govern them:

* **A template can have many aliases.** Old and new names can both resolve during a rename.
* **An alias points at one template at a time.** Moving it to another template repoints every send that uses that name.
* **An alias works anywhere the ID works.** Nothing else in the request changes.

That second rule is the useful one. Repointing an alias switches the content behind a send with no deploy, and it switches it for every caller at once.

## FAQ

> **Can I manage a template in code and in the designer?**
>
> Both operate on the same template. One team can edit in the designer while another manages it through the API. Coordinate publishes so a draft edit isn't overwritten.

> **What is the difference between a draft and a published template?**
>
> Edits go to the draft. Publishing makes the draft the active version. Normal sends render the published version.

> **Can I reference a template by a stable name?**
>
> Assign an alias and pass it as `template` on the send, so your code references a human-readable name instead of the generated ID.


# Design Studio template settings
Source: https://www.courier.com/docs/design/templates/template-settings

Every template setting in Design Studio: name, alias, conditions, and per-channel options.

Access template settings by clicking the **gear icon** in the template editor toolbar. The settings panel includes template-level configuration and per-channel settings.

![Template settings panel in Design Studio](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-settings.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=f480195ee0d7a6242cbd551f54adf1b2)

Template Settings Panel

## Template settings

### General

| Setting | Description |
| - | - |
| **Template Name** | Display name for the template in your template list |
| **Template ID** | Unique identifier used when sending notifications via API. Click the copy icon to copy. |
| **Subscription Topic** | Group templates under a subscription topic to let end users manage preferences for multiple notifications at once. See [Preferences&#xA;DOC](/docs/recipients/preferences/overview). |
| **Message Tags** | Tags applied to all messages sent from this template. Useful for filtering in logs and analytics. Tags can't be changed after messages are sent. |
| **Delete Template** | Permanently delete the template. This action can't be undone. |

### Alias

Create aliases for your template to use in API calls instead of the Template ID. Aliases make your API calls more readable and let you change the underlying template without updating your application code.

![Template alias configuration](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-alias.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=24903edf98bdb09cd02347dd01fffeaf)

Template Aliases

For example, if you create an alias `order-confirmation`, you can reference it in your Send API call:

```json theme={null}
{
  "message": {
    "template": "order-confirmation",
    "to": { "user_id": "user_123" }
  }
}
```

> [!NOTE]
>
> Each alias can only be mapped to one template at a time.

### Conditions

Enable or disable the entire template based on conditions evaluated at send time. These conditions apply to all channels in the template, not to a specific channel or integration.

![Template conditions configuration](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-conditions.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=f503bd29f1ddc3a972ad9ce28bece902)

Template Conditions

* **Conditions role**: Toggle between Enable (send if conditions match) or Disable (skip if conditions match)
* **Add condition**: Click to add conditions based on data passed in your API request

## Channel settings

Each channel configured in your template has its own settings section. Click a channel in the sidebar to configure channel-specific options.

Channel settings vary by channel type but may include:

* **Provider configuration** - Which integration to use for sending
* **Channel-specific conditions** - Send conditions that apply only to this channel
* **Formatting options** - Channel-specific formatting like email subject lines


# Template variables and Handlebars helpers
Source: https://www.courier.com/docs/design/templates/variables

Use variables and Handlebars helpers to personalize a template with send data and profile fields.

Variables insert personalized values into a notification.

Courier resolves them from the notification context, which is split into namespaces. Handlebars helpers add logic and formatting on top.

## How it works

### Write a variable in double braces

A variable is Handlebars, so it takes **double** braces:

```handlebars theme={null}
Hi {{profile.first_name}}, your order {{data.order_id}} shipped.
```

In [Design Studio
DOC](/docs/design/templates/design-studio), typing `{{` opens the variable picker and turns your selection into a variable chip. The chip is stored and rendered as `{{path}}`, so what you author and what sends are the same syntax.

> [!NOTE]
>
> **Single braces are legacy.** `{order.total}` still resolves on templates built in the older designer, and Courier keeps rendering them so existing templates keep working. Everything new uses `{{ }}`, including everything in Design Studio. Prefer `{{data.order.total}}`.

### The data namespaces

Every variable is **namespaced**. Name the root you want:

| Root | Comes from | Example |
| - | - | - |
| `data` | The `data` object on [Send a message](/docs/api-reference/send/send-a-message) | `{{data.order.total}}` |
| `profile` | The recipient's [profile&#xA;DOC](/docs/recipients/overview) (send or stored) | `{{profile.email}}` |
| `tenant` | The [tenant&#xA;DOC](/docs/tenants/context) on the send | `{{tenant.name}}` |
| `brand` | The [brand&#xA;DOC](/docs/design/brands) applied to the send | `{{brand.colors.primary}}` |

Courier also populates built-in values, including `{{urls.unsubscribe}}`, `{{urls.preferences}}`, `{{recipient}}`, `{{courier.environment}}`, and `{{datetime.year}}`. Variable names must be camelCase or snake\_case. Dashes break resolution (`{{data.first_name}}` works, `{{data.first-name}}` doesn't).

> [!NOTE]
>
> **Tenant values resolve through `{{tenant.*}}`, not a `context.` namespace.** `{{context.tenant_id}}` resolves to an empty string. Read the tenant through `{{tenant.id}}` instead.

### Prefix every variable

Design Studio templates are **strictly scoped**. An unprefixed name doesn't fall back to `data`:

| Write this | Not this |
| - | - |
| `{{data.orderId}}` | `{{orderId}}` |
| `{{profile.first_name}}` | `{{first_name}}` |
| `{{tenant.name}}` | `{{name}}` |

A bare name is worse than empty: helper names are reserved, so `{{path}}` invokes the `path` **helper** rather than reading `data.path`. Design Studio marks any variable that doesn't start with `profile.`, `data.`, or `tenant.` (or `$.item.` inside a List loop) as invalid, with the message `"<name>" must start with profile., data., tenant., or $.item. (in loops)`.

Templates created in the older designer, and inline `content` sends, are default-scoped: `data` is spread onto the root there, so a bare `{{orderId}}` does resolve. Prefixing works in both modes, so prefix everywhere.

### What `tenant` exposes

`tenant` is a narrow projection of the tenant on the send, not the whole account record:

| Variable | Resolves to |
| - | - |
| `{{tenant.id}}` | The tenant's ID |
| `{{tenant.name}}` | The tenant's name |
| `{{tenant.properties.*}}` | Any property you stored on the tenant, such as `{{tenant.properties.tier}}` |

Nothing else on the tenant is reachable. `default_preferences`, `notification_map`, `parent_tenant_id`, `brand_id`, and `user_profile` stay out of template content by design.

Design Studio autocompletes `tenant.id`, `tenant.name`, and the property paths it finds across your workspace's tenants, so the picker matches what sends.

> [!NOTE]
>
> On a default-scoped (older designer) template, a `data.tenant` field you send yourself still wins over the namespace. Reach the real tenant with `{{path "tenant.name"}}` there.

### Handlebars helpers

Helpers run on **every channel**, on Design Studio templates and older ones alike. Every example below runs against this send payload:

```json theme={null}
{
  "data": {
    "order": { "total": 42, "note": "Leave at the front door", "created_at": "2026-01-05T23:30:00Z" },
    "items": [{ "name": "widget", "price": 9.99 }, { "name": "gizmo", "price": 32.01 }],
    "subtotal": 40, "tax": 2, "tags": "new,vip"
  }
}
```

`profile.name` isn't set, so `default` has something to fall back to.

| Helper | Template | Renders |
| - | - | - |
| `default` | `{{default profile.name "there"}}` | `there` |
| `capitalize` | `{{capitalize "foo"}}` | `Foo` |
| `truncate` | `{{truncate data.order.note 9 "..."}}` | `Leave at ...` |
| `concat` | `{{concat "hello" " " "world"}}` | `hello world` |
| `trim` | `{{trim "  a string  "}}` | `a string` |
| `split` | `{{#each (split data.tags ",")}}` | `new`, then `vip` |
| `format` | `{{format "$%.2f" data.order.total}}` | `$42.00` |
| `datetime-format` | `{{datetime-format data.order.created_at "%b %d, %Y"}}` | `Jan 05, 2026` |
| `add` | `{{add data.subtotal data.tax}}` | `42` |
| `t` | `{{t "Salutation"}}` | `Salutation` from your [workspace translation strings&#xA;DOC](/docs/design/elemental/locales#workspace-translation-strings) for the recipient's locale |

Note the `data.` prefix on every payload field. Under strict scope a bare `{{order.total}}` resolves to nothing, and a bare `{{format}}` calls the helper with no arguments.

`replace-all` is a block helper, so it wraps the text it changes:

```handlebars theme={null}
{{#replace-all "_" " "}}snake_case_value{{/replace-all}}
```

Renders `snake case value`.

> **Every other helper**
>
> * **Logic:** `{{#if}}`, `{{#each}}`, `{{#with}}`, `and`, `or`, `not`, `contains`, `condition`, `conditional`, `filter`
> * **Values:** `set`, `var`, `path`, `params`, `inc`, `range`, `json-parse`, `parse-string`
> * **Text:** `line-break`, `text-direction`, `trim-left`, `trim-right`
> * **Math:** `subtract` (`sub`), `multiply` (`product`), `divide`, `mod`, `abs`, `ceil`, `floor`, `round`
>
> `condition` takes the operator as a string: `{{#if (condition data.plan "==" "pro")}}`. The editor
> autocompletes all of them.

### Where to write a helper expression

Design Studio's rich-text blocks are built for variables, not expressions: typing `{{` opens the variable picker, and a helper call typed into a chip fails the chip's name validation and turns red.

Put helper expressions in an [HTML block
DOC](/docs/design/templates/design-studio#html), where the editor accepts raw Handlebars and the whole helper set resolves at send time:

```handlebars theme={null}
<p>Total: {{format "$%.2f" (add data.subtotal data.tax)}}</p>
<ul>
{{#each data.items}}
  <li>{{capitalize this.name}}: {{format "$%.2f" this.price}}</li>
{{/each}}
</ul>
```

Whole-email `raw.html` and the Templates API accept helper expressions the same way.

### Combine helpers

Helpers nest, so one expression can feed another:

```handlebars theme={null}
{{#each data.items}}
  {{capitalize this.name}}: {{format "$%.2f" this.price}}
{{/each}}

Total: {{format "$%.2f" (add data.subtotal data.tax)}}
```

Renders:

```text theme={null}
  Widget: $9.99
  Gizmo: $32.01

Total: $42.00
```

For currency, use `format`. It's [sprintf](https://en.wikipedia.org/wiki/Printf), so write the currency symbol into the format string.

### Control whitespace

A `~` inside the braces strips every space and newline touching that side of the expression.
Whitespace doesn't show in a delivered message, so the effect only reads side by side. With
`data.name` set to `Sarah`:

```handlebars theme={null}
Hi   {{data.name}}   !
Hi   {{~data.name}}   !
Hi   {{data.name~}}   !
Hi   {{~data.name~}}   !
```

Those four lines render as:

```text theme={null}
Hi   Sarah   !
HiSarah   !
Hi   Sarah!
HiSarah!
```

Use it to keep an SMS or a plain-text email from picking up stray blank lines.

### Helpers that only work on some channels

Three helpers are registered per channel rather than everywhere. Using one where it isn't
registered raises `Missing helper: "<name>"` at send time:

| Helper | Works on | Not on |
| - | - | - |
| `markdown` | Email, Slack | SMS, push, inbox, Microsoft Teams |
| `jsonnet` | Slack, Microsoft Teams | everything else |
| `javascript` | Slack, Microsoft Teams | everything else |

These three are also absent from the helper set that resolves Elemental block fields, so a
Design Studio text or heading block can't call them on any channel. Everything in the
list above this table is channel-independent. If a universal helper raises `Missing helper`,
that is a bug worth reporting, not a limit.

### The preview doesn't resolve helpers

The designer's preview substitutes variables, but it doesn't run helpers. A
`{{truncate}}` or `{{datetime-format}}` can look wrong in the preview and render
correctly in the delivered message.

Send a test message to check helper output. The delivered message is the only
place helper results are real.

### Format dates and times

`datetime-format` turns an ISO 8601 timestamp or a milliseconds-since-epoch value into a formatted date using strftime-style tokens. Pass the value, a format string, and optionally an [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones):

```html theme={null}
{{datetime-format data.order.created_at "%b %d, %Y %I:%M %p" "America/New_York"}}
<!-- Jan 05, 2026 06:30 PM -->

{{datetime-format data.order.created_at "%d-%b-%Y"}}
<!-- 05-Jan-2026 -->
```

| Token | Meaning | Example |
| - | - | - |
| `%A` / `%a` | Weekday, full / abbreviated | Monday / Mon |
| `%B` / `%b` | Month, full / abbreviated | January / Jan |
| `%d` | Day of month, zero-padded | 05 |
| `%m` | Month number, zero-padded | 01 |
| `%Y` / `%y` | Year, with / without century | 2026 / 26 |
| `%H` / `%I` | Hour, 24- / 12-hour, zero-padded | 23 / 11 |
| `%M` / `%S` | Minute / second, zero-padded | 30 / 09 |
| `%p` | AM or PM | PM |
| `%z` | Timezone abbreviation (needs the timezone argument) | EST |

Include the timezone argument to convert the value into that zone. `%z` then renders its abbreviation. `datetime-format` throws if a numeric input isn't an integer count of milliseconds.

### When a variable is missing

Rendering is non-strict by default, and a send never fails on a missing field. A missing `{{ }}` variable renders as an **empty string**. A missing legacy single-brace variable renders as the literal placeholder (`{order.total}`).

For an inline fallback, use the `default` helper: `{{default profile.first_name "there"}}`.

The template's **Advanced** settings carry a **Throw on variable not found** checkbox, still marked Beta. After rendering, Courier scans the output for a leftover placeholder. Finding one raises `VariableNotFound`, so that provider's send fails and [Logs](https://app.courier.com/logs) names what it found.

> [!NOTE]
>
> **Throw on variable not found catches only a single-brace `{order.total}` placeholder.**\\
>
> The check looks for a single-brace placeholder still sitting in the rendered output. A `{{ }}` variable that resolved to nothing rendered as an empty string, so there is nothing left to find. Every variable in a Design Studio template is `{{ }}`, so turning the setting on there changes nothing. Use `default` for a fallback, and a test send to catch a wrong path.

## FAQ

> **What happens if a variable is missing at send time?**
>
> A `{{ }}` variable renders as an empty string and the send succeeds. Use `{{default data.value "fallback"}}` to supply a fallback. **Throw on variable not found** in the template's Advanced settings only fires on a leftover single-brace `{path}`, so it has no effect on a template authored in Design Studio.

> **Why does my variable render empty?**
>
> Almost always a missing prefix. Design Studio templates are strictly scoped, so `{{orderId}}` doesn't read `data.orderId`. Write `{{data.orderId}}`. Check for a red chip in the editor: it means the name doesn't start with `profile.`, `data.`, or `tenant.`. A bare name that matches a helper (`{{path}}`, `{{format}}`, `{{default}}`) calls the helper instead of reading your field.

> **What is the difference between the data and profile namespaces?**
>
> `data` is the payload you pass on the send. `profile` is the recipient's stored or inline profile. Both need their prefix.

> **Can I use a tenant's properties in a template?**
>
> `{{tenant.id}}`, `{{tenant.name}}`, and `{{tenant.properties.<path>}}` resolve from the tenant on the send, and Design Studio autocompletes the property paths it finds across your tenants. Other fields on the tenant record aren't reachable from template content.

> **Do Handlebars helpers work in Design Studio templates?**
>
> The full universal helper set resolves at send time on every channel. The designer's rich-text blocks are the one constraint: typing `{{` there opens the variable picker, so write helper expressions in an HTML block, in whole-email `raw.html`, or through the Templates API. Remember the `data.` prefix on payload fields.

> **How do I format a date or currency?**
>
> Use `datetime-format` for dates. For currency, `format` takes a sprintf pattern, so `{{format "$%.2f" data.order.total}}` renders `$42.00`.

> **How do I format a date like DD-Mmm-YYYY?**
>
> Use `datetime-format` with strftime tokens: `{{datetime-format data.order.created_at "%d-%b-%Y"}}` renders `05-Jan-2026`. Add a time and AM/PM with `%I:%M %p`, and pass an IANA timezone as the third argument to convert the value into that zone.

> **I am migrating from SendWithUs. Do my helpers still work?**
>
> `swu_datetimeformat`, `swu_iso8601_to_time`, and `swu_timestamp_to_time` are registered alongside the universal helpers, so existing templates keep working.

> **Why can't I reference to.given\_name in a template?**
>
> The recipient `to` object isn't a variable namespace. `to.given_name` doesn't resolve, and the editor marks it invalid: `"to.given_name" must start with profile., data., tenant., or $.item. (in loops)`. Reference recipient values through `profile.given_name` when they are stored on the profile, or pass them on the send's `data` and use `data.given_name`.


# AI agent quickstart: set up Courier in three steps
Source: https://www.courier.com/docs/get-started/ai-agent-quickstart

Set up Courier in Claude Code, Cursor, Codex, or any coding agent in three steps: save your API key, install Courier Skills, and connect the MCP server.

**1. Save your key to your local environment**

Copy your API key from [Settings → API Keys](https://app.courier.com/settings/api-keys). In your project folder, run this in your terminal with your key in place of `YOUR_COURIER_API_KEY`. Running it in your terminal keeps the key out of your agent's chat.

```bash macOS / Linux theme={null}
printf '\nCOURIER_API_KEY=YOUR_COURIER_API_KEY\n' >> .env
```

```powershell Windows theme={null}
Add-Content .env "`nCOURIER_API_KEY=YOUR_COURIER_API_KEY`n" -NoNewline
```

**2. Install Courier Skills and send a test email**

[Courier Skills
DOC](/docs/resources/skills) gives your agent Courier's own guidance on the API and each channel, so it writes working Courier code on the first try instead of guessing.

Paste this into your agent. It keeps `.env` out of git, installs the skill, and emails you a test from a new template. Approve the install command when your agent asks, then look for "Courier is set up" in your inbox.

```text Your agent wrap theme={null}
Set up Courier in this project.

1. Make sure .env is in .gitignore.
2. Run: npx skills add trycourier/courier-skills -y
3. Read .agents/skills/courier/SKILL.md. Using COURIER_API_KEY from .env, create and publish a Courier email template named "Welcome to Courier" with the subject "Courier is set up" and a haiku based on the user's name and domain. Then ask me for my email address and send that template to it with routing method "single" on the "email" channel and "agent-setup" in metadata.tags.
```

**3. Connect to the Courier MCP server**

The [Courier MCP server
DOC](/docs/resources/mcp) lets your agent work in your Courier workspace from the chat: send test notifications, check what was delivered, and read the logs when something fails.

Paste this into your agent. It connects the server with the key in `.env`. Restart your agent when it asks, then ask it to list your Courier templates to check the connection.

```text Your agent wrap theme={null}
Connect the Courier MCP server.

1. Run: npx add-mcp@2 https://mcp.courier.com -n courier -t http -h "api_key: KEY" -a AGENT -g -y
   - KEY is the COURIER_API_KEY value in .env. Read it in your shell so it never appears in this chat.
   - AGENT is your add-mcp agent name, for example claude-code, cursor, or codex.
2. Tell me to restart you so the Courier tools load.
```

[Build with AI
DOC](/docs/get-started/build-with-ai) covers what each tool does, the Courier CLI, and docs built for agents.


# Build with AI: agent skills, MCP server, and CLI
Source: https://www.courier.com/docs/get-started/build-with-ai

Connect Claude Code, Cursor, Codex, or any AI coding agent to Courier with Courier Skills, the MCP server, the CLI, and docs built for agents to read.

Your AI coding agent needs two things to build notifications with Courier: knowledge of how Courier works, and access to your workspace. [Courier Skills](/docs/resources/skills) gives it the first. The [MCP server](/docs/resources/mcp) and the [Courier CLI](/docs/resources/cli) give it the second.

Install Courier Skills so the agent knows how to build with Courier. It needs no API key:

```bash theme={null}
npx skills add trycourier/courier-skills
```

Then connect the MCP server so the agent can create templates, send test notifications, and read delivery logs in your workspace. In Claude Code:

```bash theme={null}
claude mcp add --transport http courier https://mcp.courier.com --header api_key:YOUR_COURIER_API_KEY
```

[MCP server](/docs/resources/mcp) has setup for Claude Code, Cursor, Codex, VS Code, and nine other clients.

## Courier Skills

Courier Skills gives your coding agent Courier's own guidance: how to call the API, which feature fits each job, and the rules each channel needs. Your agent gets Courier code right the first time, so it codes faster and spends fewer tokens searching docs or retrying calls that fail. It loads only the files a task needs, and it can debug the Courier code you already have.

The skill touches nothing in your workspace, so it needs no API key. [Courier Skills](/docs/resources/skills) covers the Claude Code plugin and how to check it loaded.

## MCP server

The hosted MCP server at `https://mcp.courier.com` turns the Courier API into tools your agent calls from a chat session. That makes it easy to test and debug with Courier without leaving your agent: send a test notification, check what was delivered, and read the logs when something fails. Ask in plain language:

```text wrap theme={null}
Create a profile for user_123 with sarah@acme-corp.com, send them my welcome template, and show me the delivery status.
```

**Tool calls run with the key you connect.** A production key sends to real users, so connect a Test key while you build. [MCP tools](/docs/resources/mcp/tools) lists every tool and marks which ones write.

## Courier CLI

The CLI covers the same API as the MCP server, as shell commands an agent, script, or CI job can run:

```bash theme={null}
npm install -g @trycourier/cli
export COURIER_API_KEY="YOUR_COURIER_API_KEY"

courier send message \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40"
```

[Courier CLI](/docs/resources/cli) covers flags and output formats. [CLI recipes](/docs/resources/cli/recipes) has a command for each common task.

## Docs for agents

Every docs page is available in a form agents read cheaply, with no API key:

| Source | Use it for |
| - | - |
| `https://www.courier.com/docs/mcp` | A docs MCP server that searches and reads every page and the OpenAPI specs |
| Any page URL + `.md` | One page as plain markdown |
| [`llms.txt`](https://www.courier.com/docs/llms.txt) | An index of every page, per the [llms.txt standard](https://llmstxt.org/) |
| [`llms-full.txt`](https://www.courier.com/docs/llms-full.txt) | The full docs in one file |

**`llms-full.txt` is over 3 MB**, enough to crowd out your code in a coding session. Point the agent at the docs MCP server or single `.md` pages instead.

## API keys

The MCP server and the CLI need a key. [Create one in Settings → API Keys](https://app.courier.com/settings/api-keys).

Each key belongs to one [environment](/docs/workspaces/environments). A Test key comes with a testing provider, so the agent can send before you set up a real one.

## FAQ

> **What is the difference between Courier Skills and the MCP server?**
>
> Courier Skills changes the code your agent writes and touches nothing in your workspace. The MCP server gives the agent tools that call the Courier API, so it can create templates, send notifications, and read delivery logs. Most setups install both.

> **Which AI coding tools work with Courier?**
>
> Courier Skills installs into Claude Code, Cursor, Codex, Windsurf, Cline, and any tool that loads agent skills. The MCP server has setup steps for Claude Code, Cursor, Codex, VS Code, Windsurf, Gemini CLI, Antigravity, Zed, Warp, OpenCode, Grok Build, Devin, and Claude Desktop.

> **Can an AI agent send a real notification through Courier?**
>
> An agent connected to the MCP server or CLI sends through the same API your application uses. A Test key keeps sends in your Test environment. A production key reaches real users.

> **Does Courier have an MCP server for its documentation?**
>
> Courier hosts a docs MCP server at `https://www.courier.com/docs/mcp`. It needs no API key and is separate from the API MCP server at `https://mcp.courier.com`.


# Build your first journey
Source: https://www.courier.com/docs/get-started/build-your-first-journey

Build a three-day workout email series with the Journeys API, then start it from your code.

> [!TIP]
>
> **Build it with your AI agent.** We highly recommend it: set up your agent with the [AI agent quickstart
> DOC](/docs/get-started/ai-agent-quickstart), then ask it to build this.

A journey sends a series of messages from one event, like a signup. In this example, you'll build a three-day kickoff series with the API for Acme Fit, a workout app. New members get one workout email a day for their first three days.

**1. Get your API key**

Copy a key from [Settings → API Keys](https://app.courier.com/settings/api-keys) and export it. Every example reads it from `COURIER_API_KEY`.

```bash theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
```

**2. Create the journey**

[Create a Journey](/docs/api-reference/journeys/create-a-journey) takes a name and a node list. Every journey starts with a trigger and ends with an exit. The **API Invoke** trigger lets your code start each run.

```javascript Node.js theme={null}
// npm install @trycourier/courier
import Courier from "@trycourier/courier";

const client = new Courier(); // reads COURIER_API_KEY

const journey = await client.journeys.create({
  name: "New member kickoff",
  nodes: [
    { type: "trigger", trigger_type: "api-invoke" },
    { type: "exit" },
  ],
});

console.log("Journey ID:", journey.id);
```

```python Python theme={null}
# pip install trycourier
from courier import Courier

client = Courier()  # reads COURIER_API_KEY

journey = client.journeys.create(
    name="New member kickoff",
    nodes=[
        {"type": "trigger", "trigger_type": "api-invoke"},
        {"type": "exit"},
    ],
)

print("Journey ID:", journey.id)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/journeys \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New member kickoff",
    "nodes": [
      { "type": "trigger", "trigger_type": "api-invoke" },
      { "type": "exit" }
    ]
  }'
```

```ruby Ruby theme={null}
# gem install trycourier
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

journey = courier.journeys.create(
  name: "New member kickoff",
  nodes: [
    {type: "trigger", trigger_type: "api-invoke"},
    {type: "exit"}
  ]
)

puts("Journey ID: #{journey.id}")
```

```go Go theme={null}
// go get github.com/trycourier/courier-go/v4
client := courier.NewClient(option.WithAPIKey(os.Getenv("COURIER_API_KEY")))

journey, err := client.Journeys.New(context.TODO(), courier.JourneyNewParams{
	CreateJourneyRequest: courier.CreateJourneyRequestParam{
		Name: "New member kickoff",
		Nodes: []courier.JourneyNodeUnionParam{
			{OfAPIInvokeTrigger: &courier.JourneyAPIInvokeTriggerNodeParam{
				Type:        courier.JourneyAPIInvokeTriggerNodeTypeTrigger,
				TriggerType: courier.JourneyAPIInvokeTriggerNodeTriggerTypeAPIInvoke,
			}},
			{OfExit: &courier.JourneyExitNodeParam{Type: courier.JourneyExitNodeTypeExit}},
		},
	},
})
if err != nil {
	panic(err.Error())
}

fmt.Println("Journey ID:", journey.ID)
```

```java Java theme={null}
CourierClient client = CourierOkHttpClient.builder()
    .apiKey(System.getenv("COURIER_API_KEY"))
    .build();

CreateJourneyRequest createParams = CreateJourneyRequest.builder()
    .name("New member kickoff")
    .addNode(JourneyApiInvokeTriggerNode.builder()
        .type(JourneyApiInvokeTriggerNode.Type.TRIGGER)
        .triggerType(JourneyApiInvokeTriggerNode.TriggerType.API_INVOKE)
        .build())
    .addNode(JourneyExitNode.builder().type(JourneyExitNode.Type.EXIT).build())
    .build();

JourneyResponse journey = client.journeys().create(createParams);
System.out.println("Journey ID: " + journey.id());
```

```php PHP theme={null}
$client = new Client(apiKey: getenv('COURIER_API_KEY'));

$journey = $client->journeys->create(
  name: 'New member kickoff',
  nodes: [
    ['type' => 'trigger', 'trigger_type' => 'api-invoke'],
    ['type' => 'exit'],
  ],
);

echo 'Journey ID: ' . $journey->id . PHP_EOL;
```

```csharp C# theme={null}
CourierClient client = new() { ApiKey = Environment.GetEnvironmentVariable("COURIER_API_KEY") };

JourneyCreateParams createParams = new()
{
    Name = "New member kickoff",
    Nodes =
    [
        new JourneyApiInvokeTriggerNode { Type = "trigger", TriggerType = "api-invoke" },
        new JourneyExitNode { Type = "exit" },
    ],
};

var journey = await client.Journeys.Create(createParams);
Console.WriteLine($"Journey ID: {journey.ID}");
```

```bash CLI theme={null}
# npm install -g @trycourier/cli
courier journeys create \
  --name "New member kickoff" \
  --node '{"type": "trigger", "trigger_type": "api-invoke"}' \
  --node '{"type": "exit"}'
```

The response returns the journey's `id`. Every call below uses it.

**3. Write the three emails**

[Create a journey template](/docs/api-reference/journeys/create-a-notification-template-scoped-to-a-journey) once per email. The `meta` element's `title` is the subject, and `action` renders a button. `scope: "strict"` means every variable names its source: `data.` for what you send with the run, `profile.` for the user.

```javascript Node.js theme={null}
function createEmail(name, elements) {
  return client.journeys.templates.create(journey.id, {
    channel: "email",
    state: "PUBLISHED",
    notification: {
      name,
      tags: [],
      brand: null,
      subscription: null,
      content: {
        version: "2022-01-01",
        scope: "strict",
        elements: [{ type: "channel", channel: "email", elements }],
      },
    },
  });
}

const day1 = await createEmail("Day 1", [
  { type: "meta", title: "Day 1: your {{data.level}} workout" },
  {
    type: "text",
    content:
      "Welcome to Acme Fit, {{profile.first_name}}. Your first {{data.minutes}}-minute workout covers the basics: a warm-up, three moves, and a cooldown.",
  },
  { type: "action", content: "Start Day 1", href: "https://example.com/day-1" },
]);

const day2 = await createEmail("Day 2", [
  { type: "meta", title: "Day 2: two new moves" },
  {
    type: "text",
    content:
      "Same {{data.minutes}} minutes, two new moves. Go at your own pace and pause whenever you need to.",
  },
  { type: "action", content: "Start Day 2", href: "https://example.com/day-2" },
]);

const day3 = await createEmail("Day 3", [
  { type: "meta", title: "Day 3: your first full routine" },
  {
    type: "text",
    content:
      "Put the moves from Days 1 and 2 together in a full {{data.level}} routine. Finish it to unlock your weekly plan.",
  },
  { type: "action", content: "Start Day 3", href: "https://example.com/day-3" },
]);
```

```python Python theme={null}
def create_email(name, elements):
    return client.journeys.templates.create(
        journey.id,
        channel="email",
        state="PUBLISHED",
        notification={
            "name": name,
            "tags": [],
            "brand": None,
            "subscription": None,
            "content": {
                "version": "2022-01-01",
                "scope": "strict",
                "elements": [{"type": "channel", "channel": "email", "elements": elements}],
            },
        },
    )

day1 = create_email("Day 1", [
    {"type": "meta", "title": "Day 1: your {{data.level}} workout"},
    {
        "type": "text",
        "content": "Welcome to Acme Fit, {{profile.first_name}}. Your first {{data.minutes}}-minute workout covers the basics: a warm-up, three moves, and a cooldown.",
    },
    {"type": "action", "content": "Start Day 1", "href": "https://example.com/day-1"},
])

day2 = create_email("Day 2", [
    {"type": "meta", "title": "Day 2: two new moves"},
    {
        "type": "text",
        "content": "Same {{data.minutes}} minutes, two new moves. Go at your own pace and pause whenever you need to.",
    },
    {"type": "action", "content": "Start Day 2", "href": "https://example.com/day-2"},
])

day3 = create_email("Day 3", [
    {"type": "meta", "title": "Day 3: your first full routine"},
    {
        "type": "text",
        "content": "Put the moves from Days 1 and 2 together in a full {{data.level}} routine. Finish it to unlock your weekly plan.",
    },
    {"type": "action", "content": "Start Day 3", "href": "https://example.com/day-3"},
])
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/journeys/YOUR_JOURNEY_ID/templates \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "state": "PUBLISHED",
    "notification": {
      "name": "Day 1",
      "tags": [],
      "brand": null,
      "subscription": null,
      "content": {
        "version": "2022-01-01",
        "scope": "strict",
        "elements": [
          {
            "type": "channel",
            "channel": "email",
            "elements": [
              { "type": "meta", "title": "Day 1: your {{data.level}} workout" },
              {
                "type": "text",
                "content": "Welcome to Acme Fit, {{profile.first_name}}. Your first {{data.minutes}}-minute workout covers the basics: a warm-up, three moves, and a cooldown."
              },
              {
                "type": "action",
                "content": "Start Day 1",
                "href": "https://example.com/day-1"
              }
            ]
          }
        ]
      }
    }
  }'
```

```ruby Ruby theme={null}
day1 = courier.journeys.templates.create(
  "YOUR_JOURNEY_ID",
  channel: "email",
  state: "PUBLISHED",
  notification: {
    name: "Day 1",
    tags: [],
    brand: nil,
    subscription: nil,
    content: {
      version: "2022-01-01",
      scope: "strict",
      elements: [
        {
          type: "channel",
          channel: "email",
          elements: [
            {type: "meta", title: "Day 1: your {{data.level}} workout"},
            {type: "text", content: "Welcome to Acme Fit, {{profile.first_name}}. Your first {{data.minutes}}-minute workout covers the basics: a warm-up, three moves, and a cooldown."},
            {type: "action", content: "Start Day 1", href: "https://example.com/day-1"}
          ]
        }
      ]
    }
  }
)

puts("Day 1 template ID: #{day1.id}")
```

```go Go theme={null}
// Elemental children carry no typed fields, so pass the notification as raw JSON.
notification := param.Override[courier.JourneyTemplateCreateRequestNotificationParam](json.RawMessage(`{
  "name": "Day 1",
  "tags": [],
  "brand": null,
  "subscription": null,
  "content": {
    "version": "2022-01-01",
    "scope": "strict",
    "elements": [
      {
        "type": "channel",
        "channel": "email",
        "elements": [
          { "type": "meta", "title": "Day 1: your {{data.level}} workout" },
          { "type": "text", "content": "Welcome to Acme Fit, {{profile.first_name}}. Your first {{data.minutes}}-minute workout covers the basics: a warm-up, three moves, and a cooldown." },
          { "type": "action", "content": "Start Day 1", "href": "https://example.com/day-1" }
        ]
      }
    ]
  }
}`))

day1, err := client.Journeys.Templates.New(
	context.TODO(),
	"YOUR_JOURNEY_ID",
	courier.JourneyTemplateNewParams{
		JourneyTemplateCreateRequest: courier.JourneyTemplateCreateRequestParam{
			Channel:      "email",
			State:        param.NewOpt("PUBLISHED"),
			Notification: notification,
		},
	},
)
if err != nil {
	panic(err.Error())
}

fmt.Println("Day 1 template ID:", day1.ID)
```

```java Java theme={null}
TemplateCreateParams templateParams = TemplateCreateParams.builder()
    .templateId("YOUR_JOURNEY_ID")
    .journeyTemplateCreateRequest(JourneyTemplateCreateRequest.builder()
        .channel("email")
        .state("PUBLISHED")
        .notification(JourneyTemplateCreateRequest.Notification.builder()
            .name("Day 1")
            .tags(java.util.List.of())
            .brand(java.util.Optional.empty())
            .subscription(java.util.Optional.empty())
            .content(JourneyTemplateCreateRequest.Notification.Content.builder()
                .version(JourneyTemplateCreateRequest.Notification.Content.Version._2022_01_01)
                .scope(JourneyTemplateCreateRequest.Notification.Content.Scope.STRICT)
                .addElement(ElementalChannelNodeWithType.builder()
                    .type(ElementalChannelNodeWithType.Type.CHANNEL)
                    .channel("email")
                    .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                        java.util.Map.of("type", "meta", "title", "Day 1: your {{data.level}} workout"),
                        java.util.Map.of("type", "text", "content", "Welcome to Acme Fit, {{profile.first_name}}. Your first {{data.minutes}}-minute workout covers the basics: a warm-up, three moves, and a cooldown."),
                        java.util.Map.of("type", "action", "content", "Start Day 1", "href", "https://example.com/day-1"))))
                    .build())
                .build())
            .build())
        .build())
    .build();

JourneyTemplateGetResponse day1 = client.journeys().templates().create(templateParams);
System.out.println("Day 1 template ID: " + day1.id());
```

```php PHP theme={null}
$day1 = $client->journeys->templates->create(
  'YOUR_JOURNEY_ID',
  channel: 'email',
  state: 'PUBLISHED',
  notification: [
    'name' => 'Day 1',
    'tags' => [],
    'brand' => null,
    'subscription' => null,
    'content' => [
      'version' => '2022-01-01',
      'scope' => 'strict',
      'elements' => [[
        'type' => 'channel',
        'channel' => 'email',
        'elements' => [
          ['type' => 'meta', 'title' => 'Day 1: your {{data.level}} workout'],
          ['type' => 'text', 'content' => 'Welcome to Acme Fit, {{profile.first_name}}. Your first {{data.minutes}}-minute workout covers the basics: a warm-up, three moves, and a cooldown.'],
          ['type' => 'action', 'content' => 'Start Day 1', 'href' => 'https://example.com/day-1'],
        ],
      ]],
    ],
  ],
);

echo 'Day 1 template ID: ' . $day1->id . PHP_EOL;
```

```csharp C# theme={null}
TemplateCreateParams templateParams = new()
{
    TemplateID = "YOUR_JOURNEY_ID",
    Channel = "email",
    State = "PUBLISHED",
    Notification = new()
    {
        Name = "Day 1",
        Tags = [],
        Brand = null,
        Subscription = null,
        Content = new()
        {
            Version = "2022-01-01",
            Scope = "strict",
            // Elemental nodes expose no typed content property, so build the node from raw JSON.
            Elements =
            [
                ElementalChannelNodeWithType.FromRawUnchecked(
                    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                    {
                      "type": "channel",
                      "channel": "email",
                      "elements": [
                        { "type": "meta", "title": "Day 1: your {{data.level}} workout" },
                        { "type": "text", "content": "Welcome to Acme Fit, {{profile.first_name}}. Your first {{data.minutes}}-minute workout covers the basics: a warm-up, three moves, and a cooldown." },
                        { "type": "action", "content": "Start Day 1", "href": "https://example.com/day-1" }
                      ]
                    }
                    """)),
            ],
        },
    },
};

var day1 = await client.Journeys.Templates.Create(templateParams);
Console.WriteLine($"Day 1 template ID: {day1.ID}");
```

```bash CLI theme={null}
courier journeys:templates create \
  --template-id YOUR_JOURNEY_ID \
  --channel email \
  --state PUBLISHED \
  --notification '{"name": "Day 1", "tags": [], "brand": null, "subscription": null, "content": {"version": "2022-01-01", "scope": "strict", "elements": [{"type": "channel", "channel": "email", "elements": [{"type": "meta", "title": "Day 1: your {{data.level}} workout"}, {"type": "text", "content": "Welcome to Acme Fit, {{profile.first_name}}. Your first {{data.minutes}}-minute workout covers the basics: a warm-up, three moves, and a cooldown."}, {"type": "action", "content": "Start Day 1", "href": "https://example.com/day-1"}]}]}}'
```

Each call returns the template's `id`, which you need in the next step. The Node.js and Python tabs create all three emails. In the other tabs, run the same call twice more with these names and elements:

```json Elements for the other two emails theme={null}
{
  "Day 2": [
    { "type": "meta", "title": "Day 2: two new moves" },
    {
      "type": "text",
      "content": "Same {{data.minutes}} minutes, two new moves. Go at your own pace and pause whenever you need to."
    },
    { "type": "action", "content": "Start Day 2", "href": "https://example.com/day-2" }
  ],
  "Day 3": [
    { "type": "meta", "title": "Day 3: your first full routine" },
    {
      "type": "text",
      "content": "Put the moves from Days 1 and 2 together in a full {{data.level}} routine. Finish it to unlock your weekly plan."
    },
    { "type": "action", "content": "Start Day 3", "href": "https://example.com/day-3" }
  ]
}
```

A journey run sends each template's published version, which is why each one is created with `state: "PUBLISHED"`. Publishing the journey doesn't publish its templates.

**4. Wire the nodes**

[Replace a Journey](/docs/api-reference/journeys/replace-a-journey) sets the full node list. Nodes run in array order, so this list is the whole series. Each send node points at one of your templates by its `id` in `message.template`. Delays take an ISO 8601 duration. Both delays here are `PT1M` (one minute) so you can watch the whole series land in about two minutes.

```javascript Node.js theme={null}
await client.journeys.replace(journey.id, {
  name: "New member kickoff",
  nodes: [
    { type: "trigger", trigger_type: "api-invoke" },
    { type: "send", channel: "email", message: { template: day1.id } },
    { type: "delay", mode: "duration", duration: "PT1M" },
    { type: "send", channel: "email", message: { template: day2.id } },
    { type: "delay", mode: "duration", duration: "PT1M" },
    { type: "send", channel: "email", message: { template: day3.id } },
    { type: "exit" },
  ],
});
```

```python Python theme={null}
client.journeys.replace(
    journey.id,
    name="New member kickoff",
    nodes=[
        {"type": "trigger", "trigger_type": "api-invoke"},
        {"type": "send", "channel": "email", "message": {"template": day1.id}},
        {"type": "delay", "mode": "duration", "duration": "PT1M"},
        {"type": "send", "channel": "email", "message": {"template": day2.id}},
        {"type": "delay", "mode": "duration", "duration": "PT1M"},
        {"type": "send", "channel": "email", "message": {"template": day3.id}},
        {"type": "exit"},
    ],
)
```

```bash cURL theme={null}
curl -X PUT https://api.courier.com/journeys/YOUR_JOURNEY_ID \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New member kickoff",
    "nodes": [
      { "type": "trigger", "trigger_type": "api-invoke" },
      { "type": "send", "channel": "email", "message": { "template": "DAY_1_TEMPLATE_ID" } },
      { "type": "delay", "mode": "duration", "duration": "PT1M" },
      { "type": "send", "channel": "email", "message": { "template": "DAY_2_TEMPLATE_ID" } },
      { "type": "delay", "mode": "duration", "duration": "PT1M" },
      { "type": "send", "channel": "email", "message": { "template": "DAY_3_TEMPLATE_ID" } },
      { "type": "exit" }
    ]
  }'
```

```ruby Ruby theme={null}
courier.journeys.replace(
  "YOUR_JOURNEY_ID",
  name: "New member kickoff",
  nodes: [
    {type: "trigger", trigger_type: "api-invoke"},
    {type: "send", channel: "email", message: {template: "DAY_1_TEMPLATE_ID"}},
    {type: "delay", mode: "duration", duration: "PT1M"},
    {type: "send", channel: "email", message: {template: "DAY_2_TEMPLATE_ID"}},
    {type: "delay", mode: "duration", duration: "PT1M"},
    {type: "send", channel: "email", message: {template: "DAY_3_TEMPLATE_ID"}},
    {type: "exit"}
  ]
)
```

```go Go theme={null}
_, err = client.Journeys.Replace(
	context.TODO(),
	"YOUR_JOURNEY_ID",
	courier.JourneyReplaceParams{
		CreateJourneyRequest: courier.CreateJourneyRequestParam{
			Name: "New member kickoff",
			Nodes: []courier.JourneyNodeUnionParam{
				{OfAPIInvokeTrigger: &courier.JourneyAPIInvokeTriggerNodeParam{
					Type:        courier.JourneyAPIInvokeTriggerNodeTypeTrigger,
					TriggerType: courier.JourneyAPIInvokeTriggerNodeTriggerTypeAPIInvoke,
				}},
				{OfSend: &courier.JourneySendNodeParam{
					Type:    courier.JourneySendNodeTypeSend,
					Channel: courier.JourneySendNodeChannelEmail,
					Message: courier.JourneySendNodeMessageParam{Template: param.NewOpt("DAY_1_TEMPLATE_ID")},
				}},
				{OfDelayForDuration: &courier.JourneyDelayDurationNodeParam{
					Type:     courier.JourneyDelayDurationNodeTypeDelay,
					Mode:     courier.JourneyDelayDurationNodeModeDuration,
					Duration: "PT1M",
				}},
				{OfSend: &courier.JourneySendNodeParam{
					Type:    courier.JourneySendNodeTypeSend,
					Channel: courier.JourneySendNodeChannelEmail,
					Message: courier.JourneySendNodeMessageParam{Template: param.NewOpt("DAY_2_TEMPLATE_ID")},
				}},
				{OfDelayForDuration: &courier.JourneyDelayDurationNodeParam{
					Type:     courier.JourneyDelayDurationNodeTypeDelay,
					Mode:     courier.JourneyDelayDurationNodeModeDuration,
					Duration: "PT1M",
				}},
				{OfSend: &courier.JourneySendNodeParam{
					Type:    courier.JourneySendNodeTypeSend,
					Channel: courier.JourneySendNodeChannelEmail,
					Message: courier.JourneySendNodeMessageParam{Template: param.NewOpt("DAY_3_TEMPLATE_ID")},
				}},
				{OfExit: &courier.JourneyExitNodeParam{Type: courier.JourneyExitNodeTypeExit}},
			},
		},
	},
)
if err != nil {
	panic(err.Error())
}
```

```java Java theme={null}
CreateJourneyRequest nodes = CreateJourneyRequest.builder()
    .name("New member kickoff")
    .addNode(JourneyApiInvokeTriggerNode.builder()
        .type(JourneyApiInvokeTriggerNode.Type.TRIGGER)
        .triggerType(JourneyApiInvokeTriggerNode.TriggerType.API_INVOKE)
        .build())
    .addNode(JourneySendNode.builder()
        .type(JourneySendNode.Type.SEND)
        .channel(JourneySendNode.Channel.EMAIL)
        .message(JourneySendNode.Message.builder().template("DAY_1_TEMPLATE_ID").build())
        .build())
    .addNode(JourneyDelayDurationNode.builder()
        .type(JourneyDelayDurationNode.Type.DELAY)
        .mode(JourneyDelayDurationNode.Mode.DURATION)
        .duration("PT1M")
        .build())
    .addNode(JourneySendNode.builder()
        .type(JourneySendNode.Type.SEND)
        .channel(JourneySendNode.Channel.EMAIL)
        .message(JourneySendNode.Message.builder().template("DAY_2_TEMPLATE_ID").build())
        .build())
    .addNode(JourneyDelayDurationNode.builder()
        .type(JourneyDelayDurationNode.Type.DELAY)
        .mode(JourneyDelayDurationNode.Mode.DURATION)
        .duration("PT1M")
        .build())
    .addNode(JourneySendNode.builder()
        .type(JourneySendNode.Type.SEND)
        .channel(JourneySendNode.Channel.EMAIL)
        .message(JourneySendNode.Message.builder().template("DAY_3_TEMPLATE_ID").build())
        .build())
    .addNode(JourneyExitNode.builder().type(JourneyExitNode.Type.EXIT).build())
    .build();

client.journeys().replace(JourneyReplaceParams.builder()
    .templateId("YOUR_JOURNEY_ID")
    .createJourneyRequest(nodes)
    .build());
```

```php PHP theme={null}
$client->journeys->replace(
  'YOUR_JOURNEY_ID',
  name: 'New member kickoff',
  nodes: [
    ['type' => 'trigger', 'trigger_type' => 'api-invoke'],
    ['type' => 'send', 'channel' => 'email', 'message' => ['template' => 'DAY_1_TEMPLATE_ID']],
    ['type' => 'delay', 'mode' => 'duration', 'duration' => 'PT1M'],
    ['type' => 'send', 'channel' => 'email', 'message' => ['template' => 'DAY_2_TEMPLATE_ID']],
    ['type' => 'delay', 'mode' => 'duration', 'duration' => 'PT1M'],
    ['type' => 'send', 'channel' => 'email', 'message' => ['template' => 'DAY_3_TEMPLATE_ID']],
    ['type' => 'exit'],
  ],
);
```

```csharp C# theme={null}
JourneyReplaceParams replaceParams = new()
{
    TemplateID = "YOUR_JOURNEY_ID",
    Name = "New member kickoff",
    Nodes =
    [
        new JourneyApiInvokeTriggerNode { Type = "trigger", TriggerType = "api-invoke" },
        new JourneySendNode { Type = "send", Channel = "email", Message = new() { Template = "DAY_1_TEMPLATE_ID" } },
        new JourneyDelayDurationNode { Type = "delay", Mode = "duration", Duration = "PT1M" },
        new JourneySendNode { Type = "send", Channel = "email", Message = new() { Template = "DAY_2_TEMPLATE_ID" } },
        new JourneyDelayDurationNode { Type = "delay", Mode = "duration", Duration = "PT1M" },
        new JourneySendNode { Type = "send", Channel = "email", Message = new() { Template = "DAY_3_TEMPLATE_ID" } },
        new JourneyExitNode { Type = "exit" },
    ],
};

await client.Journeys.Replace(replaceParams);
```

```bash CLI theme={null}
courier journeys replace \
  --template-id YOUR_JOURNEY_ID \
  --name "New member kickoff" \
  --node '{"type": "trigger", "trigger_type": "api-invoke"}' \
  --node '{"type": "send", "channel": "email", "message": {"template": "DAY_1_TEMPLATE_ID"}}' \
  --node '{"type": "delay", "mode": "duration", "duration": "PT1M"}' \
  --node '{"type": "send", "channel": "email", "message": {"template": "DAY_2_TEMPLATE_ID"}}' \
  --node '{"type": "delay", "mode": "duration", "duration": "PT1M"}' \
  --node '{"type": "send", "channel": "email", "message": {"template": "DAY_3_TEMPLATE_ID"}}' \
  --node '{"type": "exit"}'
```

> [!WARNING]
>
> Before real signups, replace the nodes again with `P1D` (one day) for both delays and publish. Runs use the published version, so a journey left on `PT1M` sends all three emails in two minutes.

**5. Publish**

[Publish a Journey](/docs/api-reference/journeys/publish-a-journey) makes this version the one new runs use. Runs already in flight finish on the version they started with.

```javascript Node.js theme={null}
await client.journeys.publish(journey.id);
```

```python Python theme={null}
client.journeys.publish(journey.id)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/journeys/YOUR_JOURNEY_ID/publish \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
courier.journeys.publish("YOUR_JOURNEY_ID")
```

```go Go theme={null}
_, err = client.Journeys.Publish(context.TODO(), "YOUR_JOURNEY_ID", courier.JourneyPublishParams{})
if err != nil {
	panic(err.Error())
}
```

```java Java theme={null}
client.journeys().publish("YOUR_JOURNEY_ID");
```

```php PHP theme={null}
$client->journeys->publish('YOUR_JOURNEY_ID');
```

```csharp C# theme={null}
await client.Journeys.Publish(new JourneyPublishParams { TemplateID = "YOUR_JOURNEY_ID" });
```

```bash CLI theme={null}
courier journeys publish --template-id YOUR_JOURNEY_ID
```

**6. Start it from your signup code**

[Invoke a Journey](/docs/api-reference/journeys/invoke-a-journey) starts one run for one user. Call it from your signup code right after you create the account, using the journey ID you saved in step 2. To try it now with a Test key, replace `sarah@example.com` with the address you signed up with, so the series lands in your inbox. Test includes a built-in email provider for that address. Any other address, or a Production key, needs [an email provider of your own
GUIDE](/docs/guides/send-your-first-email).

```javascript Node.js theme={null}
const { runId } = await client.journeys.invoke("YOUR_JOURNEY_ID", {
  user_id: "user_123",
  profile: { email: "sarah@example.com", first_name: "Sarah" },
  data: { level: "beginner", minutes: 20 },
});
```

```python Python theme={null}
response = client.journeys.invoke(
    "YOUR_JOURNEY_ID",
    user_id="user_123",
    profile={"email": "sarah@example.com", "first_name": "Sarah"},
    data={"level": "beginner", "minutes": 20},
)
run_id = response.run_id
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/journeys/YOUR_JOURNEY_ID/invoke \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "profile": { "email": "sarah@example.com", "first_name": "Sarah" },
    "data": { "level": "beginner", "minutes": 20 }
  }'
```

```ruby Ruby theme={null}
response = courier.journeys.invoke(
  "YOUR_JOURNEY_ID",
  user_id: "user_123",
  profile: {email: "sarah@example.com", first_name: "Sarah"},
  data: {level: "beginner", minutes: 20}
)
run_id = response.run_id
```

```go Go theme={null}
response, err := client.Journeys.Invoke(
	context.TODO(),
	"YOUR_JOURNEY_ID",
	courier.JourneyInvokeParams{
		JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
			UserID:  courier.String("user_123"),
			Profile: map[string]any{"email": "sarah@example.com", "first_name": "Sarah"},
			Data:    map[string]any{"level": "beginner", "minutes": 20},
		},
	},
)
if err != nil {
	panic(err.Error())
}
runID := response.RunID
```

```java Java theme={null}
JourneyInvokeParams invokeParams = JourneyInvokeParams.builder()
    .templateId("YOUR_JOURNEY_ID")
    .journeysInvokeRequest(JourneysInvokeRequest.builder()
        .userId("user_123")
        .profile(JourneysInvokeRequest.Profile.builder()
            .putAdditionalProperty("email", JsonValue.from("sarah@example.com"))
            .putAdditionalProperty("first_name", JsonValue.from("Sarah"))
            .build())
        .data(JourneysInvokeRequest.Data.builder()
            .putAdditionalProperty("level", JsonValue.from("beginner"))
            .putAdditionalProperty("minutes", JsonValue.from(20))
            .build())
        .build())
    .build();

String runId = client.journeys().invoke(invokeParams).runId();
```

```php PHP theme={null}
$response = $client->journeys->invoke(
  'YOUR_JOURNEY_ID',
  userID: 'user_123',
  profile: ['email' => 'sarah@example.com', 'first_name' => 'Sarah'],
  data: ['level' => 'beginner', 'minutes' => 20],
);
$runId = $response->runID;
```

```csharp C# theme={null}
JourneyInvokeParams invokeParams = new()
{
    TemplateID = "YOUR_JOURNEY_ID",
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "email", JsonSerializer.SerializeToElement("sarah@example.com") },
        { "first_name", JsonSerializer.SerializeToElement("Sarah") },
    },
    Data = new Dictionary<string, JsonElement>()
    {
        { "level", JsonSerializer.SerializeToElement("beginner") },
        { "minutes", JsonSerializer.SerializeToElement(20) },
    },
};

var response = await client.Journeys.Invoke(invokeParams);
var runId = response.RunID;
```

```bash CLI theme={null}
courier journeys invoke \
  --template-id YOUR_JOURNEY_ID \
  --user-id user_123 \
  --profile '{"email": "sarah@example.com", "first_name": "Sarah"}' \
  --data '{"level": "beginner", "minutes": 20}'
```

```text MCP theme={null}
With Courier MCP, start my New member kickoff journey for user_123 (Sarah, sarah@example.com) with data {"level": "beginner", "minutes": 20}.
```

The run starts in the background, so the call returns before anything sends. The Day 1 email goes out within seconds, and the response carries a `runId`:

```json theme={null}
{ "runId": "778b97e1-4850-4d56-87b7-b4c9b2d88004" }
```

**7. Watch the run**

[List steps for a Journey run](/docs/api-reference/journeys/list-steps-for-a-journey-run) returns each node the run reached, in node order rather than the order they ran. Every step shares the run's `created_at`, so the examples sort by `updated_at`, the time each step last changed state. The first delay reads `WAITING` until its minute is up, and each send step carries the `message_id` it produced.

```javascript Node.js theme={null}
const { steps } = await client.journeys.runs.listSteps(runId);
steps
  .sort((a, b) => (a.updated_at ?? "").localeCompare(b.updated_at ?? ""))
  .forEach((s) => console.log(s.action, s.status, s.message_id ?? ""));
```

```python Python theme={null}
steps = client.journeys.runs.list_steps(run_id).steps
for s in sorted(steps, key=lambda s: s.updated_at or ""):
    print(s.action, s.status, s.message_id or "")
```

```bash cURL theme={null}
# Sorting uses jq (https://jqlang.org).
curl https://api.courier.com/journeys/runs/YOUR_RUN_ID/steps \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  | jq '.steps | sort_by(.updated_at)[] | {action, status, message_id}'
```

```ruby Ruby theme={null}
courier.journeys.runs.list_steps(run_id).steps.sort_by { |s| s.updated_at.to_s }.each do |s|
  puts("#{s.action} #{s.status} #{s.message_id}")
end
```

```go Go theme={null}
// Add "sort" to your imports.
stepsResponse, err := client.Journeys.Runs.ListSteps(context.TODO(), runID)
if err != nil {
	panic(err.Error())
}
steps := stepsResponse.Steps
sort.Slice(steps, func(i, j int) bool { return steps[i].UpdatedAt < steps[j].UpdatedAt })
for _, s := range steps {
	fmt.Println(s.Action, s.Status, s.MessageID)
}
```

```java Java theme={null}
client.journeys().runs().listSteps(runId).steps().stream()
    .sorted(java.util.Comparator.comparing((JourneyRunStep s) -> s.updatedAt().orElse("")))
    .forEach(s -> System.out.println(s.action() + " " + s.status() + " " + s.messageId().orElse("")));
```

```php PHP theme={null}
$steps = $client->journeys->runs->listSteps($runId)->steps;
usort($steps, fn($a, $b) => strcmp($a->updatedAt ?? '', $b->updatedAt ?? ''));

foreach ($steps as $s) {
  echo $s->action . ' ' . $s->status . ' ' . ($s->messageID ?? '') . PHP_EOL;
}
```

```csharp C# theme={null}
var stepsResponse = await client.Journeys.Runs.ListSteps(new RunListStepsParams { RunID = runId });

foreach (var s in stepsResponse.Steps.OrderBy(step => step.UpdatedAt))
{
    Console.WriteLine($"{s.Action} {s.Status} {s.MessageID}");
}
```

```bash CLI theme={null}
# Sorting uses jq (https://jqlang.org).
courier journeys:runs list-steps --run-id YOUR_RUN_ID \
  | jq '.steps | sort_by(.updated_at)[] | {action, status, message_id}'
```

The journey's **Logs** tab in [Journeys](https://app.courier.com/orchestration/journeys) draws the same run on the canvas. See [journey logs
DOC](/docs/monitor/logs#journey-logs).

## FAQ

> **Why didn't an email arrive?**
>
> Check that you published the journey and created each template with `state: "PUBLISHED"`. Then look up the step's `message_id` in [Logs](https://app.courier.com/logs). Delivering to real addresses needs an [email provider of your own
> GUIDE](/docs/guides/send-your-first-email).

> **Can I edit the journey in the canvas?**
>
> The canvas and the API build the same object, so the journey opens in [Journeys](https://app.courier.com/orchestration/journeys) like any other. To build one in the canvas from the start, follow [Create your first journey
> GUIDE](/docs/guides/create-your-first-journey).

> **How do I stop the series for one user?**
>
> Add `"cancelation_token": "kickoff-{{recipient}}"` to the create or replace body. `{{recipient}}` resolves to the `user_id` you invoke with, so Sarah's run carries `kickoff-user_123`. Cancel that token when she unsubscribes or deletes her account, and her remaining emails don't send. See [Cancel a run
> DOC](/docs/journeys/invoke#cancel-a-run).

> **How do I skip users who already got started?**
>
> Add a branch node after the first delay that checks whether the user already finished Day 1, and end the run on that path. [Build an onboarding sequence
> GUIDE](/docs/guides/build-an-onboarding-sequence) walks through it.

> **What happens if my signup code retries the invoke?**
>
> Each invoke starts a new run, so a retry sends the Day 1 email twice. Send an `Idempotency-Key` header, such as `signup-user_123`, and a repeated key returns the first run instead. See [Invoke a journey
> DOC](/docs/journeys/invoke).


# Send your first message
Source: https://www.courier.com/docs/get-started/send-a-message

Send one message with the API using a Test key, then find it in the logs.

> [!TIP]
>
> **Build it with your AI agent.** We highly recommend it: set up your agent with the [AI agent quickstart
> DOC](/docs/get-started/ai-agent-quickstart), then ask it to build this.

**1. Get your API key**

Copy your **Test** key from [Settings → API Keys](https://app.courier.com/~/test/platform/api-keys).

**2. Send the message**

Replace `YOUR_COURIER_API_KEY` with your key and `you@example.com` with the address you signed up with.

```javascript Node.js theme={null}
// npm install @trycourier/courier
import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: "YOUR_COURIER_API_KEY" });

const response = await client.send.message({
  message: {
    to: { email: "you@example.com" },
    content: {
      version: "2022-01-01",
      elements: [
        { type: "meta", title: "Hello from Courier!" },
        {
          type: "html",
          content:
            "<h1>It works!</h1><p>You just sent your first notification.</p>",
        },
      ],
    },
  },
});

console.log("Sent! Request ID:", response.requestId);
```

```python Python theme={null}
# pip install trycourier
from courier import Courier

client = Courier(api_key="YOUR_COURIER_API_KEY")

response = client.send.message(
    message={
        "to": {"email": "you@example.com"},
        "content": {
            "version": "2022-01-01",
            "elements": [
                {"type": "meta", "title": "Hello from Courier!"},
                {
                    "type": "html",
                    "content": "<h1>It works!</h1><p>You just sent your first notification.</p>",
                },
            ],
        },
    }
)

print("Sent! Request ID:", response.request_id)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer YOUR_COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "email": "you@example.com" },
      "content": {
        "version": "2022-01-01",
        "elements": [
          { "type": "meta", "title": "Hello from Courier!" },
          {
            "type": "html",
            "content": "<h1>It works!</h1><p>You just sent your first notification.</p>"
          }
        ]
      }
    }
  }'
```

```ruby Ruby theme={null}
# gem install courier
require "courier"

courier = Courier::Client.new(api_key: "YOUR_COURIER_API_KEY")

response = courier.send_.message(
  message: {
    to: { email: "you@example.com" },
    content: {
      version: "2022-01-01",
      elements: [
        { type: "meta", title: "Hello from Courier!" },
        {
          type: "html",
          content: "<h1>It works!</h1><p>You just sent your first notification.</p>"
        }
      ]
    }
  }
)

puts("Sent! Request ID: #{response.request_id}")
```

```go Go theme={null}
// go get github.com/trycourier/courier-go/v4
client := courier.NewClient(option.WithAPIKey("YOUR_COURIER_API_KEY"))

// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    { "type": "meta", "title": "Hello from Courier!" },
    {
      "type": "html",
      "content": "<h1>It works!</h1><p>You just sent your first notification.</p>"
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("you@example.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})
if err != nil {
	panic(err.Error())
}

fmt.Printf("Sent! Request ID: %s\n", response.RequestID)
```

```java Java theme={null}
CourierClient client = CourierOkHttpClient.builder().apiKey("YOUR_COURIER_API_KEY").build();

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("you@example.com").build())
        // Elemental nodes carry no typed content fields, so pass the document as raw JSON.
        .content(JsonValue.from(java.util.Map.of(
            "version", "2022-01-01",
            "elements", java.util.List.of(
              java.util.Map.of(
                "type", "meta",
                "title", "Hello from Courier!"),
              java.util.Map.of(
                "type", "html",
                "content", "<h1>It works!</h1><p>You just sent your first notification.</p>")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$client = new Client(apiKey: 'YOUR_COURIER_API_KEY');

$response = $client->send->message(
  message: [
    'to' => ['email' => 'you@example.com'],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        ['type' => 'meta', 'title' => 'Hello from Courier!'],
        [
          'type' => 'html',
          'content' => '<h1>It works!</h1><p>You just sent your first notification.</p>',
        ],
      ],
    ],
  ],
);
```

```csharp C# theme={null}
CourierClient client = new() { ApiKey = "YOUR_COURIER_API_KEY" };

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "you@example.com" },
        // Elemental nodes expose no typed content fields, so build the document from raw JSON.
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                { "type": "meta", "title": "Hello from Courier!" },
                {
                  "type": "html",
                  "content": "<h1>It works!</h1><p>You just sent your first notification.</p>"
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI theme={null}
# npm install -g @trycourier/cli
export COURIER_API_KEY=YOUR_COURIER_API_KEY

courier send message \
  --message.to '{"email": "you@example.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "meta", "title": "Hello from Courier!"}, {"type": "html", "content": "<h1>It works!</h1><p>You just sent your first notification.</p>"}]}'
```

```text MCP theme={null}
With Courier MCP, send a test email to my own address with the title Hello from Courier.
```

The `meta` element's `title` becomes the email subject. The `<h1>` is the heading
inside the message, so the two are set separately.

See [Elemental
DOC](/docs/design/elemental/overview) for all the elements you can send.

The response returns a `requestId`:

```json theme={null}
{ "requestId": "1-67890abc-d1e2f3a4b5c6" }
```

**3. Check the logs**

Open [Test Logs](https://app.courier.com/~/test/logs) to see the delivery timeline.

Logs are per [environment
DOC](/docs/workspaces/environments), so a missing message usually means a key from the other one.

## FAQ

> **Do I need to configure a Provider first?**
>
> Not to email yourself. Every Test environment ships with the Courier Test Email Provider, which delivers to your signup address only.
>
> Any other recipient, or any other channel, needs a provider of your own. [Send your first email
> GUIDE](/docs/guides/send-your-first-email) connects one and verifies a sending domain.

> **What are Templates?**
>
> A [Template
> DOC](/docs/design/templates/overview) holds a notification's content and behavior in Courier, not in your code. You design it once, then send it by ID and pass only the data.
>
> This first send uses inline `content` so it needs nothing but a key. Most production sends reference a Template, so wording and design change without a deploy.

> **When do I move off Test?**
>
> Test and Production are isolated, with separate keys, Templates, integrations, and logs. Build against Test, then [swap to a Production key
> DOC](/docs/workspaces/environments#api-keys) when you go live. Test sends are billable.


# Add an inbox to Astro
Source: https://www.courier.com/docs/guides/add-an-inbox-to-astro

An endpoint and a React island: the two files that put a Courier Inbox in an Astro app.

Two files get a Courier Inbox working in Astro: an endpoint that mints a token, and a React island that renders the feed.

The endpoint exists because your API key signs the token, and that key has to stay on the server, out of the browser. Everything else is standard Astro work.

> **[courier-astro-quickstart](https://github.com/trycourier/courier-astro-quickstart)**
>
> The finished app from this guide, ready to clone and run.

## Prerequisites

* [A Courier account](https://app.courier.com/signup)
* [A Courier API key](https://app.courier.com/settings/api-keys), from any environment. Every one ships with the Courier Inbox provider already configured.
* An Astro app with the React integration, and Node 20.9 or newer
* Somewhere to read the signed-in user, such as Auth.js, Clerk, or your own session cookie

## Clone the finished app

Skip the steps below if you would rather read working code. This repo is this guide, already assembled.

```bash theme={null}
git clone https://github.com/trycourier/courier-astro-quickstart.git
cd courier-astro-quickstart
npm install
cp .env.example .env   # paste your API key
npm run dev
```

Open `localhost:4321`, then run `npm run send` in a second terminal. The message arrives in the open page without a refresh.

## Add an inbox to your app

**1. Install the packages**

The React package renders the inbox. The server package mints tokens.

```bash theme={null}
npx astro add react node
npm install @trycourier/courier-react @trycourier/courier
```

`node` is the adapter. The token endpoint runs per request, so the site needs a server.

Put your key in `.env`, which Astro loads in `dev` and `build`.

```bash .env theme={null}
COURIER_API_KEY=YOUR_COURIER_API_KEY
```

**2. Declare the key as a server secret**

Astro reads a **secret** from the environment at runtime. Everything else it inlines at build time.

```js astro.config.mjs lines highlight={13} theme={null}
import { defineConfig, envField } from "astro/config";
import node from "@astrojs/node";
import react from "@astrojs/react";

export default defineConfig({
  integrations: [react()],
  adapter: node({ mode: "standalone" }),

  env: {
    schema: {
      COURIER_API_KEY: envField.string({
        context: "server",
        access: "secret",
        optional: true,
      }),
    },
  },
});
```

`access: "secret"` is the line that matters. Reading `import.meta.env.COURIER_API_KEY` instead compiles to the key's build-time value as a string literal, which ships your key inside the bundle you deploy.

`optional: true` lets the endpoint return its own message for a missing key. Without it Astro fails the schema before the server starts.

**3. Add an endpoint that mints the token**

Your API key signs the JWT, so this runs on the server and never in the browser.

```ts src/pages/api/courier/token.ts lines highlight={2} theme={null}
import type { APIRoute } from "astro";
import { COURIER_API_KEY } from "astro:env/server";
import Courier from "@trycourier/courier";

export const prerender = false;

export const GET: APIRoute = async () => {
  if (!COURIER_API_KEY) return new Response("COURIER_API_KEY is not set", { status: 500 });

  const client = new Courier({ apiKey: COURIER_API_KEY });

  // Read the user from your own session. Never from the request.
  const session = await auth();
  if (!session) return new Response("Unauthorized", { status: 401 });

  const userId = session.user.id;

  const { token } = await client.auth.issueToken({
    scope: `user_id:${userId} inbox:read:messages inbox:write:events`,
    expires_in: "1 day",
  });

  return Response.json({ userId, token });
};
```

`export const prerender = false` is required. Astro prerenders by default, and a token minted at build time is the same token for every visitor.

Take the user id from your session, never from the request body or a query parameter. A caller who can name any user can read that user's inbox.

The endpoint calls [Create a JWT](/docs/api-reference/authentication/create-a-jwt), and the two `inbox:` scopes are the minimum for a working feed. [Scopes
DOC](/docs/in-app/authenticate-users#scopes) lists what to add for preferences and push.

**4. Render the inbox in a React island**

Fetch the token, call `signIn`, then mount `CourierInbox`.

```tsx src/components/CourierInbox.tsx lines theme={null}
import { useEffect, useRef } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react";

export default function Inbox() {
  const courier = useCourier();
  const signedIn = useRef(false);

  useEffect(() => {
    if (signedIn.current) return;
    signedIn.current = true;

    fetch("/api/courier/token")
      .then((response) => response.json())
      .then(({ userId, token }) => courier.shared.signIn({ userId, jwt: token }));
  }, [courier]);

  return <CourierInbox />;
}
```

Effects run twice in development. A second `signIn` signs the first user out again, so guard it with a ref.

**5. Hydrate it with client:only**

The inbox renders as a custom element, so it has nothing to draw on the server.

```astro src/pages/index.astro highlight={6} theme={null}
---
import Inbox from "../components/CourierInbox";
---

<main style="height: 32rem">
  <Inbox client:only="react" />
</main>
```

`CourierInbox` fills its container's width and takes its height from the parent, so size the parent.

> [!NOTE]
>
> On React 17, install `@trycourier/courier-react-17` instead. The API is identical.

**6. Send a message to the inbox**

`inbox` is a channel like `email` or `sms`. Including it in `routing.channels` is what puts the message in the feed.

```ts scripts/send.ts lines theme={null}
import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: process.env.COURIER_API_KEY! });

await client.send.message({
  message: {
    to: { user_id: "sarah-bennett" },
    routing: { method: "single", channels: ["inbox"] },
    content: { title: "Your report is ready", body: "The export has finished." },
  },
});
```

`content` here is the shorthand form, which takes a `title` and a `body`. For multi-element layouts and per-channel variants, use a [template
DOC](/docs/design/templates/overview) instead and reference it by id.

## Deploy

`astro dev` and `astro build` read `.env`. The built server doesn't, so set the key wherever you host it.

```bash theme={null}
COURIER_API_KEY=YOUR_COURIER_API_KEY node ./dist/server/entry.mjs
```

On Vercel, Netlify, or Cloudflare, swap `@astrojs/node` for that host's adapter and set `COURIER_API_KEY` in its dashboard. Nothing in the two files changes.

## Keep the session alive

The SDKs don't refresh tokens. Before the current one expires, mint a new JWT and call `signIn` again with it.

Match `expires_in` to your session length, and [refresh the token
DOC](/docs/in-app/authenticate-users#5-refresh-tokens) before it expires so an open tab keeps loading messages.

> [!WARNING]
>
> `expires_in` is optional, and omitting it mints a token that **never expires**. Always set it. Rotating the API key that signed it is the only way to revoke one.

## Verify

**1. Load the page**

The inbox renders, signed in and empty.

**2. Send a message**

Run the send against the same `user_id` your token was scoped to.

**3. Watch it arrive**

The message appears in the open page in real time, and the unread count moves.

An inbox that renders but stays empty usually has an expired or mis-scoped token. [Troubleshooting
DOC](/docs/in-app/authenticate-users#troubleshooting) walks the four causes in order.

## FAQ

> **Can I mint the token in the page's frontmatter instead?**
>
> Minting it in frontmatter works, and passing it to the island as a prop saves a round trip. The page then needs `prerender = false` too. An endpoint is shown here because it is also what you call again when the token expires.

> **Do I need an adapter?**
>
> An adapter is needed for the endpoint. A fully static Astro site has nowhere to sign a JWT, and your API key can't go in the browser to do it there.

> **Can the rest of my site stay static?**
>
> `prerender = false` is per route, so only the token endpoint runs on demand. The page holding the inbox can prerender.

> **Is the JWT safe to expose to the browser?**
>
> The JWT is built for the browser. It is scoped to one user and it expires. Your API key, which signs it, stays on the server.

> **Why is the inbox empty when the send reported success?**
>
> The feed is filtered by tenant. Signing in with a `tenantId` hides messages sent without one. See [scope the inbox to a tenant
> DOC](/docs/in-app/send-to-the-inbox#scope-the-inbox-to-a-tenant).


# Add an inbox to Next.js
Source: https://www.courier.com/docs/guides/add-an-inbox-to-nextjs

A route handler and a client component: the two files that put a Courier Inbox in Next.js.

Two files get a Courier Inbox working in Next.js: a route handler that mints a token, and a client component that renders the feed.

The route handler exists because your API key signs the token, and that key has to stay on the server, out of the browser. Everything else is standard App Router work.

> **[courier-nextjs-quickstart](https://github.com/trycourier/courier-nextjs-quickstart)**
>
> The finished app from this guide, ready to clone and run.

## Prerequisites

* [A Courier account](https://app.courier.com/signup)
* [A Courier API key](https://app.courier.com/settings/api-keys), from any environment. Every one ships with the Courier Inbox provider already configured.
* A Next.js app on the App Router, and Node 20.9 or newer
* Somewhere to read the signed-in user, such as NextAuth, Clerk, or your own session cookie

## Clone the finished app

Skip the steps below if you would rather read working code. This repo is this guide, already assembled.

```bash theme={null}
git clone https://github.com/trycourier/courier-nextjs-quickstart.git
cd courier-nextjs-quickstart
npm install
cp .env.example .env.local   # paste your API key
npm run dev
```

Open `localhost:3000`, then run `npm run send` in a second terminal. The message arrives in the open page without a refresh.

## Add an inbox to your app

**1. Install the packages**

The React package renders the inbox. The server package mints tokens.

```bash theme={null}
npm install @trycourier/courier-react @trycourier/courier
```

Put your key in `.env.local`, which Next loads automatically.

```bash .env.local theme={null}
COURIER_API_KEY=YOUR_COURIER_API_KEY
```

**2. Add a route handler that mints the token**

Your API key signs the JWT, so this runs on the server and never in the browser.

```tsx app/api/courier/token/route.ts lines theme={null}
import Courier from "@trycourier/courier";

export async function GET() {
  const client = new Courier({ apiKey: process.env.COURIER_API_KEY! });

  // Read the user from your own session. Never from the request.
  const session = await auth();
  if (!session) return new Response("Unauthorized", { status: 401 });

  const userId = session.user.id;

  const { token } = await client.auth.issueToken({
    scope: `user_id:${userId} inbox:read:messages inbox:write:events`,
    expires_in: "1 day",
  });

  return Response.json({ userId, token });
}
```

Take the user id from your session, never from the request body or a query parameter. A caller who can name any user can read that user's inbox.

The route calls [Create a JWT](/docs/api-reference/authentication/create-a-jwt), and the two `inbox:` scopes are the minimum for a working feed. [Scopes
DOC](/docs/in-app/authenticate-users#scopes) lists what to add for preferences and push.

**3. Render the inbox in a client component**

Fetch the token, call `signIn`, then mount `CourierInbox`.

```tsx components/courier-inbox.tsx lines theme={null}
"use client";

import { useEffect, useRef } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react";

export function Inbox() {
  const courier = useCourier();
  const signedIn = useRef(false);

  useEffect(() => {
    if (signedIn.current) return;
    signedIn.current = true;

    fetch("/api/courier/token")
      .then((response) => response.json())
      .then(({ userId, token }) => courier.shared.signIn({ userId, jwt: token }));
  }, [courier]);

  return <CourierInbox />;
}
```

Two details are specific to Next.js and React:

* **`"use client"` is required.** The component uses hooks, and the inbox renders as a custom element that only exists in the browser.
* **Effects run twice in development.** A second `signIn` signs the first user out again, so guard it with a ref.

**4. Give the inbox a height**

`CourierInbox` fills its container's width and takes its height from the parent, so size the parent.

```tsx app/page.tsx theme={null}
import { Inbox } from "@/components/courier-inbox";

export default function Home() {
  return (
    <main style={{ height: "32rem" }}>
      <Inbox />
    </main>
  );
}
```

> [!NOTE]
>
> On React 17, install `@trycourier/courier-react-17` instead. The API is identical.

**5. Send a message to the inbox**

`inbox` is a channel like `email` or `sms`. Including it in `routing.channels` is what puts the message in the feed.

```tsx scripts/send.ts theme={null}
import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: process.env.COURIER_API_KEY! });

await client.send.message({
  message: {
    to: { user_id: "sarah-bennett" },
    routing: { method: "single", channels: ["inbox"] },
    content: { title: "Your report is ready", body: "The export has finished." },
  },
});
```

`content` here is the shorthand form, which takes a `title` and a `body`. For multi-element layouts and per-channel variants, use a [template
DOC](/docs/design/templates/overview) instead and reference it by id.

## You don't need `ssr: false`

Wrapping the inbox in `next/dynamic` with `ssr: false` is a common reflex with component libraries built on custom elements. Courier's SDK doesn't need it.

The element base class resolves to a stub under Node, and element registration is guarded on `typeof window`. Importing the package on the server is safe, so the page still prerenders and only the inbox hydrates in the browser.

`"use client"` is the whole requirement. Adding `ssr: false` costs you the prerender and buys nothing.

## Keep the session alive

The SDKs don't refresh tokens. Before the current one expires, mint a new JWT and call `signIn` again with it.

Match `expires_in` to your session length, and [refresh the token
DOC](/docs/in-app/authenticate-users#5-refresh-tokens) before it expires so an open tab keeps loading messages.

> [!WARNING]
>
> `expires_in` is optional, and omitting it mints a token that **never expires**. Always set it. Rotating the API key that signed it is the only way to revoke one.

## Verify

**1. Load the page**

The inbox renders, signed in and empty.

**2. Send a message**

Run the send against the same `user_id` your token was scoped to.

**3. Watch it arrive**

The message appears in the open page in real time, and the unread count moves.

An inbox that renders but stays empty usually has an expired or mis-scoped token. [Troubleshooting
DOC](/docs/in-app/authenticate-users#troubleshooting) walks the four causes in order.

## FAQ

> **Can I mint the token in a Server Component instead?**
>
> Minting it in a Server Component works, and passing it to the client component as a prop saves a round trip. A route handler is shown here because it is also what you call again when the token expires.

> **Does this work with the Pages Router?**
>
> Mint the token in `pages/api/courier/token.ts` and render the inbox in any component. `"use client"` is an App Router directive, and the Pages Router ignores it.

> **Is the JWT safe to expose to the browser?**
>
> The JWT is built for the browser. It is scoped to one user and it expires. Your API key, which signs it, stays on the server.

> **Why is the inbox empty when the send reported success?**
>
> The feed is filtered by tenant. Signing in with a `tenantId` hides messages sent without one. See [scope the inbox to a tenant
> DOC](/docs/in-app/send-to-the-inbox#scope-the-inbox-to-a-tenant).


# Add an inbox to React
Source: https://www.courier.com/docs/guides/add-an-inbox-to-react

A token route and a component: the two files that put a Courier Inbox in a React app.

Two files get a Courier Inbox working in React: a server route that mints a token, and a component that renders the feed.

A Vite app is all browser, and your API key can't go there. That is the only reason this needs a server at all.

> **[courier-react-quickstart](https://github.com/trycourier/courier-react-quickstart)**
>
> The finished app from this guide, ready to clone and run.

## Prerequisites

* [A Courier account](https://app.courier.com/signup)
* [A Courier API key](https://app.courier.com/settings/api-keys), from any environment. Every one ships with the Courier Inbox provider already configured.
* A React app on Vite, and Node 20.9 or newer
* A backend you can add one route to

## Clone the finished app

Skip the steps below if you would rather read working code. This repo is this guide, already assembled.

```bash theme={null}
git clone https://github.com/trycourier/courier-react-quickstart.git
cd courier-react-quickstart
npm install
cp .env.example .env   # paste your API key
npm run dev
```

Open `localhost:5173`, then run `npm run send` in a second terminal. The message arrives in the open page without a refresh.

## Add an inbox to your app

**1. Install the packages**

The React package renders the inbox. The server package mints tokens.

```bash theme={null}
npm install @trycourier/courier-react @trycourier/courier
```

Put your key in `.env`. Your server reads it, and the browser never does.

```bash .env theme={null}
COURIER_API_KEY=YOUR_COURIER_API_KEY
```

**2. Add a route that mints the token**

Your API key signs the JWT, so this runs on your backend and never in the browser.

```js server.js lines theme={null}
import "dotenv/config";
import Courier from "@trycourier/courier";

app.get("/api/courier/token", async (request, response) => {
  const client = new Courier({ apiKey: process.env.COURIER_API_KEY });

  // Read the user from your own session. Never from the request.
  const session = await auth(request);
  if (!session) return response.status(401).end();

  const { token } = await client.auth.issueToken({
    scope: `user_id:${session.user.id} inbox:read:messages inbox:write:events`,
    expires_in: "1 day",
  });

  response.json({ userId: session.user.id, token });
});
```

Take the user id from your session, never from the request body or a query parameter. A caller who can name any user can read that user's inbox.

The route calls [Create a JWT](/docs/api-reference/authentication/create-a-jwt), and the two `inbox:` scopes are the minimum for a working feed. [Scopes
DOC](/docs/in-app/authenticate-users#scopes) lists what to add for preferences and push.

**3. Point Vite at your server**

Proxying keeps the fetch same-origin, so there is no CORS to configure.

```ts vite.config.ts highlight={7} theme={null}
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: { "/api": "http://localhost:3001" },
  },
});
```

**4. Render the inbox**

Fetch the token, call `signIn`, then mount `CourierInbox`.

```tsx src/CourierInbox.tsx lines theme={null}
import { useEffect, useRef } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react";

export function Inbox() {
  const courier = useCourier();
  const signedIn = useRef(false);

  useEffect(() => {
    if (signedIn.current) return;
    signedIn.current = true;

    fetch("/api/courier/token")
      .then((response) => response.json())
      .then(({ userId, token }) => courier.shared.signIn({ userId, jwt: token }));
  }, [courier]);

  return <CourierInbox />;
}
```

StrictMode mounts every component twice in development. A second `signIn` signs the first user out again, so guard it with a ref.

**5. Give the inbox a height**

`CourierInbox` fills its container's width and takes its height from the parent, so size the parent.

```tsx src/App.tsx theme={null}
import { Inbox } from "./CourierInbox";

export default function App() {
  return (
    <main style={{ height: "32rem" }}>
      <Inbox />
    </main>
  );
}
```

> [!NOTE]
>
> On React 17, install `@trycourier/courier-react-17` instead. The API is identical.

**6. Send a message to the inbox**

`inbox` is a channel like `email` or `sms`. Including it in `routing.channels` is what puts the message in the feed.

```ts scripts/send.ts lines theme={null}
import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: process.env.COURIER_API_KEY });

await client.send.message({
  message: {
    to: { user_id: "sarah-bennett" },
    routing: { method: "single", channels: ["inbox"] },
    content: { title: "Your report is ready", body: "The export has finished." },
  },
});
```

`content` here is the shorthand form, which takes a `title` and a `body`. For multi-element layouts and per-channel variants, use a [template
DOC](/docs/design/templates/overview) instead and reference it by id.

## Where the token route belongs

The sample ships a small `server.js` so it runs on its own. In your app, that route belongs on the backend you already have, next to the endpoint that returns the current user.

Any framework works, because the route does one thing: read the session, mint a JWT, return it. Express, Fastify, Hono, a Lambda, or a Rails controller are all fine.

## Keep the session alive

The SDKs don't refresh tokens. Before the current one expires, mint a new JWT and call `signIn` again with it.

Match `expires_in` to your session length, and [refresh the token
DOC](/docs/in-app/authenticate-users#5-refresh-tokens) before it expires so an open tab keeps loading messages.

> [!WARNING]
>
> `expires_in` is optional, and omitting it mints a token that **never expires**. Always set it. Rotating the API key that signed it is the only way to revoke one.

## Verify

**1. Load the page**

The inbox renders, signed in and empty.

**2. Send a message**

Run the send against the same `user_id` your token was scoped to.

**3. Watch it arrive**

The message appears in the open page in real time, and the unread count moves.

An inbox that renders but stays empty usually has an expired or mis-scoped token. [Troubleshooting
DOC](/docs/in-app/authenticate-users#troubleshooting) walks the four causes in order.

## FAQ

> **Can I skip the server and use the API key in the browser?**
>
> The key can send to anyone and read any user's data. It is a server credential, and a JWT scoped to one user is what the browser is meant to hold.

> **My backend is on another origin. What changes?**
>
> Drop the Vite proxy, fetch the absolute URL, and allow that origin with CORS. The token route itself doesn't change.

> **Is the JWT safe to expose to the browser?**
>
> The JWT is built for the browser. It is scoped to one user and it expires. Your API key, which signs it, stays on the server.

> **Why is the inbox empty when the send reported success?**
>
> The feed is filtered by tenant. Signing in with a `tenantId` hides messages sent without one. See [scope the inbox to a tenant
> DOC](/docs/in-app/send-to-the-inbox#scope-the-inbox-to-a-tenant).


# Send to a list or audience
Source: https://www.courier.com/docs/guides/announce-to-a-list

Send one announcement to a saved list or audience and confirm every member got it.

Send one announcement to a saved group, and confirm every member received it.

You address the group, not its people. Courier resolves membership at send time and delivers one message per member.

## Prerequisites

* [A list or audience
  DOC](/docs/recipients/lists-and-audiences/overview)
* [A published template
  DOC](/docs/design/templates/overview)
* [A Courier API key](https://app.courier.com/settings/api-keys)

## Send to the group

**1. Send to a list**

A list is a group you curate by hand. Put its `list_id` in `to` and Courier sends to each member.

```javascript Node.js highlight={3} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { list_id: 'acme-corp.beta-testers' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
  },
});
```

```python Python highlight={3} theme={null}
response = client.send.message(
    message={
        "to": {"list_id": "acme-corp.beta-testers"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={6} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "list_id": "acme-corp.beta-testers" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={3} theme={null}
response = courier.send_.message(
  message: {
    to: { list_id: "acme-corp.beta-testers" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfListRecipient: &shared.ListRecipientParam{
				ListID: courier.String("acme-corp.beta-testers"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("list_id", "acme-corp.beta-testers")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={3} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['listID' => 'acme-corp.beta-testers'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new ListRecipient { ListID = "acme-corp.beta-testers" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"list_id":"acme-corp.beta-testers"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40"}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to the acme-corp.beta-testers list.
```

**2. Send to an audience**

An audience is a group Courier keeps current from rules you write. Put its `audience_id` in `to` and everyone who matches now receives the message.

```javascript Node.js highlight={3} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { audience_id: 'active-business-users' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
  },
});
```

```python Python highlight={3} theme={null}
response = client.send.message(
    message={
        "to": {"audience_id": "active-business-users"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={6} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "audience_id": "active-business-users" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={3} theme={null}
response = courier.send_.message(
  message: {
    to: { audience_id: "active-business-users" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfAudienceRecipient: &shared.AudienceRecipientParam{
				AudienceID: "active-business-users",
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("audience_id", "active-business-users")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={3} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['audienceID' => 'active-business-users'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new AudienceRecipient { AudienceID = "active-business-users" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"audience_id":"active-business-users"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40"}'
```

**3. Reach many lists at once**

A `list_id` is a dotted namespace, so `list_pattern` targets several lists in one call. Use `*` for one part of the name, or `**` as a trailing wildcard.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      list_pattern: "acme-corp.*.beta-testers",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "list_pattern": "acme-corp.*.beta-testers",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "list_pattern": "acme-corp.*.beta-testers"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      list_pattern: "acme-corp.*.beta-testers"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={4} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "list_pattern": "acme-corp.*.beta-testers"
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={6} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("list_pattern", JsonValue.from("acme-corp.*.beta-testers"))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'list_pattern' => 'acme-corp.*.beta-testers',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={11} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "list_pattern": "acme-corp.*.beta-testers"
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"list_pattern": "acme-corp.*.beta-testers"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to every beta-testers list under acme-corp.
```

## Verify

**1. Count the messages**

Open [Logs](https://app.courier.com/logs) and confirm one message per member.

**2. Reconcile a wrong count**

Compare the log against the membership from the [Lists](/docs/api-reference/lists/get-a-list) or [Audiences](/docs/api-reference/audiences/list-audience-members) API.

**3. Check who was filtered out**

Members who opted out of the template's topic show as `UNSUBSCRIBED` rather than delivered. That is preferences working, not a failed send.

> [!NOTE]
>
> A list or audience must exist first. For a one-off set of recipients, [send in bulk
> GUIDE](/docs/guides/send-in-bulk) instead.


# Build a preference center
Source: https://www.courier.com/docs/guides/build-a-preference-center

Let users choose their topics and channels with the hosted page or the embedded component.

Give users one place to choose which messages they receive, and on which channels.

Configure topics once in the editor. Then show them as a Courier-hosted page or an embedded component. Both read and write the same preference data.

## Prerequisites

* A Courier workspace
* [The templates you want users to control](https://app.courier.com/content/templates)
* [The preferences model
  DOC](/docs/recipients/preferences/model)
* [An optional brand](https://app.courier.com/content/brands)

## Configure the topics

Use the [preferences editor](https://app.courier.com/~/test/platform/preferences) (**Platform → Preferences**). Topics, sections, and branding are all defined here. Every setting it exposes is in [the Preferences Editor reference
DOC](/docs/recipients/preferences/preferences-editor).

![The preferences editor: brand and heading settings and section tabs on the left, with a live preview of the hosted page on the right](https://mintcdn.com/courier-4f1f25dc/Ia7FGvhsFU_5CtOa/assets/preferences-editor.webp?fit=max\&auto=format\&n=Ia7FGvhsFU_5CtOa\&q=85\&s=24a120335981c1da4bb1671cb8eba5c2)

The preferences editor: page settings, sections, and topics, with a live preview of the hosted page.

**1. Set page settings**

Page settings apply to the whole page:

* An optional [brand
  DOC](/docs/design/brands), for logo and colors.
* The heading and description.
* The channel names users see. Rename them to match your product, for example "In-App" to "Inbox".

**2. Add sections**

Sections group related topics under a heading you name, such as "Account" or "Marketing". Turn on channel selection for a section to let users pick which channels deliver its topics.

**3. Add topics**

Topics are the categories users opt in or out of. For each one, set a name, its section, and a default state:

* **On (`OPTED_IN`):** users receive it unless they opt out.
* **Off (`OPTED_OUT`):** users receive nothing until they opt in.
* **Required (`REQUIRED`):** users can't opt out. Use it for critical messages, and leave unsubscribe links off templates mapped to required topics.

**4. Map templates to topics**

Mapping a template to a topic makes Courier enforce the preference on every send. Set it in a template's [settings
DOC](/docs/design/templates/design-studio) in Design Studio, or set the template's `subscription` field to `{ "topic_id": "<TOPIC_ID>" }` through the API.

**5. Publish**

Every change saves as a draft. Use **Preview Page** to open the page in draft mode, then **Publish** to make it live. Until you publish, users see the last published version.

To batch a topic's messages on a schedule, open the topic's digest settings and link a digest template. See the [digest schedules model
DOC](/docs/recipients/preferences/model#digest-schedules) for how batching, categories, and Trigger empty behave.

## Hosted page

The hosted preference center needs no frontend. It lists the user's subscription topics with the heading, description, and optional brand you set in the editor. It works on desktop and mobile. Courier serves it at `https://view.notificationcenter.app/p/<id>`. The id encodes the workspace, brand, and user, so each recipient sees their own preferences.

![A branded Courier-hosted preference page with Account Notifications and Marketing sections, per-topic toggles, a Required topic, and a digest delivery schedule](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/hosted-preference-center-superset.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=03ee1792c8d4582d4b1f77b332770590)

The Courier-hosted preference page a user opens from the preferences link: their subscription topics, grouped into sections and branded.

## Link users to the preference center

Link users to their hosted page with the `preferences` variable. Courier renders it as a secure, per-user URL. Include `to.user_id` in your send so each recipient gets their own link. Write the variable in the format for your editing context:

* Content blocks (Text, Markdown, Quote, List): `{{$.urls.preferences}}`
* Handlebars (Template blocks, email and brand templates): `{{var "urls.preferences"}}`
* Elemental JSON (action buttons and links): `{$.urls.preferences}`

Put the variable in a saved template, then send that template with the [Send API](/docs/api-reference/send/send-a-message). Below, `nt_01kx4h2jdafq8bk9aftxak4b40` is a template whose body includes `{{$.urls.preferences}}`:

```javascript Node.js theme={null}
import Courier from "@trycourier/courier";

const client = new Courier({
  apiKey: process.env["COURIER_API_KEY"],
});

const { requestId } = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});

console.log(requestId);
```

```python Python theme={null}
import os

from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
print(response.request_id)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)

puts(response)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();

var response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40"}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123.
```

For a one-click opt-out from the topic tied to a message, use the `unsubscribe` variable the same way (`{{$.urls.unsubscribe}}`, `{{var "urls.unsubscribe"}}`, or `{$.urls.unsubscribe}`).

> [!NOTE]
>
> The URL is empty when the template has no subscription topic, so [assign a topic
> DOC](/docs/design/templates/design-studio) first. On a required topic the opt-out does nothing, so leave unsubscribe links off those templates.

Place either link inside a message, or once in your [brand
DOC](/docs/design/brands) footer so it appears on every message.

### One-click unsubscribe headers

Gmail and Yahoo require bulk senders to support one-click unsubscribe. Turn on **Unsubscribe Headers** for a topic in the preferences editor, or set `include_unsubscribe_header` on the topic through the API. Courier then adds two headers to that topic's email:

```text theme={null}
List-Unsubscribe: <the recipient's unsubscribe URL>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
```

Both conditions have to hold for the headers to appear. The topic has the setting on, and the message resolves an unsubscribe URL, which means the template is mapped to that topic.

> [!NOTE]
>
> SendGrid is the only provider Courier emits these headers on today. On another email provider, set them yourself with a [provider override
> DOC](/docs/send/overrides).

## Embedded component

To keep users inside your product, embed the preference center instead of linking to the hosted page. It reads the same published topics and writes the same preference data, so a change in one place shows up in the other.

![The embeddable Courier preferences component, showing a topic section with per-topic toggles and an expanded channel picker for email, push, and SMS](https://mintcdn.com/courier-4f1f25dc/Ia7FGvhsFU_5CtOa/assets/preferences-default.webp?fit=max\&auto=format\&n=Ia7FGvhsFU_5CtOa\&q=85\&s=d31b2fb8c91c01bd97f26b09d0ecb4bc)

The embedded preference center component: subscription topics with per-topic channel choices.

Setup, theming, and building your own UI live in the In-App Notifications tab:

> **[Add a preference center](/docs/in-app/add-a-preference-center)**
>
> Install, authenticate, and render the component on every platform.

> **[Customize Preferences](/docs/in-app/customize-preferences)**
>
> Theme the component or build your own preferences UI.

## Sync changes to your own system

Courier sends each change a user makes in the preference center to your [outbound webhooks
DOC](/docs/monitor/webhooks/outbound) as a `preferences:user:updated` event, and records it in the change history. To keep a copy in your CRM or database, see [Mirror preferences in another system
DOC](/docs/recipients/preferences/api#mirror-preferences-in-another-system).

## Verify

**1. Open the preference center**

Open the hosted page from a real send (a message containing `{{$.urls.preferences}}` with `to.user_id` set), or load your embedded component as a test user.

**2. Toggle a topic off and send**

Toggle a topic off. Send a message mapped to that topic and confirm the log shows the send blocked as `UNSUBSCRIBED`.

**3. Read the change back**

[Read the change back](/docs/api-reference/user-preferences/get-users-preferences) and confirm the `status` matches what you toggled.


# Build an onboarding sequence
Source: https://www.courier.com/docs/guides/build-an-onboarding-sequence

Welcome new users over a week with delays and a branch that skips those who activated.

Walk a new user through their first week with one Journey: welcome them, wait, then nudge only the people who stalled.

A Journey is a graph that runs once per user. Each run carries that user's data, so the whole sequence is one API call from your signup code.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["Signup"] --> B["Welcome email"]
    B -->|3 days| C{"Activated?"}
    C -->|No| D["Tip email"]
    D -->|4 days| E["Nudge"]
    C -->|Yes| F["No more emails"]
```

## Prerequisites

* [A connected email provider
  DOC](/docs/integrations/email/overview)
* [A Courier API key](https://app.courier.com/settings/api-keys)
* A signup event from your app

## Build the sequence

**1. Create the Journey**

Open [Journeys](https://app.courier.com/orchestration/journeys), select **New Journey**, name it `user-onboarding`, and choose the **API Invoke** trigger so your signup code starts each run.

![The New Journey dialog with a name field and four trigger options](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/journey-new-journey-trigger.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=7c29c7f4a5f95ec0bb49a95a3b455707)

**2. Send the welcome message**

Drop a **send** node on the canvas, pick the email channel, and select **+ Create** to write the content inline. Reference the run's data with variables such as `{{first_name}}`.

Each send node owns one template scoped to this Journey, so onboarding content stays out of your workspace template list.

**3. Wait three days**

Drag a **delay** node after the send and set it to three days. The run parks there and resumes on its own, so you hold no timers in your code.

A delay is measured from when the run reaches the node, not from when the Journey started.

**4. Branch on whether they activated**

Add a **branch** node after the delay and write a condition against the run's data, for example `data.has_activated`. Wire the true path straight to an end, and the false path onward.

The branch reads the data the run is carrying. To decide on something that changed *during* the three-day wait, add a **fetch data** node before the branch and call your own API for the current value.

**5. Add the follow-ups**

On the false path, add a send node with a tip message, another **delay** of four days, and a final nudge. Only users who never activated reach these nodes.

**6. Set a cancelation token**

In the journey's settings, set the **cancelation token** to `onboarding-{{profile.id}}`. Courier interpolates it when each run starts, so every user's run carries its own token and you can stop one user's sequence without touching anyone else's.

A token that references a variable missing at run start leaves the run untagged. It is still cancelable by run ID, but not by token. [Cancellation tokens
DOC](/docs/journeys/nodes/cancel#cancel-a-group-with-a-cancellation-token) covers how the shape of the token decides what it covers.

**7. Publish**

Select **Publish** to lock the draft as a version, then copy the Journey ID. New runs use the published version. Runs in flight finish on the version they started with.

**8. Invoke it from your signup code**

Call [Invoke a Journey](/docs/api-reference/journeys/invoke-a-journey) once per new user. The run picks up the cancelation token from the journey's settings, so invoke carries only the user and the data the branch reads.

```javascript Node.js theme={null}
const journeysInvokeResponse = await client.journeys.invoke('user-onboarding', {
  user_id: 'user_123',
  data: { first_name: 'Sarah', has_activated: false },
});
```

```python Python theme={null}
journeys_invoke_response = client.journeys.invoke(
    template_id="user-onboarding",
    user_id="user_123",
    data={"first_name": "Sarah", "has_activated": False},
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/journeys/user-onboarding/invoke \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-user_123" \
  -d '{
    "user_id": "user_123",
    "data": { "first_name": "Sarah", "has_activated": false }
  }'
```

```ruby Ruby theme={null}
journeys_invoke_response = courier.journeys.invoke(
  "user-onboarding",
  user_id: "user_123",
  data: {first_name: "Sarah", has_activated: false}
)
```

```go Go theme={null}
journeysInvokeResponse, err := client.Journeys.Invoke(
	context.TODO(),
	"user-onboarding",
	courier.JourneyInvokeParams{
		JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
			UserID: courier.String("user_123"),
			Data: map[string]any{
				"first_name":    "Sarah",
				"has_activated": false,
			},
		},
	},
)
```

```java Java theme={null}
JourneyInvokeParams params = JourneyInvokeParams.builder()
    .templateId("user-onboarding")
    .journeysInvokeRequest(JourneysInvokeRequest.builder()
        .userId("user_123")
        .data(JourneysInvokeRequest.Data.builder()
            .putAdditionalProperty("first_name", JsonValue.from("Sarah"))
            .putAdditionalProperty("has_activated", JsonValue.from(false))
            .build())
        .build())
    .build();
JourneysInvokeResponse journeysInvokeResponse = client.journeys().invoke(params);
```

```php PHP theme={null}
$journeysInvokeResponse = $client->journeys->invoke(
  'user-onboarding',
  userID: 'user_123',
  data: ['first_name' => 'Sarah', 'has_activated' => false],
);
```

```csharp C# theme={null}
JourneyInvokeParams parameters = new()
{
    TemplateID = "user-onboarding",
    UserID = "user_123",
    Data = new Dictionary<string, JsonElement>()
    {
        { "first_name", JsonSerializer.SerializeToElement("Sarah") },
        { "has_activated", JsonSerializer.SerializeToElement(false) },
    },
};

var journeysInvokeResponse = await client.Journeys.Invoke(parameters);
```

```bash CLI theme={null}
courier journeys invoke \
  --api-key "$COURIER_API_KEY" \
  --template-id user-onboarding \
  --user-id user_123 \
  --data '{"first_name":"Sarah","has_activated":false}'
```

```text MCP theme={null}
With Courier MCP, start the user-onboarding journey for user_123 with first_name Sarah.
```

Send an `Idempotency-Key` header so a retried signup request returns the same run instead of starting a second sequence.

**9. Stop the sequence when they activate**

When the user finally activates, [Cancel Journey runs](/docs/api-reference/journeys/cancel-journey-runs) stops the run by the token the journey stamped on it. Anything already delivered stays delivered, and the pending steps never fire.

```javascript Node.js theme={null}
const cancelJourneyResponse = await client.journeys.cancel({ cancelation_token: 'onboarding-user_123' });
```

```python Python highlight={2} theme={null}
cancel_journey_response = client.journeys.cancel(
    cancelation_token="onboarding-user_123",
)
```

```bash cURL highlight={5} theme={null}
curl -X POST https://api.courier.com/journeys/cancel \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelation_token": "onboarding-user_123"
  }'
```

```ruby Ruby theme={null}
cancel_journey_response = courier.journeys.cancel(cancel_journey_request: {cancelation_token: "onboarding-user_123"})
```

```go Go highlight={3-4} theme={null}
cancelJourneyResponse, err := client.Journeys.Cancel(context.TODO(), courier.JourneyCancelParams{
	CancelJourneyRequest: courier.CancelJourneyRequestUnionParam{
		OfByCancelationToken: &courier.CancelJourneyRequestByCancelationTokenParam{
			CancelationToken: "onboarding-user_123",
		},
	},
})
```

```java Java highlight={1-2} theme={null}
CancelJourneyRequest.ByCancelationToken params = CancelJourneyRequest.ByCancelationToken.builder()
    .cancelationToken("onboarding-user_123")
    .build();
CancelJourneyResponse cancelJourneyResponse = client.journeys().cancel(params);
```

```php PHP highlight={2} theme={null}
$cancelJourneyResponse = $client->journeys->cancel(
  cancelationToken: 'onboarding-user_123'
);
```

```csharp C# highlight={3} theme={null}
JourneyCancelParams parameters = new()
{
    CancelJourneyRequest = new ByCancelationToken("onboarding-user_123")
};

var cancelJourneyResponse = await client.Journeys.Cancel(parameters);
```

```bash CLI highlight={3} theme={null}
courier journeys cancel \
  --api-key "$COURIER_API_KEY" \
  --cancelation-token onboarding-user_123
```

```text MCP theme={null}
With Courier MCP, cancel the journey run with the cancelation token onboarding-user_123.
```

To cancel one run instead, store the `runId` that invoke returned and pass `run_id` in place of `cancelation_token`. That branch answers with the run's resulting `status`, so you can assert the cancel landed. Cancelling by token echoes the token back and reports nothing about what it matched.

## Verify

**1. Watch a run take the right path**

Invoke for a test user with `has_activated: false` and open the Journey's **Logs** tab. Click the run to see each node's outcome drawn on the graph, and confirm the branch took the false path.

**2. Prove the delay parks the run**

The run should sit at the delay node rather than completing. Shorten the delay to a few minutes on a test copy if you would rather not wait three days.

**3. Confirm a cancel stops it**

Cancel the token while a run waits at a delay, then confirm the run reads `Canceled` and no further message is delivered.

> [!NOTE]
>
> An unpublished draft has no active version, so invoking it does nothing. Publish first, then invoke.

Every node type, and what each one accepts, is in the [nodes reference
DOC](/docs/journeys/nodes).


# Create your first journey
Source: https://www.courier.com/docs/guides/create-your-first-journey

Build a one-node journey, invoke it from your code, and read the run.

Build the smallest journey that works, start a run from your code, then open the run and read what it did.

One send node is enough to see the whole loop. Delays, branches, and digests are the same graph with more nodes on it.

To build a journey entirely with the API instead, see [Build your first journey
DOC](/docs/get-started/build-your-first-journey).

## Prerequisites

* [A connected email provider
  DOC](/docs/integrations/email/overview)
* [A Courier API key](https://app.courier.com/settings/api-keys)

## Build it

**1. Create the journey**

Open [Journeys](https://app.courier.com/orchestration/journeys), select **New Journey**, and name it. Choose the **API Invoke** trigger, which is what lets your code start each run.

**2. Add one send node**

Drop a **send** node on the canvas, pick email, and select **+ Create** to write its content inline. Each send node owns one Template scoped to this journey, so there is nothing to create separately.

Address the recipient by `user_id`. The profile supplies the email address, which means preferences apply and the address can change without touching this journey.

**3. Publish**

Select **Publish**. That locks the draft as a version and makes it the one new runs use. Copy the journey ID from the editor.

## Invoke it

[Invoke a Journey
DOC](/docs/journeys/invoke) carries the call in every language. The response returns a `runId`, which is the handle for everything below.

Send an `Idempotency-Key` if the call sits anywhere a retry could reach it, because a repeated key returns the stored result instead of starting a second run.

## Read the run

**Inspect runs in the console.** Take the `runId` from the invoke response, open the journey's **Logs** tab, and search for it.

The detail view draws each node's outcome on the graph. Click a node to see its step context: the input data, the profile, any conditions evaluated, and the output. [Journey logs
DOC](/docs/monitor/logs#journey-logs) cover the run states and what each view shows.

A journey that sends nothing looks identical to one that was never invoked until you open the run and see which node it stopped at.

## Verify

**1. The run completed**

Invoke for a test user, then confirm the run reads as complete rather than sitting on the send node.

**2. The message arrived**

Check the inbox for the address on that user's profile, then open [message logs
DOC](/docs/monitor/overview) and confirm the send is recorded against the journey.

**3. A second invoke starts a second run**

Invoke again without an `Idempotency-Key` and confirm two runs appear. Repeat with the same key and confirm only one does.

## What to add next

> **[Onboarding sequence](/docs/guides/build-an-onboarding-sequence)**
>
> Delays and a branch, so only stalled users get nudged.

> **[Nodes](/docs/journeys/nodes)**
>
> Every node type, one page each.

## Publish your changes

* **Publish the template to ship a content edit.** Editing a send node saves a template draft. A run sends the template's published version, and publishing the journey doesn't publish its templates.
* **Runs finish on the version they started with.** A new publish applies to runs that start after it.
* **Only a published journey runs.** Publish before you invoke.


# Debug email delivery
Source: https://www.courier.com/docs/guides/debug-delivery

Trace an email that never arrived from Courier logs to the provider to the inbox.

A recipient says the email never arrived. Start in Logs and work outward, from Courier to the provider to the inbox.

## Prerequisites

* A message you can point to, or the recipient and roughly when you sent it.
* Access to your email provider's dashboard, for everything past the handoff.

## Read the status first

The status tells you which half of the trip failed. [Message statuses
DOC](/docs/send/statuses) covers the full lifecycle. Two of them cause most of the confusion:

* **`SENT`** means the provider accepted the message. It isn't a delivery confirmation.
* **`DELIVERED`** means the recipient's mail server accepted it. It isn't proof the message reached the inbox.

> [!NOTE]
>
> A corporate mail gateway (Proofpoint, Mimecast, Barracuda) can quarantine a message after the server accepts it. `DELIVERED` with an empty inbox usually means the message is held on the recipient's side.

## Find where it stopped

**1. Open the message**

Filter [Logs](https://app.courier.com/logs) by recipient, template, or time range, then open the message.

**2. Read the timeline**

The timeline lists every step the message passed, from the request through routing, rendering, and the provider handoff. The last step that succeeded tells you who owns the problem.

**3. Open the provider response**

Select the send event to see what the provider returned, including its status code and its own message id. Use that id to find the same message in the provider's dashboard.

## See exactly what was rendered

The timeline tells you where a message stopped. It doesn't tell you what the recipient actually got, which is the question behind most "the notification looked wrong" reports.

[Get message content](/docs/api-reference/messages/get-message-content) returns the rendered content Courier delivered, broken out per channel:

```javascript Node.js theme={null}
const { results } = await client.messages.content("1-61e9e2f0-1f8b0d5e");

for (const output of results) {
  console.log(output.channel, output.content.subject);
}
```

```python Python theme={null}
response = client.messages.content("1-61e9e2f0-1f8b0d5e")

for output in response.results:
    print(output.channel, output.content.subject)
```

```bash cURL theme={null}
curl "https://api.courier.com/messages/1-61e9e2f0-1f8b0d5e/output" \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
response = courier.messages.content("1-61e9e2f0-1f8b0d5e")

response.results.each do |output|
  puts("#{output.channel} #{output.content.subject}")
end
```

```go Go theme={null}
response, err := client.Messages.Content(context.TODO(), "1-61e9e2f0-1f8b0d5e")
if err != nil {
	panic(err.Error())
}

for _, output := range response.Results {
	fmt.Println(output.Channel, output.Content.Subject)
}
```

```java Java theme={null}
MessageContentResponse response = client.messages().content("1-61e9e2f0-1f8b0d5e");

response.results().forEach(output ->
    System.out.println(output.channel() + " " + output.content().subject()));
```

```php PHP theme={null}
$response = $client->messages->content('1-61e9e2f0-1f8b0d5e');

foreach ($response->results as $output) {
    echo $output->channel, ' ', $output->content->subject, PHP_EOL;
}
```

```csharp C# theme={null}
var response = await client.Messages.Content("1-61e9e2f0-1f8b0d5e", new());

foreach (var output in response.Results)
{
    Console.WriteLine($"{output.Channel} {output.Content.Subject}");
}
```

```bash CLI theme={null}
courier messages content 1-61e9e2f0-1f8b0d5e \
  --api-key "$COURIER_API_KEY"
```

```text MCP theme={null}
With Courier MCP, show me the rendered content for message 1-61e9e2f0-1f8b0d5e.
```

Each result carries the `channel` it was rendered for and a `content` object holding whichever fields that channel uses, such as `subject` and `html` for email or `text` for SMS:

```json theme={null}
{
  "results": [
    {
      "channel": "email",
      "channel_id": "abc-123",
      "content": {
        "subject": "Your report is ready",
        "title": "Your report is ready",
        "html": "<html>…</html>",
        "text": "Your report is ready…"
      }
    }
  ]
}
```

This is what separates the three explanations that all look the same from the outside:

| What you see | What it means |
| :- | :- |
| A variable rendered as an empty string | The template is fine and `data` was missing a key |
| The variable name rendered literally | The template references a variable that doesn't exist |
| Content correct, provider rejected it | Neither one. Take the payload to the provider |

For the ordered list of status transitions and their timestamps, use [Get message history](/docs/api-reference/messages/get-message-history).

## Work the scenario

> **Stuck at SENT**
>
> Usually not a failure. Delivery confirmation is off until you configure it, per provider, so a healthy send stops at `SENT`. Check [how your provider reports
> DOC](/docs/send/statuses#delivery-tracking-is-per-provider) and set up its webhook or polling toggle.
>
> If tracking is already configured, the provider may be retrying a deferral, or Courier may not have polled yet. Confirm the outcome in the provider's dashboard.

> **UNDELIVERABLE**
>
> The provider rejected the message, and Courier doesn't retry. Open the event for the provider's error, then match it to a cause:
>
> * **Hard bounce.** The address doesn't exist, or the domain doesn't resolve.
> * **Soft bounce.** The mailbox is full or temporarily unavailable. Some providers retry before reporting failure.
> * **Block.** The receiving server refused the message on reputation, content, or policy.
> * **Suppression.** The address sits on the provider's suppression list from an earlier bounce or complaint. Remove it there before you can send to that address again.
>
> A valid address that bounces on reputation points at [sender authentication](#check-sender-authentication).

> **DELIVERED, but not in the inbox**
>
> The message reached the mail server. Three things commonly take it from there:
>
> * **Spam or junk.** Ask the recipient to check both folders.
> * **A security gateway.** When every affected recipient shares one domain, their IT team has to check the quarantine and allowlist your sending domain.
> * **An inbox rule.** A filter the recipient set may have moved or deleted the message.
>
> Send the same template to a personal address as a control. If that copy arrives, the problem is the recipient's domain, not your send.

> **FILTERED or UNROUTABLE**
>
> The cause is inside Courier: the message stopped before it reached a provider. `FILTERED` means preferences, a send condition, or a channel condition removed it. `UNROUTABLE` means no channel could be addressed, usually a missing email address on the profile. [Why a message is UNROUTABLE
> DOC](/docs/send/statuses#why-a-message-is-unroutable) lists each `reason` and its fix.

## Check sender authentication

Weak authentication causes failures that look random and hit many recipients at once. Confirm all three records for your sending domain:

| Record | What it does | How to check |
| - | - | - |
| **SPF** | Names the servers allowed to send for your domain | Look for a `v=spf1` TXT record that includes your provider |
| **DKIM** | Signs the message so the receiver can prove nothing altered it | Your provider's dashboard shows DKIM status and the record to add |
| **DMARC** | Tells receivers what to do when SPF or DKIM fails | Look for a TXT record at `_dmarc.yourdomain.com`, starting at `p=none` to monitor |

Each provider's setup page walks through its own records. See the [email integrations
DOC](/docs/integrations/email/overview).

> [!TIP]
>
> Tracked links use a shared `ct0.app` domain by default. A [custom tracking domain
> DOC](/docs/monitor/tracking) puts them on your own domain, which some filters treat more kindly. It is available on Business and above.

## Ask the provider

Courier's logs end where the provider takes over, so the delivery event itself lives there:

* **SendGrid**: the Activity Feed, per-message delivery events.
* **Postmark**: Activity, with bounce and complaint detail.
* **AWS SES**: the Reputation Dashboard, for bounce and complaint rates.
* **Mailgun**: Logs, for a message's full event history.
* **Mandrill**: Outbound Activity.

## Debug from an AI agent

[Courier MCP
DOC](/docs/resources/mcp) exposes the same message data as the console, so you can ask instead of click:

| What you want | Tool |
| - | - |
| Find the message | `list_messages` |
| Read its status and provider | `get_message` |
| Walk the timeline | `get_message_history` |
| See what was actually sent | `get_message_content` |
| Check the recipient's contact info | `get_user_profile_by_id` |
| Check their preferences | `get_user_preferences` |

```text MCP theme={null}
With Courier MCP, show me every undeliverable message from the last 24 hours and what each provider said.
```

An agent chains these, so one prompt can check a profile, confirm preferences, find the message, and read its timeline. The [CLI
DOC](/docs/resources/cli) covers the same ground in a script.

## Verify

Send the template to a test recipient and watch the status pass `SENT` in Logs. After a suppression or authentication fix, confirm the provider's own dashboard shows the new message as delivered.


# Go live
Source: https://www.courier.com/docs/guides/go-live

Validate a notification change in Test, then promote it to Production.

Build and validate a notification change without touching live traffic, then promote it to Production.

Test and Production are separate environments with their own keys, templates, and logs. Work in Test, review the draft against a real payload, then migrate the assets.

## The promotion path

```mermaid theme={null}
flowchart LR
    A["Edit in Test"] --> B["Preview draft"]
    B --> C{"Approval workflow?"}
    C -->|No| D["Migrate to Production"]
    C -->|Yes| E["Send for Review"]
    E --> D
```

## Prerequisites

* [A connected integration
  DOC](/docs/integrations/overview)
* [Your Test and Production API keys](https://app.courier.com/settings/api-keys)
* [The environments model
  DOC](/docs/workspaces/environments)

## Promote the change

**1. Work in the Test environment**

Switch to **Test** with the toggle in the settings menu. Templates, brands, and topics you create here are isolated from Production. Edit your template, then send with your Test key. Those sends appear only in the Test dashboard.

```javascript Node.js theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Sarah Bennett",
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "name": "Sarah Bennett",
        },
    },
)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "name": "Sarah Bennett"
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Sarah Bennett"
    }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett"
        )))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => [
      'name' => 'Sarah Bennett',
    ],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to sarah@acme-corp.com with my test key.
```

> [!TIP]
>
> **Keep test sends out of real inboxes.**\\
>
> Configure a sandbox provider key in each integration's Test configuration so Test sends stay in the sandbox.

**2. Preview the draft with a draft key**

A draft key renders the latest **unpublished** draft, not the published version. Use one to review a change against a real payload before publishing. Generate it in [Settings → API Keys](https://app.courier.com/settings/api-keys), send with it, then check the rendered output in [message logs
DOC](/docs/monitor/overview).

```javascript Node.js theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "reviewer@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Draft Preview",
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {
            "email": "reviewer@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "name": "Draft Preview",
        },
    },
)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "reviewer@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "name": "Draft Preview"
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "reviewer@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Draft Preview"
    }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("reviewer@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Draft Preview",
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("reviewer@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Draft Preview"
        )))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'reviewer@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => [
      'name' => 'Draft Preview',
    ],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "reviewer@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Draft Preview") },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "reviewer@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Draft Preview"}'
```

```text MCP theme={null}
With Courier MCP, send the unpublished draft of my nt_01kx4h2jdafq8bk9aftxak4b40 template to reviewer@acme-corp.com.
```

**3. Get approval (optional)**

If your team reviews changes before they ship, enable the [approval workflow
DOC](/docs/design/templates/api#approval-workflow). Publishing then opens a submission instead of going live, and the template stays read-only until that submission is resolved.

**4. Move the template to Production**

Read the template's content from Test and write it to Production with the Templates API. [Get Notification Content](/docs/api-reference/templates/get-notification-content) returns the `{ version, elements }` JSON, and [Replace Notification Content](/docs/api-reference/templates/replace-notification-content) writes it, using each environment's own key.

Remove every `checksum` field and any `locales` key that starts with an underscore before the PUT, and keep each element's `locales` so the Production template gets the same translations. [The round-trip contract
DOC](/docs/design/templates/api#update-content-the-round-trip-contract) covers the rest, and is the same flow as [managing templates as code
DOC](/docs/design/templates/api#manage-templates-as-code).

**Create a template's dependencies in Production yourself.** Brands, tags, and subscription topics are per environment, so set them up there first. A send that references one that is missing fails there while it worked in Test.

## Verify

**1. Smoke test with your Production key**

Send to an internal recipient in Production.

```javascript Node.js theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "ops@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Smoke Test",
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {
            "email": "ops@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "name": "Smoke Test",
        },
    },
)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "ops@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "name": "Smoke Test"
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "ops@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Smoke Test"
    }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("ops@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Smoke Test",
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("ops@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Smoke Test"
        )))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'ops@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => [
      'name' => 'Smoke Test',
    ],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "ops@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Smoke Test") },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "ops@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Smoke Test"}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to ops@acme-corp.com in production.
```

**2. Confirm the right version rendered**

Open the message in [Logs](https://app.courier.com/logs), expand the timeline, and confirm the migrated version is the one that rendered.

**3. Confirm the provider accepted it**

The same timeline shows the provider's response. A `SENT` status that doesn't progress to `DELIVERED` points at the provider, not the migration.


# Import your users
Source: https://www.courier.com/docs/guides/import-your-users

Create or update profiles one at a time or from a CSV, and delete them.

Get your users into Courier so a send only needs their `user_id`.

A profile stores one person's contact details. Load profiles from a CSV or your own database, then update them as your system of record changes.

[Users
DOC](/docs/recipients/overview) covers one profile and the field each channel reads. This guide is the same call at the scale of your whole user table.

## Prerequisites

* [A Courier account](https://app.courier.com/)
* [A Courier API key](https://app.courier.com/settings/api-keys)
* [Which field addresses which channel
  DOC](/docs/recipients/overview#what-each-channel-needs)

The examples assume a client initialized once with your key from the environment:

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});
```

```python Python theme={null}
import os

from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
```

```bash cURL theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])
```

```go Go theme={null}
client := courier.NewClient(
	option.WithAPIKey(os.Getenv("COURIER_API_KEY")),
)
```

```java Java theme={null}
CourierClient client = CourierOkHttpClient.fromEnv();
```

```php PHP theme={null}
$client = new Client(apiKey: getenv('COURIER_API_KEY'));
```

```csharp C# theme={null}
CourierClient client = new();
```

```bash CLI theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
```

## Create or update a profile

**1. Create or update a profile**

Creating and updating are the same call. [Create a Profile](/docs/api-reference/user-profiles/create-a-profile) merges the values you send into the profile, creating it if it doesn't exist and keeping any fields you leave out. The `user_id` in the path is the identifier you send to. You choose it.

```javascript Node.js theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    email: 'sarah@acme-corp.com',
    phone_number: '+15551234567',
    name: 'Sarah Bennett',
    locale: 'en-us',
    custom: { company: 'Acme Corp', plan: 'business' },
  },
});
```

```python Python theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "email": "sarah@acme-corp.com",
        "phone_number": "+15551234567",
        "name": "Sarah Bennett",
        "locale": "en-us",
        "custom": {"company": "Acme Corp", "plan": "business"},
    },
)
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "email": "sarah@acme-corp.com",
      "phone_number": "+15551234567",
      "name": "Sarah Bennett",
      "locale": "en-us",
      "custom": { "company": "Acme Corp", "plan": "business" }
    }
  }'
```

```ruby Ruby theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    email: "sarah@acme-corp.com",
    phone_number: "+15551234567",
    name: "Sarah Bennett",
    locale: "en-us",
    custom: {company: "Acme Corp", plan: "business"}
  }
)
```

```go Go theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"email":        "sarah@acme-corp.com",
			"phone_number": "+15551234567",
			"name":         "Sarah Bennett",
			"locale":       "en-us",
			"custom": map[string]any{
				"company": "Acme Corp",
				"plan":    "business",
			},
		},
	},
)
```

```java Java theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .putAdditionalProperty("phone_number", JsonValue.from("+15551234567"))
        .putAdditionalProperty("name", JsonValue.from("Sarah Bennett"))
        .putAdditionalProperty("locale", JsonValue.from("en-us"))
        .putAdditionalProperty("custom", JsonValue.from(Map.of("company", "Acme Corp", "plan", "business")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'email' => 'sarah@acme-corp.com',
  'phone_number' => '+15551234567',
  'name' => 'Sarah Bennett',
  'locale' => 'en-us',
  'custom' => ['company' => 'Acme Corp', 'plan' => 'business'],
]);
```

```csharp C# theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
        { "phone_number", JsonSerializer.SerializeToElement("+15551234567") },
        { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        { "locale", JsonSerializer.SerializeToElement("en-us") },
        { "custom", JsonSerializer.SerializeToElement(new { company = "Acme Corp", plan = "business" }) },
    },
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"email":"sarah@acme-corp.com","phone_number":"+15551234567","name":"Sarah Bennett","locale":"en-us","custom":{"company":"Acme Corp","plan":"business"}}'
```

```text MCP theme={null}
With Courier MCP, create a profile for user_123 with their email, phone number, and name.
```

> [!NOTE]
>
> **Device tokens are managed separately.**\\
>
> Push device tokens live on the user, but go through their own API, not the profile body. See [Push providers
> DOC](/docs/integrations/push/overview) to register them.

**2. Read the profile back**

Fetch the profile and confirm the stored fields, or open the user in [Users](https://app.courier.com/directory/users):

```javascript Node.js theme={null}
const profile = await client.profiles.retrieve('user_123');
```

```python Python theme={null}
profile = client.profiles.retrieve("user_123")
```

```bash cURL theme={null}
curl --request GET \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
profile = courier.profiles.retrieve("user_123")
```

```go Go theme={null}
profile, err := client.Profiles.Get(context.TODO(), "user_123")
```

```java Java theme={null}
ProfileRetrieveResponse profile = client.profiles().retrieve("user_123");
```

```php PHP theme={null}
$profile = $client->profiles->retrieve('user_123');
```

```csharp C# theme={null}
ProfileRetrieveParams parameters = new() { UserID = "user_123" };
var profile = await client.Profiles.Retrieve(parameters);
```

```bash CLI theme={null}
courier profiles retrieve \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123
```

```text MCP theme={null}
With Courier MCP, show me the stored profile for user_123.
```

**3. Replace instead of merge**

Use `POST` for everyday updates so you never drop data. Use `PUT` when the profile should become exactly what you send, dropping any field you omit.

```javascript Node.js theme={null}
const response = await client.profiles.replace('user_123', {
  profile: { email: 'sarah@acme-corp.com', name: 'Sarah Bennett' },
});
```

```python Python theme={null}
response = client.profiles.replace(
    user_id="user_123",
    profile={
        "email": "sarah@acme-corp.com",
        "name": "Sarah Bennett",
    },
)
```

```bash cURL theme={null}
curl --request PUT \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "email": "sarah@acme-corp.com",
      "name": "Sarah Bennett"
    }
  }'
```

```ruby Ruby theme={null}
response = courier.profiles.replace(
  "user_123",
  profile: {email: "sarah@acme-corp.com", name: "Sarah Bennett"}
)
```

```go Go theme={null}
response, err := client.Profiles.Replace(
	context.TODO(),
	"user_123",
	courier.ProfileReplaceParams{
		Profile: map[string]any{
			"email": "sarah@acme-corp.com",
			"name":  "Sarah Bennett",
		},
	},
)
```

```java Java theme={null}
ProfileReplaceParams params = ProfileReplaceParams.builder()
    .userId("user_123")
    .profile(ProfileReplaceParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .putAdditionalProperty("name", JsonValue.from("Sarah Bennett"))
        .build())
    .build();
ProfileReplaceResponse response = client.profiles().replace(params);
```

```php PHP theme={null}
$response = $client->profiles->replace('user_123', profile: [
  'email' => 'sarah@acme-corp.com',
  'name' => 'Sarah Bennett',
]);
```

```csharp C# theme={null}
ProfileReplaceParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
        { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
    },
};
var response = await client.Profiles.Replace(parameters);
```

```bash CLI theme={null}
courier profiles replace \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"email":"sarah@acme-corp.com","name":"Sarah Bennett"}'
```

```text MCP theme={null}
With Courier MCP, replace user_123's profile with just their email and name.
```

> [!WARNING]
>
> **Replacing removes omitted fields.**\\
>
> After a `PUT`, any field not in the request (a `phone_number`, a `custom` value) is gone. Use `POST` unless you intend a full overwrite. To change one field, use `PATCH` with a JSON-patch operation.

## Import users from a CSV

For a one-time load or an occasional top-up, import a CSV in the console. CSV import is console-only, so to load users programmatically, call the profile endpoints above for each user.

**1. Open the importer**

Go to [Users](https://app.courier.com/directory/users) and click **Import**. Download the CSV template from the dialog so your columns match exactly.

**2. Fill in the template**

Only `id` is required. Keep the header row exactly as the template provides it: don't rename, reorder, or add columns. Columns include `id`, `name`, `first_name`, `last_name`, `email`, `phone_number`, `locale`, `zoneinfo`, and the OIDC standard claims.

**3. Save as UTF-8 CSV and upload**

Save as **CSV (comma delimited)**, UTF-8 without a BOM, and with no blank line after the last row. Upload the file and click **Add Users** to create the profiles.

> **Fixing a 'Too few fields' import error**
>
> This error means the parser read a row as a single field, almost always a delimiter, encoding, or trailing-line problem:
>
> * **Wrong delimiter.** Open the file in a plain text editor. If fields are separated by semicolons or tabs (some spreadsheet locales use semicolons), re-save as CSV (comma delimited).
> * **Wrong encoding.** Garbled characters or `ÿþ` at the start mean the file is UTF-16. Recreate it as UTF-8. A UTF-8 BOM (`` before the first field) can also interfere. Remove it.
> * **Trailing blank line.** A "Too few fields" error on the last row only usually means an empty final line. Delete any blank lines after the last data row.
> * **Extra columns.** If the expected field count is higher than the template's, your header has extra trailing commas. Remove them.
>
> The most reliable fix is to build the CSV in a plain text editor rather than a spreadsheet app.

## Delete a profile

Deleting a profile removes all of its stored data. Sends to that `user_id` fail until a new profile exists.

```javascript Node.js theme={null}
await client.profiles.delete('user_123');
```

```python Python theme={null}
client.profiles.delete("user_123")
```

```bash cURL theme={null}
curl --request DELETE \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
courier.profiles.delete("user_123")
```

```go Go theme={null}
err := client.Profiles.Delete(context.TODO(), "user_123")
```

```java Java theme={null}
client.profiles().delete("user_123");
```

```php PHP theme={null}
$client->profiles->delete('user_123');
```

```csharp C# theme={null}
ProfileDeleteParams parameters = new() { UserID = "user_123" };
await client.Profiles.Delete(parameters);
```

```bash CLI theme={null}
courier profiles delete \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123
```

```text MCP theme={null}
With Courier MCP, delete the profile for user_123.
```

## Verify

**1. Read one profile back**

Fetch the profile you wrote and confirm every field you sent is there, spelled the way your templates expect.

**2. Send to the user\_id alone**

Send a message addressed only by `user_id`, with no inline profile. Courier resolves the contact details from storage, which proves the import landed.

**3. Check the count after a CSV import**

Open [Users](https://app.courier.com/directory/users) and confirm the number of profiles matches your file's row count. A short count usually means rows the parser rejected.


# Let customers edit their notifications
Source: https://www.courier.com/docs/guides/let-customers-edit-notifications

Embed Courier Create so each customer edits its own emails while your send stays the same.

Ship a Notifications tab in your product. Each customer edits their own emails, and your send never changes.

Every edit belongs to that customer's tenant. You mount the editor, scope a token to one tenant, and keep sending one template that resolves differently for each of them.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["Your settings page"] --> B["Embedded editor"]
    B --> C["Tenant's template"]
    D["Your send"] --> C
    C --> E["Branded email"]
```

## Prerequisites

* [A connected email provider
  DOC](/docs/integrations/email/overview)
* [A Courier API key](https://app.courier.com/settings/api-keys)
* [A tenant for each customer org
  GUIDE](/docs/guides/notify-across-tenants)
* A React app on 18.2.0 or newer

## Seed the tenant's template

Do this when your app creates the org. The editor opens on your wording instead of an empty page, and the send has content before anyone edits anything.

The `template_id` is an id you choose. Use the same one for every tenant, so your send never branches. Every element sits inside a `channel` block, the same rule [workspace templates
DOC](/docs/design/templates/api#content-needs-a-channel-to-live-in) follow.

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const response = await client.tenants.templates.replace('welcome', {
  tenant_id: 'acme-corp',
  template: {
    content: {
      version: '2022-01-01',
      elements: [
        {
          type: 'channel',
          channel: 'email',
          elements: [{ type: 'text', content: 'Welcome to Acme Corp!' }],
        },
      ],
    },
  },
});

console.log(response.id);
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.tenants.templates.replace(
    template_id="welcome",
    tenant_id="acme-corp",
    template={
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "channel",
                    "channel": "email",
                    "elements": [{"type": "text", "content": "Welcome to Acme Corp!"}],
                }
            ],
        }
    },
)
print(response.id)
```

```bash cURL wrap theme={null}
curl -X PUT https://api.courier.com/tenants/acme-corp/templates/welcome \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "channel",
            "channel": "email",
            "elements": [{ "type": "text", "content": "Welcome to Acme Corp!" }]
          }
        ]
      }
    }
  }'
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.tenants.templates.replace(
  "welcome",
  tenant_id: "acme-corp",
  template: {
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "channel",
          channel: "email",
          elements: [{ type: "text", content: "Welcome to Acme Corp!" }]
        }
      ]
    }
  }
)

puts(response)
```

```go Go theme={null}
// The typed elemental model has no field for a channel's child elements, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [{ "type": "text", "content": "Welcome to Acme Corp!" }]
    }
  ]
}`))

response, err := client.Tenants.Templates.Replace(
	context.TODO(),
	"welcome",
	courier.TenantTemplateReplaceParams{
		TenantID: "acme-corp",
		PutTenantTemplateRequest: courier.PutTenantTemplateRequestParam{
			Template: courier.TenantTemplateInputParam{Content: content},
		},
	},
)
```

```java Java theme={null}
TemplateReplaceParams params = TemplateReplaceParams.builder()
    .tenantId("acme-corp")
    .templateId("welcome")
    .putTenantTemplateRequest(PutTenantTemplateRequest.builder()
        .template(TenantTemplateInput.builder()
            .content(ElementalContent.builder()
                // The channel builder has no addElement, so its children go in as an additional property.
                .addElement(ElementalChannelNodeWithType.builder()
                    .type(ElementalChannelNodeWithType.Type.CHANNEL)
                    .channel("email")
                    .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                        java.util.Map.of("type", "text", "content", "Welcome to Acme Corp!"))))
                    .build())
                .version("2022-01-01")
                .build())
            .build())
        .build())
    .build();
client.tenants().templates().replace(params);
```

```php PHP theme={null}
$response = $client->tenants->templates->replace(
  'welcome',
  tenantID: 'acme-corp',
  template: [
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'channel',
          'channel' => 'email',
          'elements' => [['type' => 'text', 'content' => 'Welcome to Acme Corp!']],
        ],
      ],
    ],
  ],
);
```

```csharp C# theme={null}
TemplateReplaceParams parameters = new()
{
    TenantID = "acme-corp",
    TemplateID = "welcome",
    Template = new()
    {
        Content = new()
        {
            Version = "2022-01-01",
            Elements =
            [
                // Elemental nodes expose no typed content property, so build the node from raw JSON.
                ElementalChannelNodeWithType.FromRawUnchecked(
                    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                    {
                      "type": "channel",
                      "channel": "email",
                      "elements": [{ "type": "text", "content": "Welcome to Acme Corp!" }]
                    }
                    """)),
            ],
        },
    },
};

await client.Tenants.Templates.Replace(parameters);
```

```bash CLI theme={null}
courier tenants:templates replace \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --template-id welcome \
  --template '{"content":{"version":"2022-01-01","elements":[{"type":"channel","channel":"email","elements":[{"type":"text","content":"Welcome to Acme Corp!"}]}]}}'
```

```text MCP theme={null}
With Courier MCP, create a welcome template for acme-corp that greets their users.
```

The full lifecycle of a tenant template, including versions and deletes, is in [tenant templates
DOC](/docs/tenants/templates).

## Put the editor in your app

**1. Install the package**

```bash theme={null}
npm install @trycourier/react-designer
```

**2. Issue a token scoped to one tenant**

The editor runs in the browser, so it authenticates with a JWT rather than your API key. Mint one on your backend for the admin who is signed in, scoped to the tenant they belong to.

```javascript Node.js theme={null}
const { token } = await client.auth.issueToken({
  scope: "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
  expires_in: "1 day",
});
```

```python Python theme={null}
response = client.auth.issue_token(
    scope="user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
    expires_in="1 day",
)
```

```bash cURL wrap theme={null}
curl --request POST \
  --url https://api.courier.com/auth/issue-token \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "scope": "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
    "expires_in": "1 day"
  }'
```

```ruby Ruby theme={null}
response = courier.auth.issue_token(
  scope: "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
  expires_in: "1 day"
)
```

```go Go theme={null}
response, err := client.Auth.IssueToken(context.TODO(), courier.AuthIssueTokenParams{
  Scope:     "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
  ExpiresIn: "1 day",
})
```

```java Java theme={null}
AuthIssueTokenParams params = AuthIssueTokenParams.builder()
    .scope("user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write")
    .expiresIn("1 day")
    .build();

var response = client.auth().issueToken(params);
```

```php PHP theme={null}
$response = $client->auth->issueToken(
    scope: 'user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write',
    expiresIn: '1 day',
);
```

```csharp C# theme={null}
var response = await client.Auth.IssueToken(new AuthIssueTokenParams
{
    Scope = "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write",
    ExpiresIn = "1 day"
});
```

```bash CLI wrap theme={null}
courier auth issue-token \
  --scope "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write tenant:acme-corp:brand:read tenant:acme-corp:brand:write" \
  --expires-in "1 day"
```

```text MCP theme={null}
With Courier MCP, issue a one-day token for user_123 that can edit acme-corp's templates and brand.
```

Read the tenant id from your own session, never from the browser. A token carrying `tenants:` in place of `tenant:acme-corp:` grants every customer at once. Every scope is listed in [the designer's scopes
DOC](/docs/design/embedded-designer/overview#scopes).

**3. Mount the editor on your settings page**

`TemplateProvider` takes the template id you seeded, the tenant, and the token. `brandEditor` puts logo, colors, and footer beside the content, so one screen covers both.

```jsx theme={null}
import "@trycourier/react-designer/styles.css";
import { TemplateProvider, TemplateEditor } from "@trycourier/react-designer";

export function NotificationSettings({ tenantId, token }) {
  return (
    <TemplateProvider templateId="welcome" tenantId={tenantId} token={token}>
      <TemplateEditor routing={{ method: "single", channels: ["email"] }} brandEditor />
    </TemplateProvider>
  );
}
```

`routing` limits which channels the customer sees. Leave it out and they get every channel your workspace sends on. Every prop is in [the template editor reference
DOC](/docs/design/embedded-designer/template-editor).

**4. Publish on your own terms**

The editor auto-saves a draft and ships its own Publish button. Hide that button when publishing should run through your own review or your own UI, then call the hook.

```jsx theme={null}
import { useTemplateActions } from "@trycourier/react-designer";

function PublishButton() {
  const { publishTemplate } = useTemplateActions();
  return <button onClick={() => publishTemplate()}>Save and publish</button>;
}
```

Render it beside `<TemplateEditor hidePublish />`. A draft the customer never publishes doesn't reach anyone, so the send keeps using the last published version.

## Send what the customer published

**1. Name the tenant's template**

Reference it as `tenant/<template_id>` and set the tenant in the context. The word `tenant` is literal, and your tenant id goes in `context.tenant_id`.

```javascript Node.js highlight={9} theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const { requestId } = await client.send.message({
  message: {
    template: 'tenant/welcome',
    context: { tenant_id: 'acme-corp' },
    to: { user_id: 'user_123' },
  },
});

console.log(requestId);
```

```python Python highlight={9} theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "template": "tenant/welcome",
        "context": {"tenant_id": "acme-corp"},
        "to": {"user_id": "user_123"},
    },
)
print(response.request_id)
```

```bash cURL highlight={6} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "tenant/welcome",
      "context": { "tenant_id": "acme-corp" },
      "to": { "user_id": "user_123" }
    }
  }'
```

```ruby Ruby highlight={7} theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    template: "tenant/welcome",
    context: { tenant_id: "acme-corp" },
    to: { user_id: "user_123" }
  }
)

puts(response)
```

```go Go highlight={3} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		Template: courier.String("tenant/welcome"),
		Context:  shared.MessageContextParam{TenantID: courier.String("acme-corp")},
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .template("tenant/welcome")
        .context(JsonValue.from(java.util.Map.of("tenant_id", "acme-corp")))
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={3} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'tenant/welcome',
    'context' => ['tenantID' => 'acme-corp'],
    'to' => ['userID' => 'user_123'],
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        Template = "tenant/welcome",
        Context = new MessageContext { TenantID = "acme-corp" },
        To = new UserRecipient { UserID = "user_123" },
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"template":"tenant/welcome","context":{"tenant_id":"acme-corp"},"to":{"user_id":"user_123"}}'
```

```text MCP theme={null}
With Courier MCP, send acme-corp's welcome template to user_123.
```

This is the whole payoff. The call is identical for every customer, and only `tenant_id` changes.

**2. Reach the whole org**

Swap `to` for a `tenant_id` and Courier sends to every member of that org, still in their own content and brand. [Send with tenants
DOC](/docs/tenants/send) covers each targeting shape.

## Verify

**1. Edit as a customer would**

Open your settings page signed in as a user of `acme-corp`, change a line of copy and the logo, then publish.

**2. Read the template back**

[Fetch the tenant's template](/docs/api-reference/tenant-templates/get-a-template-in-tenant) and confirm the published content carries the edit.

**3. Send and compare two orgs**

Send to a user in `acme-corp` and a user in `beta-inc`, then open both in [Logs](https://app.courier.com/logs). Same call, same template id, two different messages.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| The editor renders blank | No template exists at that id for this tenant | Seed it with the create call above |
| Requests from the editor 401 | The token expired, or it is missing a scope | Reissue with the `notifications` and `brand` scopes |
| Edits save but never arrive | The draft was never published | Publish from the editor, or call `publishTemplate` |
| The send renders your copy, not theirs | The `tenant/` prefix or `context.tenant_id` is missing | Send `template: "tenant/welcome"` in that tenant's context |
| One customer sees another's content | The token used a plural `tenants:` scope | Scope it to `tenant:<id>:` for the signed-in org |

Brand, defaults, and templates all resolve from the same tenant, in the order set out in [tenant context
DOC](/docs/tenants/context). To give a customer their own defaults as well as their own copy, see [tenant default preferences
DOC](/docs/tenants/preferences).


# Migrate from Braze
Source: https://www.courier.com/docs/guides/migrate/from-braze

Move transactional flows from Braze canvases and campaigns to Courier journeys and templates.

Plan and run a migration of your transactional notification flows from Braze to Courier.

> [!NOTE]
>
> Braze is a marketing automation platform: campaigns, analytics, and customer engagement. Only the transactional and product notification workflows move to Courier. Marketing campaign orchestration is outside its scope.

## Map Braze concepts to Courier

| Braze | Courier |
| - | - |
| [Campaigns](https://www.braze.com/docs/user_guide/engagement_tools/campaigns/) | [Templates&#xA;DOC](/docs/design/templates/overview) + [Send API&#xA;DOC](/docs/send/overview) |
| [Canvas](https://www.braze.com/docs/user_guide/engagement_tools/canvas/) | [Journeys&#xA;DOC](/docs/journeys/overview) |
| [Segments](https://www.braze.com/docs/user_guide/engagement_tools/segments/) | [Audiences&#xA;DOC](/docs/recipients/lists-and-audiences/audiences) |
| [User Profiles](https://www.braze.com/docs/user_guide/data/unification/user_data/) | [Users / Profiles&#xA;DOC](/docs/recipients/overview) |
| [Subscription Groups](https://www.braze.com/docs/user_guide/message_building_by_channel/sms_mms_rcs/subscription_groups/) | [Preferences&#xA;DOC](/docs/recipients/preferences/overview) |
| [Content Cards](https://www.braze.com/docs/user_guide/message_building_by_channel/content_cards/) | [Inbox&#xA;DOC](/docs/in-app/overview) |
| [Connected Content](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/connected_content/) | `data` on send + [Fetch data node&#xA;DOC](/docs/journeys/nodes/fetch-data) |
| [Currents](https://www.braze.com/docs/user_guide/data/distribution/braze_currents/) | [Outbound Webhooks&#xA;DOC](/docs/monitor/webhooks/outbound) |
| [Liquid templating](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/liquid/) | [Handlebars variables&#xA;DOC](/docs/design/templates/variables) |

### Campaigns and templates

Braze [campaigns](https://www.braze.com/docs/user_guide/engagement_tools/campaigns/) bundle content, audience targeting, scheduling, and delivery into one resource. Courier splits them: [templates
DOC](/docs/design/templates/overview) own the content, and the [Send API
DOC](/docs/send/overview) or [Journeys
DOC](/docs/journeys/overview) handle delivery.

Your product team updates copy in Design Studio without touching delivery logic. Your engineers change routing or timing without breaking template content.

One template holds content for every channel (email, SMS, push, chat, inbox). Build it with drag-and-drop blocks, or define it in [Elemental
DOC](/docs/design/elemental/overview) JSON.

### Canvas and Journeys

Braze [Canvas](https://www.braze.com/docs/user_guide/engagement_tools/canvas/) is a visual builder for multi-step, multi-channel journeys. Courier [Journeys
DOC](/docs/journeys/overview) do the same for transactional flows: [delays
DOC](/docs/journeys/nodes/delay), [branching
DOC](/docs/journeys/nodes/branch), [batching
DOC](/docs/journeys/nodes/batch), [digests
DOC](/docs/journeys/nodes/digest), and [cancellation
DOC](/docs/journeys/nodes/cancel).

| Canvas Step | Courier Equivalent |
| - | - |
| Message step | [Send node&#xA;DOC](/docs/journeys/nodes/send) (references a template) |
| Delay step | [Delay node&#xA;DOC](/docs/journeys/nodes/delay) |
| Decision split | [Branch node&#xA;DOC](/docs/journeys/nodes/branch) |
| Action paths | [Branch node&#xA;DOC](/docs/journeys/nodes/branch) with conditions |
| Audience paths | [Audiences&#xA;DOC](/docs/recipients/lists-and-audiences/audiences) + [branch&#xA;DOC](/docs/journeys/nodes/branch) conditions on profile data |

Canvas entry criteria become [journey triggers
DOC](/docs/journeys/invoke): an API invoke, an inbound webhook, a Segment event, or a user joining an audience. Build journeys [in the UI
DOC](/docs/journeys/build) or through the [Journeys API
DOC](/docs/journeys/build).

### Segments and audiences

Braze [segments](https://www.braze.com/docs/user_guide/engagement_tools/segments/) filter on user attributes, behaviors, and events. Courier [Audiences
DOC](/docs/recipients/lists-and-audiences/audiences) group users dynamically by profile attributes. Define the filter rules once and Courier keeps membership current as profiles change.

You can also target a [List](/docs/api-reference/lists/list-lists), a static subscriber group, or send to individual users.

### Users and profiles

Courier [profiles
DOC](/docs/recipients/overview) store a recipient's email, phone, push tokens, and any custom properties you personalize with. Profiles accept nested JSON, so structured data like account tiers, team roles, or feature flags fits as-is.

Create profiles ahead of time through the API, or identify users inline at send time. Pass a `user_id` that doesn't exist yet and Courier creates the profile.

### Subscription groups and preferences

Braze [subscription groups](https://www.braze.com/docs/user_guide/message_building_by_channel/sms_mms_rcs/subscription_groups/) manage opt-in and opt-out per channel. Courier [Preferences
DOC](/docs/recipients/preferences/overview) go further. Users opt out by channel, category, or notification topic, and Courier enforces that at send time.

Courier also ships a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page) and embeddable [React components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) for a preference center inside your app.

### Content Cards and Inbox

Braze [Content Cards](https://www.braze.com/docs/user_guide/message_building_by_channel/content_cards/) deliver persistent in-app content. Courier [Inbox
DOC](/docs/in-app/overview) is a real-time in-app notification center, with drop-in components for [React
DOC](/docs/sdk-libraries/courier-react-web), [iOS
DOC](/docs/sdk-libraries/ios), [Android
DOC](/docs/sdk-libraries/android), and [vanilla JS
DOC](/docs/sdk-libraries/courier-js-web).

Inbox runs on the same delivery pipeline as email, push, and SMS. There's no separate provider to configure. You get read/unread state, archiving, per-user history, [toast notifications
DOC](/docs/in-app/add-toasts), and [tab-based organization
DOC](/docs/in-app/customize-the-inbox).

### Connected content and dynamic data

Braze's [Connected Content](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/connected_content/) pulls external data into templates at render time. In Courier, you pass the data a template needs in the `data` field on the send request. To fetch data mid-journey, the [Fetch data node
DOC](/docs/journeys/nodes/fetch-data) calls an external API and passes the response to later nodes.

### Templating language

Braze uses [Liquid](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/liquid/) to personalize messages. Courier uses [Handlebars variables
DOC](/docs/design/templates/variables) and `{{variable}}` syntax. Both support conditionals, loops, and helpers for date formatting, string manipulation, and conditional rendering.

## Why Courier

* **API-first for developers.** Courier is built for transactional and product notifications. A single API call sends to any channel. No campaign setup required.
* **Content and logic stay separate.** Templates and journeys are independent resources. Your product team updates copy in Design Studio while your engineers tune journey timing.
* **Design Studio.** Build email, SMS, push, and chat content with drag-and-drop blocks. Preview across channels, personalize with variables, and publish without deploying code.
* **Built-in in-app channel.** Courier Inbox works without a third-party provider. Drop in a React, iOS, or Android component and send on the same pipeline as email and push.
* **Automatic failover.** Configure multiple providers per channel. If your primary email provider goes down, traffic shifts to the backup without a code change.
* **The providers you already use.** Email, SMS, push, chat, webhooks, CDPs, and observability tools. Switch providers without changing your send code.
* **Full delivery observability.** [Message Logs
  DOC](/docs/monitor/overview) track every message from API request to provider delivery, with a timeline, error details, and the rendered content.

## Migrate step by step

**1. Create your Courier workspace**

[Sign up](https://app.courier.com/signup) and create a workspace. Test and Production [environments
DOC](/docs/workspaces/environments) have independent API keys, so you can migrate without touching live traffic.

**2. Configure integrations**

Go to **Integrations** in the Courier dashboard and connect the same providers you use in Braze (SendGrid, Twilio, FCM). Each provider maps to a channel type (email, SMS, push, chat). Configure multiple providers per channel for [failover
DOC](/docs/send/routing).

If you use Braze Content Cards for in-app messaging, [Courier Inbox
DOC](/docs/in-app/overview) is already set up in production and test. No external provider needed.

**3. Recreate templates**

Braze campaigns bundle content and delivery config. Extract the content into [templates
DOC](/docs/design/templates/overview) in Design Studio:

1. Create a new template for each transactional notification type
2. Add content blocks for each channel (email, SMS, push, etc.)
3. Convert Liquid variables (`{{user.first_name}}`) to [Handlebars syntax
   DOC](/docs/design/templates/variables) (`{{first_name}}`). The data comes from the send request's `data` field
4. Publish the template to make it available for sending

Recreate multi-step Canvas flows separately in [Journeys
DOC](/docs/journeys/overview).

**4. Migrate user data**

Create profiles with the same identifiers you use in Braze, through the [Profiles API](/docs/api-reference/user-profiles/create-a-profile) or inline at send time.

```json theme={null}
{
  "user_id": "user_123",
  "profile": {
    "email": "sarah@acme-corp.com",
    "phone_number": "+15551234567",
    "custom": {
      "name": "Sarah Bennett",
      "plan": "enterprise"
    }
  }
}
```

**5. Set up preferences**

If you use Braze subscription groups, recreate your preference structure in Courier:

1. Define [subscription topics
   DOC](/docs/recipients/preferences/overview) that map to your Braze subscription groups
2. Configure default channel routing per topic
3. Migrate user preference selections via the [Preferences API](/docs/api-reference/user-preferences/get-users-preferences)

Courier also provides a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page), or [React components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) for embedding preferences in your app.

**6. Update your send calls**

Replace Braze's campaign trigger or Canvas trigger API calls with Courier's [Send API
DOC](/docs/send/overview):

```javascript Node.js theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: {
      order_id: 'ORD-456',
      total: 79.99,
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "order_id": "ORD-456",
            "total": 79.99,
        },
    },
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "order_id": "ORD-456",
        "total": 79.99
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { order_id: "ORD-456", total: 79.99 }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"order_id": "ORD-456",
			"total": 79.99,
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "order_id", "ORD-456",
            "total", 79.99)))
        .build())
    .build();
client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['order_id' => 'ORD-456', 'total' => 79.99],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "order_id", JsonSerializer.SerializeToElement("ORD-456") },
            { "total", JsonSerializer.SerializeToElement(79.99) },
        },
    },
};

await client.Send.Message(parameters);
```

```bash CLI theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"order_id":"ORD-456","total":79.99}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with the order details.
```

Courier handles routing, preferences, and failover from your template and workspace configuration.

**7. Set up event streaming**

If you stream delivery events with Braze Currents, configure [Outbound Webhooks
DOC](/docs/monitor/webhooks/outbound) to forward message events (sent, delivered, opened, clicked) to your data warehouse or analytics pipeline.

**8. Test and cut over**

1. Send test messages in your Test environment and verify delivery in [Message Logs](https://app.courier.com/logs)
2. Validate that preferences, routing, and template rendering match your Braze setup
3. Switch your production code to use Courier's Production API key
4. Monitor [Message Logs
   DOC](/docs/monitor/overview) and [Analytics
   DOC](/docs/monitor/overview) for delivery confirmation

## Migrate with an AI agent

Most of this migration is mechanical: read a campaign definition, create the equivalent Courier template, rewrite the call site. A coding agent handles that well.

Three things to set up first:

* **[Courier Skills
  DOC](/docs/resources/skills)** teaches the agent Courier's real APIs and patterns so it stops guessing at endpoints:

  ```bash theme={null}
  npx skills add trycourier/courier-skills
  ```

  In Claude Code, install it as a plugin instead. The plugin self-updates and ships the Courier docs MCP server.

* **[Courier's MCP server
  DOC](/docs/resources/mcp)** gives the agent direct access to your workspace: create templates, build journeys, upsert users, and read send logs. See [Build with AI
  DOC](/docs/get-started/build-with-ai) for setup in Claude Code, Cursor, Codex, and VS Code.

* **Docs for agents.** Point it at [llms-full.txt](https://www.courier.com/docs/llms-full.txt) when it needs API detail beyond this page.

Then start it with a prompt like this one. Fill in the bracketed parts.

```text theme={null}
Help me migrate our notifications from Braze to Courier.

Read first:
- https://www.courier.com/docs/guides/migrate/from-braze
  (concept mapping and the migration steps you should follow)
- https://www.courier.com/docs/llms-full.txt
  (full Courier docs, for API detail as you need it)

Our setup:
- Codebase: [path]
- Braze API credentials: [env var]
- Courier: connected through the Courier MCP server

Work in this order. Stop after step 3 and wait for my review
before you create anything in Courier.

0. Setup. Install Courier Skills so you build against Courier's real
   APIs and patterns rather than guessing:
   npx skills add trycourier/courier-skills
   Then confirm the Courier MCP server is connected. If either one is
   missing, stop and tell me before going further.

1. Inventory. Use the Braze REST API to list every active campaign
   and Canvas. For each, record: name, entry trigger (API-triggered,
   scheduled, or action-based), channels, target segment, and whether
   it is a single send or a multi-step flow.

2. Classify each as:
   - transactional (an action in our product must produce it)
   - marketing (campaign or lifecycle)
   - in-app guidance (Content Cards, in-app messages)

3. Find the send sites. Grep the codebase for Braze
   POST /messages/send, POST /campaigns/trigger/send, and
   POST /canvas/trigger/send calls, plus POST /users/track calls that
   only exist to set an attribute a campaign triggers on. Map each to
   the campaign or Canvas it fires.

   Report the inventory, the classification, and the send-site list.
   Then wait.

4. Transactional first. For each transactional campaign: create the
   Courier template with the channels it needs, convert its Liquid
   personalization to Courier variables, then rewrite the call site to
   a Courier /send that names the template and passes data. Leave the
   Braze call in place behind a flag so we can run both and compare.

5. Canvases become journeys. Recreate each multi-step Canvas through
   the Courier journeys API. Delay steps become delay nodes, decision
   splits become branch nodes, message steps become send nodes, and
   exit criteria become cancel nodes.

6. Preferences. Map each Braze subscription group to a Courier
   subscription topic and import the opt-out state before any
   marketing send.

Rules:
- Never send to a real user. Use a test profile in the Test
  environment for every verification send.
- Never pause, disable, or delete anything in Braze. That is my call.
- If something in Braze has no Courier equivalent, say so in your
  report rather than approximating it.
```

Review the Liquid conversion in step 4 closely. Braze resolves `{{user.*}}` against its own user store. Each one becomes either a Profile attribute you sync or a value you pass in `data`. Decide that before the Templates exist, not after.

## Map the API

| Operation | Braze | Courier |
| - | - | - |
| Send a notification | `POST /messages/send` | [Send a message](/docs/api-reference/send/send-a-message) |
| Trigger a workflow | `POST /canvas/trigger/send` | [Invoke a Journey](/docs/api-reference/journeys/invoke-a-journey) |
| Create/update a user | `POST /users/track` | [Replace a Profile](/docs/api-reference/user-profiles/replace-a-profile) |
| Get a user | `POST /users/export/ids` | [Get a Profile](/docs/api-reference/user-profiles/get-a-profile) |
| Manage subscriptions | `POST /subscription/status/set` | [Update or create user Preferences for a Subscription Topic](/docs/api-reference/user-preferences/update-or-create-user-preferences-for-a-subscription-topic) |
| Get message status | Campaign analytics endpoints | [Get message](/docs/api-reference/messages/get-message) |
| Bulk operations | `POST /users/track` (batch) | [Create a bulk job](/docs/api-reference/bulk/create-a-bulk-job) |


# Migrate from an in-house system
Source: https://www.courier.com/docs/guides/migrate/from-in-house

Replace homegrown notification code with Courier one notification type at a time.

Most teams don't arrive from another vendor. They arrive from a `sendEmail()` helper that grew for three years.

This guide maps that code to Courier and moves it across one notification type at a time, with both systems running until the logs agree.

## What you already built

A homegrown system is rarely one component. It is a provider SDK, a template directory, a preferences table, and a cron job, each added when something broke.

| What you maintain | What replaces it |
| :- | :- |
| `sendEmail()` wrapping a provider SDK | [One send call&#xA;DOC](/docs/send/overview), with the provider chosen by config |
| A second wrapper for SMS, and a third for push | The same call, with [routing&#xA;DOC](/docs/send/routing) deciding the channel |
| Hardcoded HTML, or a templates directory | [Templates&#xA;DOC](/docs/design/templates/overview), editable without a deploy |
| A `notification_preferences` table and its checks | [Preferences&#xA;DOC](/docs/recipients/preferences/overview), enforced at send time |
| A cron job that batches the nightly digest | A [digest node&#xA;DOC](/docs/journeys/nodes/digest) |
| Retry, backoff, and dead-letter handling | [Retries and provider failover&#xA;DOC](/docs/send/routing#failover) |
| `user_id` to email and phone lookups | [Profiles&#xA;DOC](/docs/recipients/overview) |
| A WebSocket feed, unread counts, and read state | [Inbox&#xA;DOC](/docs/in-app/overview) |

The preferences row is the one teams underestimate. A `notification_preferences` table is easy to add and hard to finish, because every new notification type needs a column, a migration, and a check at every call site.

## What this actually buys you

Frame the project as deleting code you maintain, not as adopting a platform. That is what it is, and it is the honest way to size it.

**Provider changes stop being deploys.** Swapping SendGrid for SES becomes configuration. Adding a backup provider becomes configuration.

**Copy changes stop being tickets.** A PM edits a template and publishes. Your queue doesn't know the difference.

**The failure modes get names.** A homegrown send that vanishes leaves you grepping logs. Courier gives every message a [status
DOC](/docs/send/statuses) and a reason, so `UNROUTABLE` and `BOUNCED` and `OPT_IN_REQUIRED` are distinguishable.

Cost is worth checking early rather than at the end. [How sends are counted
DOC](/docs/workspaces/billing#how-sends-are-counted) is the number to model against, and it counts sends rather than seats or channels.

## Migrate incrementally

Nobody rewrites every notification in one release. Move one type, prove it, then move the next.

**1. Inventory what you send**

List every notification your code can produce, and for each one record the trigger, the channel, and the audience.

The list is usually longer than anyone expects, and it is the artefact the rest of the migration runs on. Sort it by volume. The lowest-volume, least-critical notification is the one to move first.

**2. Connect the providers you already use**

Add your existing SendGrid, Twilio, or FCM credentials as [integrations
DOC](/docs/integrations/overview). You keep the same accounts, the same sending domains, and the same sender reputation.

Nothing about deliverability changes at this step, which is what makes the cutover reversible.

**3. Move your users in**

Send your existing user records to [Create a Profile](/docs/api-reference/user-profiles/create-a-profile) and keep the id your database already uses. [Import your users
GUIDE](/docs/guides/import-your-users) covers the bulk path.

Reusing your own `user_id` matters more than it looks. It means no mapping table, and it means a send from anywhere in your code can address a user with the id it already has.

**4. Rebuild one notification**

Take the lowest-stakes item from your inventory. Recreate its content as a [template
DOC](/docs/design/templates/overview), then replace that one call site with a Courier send.

Leave every other call site alone.

**5. Run both, and compare**

Keep your old path sending, and have Courier send to a test recipient in the [Test environment
DOC](/docs/workspaces/environments). Compare what arrives.

You're checking three things: the content renders the same, the recipient resolves to the same person, and the timing is what you expect.

**6. Cut over, then delete**

Point production at the Courier send and remove the old code path. Not commented out, removed. A dead path that still compiles is one someone reintroduces in six months.

Then take the next item from the inventory.

## Verify

**1. Confirm delivery in the logs**

Open [Logs](https://app.courier.com/logs) and find the message. The timeline shows routing, rendering, and the provider handoff.

**2. Check a preference is honored**

Opt a test user out of the topic, send again, and confirm the message is `FILTERED` rather than delivered. That proves your preferences moved, which is the part most likely to be missed.

**3. Compare against the old system**

For the notification you moved, confirm the volume in Courier matches what your old path used to send over the same period. A gap means a call site you haven't found yet.

## What you can delete at the end

The point of the inventory is that it doubles as a deletion list.

* Provider SDK wrappers, and the per-provider error handling around them
* The template directory, and whatever renders it
* The preferences table, its migrations, and every call-site check
* Retry, backoff, and dead-letter queues for notification sends
* The cron jobs that batch digests
* The WebSocket server behind your in-app feed, if you adopt [Inbox
  DOC](/docs/in-app/overview)

Keep one thing: whatever decides *that* a notification should happen. That logic is your product, and it belongs in your code. Courier owns everything after that decision.


# Migrate from Intercom
Source: https://www.courier.com/docs/guides/migrate/from-intercom

Map Intercom series, messages, and contacts to Courier, and keep the help desk in place.

This guide maps Fin (formerly Intercom) concepts to Courier, covers transactional and marketing sends, and lays out a phased plan.

It says "Intercom" throughout, because the product surfaces and the API still call themselves Intercom.

Intercom is a support platform, and doubling down on that. The company renamed itself Fin in May 2026, after its AI support agent. Salesforce has signed a definitive agreement to acquire it and fold that agent technology into Agentforce. Outbound messaging sits beside that focus, and the API shows where the investment went. Sends are modeled as support conversations owned by an agent seat. Push and SMS have no send endpoint. Campaign definitions can be exported but never created in code.

Reasonable tradeoffs for a help desk, poor ones for the messages your product sends. A password reset, receipt, usage alert, or onboarding sequence needs a send API, per-channel routing, provider failover, preference enforcement, and delivery logs. Threading a conversation between a customer and an agent needs almost none of that.

Most teams land on a split. Intercom keeps the help desk, and Courier takes over what your product sends. Courier's UI and API are at full parity, so every Template, Journey, Audience, and Topic can be created programmatically. A coding agent with [Courier's MCP server
DOC](/docs/resources/mcp) can do most of the mechanical translation, using the [ready-made prompt](#migrate-with-an-ai-agent) below.

## Map Intercom concepts to Courier

| Intercom | Courier |
| - | - |
| [Series](https://www.intercom.com/help/en/collections/2091449-outbound) | [Journeys&#xA;DOC](/docs/journeys/overview) |
| Event-triggered outbound messages | [Send API&#xA;DOC](/docs/send/overview) or [journey triggers&#xA;DOC](/docs/journeys/invoke) |
| [`POST /events`](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/data-events) as a send trigger | Direct [Send a message](/docs/api-reference/send/send-a-message) or [journey invoke&#xA;DOC](/docs/journeys/invoke) |
| [`POST /messages`](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/messages) | [Send API&#xA;DOC](/docs/send/overview) with a template |
| One-off email or post to a segment | [Broadcasts&#xA;DOC](/docs/broadcasts/overview) |
| Message composer and content blocks | [Design Studio&#xA;DOC](/docs/design/templates/design-studio) |
| Contacts and custom attributes | [User profiles&#xA;DOC](/docs/recipients/overview) (nested JSON) |
| Segments | [Audiences&#xA;DOC](/docs/recipients/lists-and-audiences/audiences) |
| [Subscription Types](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/subscription-types) | [Preference topics&#xA;DOC](/docs/recipients/preferences/overview) |
| Mobile Push | Push channel through [your providers&#xA;DOC](/docs/integrations/overview) |
| SMS and WhatsApp | SMS and chat channels through [your providers&#xA;DOC](/docs/integrations/overview) |
| Posts, News items | [Courier Inbox&#xA;DOC](/docs/in-app/overview) |
| Banners | Your own UI over [Courier Inbox&#xA;DOC](/docs/in-app/overview) data today, in-app banners on the roadmap |
| Message frequency rules | [Send limits&#xA;DOC](/docs/send/statuses#send-limits) and [throttle nodes&#xA;DOC](/docs/journeys/nodes/throttle) |
| Access tokens | [API keys&#xA;DOC](/docs/reference/api-overview#authentication) |
| Messenger, Intercom Inbox, tickets, Workflows, Help Center, Fin | Stays in Intercom |

### Series and Journeys

Intercom [Series](https://www.intercom.com/help/en/collections/2091449-outbound) is the multi-step campaign builder: contacts enter on a rule or an event, then move through waits, splits, and sends. It requires the Proactive Support Plus add-on.

Courier [Journeys
DOC](/docs/journeys/overview) fill the same role, with [four trigger types
DOC](/docs/journeys/invoke): API invoke, inbound webhook, Segment event, and audience membership.

| Series element | Courier equivalent |
| - | - |
| Message node (email, push, chat, SMS) | [Send node&#xA;DOC](/docs/journeys/nodes/send) (references a template) |
| Wait or delay | [Delay node&#xA;DOC](/docs/journeys/nodes/delay) |
| Rules branch | [Branch node&#xA;DOC](/docs/journeys/nodes/branch) |
| Exit rules | [Cancel node&#xA;DOC](/docs/journeys/nodes/cancel) + [cancellation API&#xA;DOC](/docs/journeys/invoke) |
| A/B content test | [Experiments&#xA;DOC](/docs/journeys/experiments) on send nodes |
| Tag or attribute update | [Update a Profile](/docs/api-reference/user-profiles/update-a-profile) |

Two node types have no Series equivalent:

* **[Batch
  DOC](/docs/journeys/nodes/batch) and [digest
  DOC](/docs/journeys/nodes/digest) nodes** collapse many events into one message. In Intercom, you precompute roll-ups in your own backend before firing the triggering event.
* **[Fetch data nodes
  DOC](/docs/journeys/nodes/fetch-data)** call an external API mid-journey and use the response in later steps.

Journeys are also [buildable through the API
DOC](/docs/journeys/build). Intercom has no Series endpoint, so a Series exists only in the UI. Its one [workflow endpoint](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/workflows), `GET /export/workflows/{id}`, is read-only, documented as an EU Data Act compliance export, and covers Workflows rather than Series. Either way, campaign definitions can't be versioned as code.

### Event-triggered messages and the Send API

This is the biggest change in the migration. Plan it first.

Intercom's `POST /messages` endpoint accepts `message_type` values of `in_app`, `email`, or `whatsapp`. There is no push or SMS send endpoint. Its `template` field is a message style (`plain` or `personal`), not a reference to content you built in the composer. So sending a designed message from your backend is indirect: post an event, and let a message you configured in the UI match on it.

```bash theme={null}
# Intercom: fire an event and let a pre-configured rule match it
curl -X POST https://api.intercom.io/events \
  -H "Authorization: Bearer $INTERCOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "password_reset_requested",
    "created_at": 1755500000,
    "user_id": "user_123",
    "metadata": { "reset_url": "https://app.example.com/r/abc123" }
  }'
```

That returns `202 Accepted` with an empty body. Your code learns the event was accepted, not that a message was created. Intercom exposes no delivery status endpoint for email, push, or in-app.

In Courier, the same send is explicit. You name the template, the recipient, and the data, and the response carries a `requestId`:

```javascript Node.js theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      reset_url: "https://app.example.com/r/abc123",
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "reset_url": "https://app.example.com/r/abc123",
        },
    },
)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "reset_url": "https://app.example.com/r/abc123"
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      reset_url: "https://app.example.com/r/abc123"
    }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"reset_url": "https://app.example.com/r/abc123",
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "reset_url", "https://app.example.com/r/abc123"
        )))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => [
      'reset_url' => 'https://app.example.com/r/abc123',
    ],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "reset_url", JsonSerializer.SerializeToElement("https://app.example.com/r/abc123") },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"reset_url": "https://app.example.com/r/abc123"}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123.
```

For a single-recipient send, that `requestId` is also the message's ID. Use it to [get the message](/docs/api-reference/messages/get-message), [read its delivery history](/docs/api-reference/messages/get-message-history), or [cancel it](/docs/api-reference/messages/cancel-message). Sends to a list or audience derive a separate ID per recipient, which you look up through the [Messages API](/docs/api-reference/messages/list-messages).

Several Intercom event constraints disappear with the switch. Check each against your setup:

* Intercom caps a workspace at **120 active event names**, and each event can drive at most **50 live proactive support messages**. Courier templates are addressed by ID, so there is no shared namespace to run out of.
* Intercom events are **flat**. Its API docs state that nested JSON isn't supported. Courier `data` and [user profiles
  DOC](/docs/recipients/overview) both take arbitrary nested JSON, so an order with line items goes through as-is.
* Intercom **de-duplicates** events on workspace, contact, event name, and `created_at` at second granularity, and drops duplicates with a `202`. Two legitimate identical sends in the same second collapse into one. Courier treats every send request as its own message.
* New Intercom event metadata can take **up to 24 hours** to become available in the message composer and filters. Courier templates reference variables directly, so a new field is usable on the next send.
* An Intercom outbound message can carry **only one event-based rule**, and event-triggered messages aren't eligible for re-notification.

### Transactional sending

Intercom supports transactional messaging on email, in-product messages, and push, and transactional email can reach unsubscribed contacts. Two things usually drive the migration:

**It is an add-on, not a mode.** Transactional and event-triggered messaging require the Proactive Support Plus add-on. Courier has no transactional subsystem to enable. Every send goes through the same pipeline, and you control preference enforcement per topic by marking a [preference topic
DOC](/docs/recipients/preferences/overview) as required.

**Sending is on shared infrastructure.** Intercom's docs state that [dedicated IP addresses aren't available](https://www.intercom.com/help/en/articles/9744849-connect-your-email-support-channel) and that all email goes over shared IPs. There is no option to send through your own email provider. Intercom also documents activity-based sending restrictions. When triggered, these limit email to contacts seen, heard from, or engaged within the last 180 days. Event-driven email usually delivers in seconds, but can be delayed up to 30 minutes under load.

Courier sends through [your own provider accounts
DOC](/docs/integrations/overview). Your SendGrid, SES, Postmark, Twilio, or FCM credentials, your domains, your reputation, your dedicated IP if you have one. Courier adds orchestration on top: [channel routing
DOC](/docs/send/routing#channel-priority), [provider failover
DOC](/docs/send/routing#failover), and [error handling
DOC](/docs/send/statuses). If a provider degrades, you swap it in Courier without redeploying.

### Contacts, custom attributes, and user profiles

Intercom contacts carry standard fields plus custom attributes defined through [data attributes](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/data-attributes). Courier [user profiles
DOC](/docs/recipients/overview) are JSON documents keyed by `user_id`.

The translation is direct: the contact's `external_id` becomes the Courier `user_id`, channel addresses (`email`, `phone_number`, push tokens) become profile addresses, and custom attributes become profile attributes. Because profiles accept nested JSON, attribute structures you had to flatten for Intercom can keep their shape.

Load contacts with the [bulk API](/docs/api-reference/bulk/create-a-bulk-job), or create them inline: sending to an unknown `user_id` with profile data creates the user. Intercom segments become [audiences
DOC](/docs/recipients/lists-and-audiences/audiences), which recalculate automatically as profile attributes change.

Push tokens are the one item to plan around. Intercom collects device tokens through its mobile SDK, so they live inside Intercom rather than in your data. Register tokens with Courier's [device token API](/docs/api-reference/device-tokens/add-multiple-tokens-to-user) from your app, and run both in parallel until coverage is high enough to cut over.

### Keeping Intercom for support

This migration doesn't touch the help desk. Messenger, the Intercom Inbox, tickets, [Workflows](https://www.intercom.com/help/en/articles/7836459-workflows-explained), Help Center, and Fin all stay where they are. One sync keeps the two in step:

1. **Your application is the source of truth** for who the user is and what they did.
2. **Into Courier**: upsert [profiles](/docs/api-reference/user-profiles/update-a-profile) with identifiers, channel addresses, and the attributes you segment or personalize on.
3. **Into Intercom**: keep sending the contact updates and events your support team reads for context in the Intercom Inbox.

Events you fired only to trigger outbound messages can stop. Events your agents read in the contact timeline keep going.

### Subscription Types and preferences

Intercom [Subscription Types](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/subscription-types) support opt-in and opt-out consent, and their `content_types` field accepts `email` or `sms_message`, so consent covers only those two channels.

Courier [preference topics
DOC](/docs/recipients/preferences/overview) cover every channel, including push and in-app, and Courier enforces them at send time. Each topic can be opt-in or opt-out, required, or channel-specific, so a user can keep receipts on email while turning off push for the same topic.

Map each Subscription Type to a preference topic and import the opt-out state before your first send. Intercom's `GET /contacts/{id}/subscriptions` returns only the subscriptions a contact explicitly set. Contacts sitting on a default are absent from the response, so decide each topic's default in Courier deliberately rather than inferring it.

Courier gives you a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page), or [embeddable components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) to build the preference center into your product.

### Frequency capping

Intercom controls volume per message: you set how often a message can send and cap total occurrences per contact. Courier has two mechanisms that work across messages.

[Send limits
DOC](/docs/send/statuses#send-limits) cap volume globally, per user, per subscription topic, or per tenant. The window is an hour, day, week, month, or billing period. A blocked message shows `THROTTLED` in the logs. [Throttle nodes
DOC](/docs/journeys/nodes/throttle) cap how many times a user or the whole population passes a point in a journey.

### In-product messages

The Intercom Messenger renders Intercom's in-product surfaces: Posts, Banners, Carousels, Tooltips, Checklists, and News items. Coverage varies by surface. Banners, for example, run on desktop and mobile web but not inside iOS and Android apps.

The closest Courier equivalent is [Courier Inbox
DOC](/docs/in-app/overview), a notification feed with read and unread state, [tabs
DOC](/docs/in-app/customize-the-inbox), and [toasts
DOC](/docs/in-app/add-toasts). It ships as components for [React
DOC](/docs/sdk-libraries/courier-react-web), [JavaScript
DOC](/docs/sdk-libraries/courier-js-web), and mobile. A feed isn't a Messenger replacement, so the mapping isn't one to one:

* **Posts and News items** map cleanly to Courier Inbox messages.
* **Banners** are on the Courier roadmap as a first-class in-app surface. Until they ship, either keep banners in Intercom or render one in your own UI over Courier Inbox data. If banners are load-bearing for you, scope them separately rather than blocking the cutover on them.
* **Tooltips, Checklists, Product Tours, and Carousels** are in-product guidance and onboarding UI. Those stay in Intercom or move to a product-adoption tool. Courier doesn't replace them.

Billing works differently here too. Intercom meters Posts, Mobile Push, Product Tours, Carousels, and Surveys under a single "Messages Sent" metric. The allowance comes with the Proactive Support Plus add-on, so in-product messages and push draw down the same pool.

### Personalization and localization

Intercom personalizes with attribute insertion and fallbacks in the composer. Event-triggered messages can also use event metadata, limited to the first metadata keys on the event. The attribute has to exist on the contact, or the value has to arrive as flat event metadata.

Courier templates use [variables
DOC](/docs/design/templates/variables) in single curly brackets. They resolve from four sources rather than one:

| Source | Use it for |
| - | - |
| `data` | Values you pass on the send call, like `{order.total}` |
| `profile` | Attributes stored on the user, like `{profile.firstName}` |
| `tenant` | Attributes stored on the account or workspace the user belongs to, like `{tenant.name}` |
| `brand` | Themed values, like `{brand.colors.primary}` |

Anything not prefixed resolves against `data`, so `{orderId}` and `{data.orderId}` are the same. Nested paths work, so `{order.shipping.carrier}` renders without flattening the payload first.

The `tenant` source has no Intercom equivalent. If you send on behalf of customer accounts, per-account values live on the [tenant
DOC](/docs/tenants/overview). Company name, support address, and logo stop being copied onto every user profile or passed on every send.

For localization, Intercom's documented pattern is one message per language, targeted with an audience rule on the contact's language. Courier keeps locales on a single template: set `locale` on the profile or the send request, and Courier renders the matching version. Add translations with AI Translation in [Design Studio
DOC](/docs/design/templates/design-studio), or write your own with [Replace Notification Locale](/docs/api-reference/templates/replace-notification-locale). [Template translations
DOC](/docs/design/elemental/locales) covers the full workflow.

### Authentication

Intercom authenticates with a workspace access token. Its rate limit is 10,000 API calls per minute per app and 25,000 per workspace, enforced in ten-second buckets. Courier uses [API key authentication
DOC](/docs/reference/api-overview#authentication): a bearer token per workspace, with separate keys for test and production. Client-side surfaces like Courier Inbox use short-lived [JWTs
DOC](/docs/in-app/authenticate-users) scoped to a single user.

## Plan the migration

Do transactional first. Those sends are already API-driven and carry the most risk if they break. They are also the ones Intercom's shared sending and 30-minute delay ceiling serve least well. Marketing sends are less urgent and take longer to rebuild.

### Phase 1: Inventory

1. **List every live outbound message and Series.** Note the trigger, channels, and audience for each. No endpoint returns Series definitions, so take these from the Outbound list filtered to live messages. For per-message volume, [`POST /export/content/data`](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/data-export) exports delivery and engagement data for outbound content, Series included, over a date range. One active job per workspace.
2. **Split the list into transactional, marketing, and in-product.** Transactional is anything a user action must produce: password resets, receipts, confirmations, alerts. In-product is banners, tours, tooltips, and checklists. Those stay in Intercom or move elsewhere.
3. **List the events you fire.** Mark which ones exist only to trigger a message and which ones your support team reads in the Intercom Inbox. The first group retires. The second stays.

### Phase 2: Transactional

4. **Connect your providers.** Add your email, SMS, and push provider credentials in Courier and verify your sending domains. You're moving off shared IPs, so check domain authentication before the first production send.
5. **Set up the profile sync.** Upsert `user_id`, channel addresses, and the attributes your templates need. Start registering push tokens with Courier from your app now, in parallel with the Intercom SDK, so tokens accumulate ahead of the push cutover.
6. **Rebuild the highest-volume transactional templates** in [Design Studio
   DOC](/docs/design/templates/design-studio), with content for each channel the message sends on.
7. **Replace event posts with send calls.** Each `POST /events` that existed only to trigger a message becomes a [Send a message](/docs/api-reference/send/send-a-message) naming the template and passing `data`. Usually a small diff, and it removes an indirection: the call now returns an ID you can trace to delivery status.
8. **Run in parallel and compare.** Send to a test audience through both systems, diff the rendered output, then cut over one message type at a time. Watch the [logs](/docs/api-reference/messages/list-messages) rather than the calendar.

### Phase 3: Preferences

9. **Map Subscription Types to preference topics**, decide the default for each, and import opt-outs before any marketing send. Do this before Phase 4, not during it.

### Phase 4: Marketing

10. **Rebuild Series as journeys**, starting with onboarding. Recreate the trigger, then the nodes. Where a Series precomputed a roll-up in your backend, replace that with a [batch
    DOC](/docs/journeys/nodes/batch) or [digest
    DOC](/docs/journeys/nodes/digest) node.
11. **Convert segments to audiences.** Segment rules become audience filters on profile attributes, and membership updates itself as profiles change.
12. **Move one-off sends to [broadcasts
    DOC](/docs/broadcasts/overview)**: pick a template, pick an audience, send now or schedule it.
13. **Add frequency caps.** Per-message rules in Intercom become [send limits
    DOC](/docs/send/statuses#send-limits) that hold across every journey and broadcast.

### Phase 5: Decommission

14. **Pause the Intercom message, don't delete it,** once its Courier replacement has run clean for a full cycle.
15. **Drop the Proactive Support Plus add-on** when no live message needs it, and stop firing the events that existed only to trigger sends.

## Migrate with an AI agent

Most of this migration is mechanical: read a message definition, create the equivalent template, rewrite the call site. That suits a coding agent well.

Three things to set up first:

* **[Courier Skills
  DOC](/docs/resources/skills)** teaches the agent Courier's real APIs and patterns, so it stops guessing at endpoints:

  ```bash theme={null}
  npx skills add trycourier/courier-skills
  ```

  In Claude Code you can install it as a plugin instead, which self-updates and ships the Courier docs MCP server.

* **[Courier's MCP server
  DOC](/docs/resources/mcp)** gives the agent direct access to your workspace. It can create templates, build journeys, upsert users, and read send logs as it works. See [Build with AI
  DOC](/docs/get-started/build-with-ai) for setup in Claude Code, Cursor, Codex, and VS Code.

* **Docs for agents.** Point it at [llms-full.txt](https://www.courier.com/docs/llms-full.txt) when it needs API detail beyond this page.

Then start it with a prompt like this one. Fill in the bracketed parts.

```text theme={null}
Help me migrate our notification sending from Intercom to Courier.

Read first:
- https://www.courier.com/docs/guides/migrate/from-intercom
  (concept mapping, constraints, and the phased plan you should follow)
- https://www.courier.com/docs/llms-full.txt
  (full Courier docs, for API detail as you need it)

Our setup:
- Codebase: [path]
- Intercom access token: [env var]
- Courier: connected through the Courier MCP server

Work in this order. Stop after step 3 and wait for my review
before you create anything in Courier.

0. Setup. Install Courier Skills so you build against Courier's real
   APIs and patterns rather than guessing:
   npx skills add trycourier/courier-skills
   Then confirm the Courier MCP server is connected. If either one is
   missing, stop and tell me before going further.

1. Inventory. Intercom has no endpoint that lists Series or outbound
   messages, so I will paste in the list from the Outbound screen.
   For each item, record: name, trigger (manual, rule, or event),
   channels, audience, and the event name if it is event-triggered.
   If you need per-message volume, use POST /export/content/data.

2. Classify each item as:
   - transactional (a user action must produce it)
   - marketing (campaign or lifecycle)
   - in-product guidance (banner, tooltip, tour, checklist, carousel)
   The third group does not move to Courier. Flag it and leave it.

3. Find the send sites. Grep the codebase for Intercom POST /events
   and POST /messages calls. For each event call, decide whether it
   exists to trigger a message or only to give support agents context
   in the Intercom Inbox. Only the first group becomes a Courier send.

   Report the inventory, the classification, and the send-site list.
   Then wait.

4. Transactional first. For each transactional item: create the
   Courier template with the channels it needs, then rewrite its call
   site from an Intercom event post to a Courier /send that names the
   template and passes data. Leave the Intercom call in place behind a
   flag so we can run both and compare output.

5. Journeys. Recreate each Series through the Courier journeys API.
   Waits become delay nodes, rules branches become branch nodes,
   messages become send nodes, exit rules become cancel nodes. Where
   the Series depended on our backend precomputing a roll-up, use a
   batch or digest node instead.

Rules:
- Never send to a real user. Use a test profile for every verification send.
- Never pause, unpublish, or delete anything in Intercom. That is my call.
- If an Intercom message relies on something Courier does not have, say so
  in your report rather than approximating it.
```

Review the classification in step 2 closely. Whether a message counts as transactional decides whether its preference topic is marked required. Getting it backwards means a receipt users can unsubscribe from, or a marketing email they can't.

## FAQ

> **Do I have to stop using Intercom?**
>
> Most teams keep both. Intercom keeps the help desk: Messenger, the Intercom Inbox, tickets, Help Center, Workflows, and Fin. Courier takes over the notifications your product sends. Keep sending Intercom the contact updates and events your agents read for context, and retire only the events that existed to trigger outbound messages.

> **What replaces Series in Courier?**
>
> [Journeys
> DOC](/docs/journeys/overview). Entry rules become [triggers
> DOC](/docs/journeys/invoke): API invoke, inbound webhook, Segment event, or audience membership. Series nodes map across too. Waits become [delay
> DOC](/docs/journeys/nodes/delay), rules branches become [branch
> DOC](/docs/journeys/nodes/branch), and messages become [send nodes
> DOC](/docs/journeys/nodes/send). Journeys add [batch
> DOC](/docs/journeys/nodes/batch), [digest
> DOC](/docs/journeys/nodes/digest), [throttle
> DOC](/docs/journeys/nodes/throttle), and [fetch data
> DOC](/docs/journeys/nodes/fetch-data) nodes, and they can be [built through the API
> DOC](/docs/journeys/build).

> **How do I send a push notification from my backend?**
>
> Call the [send API
> DOC](/docs/send/overview) with the template and recipient. Intercom has no push send endpoint. Triggering push from code meant posting an event and matching it against a message configured in the UI. In Courier the send is explicit and returns an ID you can trace through to [delivery history](/docs/api-reference/messages/get-message-history).

> **What happens to my Intercom push tokens?**
>
> Tokens collected by Intercom's mobile SDK live in Intercom. Start registering tokens with Courier's [device token API](/docs/api-reference/device-tokens/add-multiple-tokens-to-user) from your app while Intercom is still live. Let coverage build across a release cycle or two, then cut push over. Plan this early, since it moves at the speed of app adoption rather than your backend deploys.

> **Can I keep my email deliverability during the move?**
>
> You improve your control over it. Intercom sends over shared IPs and doesn't support bringing your own email provider. Courier sends through [your own provider accounts
> DOC](/docs/integrations/overview), so your domains, reputation, and dedicated IP if you have one carry over. Authenticate your sending domain with your provider before the first production send.

> **What parts of Intercom does Courier not replace?**
>
> The help desk (Messenger, the Intercom Inbox, tickets, Workflows), the Help Center and Articles, and Fin with the AI agent surfaces. Also in-product guidance UI such as Tooltips, Product Tours, Checklists, and Carousels. In-app banners are on the Courier roadmap. Courier replaces message delivery and orchestration: transactional sends, campaigns, journeys, templates, preferences, and the in-app notification feed.


# Migrate from Knock
Source: https://www.courier.com/docs/guides/migrate/from-knock

Map Knock workflows, channels, and recipients to Courier, with an API mapping and a plan.

Plan and run a migration from Knock to Courier.

## Map Knock concepts to Courier

| Knock | Courier |
| - | - |
| [Channels](https://docs.knock.app/concepts/channels) | [Integrations&#xA;DOC](/docs/integrations/overview) |
| [Workflows](https://docs.knock.app/concepts/workflows) | [Templates&#xA;DOC](/docs/design/templates/overview) + [Journeys&#xA;DOC](/docs/journeys/overview) |
| [Recipients / Users](https://docs.knock.app/concepts/users) | [Users / Profiles&#xA;DOC](/docs/recipients/overview) |
| [Objects](https://docs.knock.app/concepts/objects) | [Entity-scoped lists&#xA;GUIDE](/docs/guides/notify-everyone-watching) + `data` on send |
| [Subscriptions](https://docs.knock.app/concepts/subscriptions) | [List subscriptions&#xA;DOC](/docs/recipients/lists-and-audiences/lists) |
| [Preferences](https://docs.knock.app/preferences/overview) | [Preferences&#xA;DOC](/docs/recipients/preferences/overview) |
| [Tenants](https://docs.knock.app/concepts/tenants) | [Tenants&#xA;DOC](/docs/tenants/overview) |
| [Feeds](https://docs.knock.app/integrations/in-app/knock) (in-app) | [Inbox&#xA;DOC](/docs/in-app/overview) |
| [Commits](https://docs.knock.app/concepts/commits) | Publish (draft/live) |

### Integrations

Knock [Channels](https://docs.knock.app/concepts/channels) map to Courier [Integrations
DOC](/docs/integrations/overview), where you configure providers like SendGrid, Twilio, and FCM. Add several providers to one channel type and Courier [fails over
DOC](/docs/send/routing) between them. If your primary email provider is down, the backup takes over with no code changes.

Courier supports providers across email, SMS, push, chat, and webhooks. Provider config lives in the dashboard, so adding or swapping one never needs a deploy.

### Templates and Journeys

Knock bundles content and delivery logic into one [Workflow](https://docs.knock.app/concepts/workflows). Courier splits them into two resources. This is the biggest difference between the platforms.

[Templates
DOC](/docs/design/templates/overview) own the content. Design them visually in Design Studio, with drag-and-drop blocks for email, SMS, push, and chat. Or define them in code with [Elemental
DOC](/docs/design/elemental/overview) JSON. Either way, your product team ships copy changes without an engineering cycle.

[Journeys
DOC](/docs/journeys/overview) own the orchestration: [delays
DOC](/docs/journeys/nodes/delay), [branching
DOC](/docs/journeys/nodes/branch), [batching
DOC](/docs/journeys/nodes/batch), [digests
DOC](/docs/journeys/nodes/digest), and [cancellation
DOC](/docs/journeys/nodes/cancel). A journey's [send node
DOC](/docs/journeys/nodes/send) references a template by ID, so the two evolve independently.

A journey starts from a [trigger
DOC](/docs/journeys/invoke): an API invoke, an inbound webhook, a Segment event, or a user joining an audience. Those are the same entry points as Knock workflow triggers.

### Users and profiles

Courier [profiles
DOC](/docs/recipients/overview) store a recipient's email, phone, push tokens, and any custom properties you personalize with. Profiles accept nested JSON, so structured data like feature flags, team roles, or subscription tiers fits.

Create profiles ahead of time through the API, or identify users inline at send time. If you pass a `user_id` that doesn't exist yet, Courier creates the profile.

### Objects and subscriptions

Knock [Objects](https://docs.knock.app/concepts/objects) are non-user entities people subscribe to, like a document or a project. That splits into two things in Courier, and they move separately.

**The subscriber set becomes a list.** A `list_id` is a dotted namespace, so `document.doc_a1b2.watchers` names the watchers of one document. Subscribing a user creates the list, so there is no object to register first, and `list_pattern` reaches every entity of a kind in one send. [Notify everyone watching
GUIDE](/docs/guides/notify-everyone-watching) walks the whole pattern.

**The entity's own attributes become `data`.** Whatever the template renders about the document, such as its title or URL, goes in `data` on the send.

### Preferences

Knock's [PreferenceSet](https://docs.knock.app/preferences/overview) maps to Courier [Preferences
DOC](/docs/recipients/preferences/overview). Users opt out by channel, category, or notification topic, and Courier enforces that at send time. Your code needs no conditional logic.

Courier also ships a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page) you can deploy in minutes. Embeddable [React components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) put a preference center inside your app.

### Tenants

[Tenants
DOC](/docs/tenants/overview) in Courier work like [Tenants](https://docs.knock.app/concepts/tenants) in Knock. Scope branding, preference defaults, and notification feeds to a customer organization, workspace, or account. Pass a `tenant_id` at send time and Courier applies that tenant's branding and preference defaults.

One difference: Courier stores branding attributes on the Tenant resource, not as a separate Brands object.

### In-app notifications

Knock's [Feeds](https://docs.knock.app/integrations/in-app/knock) map to Courier [Inbox
DOC](/docs/in-app/overview), a real-time notification center with drop-in components for [React
DOC](/docs/sdk-libraries/courier-react-web), [iOS
DOC](/docs/sdk-libraries/ios), [Android
DOC](/docs/sdk-libraries/android), and [vanilla JS
DOC](/docs/sdk-libraries/courier-js-web). Inbox runs on the same pipeline as your other channels, so there's no extra provider to configure.

You get read/unread state, archiving, per-user history, and [toast notifications
DOC](/docs/in-app/add-toasts).

### Versioning

Knock uses a git-style [commit model](https://docs.knock.app/concepts/commits) to version dashboard changes. Courier uses draft and published states. Edit templates and journeys in draft, preview them, and publish when ready. Published versions are immutable, so you always have a snapshot of what's live.

## Why Courier

* **Content and logic stay separate.** Templates and journeys are independent. Your product team updates copy in Design Studio while engineers tune journey timing.
* **Design Studio.** Build email, SMS, push, and chat content with drag-and-drop blocks. Preview across channels, personalize with variables, and publish without deploying code.
* **Built-in in-app channel.** Courier Inbox needs no third-party provider. Drop in a React, iOS, or Android component and deliver on the same pipeline as email and push.
* **Automatic failover.** Configure multiple providers per channel. If SendGrid goes down, your email goes out through the backup.
* **Hosted preferences.** Ship a user-facing preference center with one config, or embed React components in your app. No custom UI required.
* **The providers you already use.** Email, SMS, push, chat, webhooks, CDPs, and observability tools. Switch providers without changing your send code.
* **Delivery observability.** [Message Logs
  DOC](/docs/monitor/overview) track every message from API request to provider delivery, with a timeline, error details, and the rendered content.

## Migrate step by step

**1. Create your Courier workspace**

[Sign up](https://app.courier.com/signup) and create a workspace. Courier gives you separate Test and Production [environments
DOC](/docs/workspaces/environments) with their own API keys, so you can migrate without touching live traffic.

**2. Configure integrations**

Go to **Integrations** in your Courier dashboard and connect the same providers you use in Knock (SendGrid, Twilio, FCM, etc.). Each provider maps to a channel type (email, SMS, push, chat). Configure multiple providers per channel for [failover
DOC](/docs/send/routing).

If you use Knock's in-app feed, [Courier Inbox
DOC](/docs/in-app/overview) is already set up in production and test. No external provider needed.

**3. Recreate templates**

Knock workflows combine content and logic. In Courier, recreate the content as [templates
DOC](/docs/design/templates/overview) in Design Studio:

1. Create a new template for each notification type
2. Add content blocks for each channel (email, SMS, push, etc.)
3. Use [`\{\{variable\}\}`
   DOC](/docs/design/templates/variables) syntax for dynamic data. Courier supports the same Handlebars-style variables
4. Publish the template to make it available for sending

If your Knock workflows include orchestration logic (delays, conditions, batching), recreate that in [Journeys
DOC](/docs/journeys/overview).

**4. Migrate user data**

Create user profiles in Courier with the same identifiers you use in Knock. Use the [Profiles API](/docs/api-reference/user-profiles/create-a-profile), or identify users inline at send time.

```json theme={null}
{
  "user_id": "user_123",
  "profile": {
    "email": "sarah@acme-corp.com",
    "phone_number": "+15551234567",
    "custom": {
      "name": "Sarah Bennett",
      "plan": "enterprise"
    }
  }
}
```

**5. Set up preferences**

If you use Knock's PreferenceSet, recreate that structure in Courier:

1. Define [subscription topics
   DOC](/docs/recipients/preferences/overview) that map to your Knock categories
2. Configure default channel routing per topic
3. Migrate user preference selections via the [Preferences API](/docs/api-reference/user-preferences/get-users-preferences)

Courier also provides a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page) you can deploy immediately, or [React components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) to embed preferences in your app.

**6. Update your send calls**

Replace Knock's workflow trigger calls with Courier's [Send API
DOC](/docs/send/overview). A basic send looks like this:

```javascript Node.js theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: {
      name: 'Sarah Bennett',
      action_url: 'https://app.example.com',
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "name": "Sarah Bennett",
            "action_url": "https://app.example.com",
        },
    },
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "name": "Sarah Bennett",
        "action_url": "https://app.example.com"
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett", action_url: "https://app.example.com" }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
			"action_url": "https://app.example.com",
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett",
            "action_url", "https://app.example.com")))
        .build())
    .build();
client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['name' => 'Sarah Bennett', 'action_url' => 'https://app.example.com'],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
            { "action_url", JsonSerializer.SerializeToElement("https://app.example.com") },
        },
    },
};

await client.Send.Message(parameters);
```

```bash CLI theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"name":"Sarah Bennett","action_url":"https://app.example.com"}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with their name.
```

Courier applies routing, preferences, and failover from your template and workspace configuration.

**7. Test and cut over**

1. Send test messages in your Test environment and verify delivery in [Message Logs](https://app.courier.com/logs)
2. Validate that preferences, routing, and template rendering match your Knock setup
3. Switch your production code to use Courier's Production API key
4. Monitor [Message Logs
   DOC](/docs/monitor/overview) and [Analytics
   DOC](/docs/monitor/overview) for delivery confirmation

## Map the API

| Operation | Knock | Courier |
| - | - | - |
| Send a notification | `POST /workflows/:key/trigger` | [Send a message](/docs/api-reference/send/send-a-message) |
| Create/update a user | `PUT /users/:id` | [Replace a Profile](/docs/api-reference/user-profiles/replace-a-profile) |
| Get a user | `GET /users/:id` | [Get a Profile](/docs/api-reference/user-profiles/get-a-profile) |
| Set user preferences | `PUT /users/:id/preferences/:set_id` | [Update or create user Preferences for a Subscription Topic](/docs/api-reference/user-preferences/update-or-create-user-preferences-for-a-subscription-topic) |
| Get message status | `GET /messages/:id` | [Get message](/docs/api-reference/messages/get-message) |
| List messages | `GET /messages` | [List messages](/docs/api-reference/messages/list-messages) |
| Create/update tenant | `PUT /tenants/:id` | [Create or replace a Tenant](/docs/api-reference/tenants/create-or-replace-a-tenant) |


# Migrate from Novu
Source: https://www.courier.com/docs/guides/migrate/from-novu

Map Novu workflows, steps, and subscribers to Courier, with an API mapping and a plan.

This guide maps Novu concepts to Courier and gives you a step-by-step migration plan.

## Map Novu concepts to Courier

| Novu | Courier |
| - | - |
| [Workflows](https://docs.novu.co/platform/concepts/workflows) | [Templates&#xA;DOC](/docs/design/templates/overview) + [Journeys&#xA;DOC](/docs/journeys/overview) |
| [Subscribers](https://docs.novu.co/platform/concepts/subscribers) | [Users / Profiles&#xA;DOC](/docs/recipients/overview) |
| [Topics](https://docs.novu.co/platform/concepts/topics) | [Subscription Topics&#xA;DOC](/docs/recipients/preferences/overview) |
| [Integrations](https://docs.novu.co/integrations/overview) | [Integrations&#xA;DOC](/docs/integrations/overview) |
| [Digest](https://docs.novu.co/platform/workflow/add-and-configure-steps/configure-action-steps/digest) | [Batch&#xA;DOC](/docs/journeys/nodes/batch) + [Digest&#xA;DOC](/docs/journeys/nodes/digest) nodes |
| [Delay](https://docs.novu.co/platform/workflow/add-and-configure-steps/configure-action-steps/delay) | [Delay node&#xA;DOC](/docs/journeys/nodes/delay) |
| [Preferences](https://docs.novu.co/platform/concepts/preferences) | [Preferences&#xA;DOC](/docs/recipients/preferences/overview) |
| [Inbox](https://docs.novu.co/inbox/overview) | [Inbox&#xA;DOC](/docs/in-app/overview) |
| [Tenants](https://docs.novu.co/platform/concepts/tenants) | [Tenants&#xA;DOC](/docs/tenants/overview) |

### Workflows, templates, and Journeys

Novu [workflows](https://docs.novu.co/platform/concepts/workflows) combine content, channel routing, and orchestration logic (digest, delay, conditions) in one resource. Courier splits these into two independent pieces. That is the biggest architectural difference between the platforms.

[Templates
DOC](/docs/design/templates/overview) own the content layer. Design them visually in Design Studio (drag-and-drop blocks for email, SMS, push, and chat) or in code with [Elemental
DOC](/docs/design/elemental/overview) JSON. Either way, your product team ships copy changes without an engineering cycle.

[Journeys
DOC](/docs/journeys/overview) own the orchestration layer: [delays
DOC](/docs/journeys/nodes/delay), [branching
DOC](/docs/journeys/nodes/branch), [batching
DOC](/docs/journeys/nodes/batch), [digests
DOC](/docs/journeys/nodes/digest), and [cancellation
DOC](/docs/journeys/nodes/cancel). A journey's [send node
DOC](/docs/journeys/nodes/send) references a template by ID, so the two evolve independently.

| Novu step type | Courier equivalent |
| - | - |
| Channel step (email, SMS, push, chat) | [Send node&#xA;DOC](/docs/journeys/nodes/send) (references a template) |
| Digest step | [Batch node&#xA;DOC](/docs/journeys/nodes/batch) (window-based) or [Digest node&#xA;DOC](/docs/journeys/nodes/digest) (schedule-based) |
| Delay step | [Delay node&#xA;DOC](/docs/journeys/nodes/delay) |
| Custom step | [Fetch data node&#xA;DOC](/docs/journeys/nodes/fetch-data) or [branch&#xA;DOC](/docs/journeys/nodes/branch) logic |

A journey starts from a [trigger
DOC](/docs/journeys/invoke): an API invoke, an inbound webhook, a Segment event, or a user joining an audience. Build journeys visually [in the UI
DOC](/docs/journeys/build) or through the [Journeys API
DOC](/docs/journeys/build).

### Subscribers and users

Novu [subscribers](https://docs.novu.co/platform/concepts/subscribers) map to Courier [profiles
DOC](/docs/recipients/overview). Both store email, phone, push tokens, locale, and custom properties.

Courier profiles accept nested JSON, so account tiers, team roles, and feature flags fit as-is. Create profiles ahead of time through the API, or identify users inline at send time. Pass a `user_id` that doesn't exist yet and Courier creates the profile.

### Topics and subscription topics

Novu [topics](https://docs.novu.co/platform/concepts/topics) group subscribers for bulk delivery. The Courier equivalent depends on your use case:

* **For notification categories** (letting users opt in/out of types of notifications): use [Subscription Topics
  DOC](/docs/recipients/preferences/overview) within Preferences
* **For bulk delivery to groups**: use [Lists](/docs/api-reference/lists/list-lists) or [Audiences
  DOC](/docs/recipients/lists-and-audiences/audiences)

### Integrations

Novu and Courier both call provider connections "integrations." Courier supports providers across email, SMS, push, chat, and webhooks. Wire up multiple providers for one channel type and Courier [fails over
DOC](/docs/send/routing) between them automatically, with no code changes.

### Digest and delay

Courier's [Batch node
DOC](/docs/journeys/nodes/batch) covers Novu's [digest step](https://docs.novu.co/platform/workflow/add-and-configure-steps/configure-action-steps/digest) with a time window. It collects matching events, then releases them as one aggregated payload for a single summary notification. Your template receives the full list of collected events. For summaries that release on a fixed schedule the user controls (a daily activity email, a weekly report), use the [Digest node
DOC](/docs/journeys/nodes/digest) instead.

[Delay
DOC](/docs/journeys/nodes/delay) works like Novu's delay step. Specify a duration and the journey pauses before the next node.

### Preferences

Novu's [preference system](https://docs.novu.co/platform/concepts/preferences) supports global and per-workflow channel controls. Courier [Preferences
DOC](/docs/recipients/preferences/overview) support the same hierarchy (global, per-topic, per-channel) and enforce it at send time.

Courier also ships a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page) you can deploy in minutes, plus embeddable [React components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) for in-app preference centers. No custom UI required.

### In-app notifications

Novu's [Inbox](https://docs.novu.co/inbox/overview) component handles in-app notifications. Courier [Inbox
DOC](/docs/in-app/overview) does the same, with drop-in components for [React
DOC](/docs/sdk-libraries/courier-react-web), [iOS
DOC](/docs/sdk-libraries/ios), [Android
DOC](/docs/sdk-libraries/android), and [vanilla JS
DOC](/docs/sdk-libraries/courier-js-web).

Courier Inbox runs on the same delivery pipeline as email, push, and SMS. There's no separate service to manage. You get read/unread state, archiving, per-user history, [toast notifications
DOC](/docs/in-app/add-toasts), and [tab-based organization
DOC](/docs/in-app/customize-the-inbox).

### Tenants

Courier [tenants
DOC](/docs/tenants/overview) work like Novu [tenants](https://docs.novu.co/platform/concepts/tenants). Scope branding, preference defaults, and notification feeds to one customer organization. Pass a `tenant_id` at send time and Courier applies that tenant's branding and preferences.

## Why Courier

* **Fully managed infrastructure.** No self-hosting to maintain, no bridge endpoints to deploy. Courier handles orchestration, delivery, retries, and scaling.
* **Content and logic stay separate.** Templates and journeys are independent resources. Your product team updates copy in Design Studio while engineers tune journey timing.
* **Design Studio.** Build email, SMS, push, and chat content with drag-and-drop blocks. Preview across channels, personalize with variables, and publish without deploying code.
* **Built-in in-app channel.** Courier Inbox works without a third-party provider. Drop in a React, iOS, or Android component and deliver in-app notifications on the same pipeline as email and push.
* **Automatic failover.** Configure multiple providers per channel and Courier fails over automatically. If SendGrid goes down, your email still goes out through your backup provider.
* **Hosted preferences out of the box.** Ship a user-facing preference center with a single config, or embed React components directly in your app. No custom UI required.
* **The providers you already use.** Email, SMS, push, chat, webhooks, CDPs, and observability tools. Switch providers without changing your send code.
* **Full delivery observability.** [Message Logs
  DOC](/docs/monitor/overview) track every message from API request to provider delivery with a detailed timeline, error details, and rendered content inspection.

## Migrate step by step

**1. Create your Courier workspace**

[Sign up](https://app.courier.com/signup) and create a workspace. Courier gives you separate Test and Production [environments
DOC](/docs/workspaces/environments) with their own API keys, so you can migrate without touching live traffic.

**2. Configure integrations**

Go to **Integrations** in your Courier dashboard and connect the same providers you use in Novu (SendGrid, Twilio, FCM, etc.). Each provider maps to a channel type (email, SMS, push, chat). Configure multiple providers per channel for [failover
DOC](/docs/send/routing).

If you use Novu's inbox component, [Courier Inbox
DOC](/docs/in-app/overview) is already set up in production and test. No external provider needed.

**3. Recreate templates**

Novu workflows contain inline content per channel step. In Courier, extract the content into [templates
DOC](/docs/design/templates/overview):

1. Create a new template for each notification type
2. Add content blocks for each channel (email body, SMS text, push title/body, etc.)
3. Use `{{variable}}` syntax for dynamic data. Both platforms use the same Handlebars-style approach
4. Publish the template to make it available for sending

**4. Recreate workflows as journeys**

If your Novu workflows include digest, delay, or conditional logic, recreate them in [Journeys
DOC](/docs/journeys/overview). Build journeys visually [in the UI
DOC](/docs/journeys/build) or programmatically via the [Journeys API
DOC](/docs/journeys/build).

For notification types that need no orchestration (no delays, no digests), skip journeys and send directly via the [Send API
DOC](/docs/send/overview).

**5. Migrate subscriber data**

Create user profiles in Courier with the same identifiers you use in Novu, via the [Profiles API](/docs/api-reference/user-profiles/create-a-profile) or inline at send time.

```json theme={null}
{
  "user_id": "user_123",
  "profile": {
    "email": "sarah@acme-corp.com",
    "phone_number": "+15551234567",
    "custom": {
      "name": "Sarah Bennett",
      "plan": "enterprise"
    }
  }
}
```

**6. Set up preferences**

If you use Novu's subscriber preferences, recreate your structure in Courier:

1. Define [subscription topics
   DOC](/docs/recipients/preferences/overview) that map to your Novu workflow categories
2. Configure default channel routing per topic
3. Migrate subscriber preference selections via the [Preferences API](/docs/api-reference/user-preferences/get-users-preferences)

Courier also provides a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page) you can deploy immediately, or [React components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) to embed preferences in your app.

**7. Update your trigger calls**

Replace Novu's workflow trigger calls with Courier's [Send API
DOC](/docs/send/overview):

```javascript Node.js theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: {
      order_id: 'ORD-456',
      total: 79.99,
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "order_id": "ORD-456",
            "total": 79.99,
        },
    },
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "order_id": "ORD-456",
        "total": 79.99
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { order_id: "ORD-456", total: 79.99 }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"order_id": "ORD-456",
			"total": 79.99,
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "order_id", "ORD-456",
            "total", 79.99)))
        .build())
    .build();
client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['order_id' => 'ORD-456', 'total' => 79.99],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "order_id", JsonSerializer.SerializeToElement("ORD-456") },
            { "total", JsonSerializer.SerializeToElement(79.99) },
        },
    },
};

await client.Send.Message(parameters);
```

```bash CLI theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"order_id":"ORD-456","total":79.99}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with the order details.
```

Courier handles routing, preferences, and failover automatically based on your template and workspace configuration.

**8. Test and cut over**

1. Send test messages in your Test environment and verify delivery in [Message Logs](https://app.courier.com/logs)
2. Validate that preferences, routing, and template rendering match your Novu setup
3. Switch your production code to use Courier's Production API key
4. Monitor [Message Logs
   DOC](/docs/monitor/overview) and [Analytics
   DOC](/docs/monitor/overview) for delivery confirmation

## Map the API

| Operation | Novu | Courier |
| - | - | - |
| Send a notification | `POST /v1/events/trigger` | [Send a message](/docs/api-reference/send/send-a-message) |
| Create/update a subscriber | `PUT /v1/subscribers/:id` | [Replace a Profile](/docs/api-reference/user-profiles/replace-a-profile) |
| Get a subscriber | `GET /v1/subscribers/:id` | [Get a Profile](/docs/api-reference/user-profiles/get-a-profile) |
| Set preferences | `PATCH /v2/subscribers/:id/preferences` | [Update or create user Preferences for a Subscription Topic](/docs/api-reference/user-preferences/update-or-create-user-preferences-for-a-subscription-topic) |
| Get message status | `GET /v1/messages/:id` | [Get message](/docs/api-reference/messages/get-message) |
| List messages | `GET /v1/messages` | [List messages](/docs/api-reference/messages/list-messages) |
| Manage topics | `POST /v1/topics` | [Update a List](/docs/api-reference/lists/update-a-list) |


# Migrate from OneSignal
Source: https://www.courier.com/docs/guides/migrate/from-onesignal

Map OneSignal messages, segments, and players to Courier, with an API mapping and a plan.

This guide maps OneSignal concepts to Courier and gives you a step-by-step migration plan.

## Map OneSignal concepts to Courier

| OneSignal | Courier |
| - | - |
| [Apps](https://documentation.onesignal.com/docs/en/apps-organizations) | [Workspaces&#xA;DOC](/docs/workspaces/overview) |
| [Segments](https://documentation.onesignal.com/docs/en/segmentation) | [Audiences&#xA;DOC](/docs/recipients/lists-and-audiences/audiences) |
| [Templates](https://documentation.onesignal.com/docs/en/templates) | [Templates&#xA;DOC](/docs/design/templates/overview) |
| [Journeys](https://documentation.onesignal.com/docs/journeys-overview) | [Journeys&#xA;DOC](/docs/journeys/overview) |
| [Subscriptions](https://documentation.onesignal.com/docs/en/subscriptions) | Channel tokens on [User Profiles&#xA;DOC](/docs/recipients/overview) |
| [Users / Aliases](https://documentation.onesignal.com/docs/en/aliases) | [Users / Profiles&#xA;DOC](/docs/recipients/overview) |
| [Tags](https://documentation.onesignal.com/docs/en/add-user-data-tags) | Custom properties on profiles + [Preferences&#xA;DOC](/docs/recipients/preferences/overview) |
| [Outcomes](https://documentation.onesignal.com/docs/custom-outcomes) | [Analytics&#xA;DOC](/docs/monitor/overview) + [Message Logs&#xA;DOC](/docs/monitor/overview) |
| In-App Messages | [Inbox&#xA;DOC](/docs/in-app/overview) |

### Apps and workspaces

OneSignal [apps](https://documentation.onesignal.com/docs/en/apps-organizations) map to Courier [workspaces
DOC](/docs/workspaces/overview). Each workspace has its own integrations, templates, and user profiles, plus separate Test and Production [environments
DOC](/docs/workspaces/environments).

### Segments and audiences

OneSignal [segments](https://documentation.onesignal.com/docs/en/segmentation) filter on user attributes, activity, and tags to build dynamic groups. Courier [Audiences
DOC](/docs/recipients/lists-and-audiences/audiences) work the same way. Define filter rules on profile attributes and Courier keeps membership current as profiles change.

For static groups like mailing lists or beta testers, use [Lists](/docs/api-reference/lists/list-lists).

### Templates

OneSignal [templates](https://documentation.onesignal.com/docs/en/templates) are reusable message blueprints for push, email, and SMS. One Courier [template
DOC](/docs/design/templates/overview) holds content for every channel: email, SMS, push, chat, and inbox.

[Design Studio
DOC](/docs/design/templates/design-studio) uses drag-and-drop content blocks. [Elemental
DOC](/docs/design/elemental/overview) JSON is the code-first path. Both support [`\{\{variable\}\}`
DOC](/docs/design/templates/variables) Handlebars personalization, channel-specific overrides, and [localization
DOC](/docs/design/elemental/locales).

OneSignal uses Liquid syntax. Courier uses Handlebars. Both have conditionals, loops, and variable interpolation, with different syntax.

### Journeys

OneSignal [Journeys](https://documentation.onesignal.com/docs/journeys-overview) are automated multi-step message flows. Courier [Journeys
DOC](/docs/journeys/overview) do the same, with [delays
DOC](/docs/journeys/nodes/delay), [branching
DOC](/docs/journeys/nodes/branch), [batching
DOC](/docs/journeys/nodes/batch), [digests
DOC](/docs/journeys/nodes/digest), and [cancellation
DOC](/docs/journeys/nodes/cancel).

| Journey Step | Courier Equivalent |
| - | - |
| Send message | [Send node&#xA;DOC](/docs/journeys/nodes/send) (references a template) |
| Wait | [Delay node&#xA;DOC](/docs/journeys/nodes/delay) |
| Yes/No branch | [Branch node&#xA;DOC](/docs/journeys/nodes/branch) |
| Multi-split branch | [Branch node&#xA;DOC](/docs/journeys/nodes/branch) with multiple paths |

A journey starts from a [trigger
DOC](/docs/journeys/invoke): an API invoke, an inbound webhook, a Segment event, or a user joining an audience. Build journeys visually [in the UI
DOC](/docs/journeys/build) or define them through the [Journeys API
DOC](/docs/journeys/build).

### Users, subscriptions, and profiles

OneSignal separates [users](https://documentation.onesignal.com/docs/en/aliases) (identified by aliases) from [subscriptions](https://documentation.onesignal.com/docs/en/subscriptions) (individual devices, email addresses, phone numbers). One Courier [profile
DOC](/docs/recipients/overview) per user holds all of it: email, phone, push tokens, and custom properties.

Profiles accept nested JSON, so account tiers, team roles, or feature flags fit as they are. Create profiles ahead of time through the API, or identify users inline at send time.

### Tags and preferences

OneSignal [tags](https://documentation.onesignal.com/docs/en/add-user-data-tags) are key-value pairs used for both targeting and preference management. Courier splits these in two:

* **Custom profile properties**: any attribute on a user profile, for targeting and personalization
* **[Preferences
  DOC](/docs/recipients/preferences/overview)**: opt-in and opt-out by channel, category, or topic, enforced at send time

### In-app messages and Inbox

OneSignal's in-app messages are modal overlays triggered by user activity. Courier [Inbox
DOC](/docs/in-app/overview) is a persistent in-app notification center with drop-in components for [React
DOC](/docs/sdk-libraries/courier-react-web), [iOS
DOC](/docs/sdk-libraries/ios), [Android
DOC](/docs/sdk-libraries/android), and [vanilla JS
DOC](/docs/sdk-libraries/courier-js-web).

Inbox runs on the same delivery pipeline as email, push, and SMS, with no separate provider to configure. You get read/unread state, archiving, per-user history, [toast notifications
DOC](/docs/in-app/add-toasts), and [tab-based organization
DOC](/docs/in-app/customize-the-inbox).

### Outcomes and analytics

OneSignal [Outcomes](https://documentation.onesignal.com/docs/custom-outcomes) track conversion events tied to notifications. Courier gives you [Message Logs
DOC](/docs/monitor/overview) (per-message timeline from API request to provider delivery) and [Analytics
DOC](/docs/monitor/overview) (aggregate delivery and engagement metrics). To pipe events into your own analytics, configure [Outbound Webhooks
DOC](/docs/monitor/webhooks/outbound).

## Why Courier

* **Multi-channel.** Courier treats email, SMS, push, chat, webhooks, and in-app as equal channels with one orchestration layer. You're not bolting non-push channels onto a push-first platform.
* **Content and logic stay separate.** Templates and journeys are independent resources. Your product team updates copy in Design Studio while engineers tune journey timing. Neither blocks the other.
* **Design Studio.** Build email, SMS, push, and chat content with drag-and-drop blocks. Preview across channels, personalize with variables, and publish without deploying code.
* **Automatic failover.** Configure multiple providers per channel and Courier fails over automatically. If your primary email provider goes down, traffic shifts to the backup without code changes.
* **Built-in in-app channel.** Courier Inbox works without a third-party provider. Drop in a React, iOS, or Android component and deliver in-app notifications on the same pipeline as email and push.
* **Hosted preferences.** Ship a user-facing preference center with a single config, or embed React components in your app. No custom UI required.
* **The providers you already use.** Email, SMS, push, chat, webhooks, CDPs, and observability tools. Switch providers without changing your send code.
* **Full delivery observability.** [Message Logs
  DOC](/docs/monitor/overview) track every message from API request to provider delivery with a detailed timeline, error details, and rendered content inspection.

## Migrate step by step

**1. Create your Courier workspace**

[Sign up](https://app.courier.com/signup) and create a workspace. The Test and Production [environments
DOC](/docs/workspaces/environments) have independent API keys, so you can migrate without touching live traffic.

**2. Configure integrations**

Go to **Integrations** in your Courier dashboard and connect a provider for each channel you use in OneSignal. If you send push via FCM and APNs, configure both. Connect your email and SMS providers (SendGrid, Twilio, etc.). Multiple providers on one channel gives you [failover
DOC](/docs/send/routing).

For in-app notifications, [Courier Inbox
DOC](/docs/in-app/overview) is already set up in production and test. No external provider needed.

**3. Recreate templates**

OneSignal templates are per-channel. In Courier, a single [template
DOC](/docs/design/templates/overview) holds content for all channels:

1. Create a new template for each notification type
2. Add content blocks for each channel (email body, SMS text, push title/body, etc.)
3. Convert Liquid variables to Handlebars (`{{variable}}`). The data comes from the send request's `data` field
4. Publish the template so you can send it

**4. Migrate user data**

Create Courier profiles that consolidate your OneSignal user and subscription data. Use the [Profiles API](/docs/api-reference/user-profiles/create-a-profile), or identify users inline at send time.

```json theme={null}
{
  "user_id": "user_123",
  "profile": {
    "email": "sarah@acme-corp.com",
    "phone_number": "+15551234567",
    "firebaseToken": "fcm_device_token_here",
    "custom": {
      "name": "Sarah Bennett",
      "plan": "enterprise"
    }
  }
}
```

**5. Set up preferences**

If you use OneSignal tags for opt-in and opt-out, rebuild that structure with Courier [Preferences
DOC](/docs/recipients/preferences/overview):

1. Define [subscription topics
   DOC](/docs/recipients/preferences/overview) for each notification category
2. Configure default channel routing per topic
3. Migrate user preference selections via the [Preferences API](/docs/api-reference/user-preferences/get-users-preferences)

Courier ships a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page) you can deploy immediately, or [React components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) to embed preferences in your app.

**6. Update your send calls**

Replace OneSignal's Create Notification API calls with Courier's [Send API
DOC](/docs/send/overview):

```javascript Node.js theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: {
      order_id: 'ORD-456',
      total: 79.99,
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "order_id": "ORD-456",
            "total": 79.99,
        },
    },
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "order_id": "ORD-456",
        "total": 79.99
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { order_id: "ORD-456", total: 79.99 }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"order_id": "ORD-456",
			"total": 79.99,
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "order_id", "ORD-456",
            "total", 79.99)))
        .build())
    .build();
client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['order_id' => 'ORD-456', 'total' => 79.99],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "order_id", JsonSerializer.SerializeToElement("ORD-456") },
            { "total", JsonSerializer.SerializeToElement(79.99) },
        },
    },
};

await client.Send.Message(parameters);
```

```bash CLI theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"order_id":"ORD-456","total":79.99}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with the order details.
```

Courier applies routing, preferences, and failover from your template and workspace configuration. For multi-channel sends, set the `routing` field:

```javascript Node.js highlight={7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push",
        "email",
        "sms",
      ],
    },
  },
});
```

```python Python highlight={7} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": [
                "push",
                "email",
                "sms",
            ],
        },
    },
)
```

```bash cURL highlight={10} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": [
          "push",
          "email",
          "sms"
        ]
      }
    }
  }'
```

```ruby Ruby highlight={7} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push",
        "email",
        "sms"
      ]
    }
  }
)
```

```go Go highlight={9} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
				{OfString: courier.String("email")},
				{OfString: courier.String("sms")},
			},
			Method: "single",
		},
	},
})
```

```java Java highlight={5} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("push")
            .addChannel("email")
            .addChannel("sms")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={7} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => [
        'push',
        'email',
        'sms',
      ],
    ],
  ],
);
```

```csharp C# highlight={7} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["push", "email", "sms"], Method = Send::Method.Single },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push", "email", "sms"]}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 over email and push.
```

This tries push first, then email, then SMS. The first successful delivery wins.

**7. Recreate journeys**

If you use OneSignal Journeys, recreate them in Courier [Journeys
DOC](/docs/journeys/overview), visually or through the [Journeys API
DOC](/docs/journeys/build).

For notifications that need no orchestration, skip journeys and send directly via the Send API.

**8. Test and cut over**

1. Send test messages in your Test environment and verify delivery in [Message Logs](https://app.courier.com/logs)
2. Check that preferences, routing, and template rendering match your OneSignal setup
3. Switch your production code to Courier's Production API key
4. Monitor [Message Logs
   DOC](/docs/monitor/overview) and [Analytics
   DOC](/docs/monitor/overview) for delivery confirmation

## Migrate with an AI agent

Most of this migration is mechanical: read a template definition, create the equivalent Courier template, rewrite the call site. That suits a coding agent well.

Three things to set up first:

* **[Courier Skills
  DOC](/docs/resources/skills)** teaches the agent Courier's real APIs and patterns so it stops guessing at endpoints:

  ```bash theme={null}
  npx skills add trycourier/courier-skills
  ```

  In Claude Code you can install it as a plugin instead, which self-updates and ships the Courier docs MCP server.

* **[Courier's MCP server
  DOC](/docs/resources/mcp)** gives the agent direct access to your workspace, so it can create templates, build journeys, upsert users, and read send logs. See [Build with AI
  DOC](/docs/get-started/build-with-ai) for setup in Claude Code, Cursor, Codex, and VS Code.

* **Docs for agents.** Point it at [llms-full.txt](https://www.courier.com/docs/llms-full.txt) when it needs API detail beyond this page.

Then start it with a prompt like this one. Fill in the bracketed parts.

```text theme={null}
Help me migrate our notifications from OneSignal to Courier.

Read first:
- https://www.courier.com/docs/guides/migrate/from-onesignal
  (concept mapping and the migration steps you should follow)
- https://www.courier.com/docs/llms-full.txt
  (full Courier docs, for API detail as you need it)

Our setup:
- Codebase: [path]
- OneSignal API credentials: [env var]
- Courier: connected through the Courier MCP server

Work in this order. Stop after step 3 and wait for my review
before you create anything in Courier.

0. Setup. Install Courier Skills so you build against Courier's real
   APIs and patterns rather than guessing:
   npx skills add trycourier/courier-skills
   Then confirm the Courier MCP server is connected. If either one is
   missing, stop and tell me before going further.

1. Inventory. Use the OneSignal API to list every template, journey,
   and segment in each app. For each template record its channels; for
   each journey record its trigger, steps, and target segment.

2. Classify each as:
   - transactional (an action in our product must produce it)
   - marketing (campaign or lifecycle)
   - in-app messages (these are a separate surface, see the guide)

3. Find the send sites. Grep the codebase for OneSignal
   POST /notifications calls. Note which ones send inline content and
   which reference a template_id, and which target segments or filters
   rather than an external_id.

   Report the inventory, the classification, and the send-site list.
   Then wait.

4. Transactional first. For each one: create the Courier template with
   the channels it needs, then rewrite the call site to a Courier /send
   that names the template and passes data. Recipients addressed by
   external_id become a Courier user_id. Leave the OneSignal call in
   place behind a flag so we can run both and compare.

5. Journeys. Recreate each OneSignal journey through the Courier
   journeys API. Waits become delay nodes, branches become branch
   nodes, message steps become send nodes.

6. Segments and tags. Convert segments to Courier audiences built on
   profile attributes, and map the tags you use for opt-out into
   Courier subscription topics rather than leaving them as attributes.

Rules:
- Never send to a real user. Use a test profile in the Test
  environment for every verification send.
- Never pause, disable, or delete anything in OneSignal. That is my call.
- If something in OneSignal has no Courier equivalent, say so in your
  report rather than approximating it.
```

In step 6, map only the opt-out tags to subscription topics. OneSignal data tags cover both segmentation and opt-out, and anything that gates whether a user may be contacted belongs in Preferences, where Courier enforces it at send time.

## Map the API

| Operation | OneSignal | Courier |
| - | - | - |
| Send a notification | `POST /notifications` | [Send a message](/docs/api-reference/send/send-a-message) |
| Create/update a user | `POST /apps/:id/users` | [Replace a Profile](/docs/api-reference/user-profiles/replace-a-profile) |
| Get a user | `GET /apps/:id/users/by/external_id/:id` | [Get a Profile](/docs/api-reference/user-profiles/get-a-profile) |
| Add a subscription | `POST /apps/:id/users/by/external_id/:id/subscriptions` | Push tokens on [Replace a Profile](/docs/api-reference/user-profiles/replace-a-profile) |
| Manage segments | `POST /apps/:id/segments` | [Update an Audience](/docs/api-reference/audiences/update-an-audience) |
| Get message status | `GET /notifications/:id` | [Get message](/docs/api-reference/messages/get-message) |
| Bulk operations | `POST /notifications` (with `include_aliases`) | [Create a bulk job](/docs/api-reference/bulk/create-a-bulk-job) |
| Create a template | `POST /templates` | [Design Studio&#xA;DOC](/docs/design/templates/design-studio) or [Elemental API&#xA;DOC](/docs/design/elemental/overview) |


# Migrate from Salesforce Marketing Cloud
Source: https://www.courier.com/docs/guides/migrate/from-salesforce-marketing-cloud

Map SFMC journeys, data extensions, and sends to Courier, with a phased plan.

Plan a migration from Salesforce Marketing Cloud Engagement (SFMC) to Courier.

Most teams land on the same split. Salesforce keeps the customer data, Courier does the sending. Engineers, marketers, and AI agents build and send messages in Courier from data synced out of Salesforce.

## Map Salesforce Marketing Cloud concepts to Courier

| Salesforce Marketing Cloud | Courier |
| - | - |
| [Journey Builder](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/journey-builder-api-overview.html) | [Journeys&#xA;DOC](/docs/journeys/overview) |
| Automation Studio (one-time and scheduled sends) | [Broadcasts&#xA;DOC](/docs/broadcasts/overview) |
| Automation Studio (recurring sends) | Your scheduler + [send to a list or audience&#xA;DOC](/docs/send/overview) |
| Automation Studio (SQL queries, imports) | Stays in your data stack. Sync results to Courier |
| Email Studio / Content Builder | [Design Studio&#xA;DOC](/docs/design/templates/design-studio) |
| Data Extensions | [User profiles&#xA;DOC](/docs/recipients/overview) (nested JSON) |
| Contact Builder / All Contacts | [Users&#xA;DOC](/docs/recipients/overview#the-profile-object) |
| Filtered Data Extensions / segments | [Audiences&#xA;DOC](/docs/recipients/lists-and-audiences/audiences) |
| [Triggered Sends / Transactional Messaging API](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/transactional-messaging-api.html) | [Send API&#xA;DOC](/docs/send/overview) |
| [API Event entry sources](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/journey-builder-api-overview.html) | [Journey triggers&#xA;DOC](/docs/journeys/invoke): API, webhook, Segment, audience |
| [AMPscript](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/ampscript.html) / SSJS personalization | [Handlebars variables&#xA;DOC](/docs/design/templates/variables) + `data` on send |
| Subscription Center / publication lists | [Preferences&#xA;DOC](/docs/recipients/preferences/overview) |
| MobileConnect / MobilePush (SMS and push) | SMS and push channels through [your providers&#xA;DOC](/docs/integrations/overview) |
| MobilePush inbox / in-app messages | [Inbox&#xA;DOC](/docs/in-app/overview) |
| Sender Authentication Package (SAP) | Domain configuration with your [email provider&#xA;DOC](/docs/integrations/overview) |
| Installed packages (OAuth 2.0 client credentials) | [API keys&#xA;DOC](/docs/reference/api-overview#authentication) |

### Journey Builder and Journeys

Journey Builder runs multi-step campaigns from entry sources. A contact lands in a Data Extension, fires an API event, or matches an audience. From there it moves through waits, decision splits, and sends.

Courier [Journeys
DOC](/docs/journeys/overview) fill the same role. A journey starts from a [trigger
DOC](/docs/journeys/invoke): API invoke, inbound webhook, Segment event, or audience membership.

| Journey Builder activity | Courier equivalent |
| - | - |
| Email / SMS / push activity | [Send node&#xA;DOC](/docs/journeys/nodes/send) (references a template) |
| Wait activity | [Delay node&#xA;DOC](/docs/journeys/nodes/delay) |
| Decision split | [Branch node&#xA;DOC](/docs/journeys/nodes/branch) |
| Einstein STO / engagement splits | [Experiments&#xA;DOC](/docs/journeys/experiments) on send nodes |
| Journey exit criteria | [Cancel node&#xA;DOC](/docs/journeys/nodes/cancel) + [cancellation API&#xA;DOC](/docs/journeys/invoke) |
| Update contact activity | [Update a Profile](/docs/api-reference/user-profiles/update-a-profile) |
| Custom activity (fetch external data) | [Fetch data node&#xA;DOC](/docs/journeys/nodes/fetch-data) |

Two Courier nodes Journey Builder handles differently:

* **[Throttle nodes
  DOC](/docs/journeys/nodes/throttle)** cap how many times a user (or all users globally) can pass a point in a journey within a time window. SFMC has no built-in send-collision control, so teams build exclusion logic by hand across journeys. A throttle node expresses "max 3 marketing messages per user per 24 hours" directly in the workflow.
* **[Batch
  DOC](/docs/journeys/nodes/batch) and [digest
  DOC](/docs/journeys/nodes/digest) nodes** collapse many events into one message, which in SFMC requires SQL queries and scheduled automations.

### Automation Studio

Automation Studio does three jobs. Each migrates somewhere different.

**One-time and scheduled sends** become [Broadcasts
DOC](/docs/broadcasts/overview). Pick a template and a list or audience, then send now or schedule a date, time, and timezone. Scheduled broadcasts can be rescheduled or canceled until they fire.

**Recurring sends** (a daily or weekly automation that sends to a refreshed Data Extension) run through your own scheduler instead, since a broadcast fires once. Run the schedule where your other cron jobs live and call the [send API
DOC](/docs/send/overview) against a list or audience. Audience membership updates automatically as profiles change, so the "refresh the Data Extension, then send" two-step collapses into one API call.

**Data workflows** (SQL query activities, file imports, data extracts) don't move to Courier. Courier isn't an ETL tool. Run those transformations in your data warehouse, in Salesforce, or in your application. Sync the results to Courier as user profile attributes or audience memberships. The SQL that lived in Automation Studio moves into version-controlled code in your own stack.

### Email Studio, Content Builder, and Design Studio

Templates move to [Design Studio
DOC](/docs/design/templates/design-studio). A Courier template holds content for every channel (email, SMS, push, in-app, chat) in one resource. Build it with drag-and-drop blocks, or define it as [Elemental
DOC](/docs/design/elemental/overview) JSON.

For one-time campaign sends that lived in Email Studio, use [Broadcasts
DOC](/docs/broadcasts/overview) with the template and an audience.

### Data Extensions and user profiles

Data Extensions are relational tables. Courier [user profiles
DOC](/docs/recipients/overview) are JSON documents keyed by `user_id`. This is the biggest shift in the migration.

Your **sendable Data Extension** (the one keyed by subscriber key with email, phone, and personalization fields) becomes the Courier user profile. Profiles accept nested JSON, so attributes like plan tier, care team, or order history need no schema migration.

**Relational Data Extensions** (lookup tables you join with SQL) stay in your database. Flatten what a message needs onto the profile at sync time, or pass it in the `data` field at send time. Data that changes per event belongs in `data`. Data that describes the person belongs on the profile.

Load users in bulk with the [bulk API
GUIDE](/docs/guides/send-in-bulk) or create them inline: sending to an unknown `user_id` with profile data creates the user.

### Keeping Salesforce as the system of record

You don't migrate off Salesforce, only off Marketing Cloud's sending layer. Contacts, deals, and consent records stay in Salesforce CRM. What SFMC did with Marketing Cloud Connect, you do with a sync process you control:

1. **Outbound from Salesforce**: platform events, Change Data Capture, or a scheduled export push contact changes to your backend.
2. **Into Courier**: your backend upserts profiles through the [users API](/docs/api-reference/user-profiles/update-a-profile) or bulk jobs, and audience membership recalculates automatically from profile attributes.
3. **At send time**: your application triggers sends and journeys with event data. Courier joins it with the synced profile.

The sync is one-directional and small. Courier needs identifiers, channel addresses, and the attributes you segment or personalize on, not your whole CRM.

### Triggered sends and the Send API

SFMC's Triggered Sends and Transactional Messaging API map to the Courier [send API
DOC](/docs/send/overview). One request sends to a user across any configured channel. Courier handles routing, provider failover, and delivery tracking. No separate transactional subsystem to configure. Every send goes through the same pipeline.

### Subscription Center and preferences

SFMC publication lists and the Subscription Center manage opt-outs, mostly for email. Courier [Preferences
DOC](/docs/recipients/preferences/overview) manage opt-in and opt-out per topic and per channel. Courier enforces them at send time.

You get a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page), or [embeddable components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) to build the preference center into your product. Map each publication list to a preference topic during migration, and carry unsubscribes over before the first send.

### AMPscript and personalization

AMPscript and SSJS blocks become [Handlebars variables
DOC](/docs/design/templates/variables) plus data you pass on the send call. `Lookup()` and `LookupRows()` patterns invert. A template used to reach into a Data Extension at render time. Now you fetch the data first, or use a [fetch data node
DOC](/docs/journeys/nodes/fetch-data) mid-journey, then pass it in `data`. Templates render from what you give them, which makes sends reproducible and testable.

### Authentication

SFMC authenticates through installed packages: OAuth 2.0 client credentials against a tenant-specific subdomain, with scoped tokens that expire. Courier uses [API key authentication
DOC](/docs/reference/api-overview#authentication), a bearer token per workspace, with separate keys for test and production. Server-side calls use the key directly. Client-side surfaces like in-app inbox use short-lived [JWTs
DOC](/docs/in-app/authenticate-users) scoped to a user.

## Plan the migration

1. **Inventory what actually sends.** Export your active journeys, triggered sends, and automations. Most SFMC accounts carry years of dead journeys. Migrate the live ones.
2. **Stand up the data sync.** Salesforce to your backend to Courier profiles. Validate with a test audience before moving anything user-facing.
3. **Recreate templates in Design Studio.** Start from the highest-volume sends. Move AMPscript logic into send-time `data`.
4. **Map publication lists to preference topics** and import unsubscribes first.
5. **Rebuild journeys, one at a time.** Run the Courier journey in parallel against a test audience and compare output. Then cut the entry source over and pause the SFMC journey.
6. **Point triggered sends at the send API.** They cut over cleanly, because they are already API-driven in SFMC.
7. **Decommission by watching send logs**, not the calendar. When an SFMC journey has sent nothing in 30 days and its Courier replacement is live, retire it.

## Migrate with an AI agent

If you're running the migration with Claude Code, Cursor, or another coding agent, two things help:

* **[Courier's MCP server
  DOC](/docs/resources/mcp)** gives your agent direct access to your workspace. It can create templates, build journeys, upsert users, and inspect send logs as it works through the plan above.
* The concept-mapping table at the top of this page is the translation layer. An agent holding an SFMC journey export and that table can propose the equivalent Courier journey. The [journeys API
  DOC](/docs/journeys/build) lets it build the result programmatically.

A workable prompt: export the journey definition from SFMC's REST API (`/interaction/v1/interactions`), then hand it to your agent with this page. Ask for the equivalent Courier journey, plus the profile fields the sync has to provide.

## FAQ

> **Can I keep Salesforce as my system of record?**
>
> Salesforce should stay your system of record. Contacts, deals, and consent records stay in Salesforce CRM. A sync you control (platform events, Change Data Capture, or scheduled exports) pushes identifiers, channel addresses, and segmentation attributes into Courier as [user profiles
> DOC](/docs/recipients/overview). Courier replaces Marketing Cloud's sending layer, not your CRM.

> **What replaces Salesforce Journey Builder in Courier?**
>
> [Journeys
> DOC](/docs/journeys/overview). Entry sources become [triggers
> DOC](/docs/journeys/invoke): API invoke, inbound webhook, Segment event, or audience membership. Journey Builder activities map to nodes. Waits become [delay
> DOC](/docs/journeys/nodes/delay), decision splits become [branch
> DOC](/docs/journeys/nodes/branch), and sends become [send nodes
> DOC](/docs/journeys/nodes/send). Courier adds [throttle
> DOC](/docs/journeys/nodes/throttle) and [digest
> DOC](/docs/journeys/nodes/digest) nodes that Journey Builder has no equivalent for.

> **What happens to my Data Extensions?**
>
> Your sendable Data Extension becomes Courier user profiles: JSON documents keyed by `user_id` that accept nested attributes without a schema. Relational Data Extensions stay in your database. Flatten what a message needs onto the profile at sync time, or pass it in the `data` field at send time.

> **Does Courier support AMPscript?**
>
> Personalization uses [Handlebars variables
> DOC](/docs/design/templates/variables) in templates plus data you pass on the send call. AMPscript patterns that look up data at render time invert in Courier. Fetch the data before you send, or use a [fetch data node
> DOC](/docs/journeys/nodes/fetch-data) mid-journey, then pass the result in `data`.

> **What parts of Salesforce Marketing Cloud does Courier not replace?**
>
> Landing pages (CloudPages), ad audience activation (Advertising Studio), marketing attribution, and Automation Studio's data-transformation work (SQL query activities, imports, extracts). Those stay in Salesforce or elsewhere in your stack. Courier replaces message delivery and orchestration: journeys, triggered sends, campaigns, templates, and preferences.


# Migrate from SuprSend
Source: https://www.courier.com/docs/guides/migrate/from-suprsend

Map SuprSend workflows, templates, and subscribers to Courier, with an API mapping and a plan.

This guide maps SuprSend concepts to Courier and gives you a step-by-step migration plan.

## Map SuprSend concepts to Courier

| SuprSend | Courier |
| - | - |
| [Workflows](https://docs.suprsend.com/docs/workflows) | [Journeys&#xA;DOC](/docs/journeys/overview) |
| [Templates](https://docs.suprsend.com/docs/templates) | [Templates&#xA;DOC](/docs/design/templates/overview) |
| [Vendors](https://docs.suprsend.com/docs/vendors) | [Integrations&#xA;DOC](/docs/integrations/overview) |
| [Smart Channel Routing](https://docs.suprsend.com/docs/design-workflow) | [Channel Priority&#xA;DOC](/docs/send/routing) + [Failover&#xA;DOC](/docs/send/routing) |
| [Batching](https://docs.suprsend.com/docs/batch) | [Batch node&#xA;DOC](/docs/journeys/nodes/batch) |
| [Subscribers](https://docs.suprsend.com/docs/users) | [Users / Profiles&#xA;DOC](/docs/recipients/overview) |
| [Preferences](https://docs.suprsend.com/docs/preferences) | [Preferences&#xA;DOC](/docs/recipients/preferences/overview) |
| [Inbox](https://docs.suprsend.com/docs/inbox-quick-start) | [Inbox&#xA;DOC](/docs/in-app/overview) |
| [Tenants](https://docs.suprsend.com/docs/tenants) | [Tenants&#xA;DOC](/docs/tenants/overview) |

### Workflows and Journeys

SuprSend [workflows](https://docs.suprsend.com/docs/workflows) orchestrate notifications with four node types: trigger, function, branch, and delivery. Courier [Journeys
DOC](/docs/journeys/overview) do the same with a visual builder and an API.

| SuprSend Node | Courier Equivalent |
| - | - |
| Trigger node | [Journey trigger&#xA;DOC](/docs/journeys/invoke) (API invoke, inbound webhook, Segment event, or audience membership) |
| Delay (function node) | [Delay node&#xA;DOC](/docs/journeys/nodes/delay) |
| Batch (function node) | [Batch node&#xA;DOC](/docs/journeys/nodes/batch) |
| Branch node | [Branch node&#xA;DOC](/docs/journeys/nodes/branch) |
| Delivery node | [Send node&#xA;DOC](/docs/journeys/nodes/send) (references a template + routing) |

The important difference: journeys and templates are separate resources in Courier. A send node references a template by ID. Your product team changes what a notification says without opening the journey. Engineers change timing and conditions without touching copy.

Build journeys visually [in the UI
DOC](/docs/journeys/build) or define them through the [Journeys API
DOC](/docs/journeys/build).

### Templates

SuprSend splits notification content into [template groups](https://docs.suprsend.com/docs/templates), one template per channel. A Courier [template
DOC](/docs/design/templates/overview) is a single resource holding content for every channel: email, SMS, push, chat, and inbox.

[Design Studio
DOC](/docs/design/templates/design-studio) uses drag-and-drop content blocks. [Elemental
DOC](/docs/design/elemental/overview) JSON is the code-first path. Both support [`\{\{variable\}\}`
DOC](/docs/design/templates/variables) Handlebars-style personalization, channel-specific overrides, and [localization
DOC](/docs/design/elemental/locales).

Your product team updates copy, layout, and branding in Design Studio without code or a deploy. Publish and it goes live immediately.

### Integrations

SuprSend [vendors](https://docs.suprsend.com/docs/vendors) are Courier [Integrations
DOC](/docs/integrations/overview): the provider connections that deliver messages, such as SendGrid, Twilio, FCM, and Slack.

Courier supports providers on every channel. Wire up multiple providers for the same channel type and Courier [fails over
DOC](/docs/send/routing) between them automatically. If your primary email provider goes down, traffic shifts to the backup with no code change and no manual step.

### Routing

Courier's `single` [routing method
DOC](/docs/send/routing) replicates SuprSend's [smart channel routing](https://docs.suprsend.com/docs/design-workflow). Courier tries channels in the order you specify and stops at the first success. The `all` method sends to every listed channel at once.

Set routing per send request or per template. Provider-level [failover
DOC](/docs/send/routing) layers on top, so you get fallback at both the channel and provider layers.

### Digests and batching

Courier's [Batch node
DOC](/docs/journeys/nodes/batch) works like SuprSend's [batch function](https://docs.suprsend.com/docs/batch). It collects matching events over a window you configure, then releases them as one payload for a single summary notification. Your template gets the full list of collected events, so you can render summaries across email, push, or in-app. For summaries that release on a fixed schedule the user controls, use the [Digest node
DOC](/docs/journeys/nodes/digest).

### Users and profiles

Courier [profiles
DOC](/docs/recipients/overview) store recipient data: email, phone, push tokens, and any custom properties. Profiles accept nested JSON, which suits structured data like subscription tiers, team roles, or feature flags.

Create profiles ahead of time through the API, or inline at send time. Pass a `user_id` that doesn't exist yet and Courier creates the profile.

### Preferences

SuprSend's [preference system](https://docs.suprsend.com/docs/preferences) supports global channel opt-outs, category-level controls, and per-category overrides. Courier [Preferences
DOC](/docs/recipients/preferences/overview) support the same hierarchy and enforce it at send time. You write no conditional logic.

Courier also ships a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page) you can deploy in minutes and embeddable [React components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) for in-app preference centers. No custom UI required.

### In-app notifications

Courier [Inbox
DOC](/docs/in-app/overview) is a real-time in-app notification center with drop-in components for [React
DOC](/docs/sdk-libraries/courier-react-web), [iOS
DOC](/docs/sdk-libraries/ios), [Android
DOC](/docs/sdk-libraries/android), and [vanilla JS
DOC](/docs/sdk-libraries/courier-js-web). It runs on the same delivery pipeline as email, push, and SMS, so there's no separate provider to configure.

You get read/unread state, archiving, per-user history, [toast notifications
DOC](/docs/in-app/add-toasts), and [tab-based organization
DOC](/docs/in-app/customize-the-inbox).

### Tenants

[Tenants
DOC](/docs/tenants/overview) work much the same on both platforms. You scope branding, preference defaults, and notification feeds to a customer organization. Pass a `tenant_id` at send time and Courier applies that tenant's branding and preferences. Branding lives on the Tenant resource rather than a separate object.

## Why Courier

* **Content and logic stay separate.** Templates and journeys are independent. Your product team updates copy in Design Studio while engineers tune journey timing.
* **Design Studio.** Build email, SMS, push, and chat content with drag-and-drop blocks. Preview across channels, personalize with variables, and publish without deploying code.
* **Routing you control.** Priority-based fallback (`single`) or broadcast to all channels (`all`). Configure multiple providers per channel for automatic failover at the provider level too.
* **Built-in in-app channel.** Courier Inbox works without a third-party provider. Drop in a React, iOS, or Android component and deliver in-app notifications on the same pipeline as email and push.
* **Hosted preferences out of the box.** Ship a user-facing preference center with a single config, or embed React components in your app. No custom UI required.
* **The providers you already use.** Email, SMS, push, chat, webhooks, CDPs, and observability tools. Switch providers without changing your send code.
* **Full delivery observability.** [Message Logs
  DOC](/docs/monitor/overview) track every message from API request to provider delivery, with a timeline, error details, and rendered content inspection.

## Migrate step by step

**1. Create your Courier workspace**

[Sign up](https://app.courier.com/signup) and create a workspace. Courier gives you separate Test and Production [environments
DOC](/docs/workspaces/environments) with their own API keys, so you can migrate without touching live traffic.

**2. Configure integrations**

Go to **Integrations** in your Courier dashboard and connect the same providers you use as SuprSend vendors (SendGrid, Twilio, FCM, etc.). Each provider maps to a channel type (email, SMS, push, chat). Configure multiple providers per channel for [failover
DOC](/docs/send/routing).

If you use SuprSend's inbox, [Courier Inbox
DOC](/docs/in-app/overview) is already set up in production and test. No external provider needed.

**3. Recreate templates**

SuprSend template groups contain per-channel templates. In Courier, a single [template
DOC](/docs/design/templates/overview) holds content for all channels:

1. Create a new template for each notification type
2. Add channel-specific content blocks (email body, SMS text, push title/body, etc.)
3. Use `{{variable}}` syntax for dynamic data. Both platforms use Handlebars-style variables
4. Publish the template to make it available for sending

**4. Recreate workflows as journeys**

Recreate SuprSend workflows that use delays, batching, or branching in [Journeys
DOC](/docs/journeys/overview). Build them visually [in the UI
DOC](/docs/journeys/build) or define them through the [Journeys API
DOC](/docs/journeys/build).

For notification types that need no orchestration (no delays, no batching), skip journeys and send directly via the [Send API
DOC](/docs/send/overview).

**5. Migrate user data**

Create Courier profiles with the same identifiers you use in SuprSend. Use the [Profiles API](/docs/api-reference/user-profiles/create-a-profile), or create them inline at send time.

```json theme={null}
{
  "user_id": "user_123",
  "profile": {
    "email": "sarah@acme-corp.com",
    "phone_number": "+15551234567",
    "custom": {
      "name": "Sarah Bennett",
      "plan": "enterprise"
    }
  }
}
```

**6. Set up preferences**

If you use SuprSend's preference system, recreate your structure in Courier:

1. Define [subscription topics
   DOC](/docs/recipients/preferences/overview) that map to your SuprSend categories
2. Configure default channel routing per topic
3. Migrate user preference selections via the [Preferences API](/docs/api-reference/user-preferences/get-users-preferences)

Courier also provides a [hosted preference page
GUIDE](/docs/guides/build-a-preference-center#hosted-page) you can deploy immediately, or [React components
GUIDE](/docs/guides/build-a-preference-center#embedded-component) for embedding preferences in your app.

**7. Update your send calls**

Replace SuprSend's workflow trigger calls with Courier's [Send API
DOC](/docs/send/overview). A basic send looks like this:

```javascript Node.js theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: {
      order_id: 'ORD-456',
      total: 79.99,
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "order_id": "ORD-456",
            "total": 79.99,
        },
    },
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "order_id": "ORD-456",
        "total": 79.99
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { order_id: "ORD-456", total: 79.99 }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"order_id": "ORD-456",
			"total": 79.99,
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "order_id", "ORD-456",
            "total", 79.99)))
        .build())
    .build();
client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['order_id' => 'ORD-456', 'total' => 79.99],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "order_id", JsonSerializer.SerializeToElement("ORD-456") },
            { "total", JsonSerializer.SerializeToElement(79.99) },
        },
    },
};

await client.Send.Message(parameters);
```

```bash CLI theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"order_id":"ORD-456","total":79.99}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with the order details.
```

Courier applies routing, preferences, and failover from your template and workspace configuration. For multi-channel sends, set the `routing` field:

```javascript Node.js highlight={7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push",
        "email",
        "sms",
      ],
    },
  },
});
```

```python Python highlight={7} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": [
                "push",
                "email",
                "sms",
            ],
        },
    },
)
```

```bash cURL highlight={10} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": [
          "push",
          "email",
          "sms"
        ]
      }
    }
  }'
```

```ruby Ruby highlight={7} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push",
        "email",
        "sms"
      ]
    }
  }
)
```

```go Go highlight={9} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
				{OfString: courier.String("email")},
				{OfString: courier.String("sms")},
			},
			Method: "single",
		},
	},
})
```

```java Java highlight={5} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("push")
            .addChannel("email")
            .addChannel("sms")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={7} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => [
        'push',
        'email',
        'sms',
      ],
    ],
  ],
);
```

```csharp C# highlight={7} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["push", "email", "sms"], Method = Send::Method.Single },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push", "email", "sms"]}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 over email and push.
```

This tries push first, then email, then SMS. The same pattern as SuprSend's smart channel routing.

**8. Test and cut over**

1. Send test messages in your Test environment and verify delivery in [Message Logs](https://app.courier.com/logs)
2. Validate that preferences, routing, and template rendering match your SuprSend setup
3. Switch your production code to Courier's Production API key
4. Monitor [Message Logs
   DOC](/docs/monitor/overview) and [Analytics
   DOC](/docs/monitor/overview) for delivery confirmation

## Map the API

| Operation | SuprSend | Courier |
| - | - | - |
| Send a notification | `POST /trigger` | [Send a message](/docs/api-reference/send/send-a-message) |
| Create/update a user | `POST /subscriber` | [Replace a Profile](/docs/api-reference/user-profiles/replace-a-profile) |
| Get a user | `GET /subscriber/:id` | [Get a Profile](/docs/api-reference/user-profiles/get-a-profile) |
| Set user preferences | `POST /subscriber/:id/category/:cat/preference` | [Update or create user Preferences for a Subscription Topic](/docs/api-reference/user-preferences/update-or-create-user-preferences-for-a-subscription-topic) |
| Get message status | `GET /event/:id` | [Get message](/docs/api-reference/messages/get-message) |
| Create/update tenant | Tenant API | [Create or replace a Tenant](/docs/api-reference/tenants/create-or-replace-a-tenant) |


# Migrate to Courier
Source: https://www.courier.com/docs/guides/migrate/overview

Map your concepts to Courier's, move recipients and content, then cut over sends.

Every migration follows the same shape: map your concepts to Courier's, move recipients and content, then cut over sends.

## How a migration maps

Most notification platforms share the same building blocks.

| Your current platform | Courier |
| - | - |
| Delivery channels / provider connections | [Integrations&#xA;DOC](/docs/integrations/overview) (bring your own provider, with [failover&#xA;DOC](/docs/send/routing)) |
| Workflows that bundle content and logic | [Templates&#xA;DOC](/docs/design/templates/overview) for content, [journeys&#xA;DOC](/docs/journeys/overview) for orchestration |
| Recipients / subscribers | [Users & profiles&#xA;DOC](/docs/recipients/overview) |
| Segments | [Lists & audiences&#xA;DOC](/docs/recipients/lists-and-audiences/overview) |
| Notification preferences | [Preferences&#xA;DOC](/docs/recipients/preferences/overview) |
| Multi-tenant accounts | [Tenants&#xA;DOC](/docs/tenants/overview) |
| In-app feeds | [Inbox&#xA;DOC](/docs/in-app/overview) |

One difference to plan around: Courier separates **content** (templates) from **orchestration** (journeys). A PM can change copy while an engineer changes timing.

## The general plan

1. Connect your providers as [integrations
   DOC](/docs/integrations/overview).
2. Move recipients into [profiles
   GUIDE](/docs/guides/import-your-users) and rebuild segments as [lists or audiences
   DOC](/docs/recipients/lists-and-audiences/overview).
3. Recreate content as [templates
   DOC](/docs/design/templates/api) and orchestration as [journeys
   DOC](/docs/journeys/build).
4. Move preferences and, if you use them, tenants.
5. Cut over sends and verify in [logs
   DOC](/docs/monitor/overview).

## Migrate from your platform

> **[From an in-house system](/docs/guides/migrate/from-in-house)**
>
> Replace homegrown notification code, one type at a time.

> **[From Knock](/docs/guides/migrate/from-knock)**
>
> Map workflows, recipients, and preferences from Knock.

> **[From SuprSend](/docs/guides/migrate/from-suprsend)**
>
> Move subscribers, templates, and channels from SuprSend.

> **[From Novu](/docs/guides/migrate/from-novu)**
>
> Map subscribers, workflows, and layouts from Novu.

> **[From OneSignal](/docs/guides/migrate/from-onesignal)**
>
> Move users, segments, and push from OneSignal.

> **[From Braze](/docs/guides/migrate/from-braze)**
>
> Map user profiles, segments, and campaigns from Braze.

> **[From Salesforce Marketing Cloud](/docs/guides/migrate/from-salesforce-marketing-cloud)**
>
> Move data extensions, journeys, and triggered sends.

> **[From Intercom](/docs/guides/migrate/from-intercom)**
>
> Map contacts, series, and in-product messages from Intercom.

## Upgrade Courier React

Already on Courier and moving off React v7? The [React v8+ migration guide
DOC](/docs/sdk-libraries/courier-react-v8-migration-guide) covers the Inbox, Toast, and Preferences components.


# Notify across tenants
Source: https://www.courier.com/docs/guides/notify-across-tenants

Send from one workspace to many customer organizations, each with its own brand and defaults.

Send from one workspace to many customer orgs, each with its own logo, colors, and notification defaults.

A tenant holds the settings for one customer org. You keep a single set of templates and one integration per channel. Name a tenant on the send, and Courier applies that org's brand and defaults.

## Prerequisites

* [A connected provider
  DOC](/docs/integrations/overview)
* [A published template with its brand enabled
  DOC](/docs/design/templates/overview)
* [A Courier API key](https://app.courier.com/settings/api-keys)

## Set up a tenant

**1. Create a brand for the customer**

Open [Brands](https://app.courier.com/content/brands) and create one brand per customer org with their logo, colors, and footer. Copy its brand ID.

One brand serves every template that org receives, so this is the only place their visual identity lives. See [brands
DOC](/docs/design/brands) for what a brand controls.

**2. Create the tenant**

[Create or replace a Tenant](/docs/api-reference/tenants/create-or-replace-a-tenant) takes an id you choose, so the same call creates the tenant on signup and updates it on every change after. Point it at the brand you just made.

```javascript Node.js theme={null}
const tenant = await client.tenants.update('acme-corp', {
  name: 'Acme Corp',
  brand_id: 'bnd_acmecorp',
  properties: { plan: 'enterprise' },
});
```

```python Python theme={null}
tenant = client.tenants.update(
    tenant_id="acme-corp",
    name="Acme Corp",
    brand_id="bnd_acmecorp",
    properties={"plan": "enterprise"},
)
```

```bash cURL theme={null}
curl -X PUT https://api.courier.com/tenants/acme-corp \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "brand_id": "bnd_acmecorp",
    "properties": { "plan": "enterprise" }
  }'
```

```ruby Ruby theme={null}
tenant = courier.tenants.update(
  "acme-corp",
  name: "Acme Corp",
  brand_id: "bnd_acmecorp",
  properties: {plan: "enterprise"}
)
```

```go Go theme={null}
tenant, err := client.Tenants.Update(
	context.TODO(),
	"acme-corp",
	courier.TenantUpdateParams{
		Name:    "Acme Corp",
		BrandID: courier.String("bnd_acmecorp"),
		Properties: map[string]any{
			"plan": "enterprise",
		},
	},
)
```

```java Java theme={null}
TenantUpdateParams params = TenantUpdateParams.builder()
    .tenantId("acme-corp")
    .name("Acme Corp")
    .brandId("bnd_acmecorp")
    .properties(TenantUpdateParams.Properties.builder()
        .putAdditionalProperty("plan", JsonValue.from("enterprise"))
        .build())
    .build();
Tenant tenant = client.tenants().update(params);
```

```php PHP theme={null}
$tenant = $client->tenants->update(
  'acme-corp',
  name: 'Acme Corp',
  brandID: 'bnd_acmecorp',
  properties: ['plan' => 'enterprise'],
);
```

```csharp C# theme={null}
var tenant = await client.Tenants.Update(
    "acme-corp",
    new()
    {
        Name = "Acme Corp",
        BrandID = "bnd_acmecorp",
        Properties = new Dictionary<string, JsonElement>()
        {
            { "plan", JsonSerializer.SerializeToElement("enterprise") }
        },
    }
);
```

```bash CLI theme={null}
courier tenants update \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --name "Acme Corp" \
  --brand-id bnd_acmecorp \
  --properties '{"plan":"enterprise"}'
```

```text MCP theme={null}
With Courier MCP, create a tenant called Acme Corp and point it at my Acme brand.
```

Setting `brand_id` on the tenant makes branding automatic. On any send that names this tenant, Courier picks the tenant's brand without a `brand_id` on the request.

**3. Set the org's notification defaults**

Give the tenant `default_preferences` so a new user in that org starts opted in or out to match the org, before they ever open a preference center. See [tenant default preferences
DOC](/docs/tenants/preferences) for the per-topic calls.

**4. Add users to the tenant**

Put each of the org's users in the tenant so membership drives who receives a fan-out send. Add them one at a time, or in one call with `bulk_add_user_tenants`.

A user can belong to more than one tenant, which matters for the send shape you choose next.

## Send with the tenant

**1. Notify one user in their org's context**

Set `context.tenant_id` on the recipient. The message renders with that org's brand, and preference lookups scope to that org.

```javascript Node.js highlight={6} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      user_id: "user_123",
      context: {
        tenant_id: "acme-corp",
      },
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      amount: 420.00,
    },
  },
});
```

```python Python highlight={6} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
            "context": {
                "tenant_id": "acme-corp",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "amount": 420.00,
        },
    },
)
```

```bash cURL highlight={9} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123",
        "context": {
          "tenant_id": "acme-corp"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "amount": 420.00
      }
    }
  }'
```

```ruby Ruby highlight={6} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123",
      context: {
        tenant_id: "acme-corp"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      amount: 420.00
    }
  }
)
```

```go Go highlight={7} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
				Context: shared.MessageContextParam{
					TenantID: courier.String("acme-corp"),
				},
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"amount": 420.00,
		},
	},
})
```

```java Java highlight={5} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder()
            .userId("user_123")
            .context(MessageContext.builder().tenantId("acme-corp").build())
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "amount", 420.00
        )))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={6} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
      'context' => [
        'tenant_id' => 'acme-corp',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => [
      'amount' => 420.00,
    ],
  ],
);
```

```csharp C# highlight={8} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient
        {
            UserID = "user_123",
            Context = new MessageContext { TenantID = "acme-corp" },
        },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "amount", JsonSerializer.SerializeToElement(420.00) },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123", "context": {"tenant_id": "acme-corp"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"amount": 420.00}'
```

```text MCP theme={null}
With Courier MCP, send to user_123 with tenant context acme-corp so it uses that org's brand.
```

The user's own stored profile and preferences still win over the tenant's, so a person who opted out stays opted out.

**2. Notify the whole org**

Put a `tenant_id` in `to` and Courier looks up the tenant's members and sends to each one.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      tenant_id: "acme-corp",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "inbox",
      ],
    },
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "tenant_id": "acme-corp",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": [
                "inbox",
            ],
        },
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "tenant_id": "acme-corp"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": [
          "inbox"
        ]
      }
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      tenant_id: "acme-corp"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "inbox"
      ]
    }
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				TenantID: courier.String("acme-corp"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("inbox")},
			},
			Method: "single",
		},
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().tenantId("acme-corp").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("inbox")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'tenant_id' => 'acme-corp',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => [
        'inbox',
      ],
    ],
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { TenantID = "acme-corp" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["inbox"], Method = Send::Method.Single },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"tenant_id": "acme-corp"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["inbox"]}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to every member of acme-corp.
```

Every targeting shape, including walking a tenant hierarchy up or down, is in [send with tenants
DOC](/docs/tenants/send).

**3. Give one org different content (optional)**

When an org needs its own wording, not only its own colors, create a tenant template and reference it as `template: "tenant/<template_id>"`. Courier merges its content over the message. See [tenant templates
DOC](/docs/tenants/templates).

To let the customer write that wording themselves, [put the editor in your app
GUIDE](/docs/guides/let-customers-edit-notifications).

## Verify

**1. Confirm the brand resolved**

Send to a user in the tenant, then open the message in [Logs](https://app.courier.com/logs). The output should carry that org's logo and colors, not your workspace default.

**2. Compare two tenants**

Send the same template to a user in a second tenant and confirm the two rendered messages differ only by brand.

**3. Check the fan-out count**

Send with `to.tenant_id` and confirm the log shows one message per member of that tenant.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| `Tenant Context Not Found` | The user belongs to several tenants and the send named none | Set `context.tenant_id` on the send |
| Workspace default brand renders | Neither the send, the tenant, nor the template set a brand | Set `brand_id` on the tenant, and enable the brand on the template |
| A tenant's message is missing from the inbox | The client signed in without a `tenantId`, or with another tenant's | Pass the send's `tenant_id` as `tenantId` at `signIn` |
| A child org is missing a parent setting | The chain is deeper than four levels | Flatten the hierarchy to four or fewer |

Which isolation layer to reach for, tenant against environment against workspace, is covered in [workspaces
DOC](/docs/workspaces/overview#workspace-environment-or-tenant). The merge rules behind all of the above are in [tenant context
DOC](/docs/tenants/context).


# Notify everyone watching
Source: https://www.courier.com/docs/guides/notify-everyone-watching

Model watchers of a document or ticket as a list per entity, then notify them in one send.

Someone comments on a document, and everyone watching it should hear about it. This guide models watchers as a list per entity.

A `list_id` is a dotted namespace, so `document.doc_a1b2.watchers` names the watchers of one document.

## Prerequisites

* [A Courier API key](https://app.courier.com/settings/api-keys)
* A [profile
  DOC](/docs/recipients/overview) for each user you subscribe
* A published [template
  DOC](/docs/design/templates/overview) to send

## Name the list after the entity

Pick a naming convention before you write any code, because the name is the only thing tying a list to the thing it belongs to. A `list_id` holds up to six dot-separated segments:

```text theme={null}
<entity type>.<entity id>.<relationship>
```

| The thing | The list |
| :- | :- |
| Watchers of a document | `document.doc_a1b2.watchers` |
| Members of a project | `project.proj_9f3e.members` |
| Subscribers to a ticket | `ticket.tkt_77c1.subscribers` |

Keeping the entity type in the first segment is what makes [wildcards
GUIDE](/docs/guides/notify-everyone-watching#reach-every-entity-of-a-kind) useful later. Entity ids with dots in them won't work, since a dot starts a new segment.

## Wire up watching

**1. Subscribe a user when they start watching**

One call, and it is idempotent. [Subscribe a user Profile to a List](/docs/api-reference/lists/subscribe-a-user-profile-to-a-list) **creates the list if it doesn't exist**, so you never check first.

```javascript Node.js theme={null}
await client.lists.subscriptions.subscribeUser("user_123", {
  list_id: "document.doc_a1b2.watchers",
});
```

```python Python theme={null}
client.lists.subscriptions.subscribe_user(
    "user_123",
    list_id="document.doc_a1b2.watchers",
)
```

```bash cURL theme={null}
curl -X PUT https://api.courier.com/lists/document.doc_a1b2.watchers/subscriptions/user_123 \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```ruby Ruby theme={null}
courier.lists.subscriptions.subscribe_user(
  "user_123",
  list_id: "document.doc_a1b2.watchers"
)
```

```go Go theme={null}
err := client.Lists.Subscriptions.SubscribeUser(
	context.TODO(),
	"user_123",
	courier.ListSubscriptionSubscribeUserParams{
		ListID: "document.doc_a1b2.watchers",
	},
)
```

```java Java theme={null}
SubscriptionSubscribeUserParams params = SubscriptionSubscribeUserParams.builder()
    .listId("document.doc_a1b2.watchers")
    .userId("user_123")
    .build();

client.lists().subscriptions().subscribeUser(params);
```

```php PHP theme={null}
$client->lists->subscriptions->subscribeUser(
  'user_123',
  listID: 'document.doc_a1b2.watchers',
);
```

```csharp C# theme={null}
await client.Lists.Subscriptions.SubscribeUser(
    "user_123",
    new() { ListID = "document.doc_a1b2.watchers" }
);
```

```bash CLI theme={null}
courier lists:subscriptions subscribe-user \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --list-id document.doc_a1b2.watchers
```

```text MCP theme={null}
With Courier MCP, subscribe user_123 to the list document.doc_a1b2.watchers.
```

Call this wherever your app already records a watch: an explicit **Watch** button, or implicitly when someone comments or is assigned.

**2. Notify everyone watching**

Address the list instead of a user. Courier fans out to every subscriber and applies each recipient's own [preferences
DOC](/docs/recipients/preferences/overview).

```javascript Node.js highlight={3} theme={null}
await client.send.message({
  message: {
    to: { list_id: "document.doc_a1b2.watchers" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { document_title: "Q3 Roadmap", commenter: "Sarah Bennett" },
  },
});
```

```python Python highlight={3} theme={null}
client.send.message(
    message={
        "to": {"list_id": "document.doc_a1b2.watchers"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"document_title": "Q3 Roadmap", "commenter": "Sarah Bennett"},
    },
)
```

```bash cURL highlight={6} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "list_id": "document.doc_a1b2.watchers" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "document_title": "Q3 Roadmap", "commenter": "Sarah Bennett" }
    }
  }'
```

```ruby Ruby highlight={3} theme={null}
courier.send_.message(
  message: {
    to: {list_id: "document.doc_a1b2.watchers"},
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {document_title: "Q3 Roadmap", commenter: "Sarah Bennett"}
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfListRecipient: &shared.ListRecipientParam{
				ListID: courier.String("document.doc_a1b2.watchers"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"document_title": "Q3 Roadmap",
			"commenter":      "Sarah Bennett",
		},
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofListRecipient(
        ListRecipient.builder().listId("document.doc_a1b2.watchers").build()))
    .template("nt_01kx4h2jdafq8bk9aftxak4b40")
    .data(SendMessageParams.Message.Data.builder()
        .putAdditionalProperty("document_title", JsonValue.from("Q3 Roadmap"))
        .putAdditionalProperty("commenter", JsonValue.from("Sarah Bennett"))
        .build())
    .build();

client.send().message(SendMessageParams.builder().message(message).build());
```

```php PHP highlight={3} theme={null}
$client->send->message(
  message: [
    'to' => ['list_id' => 'document.doc_a1b2.watchers'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['document_title' => 'Q3 Roadmap', 'commenter' => 'Sarah Bennett'],
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new ListRecipient { ListID = "document.doc_a1b2.watchers" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new()
        {
            ["document_title"] = "Q3 Roadmap",
            ["commenter"] = "Sarah Bennett",
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"list_id": "document.doc_a1b2.watchers"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"document_title": "Q3 Roadmap", "commenter": "Sarah Bennett"}'
```

```text MCP theme={null}
With Courier MCP, send the nt_01kx4h2jdafq8bk9aftxak4b40 template to the list document.doc_a1b2.watchers.
```

One send reaches every watcher, however many there are. You don't fan out yourself.

**3. Unsubscribe when they stop watching**

[Unsubscribe a user Profile from a List](/docs/api-reference/lists/unsubscribe-a-user-profile-from-a-list) removes one watcher and leaves the rest alone.

```javascript Node.js theme={null}
await client.lists.subscriptions.unsubscribeUser("user_123", {
  list_id: "document.doc_a1b2.watchers",
});
```

```python Python theme={null}
client.lists.subscriptions.unsubscribe_user(
    "user_123",
    list_id="document.doc_a1b2.watchers",
)
```

```bash cURL theme={null}
curl -X DELETE https://api.courier.com/lists/document.doc_a1b2.watchers/subscriptions/user_123 \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
courier.lists.subscriptions.unsubscribe_user(
  "user_123",
  list_id: "document.doc_a1b2.watchers"
)
```

```go Go theme={null}
err := client.Lists.Subscriptions.UnsubscribeUser(
	context.TODO(),
	"user_123",
	courier.ListSubscriptionUnsubscribeUserParams{
		ListID: "document.doc_a1b2.watchers",
	},
)
```

```java Java theme={null}
SubscriptionUnsubscribeUserParams params = SubscriptionUnsubscribeUserParams.builder()
    .listId("document.doc_a1b2.watchers")
    .userId("user_123")
    .build();

client.lists().subscriptions().unsubscribeUser(params);
```

```php PHP theme={null}
$client->lists->subscriptions->unsubscribeUser(
  'user_123',
  listID: 'document.doc_a1b2.watchers',
);
```

```csharp C# theme={null}
await client.Lists.Subscriptions.UnsubscribeUser(
    "user_123",
    new() { ListID = "document.doc_a1b2.watchers" }
);
```

```bash CLI theme={null}
courier lists:subscriptions unsubscribe-user \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --list-id document.doc_a1b2.watchers
```

```text MCP theme={null}
With Courier MCP, unsubscribe user_123 from the list document.doc_a1b2.watchers.
```

When the entity itself is deleted, delete the whole list with [Delete a List](/docs/api-reference/lists/delete-a-list) rather than removing watchers one at a time.

## Ask who is watching what

Both directions of the relationship are readable, which is what makes this usable as your app's own watch state rather than a write-only copy of it.

| Question | Endpoint |
| :- | :- |
| Who is watching this document? | [List subscriptions for a List](/docs/api-reference/lists/list-subscriptions-for-a-list) |
| What is this user watching? | [Get List subscriptions](/docs/api-reference/user-profiles/get-list-subscriptions) |

Both are [cursor-paginated
DOC](/docs/reference/api-overview#pagination).

## Reach every entity of a kind

Because the entity type leads the `list_id`, one pattern can address many lists at once. Swap `list_id` for `list_pattern`, where `*` matches a single segment:

```json theme={null}
{
  "to": { "list_pattern": "document.*.watchers" }
}
```

That reaches everyone watching any document, without you listing them.

> [!NOTE]
>
> A recipient watching several matched entities is deduplicated, so nobody receives the same message twice from one send.

## Per-watcher preferences

A subscription can carry its own `preferences`, which apply to that subscription alone. Someone can follow a noisy project on digest while staying on instant notifications everywhere else. See [preferences
DOC](/docs/recipients/preferences/overview) for the status model.

## Verify

**1. Subscribe two users**

Subscribe two test users to `document.doc_a1b2.watchers`.

**2. Read the list back**

Call [List subscriptions for a List](/docs/api-reference/lists/list-subscriptions-for-a-list) and confirm both appear, which also proves the list was created by the subscribe call.

**3. Send and check the logs**

Send to the list, then open [Logs](https://app.courier.com/logs). You should see one message per subscriber, each with its own status.

**4. Unsubscribe one and send again**

The second send reaches one recipient. The unsubscribed user gets nothing.

## FAQ

> **Do I have to create the list before subscribing anyone?**
>
> Subscribing creates the list when it doesn't exist, so a Watch button is one call with no setup and no existence check.

> **What happens when a watcher has opted out?**
>
> Courier applies each recipient's preferences during fan-out, so an opted-out watcher is filtered and the rest still receive the message. The send doesn't fail.

> **How many watchers can one list hold?**
>
> Lists are built for fan-out, so a busy document with thousands of watchers is one send. Read members back with cursor pagination rather than all at once.

> **Can I scope this to one tenant?**
>
> Add a `MEMBER_OF` filter on the recipient alongside `context.tenant_id`. Tenant context alone sets branding and preferences without restricting who receives the message. See [scoping a list send to a tenant
> DOC](/docs/recipients/lists-and-audiences/lists#scoping-a-list-send-to-a-tenant).

> **Should I use an audience instead?**
>
> Use an audience when membership follows from profile data, such as every user on the Pro plan. Watching is an explicit act that no profile field implies, so a list is the right shape.


# Send a welcome email from Auth0
Source: https://www.courier.com/docs/guides/notify-from-auth0

Call Courier from an Auth0 post-registration Action, with no webhook route to host.

Auth0 runs your code itself, so this one needs no webhook route. A **post-user-registration** Action calls Courier straight from Auth0.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["User registers"] --> B["Auth0 Action"]
    B --> C["Create profile"]
    C --> D["Welcome email"]
```

## Prerequisites

* [A Courier Test API key](https://app.courier.com/~/test/platform/api-keys)
* An Auth0 tenant with a Database or Passwordless connection
* A published [template
  DOC](/docs/design/templates/overview) to send

## How this differs from a webhook

Clerk and Stripe post to a route you host, so you verify a signature and run your own code. Auth0 Actions are your code, running inside Auth0. Three consequences follow.

**No route, no signature, no tunnel.** There is nothing public to host and nothing to verify, because nothing crossed the internet to reach you. Local development needs no `ngrok`.

**Secrets live in the Action.** Auth0 stores them and exposes them as `event.secrets`, so your Courier key never sits in your app's environment.

**Auth0 doesn't wait for the Action to finish.** A slow or failing Action never blocks a signup. Auth0's logs show whether it ran.

## Set it up

**1. Create the Action**

In the Auth0 Dashboard, go to **Actions → Library**, select **Build Custom**, and create an Action on the **Post User Registration** trigger.

**2. Add the SDK and your key**

In the Action editor, open the **Dependencies** panel in the left sidebar and add `@trycourier/courier`. Actions install npm packages into the runtime, so the [Node SDK
DOC](/docs/sdk-libraries/node) works here exactly as it does on your own server.

Then open the key icon in the same sidebar and add a secret named `COURIER_API_KEY` with your Courier key as its value.

Auth0 exposes the secret to the Action as `event.secrets.COURIER_API_KEY`. It is never in your application's environment and never in the Action's source.

**3. Write the Action**

The Action receives the newly created user on `event.user`. Create the profile, then send.

```javascript Post User Registration lines theme={null}
const Courier = require("@trycourier/courier");

exports.onExecutePostUserRegistration = async (event) => {
  const courier = new Courier({ apiKey: event.secrets.COURIER_API_KEY });
  const { user_id, email, given_name } = event.user;

  // Auth0's user_id becomes the Courier user id, so both systems agree.
  await courier.profiles.create(user_id, {
    profile: { email, given_name },
  });

  await courier.send.message({
    message: {
      to: { user_id },
      template: "nt_01kx4h2jdafq8bk9aftxak4b40",
      data: { name: given_name ?? "there" },
    },
  });
};
```

Actions are CommonJS, so the SDK comes in with `require` rather than `import`. Everything else is the same code you would write on your own server, and the [Node SDK reference
DOC](/docs/sdk-libraries/node) applies unchanged.

> [!NOTE]
>
> A failed send doesn't fail the signup or show the user an error. Wrap the calls in `try`/`catch` and `console.log` the error, then check **Monitoring → Logs** to confirm sends succeed.

**4. Deploy and add it to the flow**

Select **Deploy**, then go to **Actions → Triggers → post-user-registration** and drag the Action into the flow between Start and Complete. An Action that is deployed but not in the flow never runs, which is the most common reason nothing happens.

## Verify

**1. Register a test user**

Create a user through your app's signup, or from **User Management → Users** in the Auth0 Dashboard. The trigger fires for Database and Passwordless connections.

**2. Check the Auth0 log**

In **Monitoring → Logs**, find the registration event.

**3. Confirm the send**

Open [Logs](https://app.courier.com/logs) in Courier and confirm the message.

> [!NOTE]
>
> The trigger fires for **Database and Passwordless connections only**. A user arriving through a social or enterprise connection doesn't fire it, so a Google sign-up sends nothing. For those, use a post-login Action and check whether the login is the user's first.

## Adapt it for other triggers

| Auth0 trigger | What to send |
| :- | :- |
| `post-user-registration` | Welcome, for database and passwordless signups |
| `post-login` | A new-device or new-location alert |
| `send-phone-message` | Route Auth0's own MFA codes through Courier |
| `post-change-password` | A password-changed confirmation |

`post-login` runs on every login, so gate anything you send there on a condition. Sending on each login is how a welcome email becomes a complaint.


# Send a welcome email from Clerk
Source: https://www.courier.com/docs/guides/notify-from-clerk

Turn Clerk's user.created webhook into a Courier profile and a welcome email.

Clerk fires `user.created` the moment someone signs up. This guide turns that into a Courier profile and a welcome message.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["Sign-up"] --> B["Clerk webhook"]
    B --> C{"Signature valid?"}
    C -->|Yes| D["Create profile"]
    D --> E["Welcome email"]
    C -->|No| F["Reject"]
```

## Prerequisites

* [A Courier Test API key](https://app.courier.com/~/test/platform/api-keys)
* A Clerk application, and somewhere to host an HTTPS route
* A published [template
  DOC](/docs/design/templates/overview) to send

## Why this needs a route in your app

Courier has an [inbound webhook
DOC](/docs/monitor/webhooks/inbound) that many sources can post to directly. Clerk isn't one of them, for three reasons.

**The field names don't line up.** Courier reads `event` and `userId` from a payload. Clerk sends `type` and `data.id`. Posted straight through, the event arrives named `custom` with no recipient attached.

**The user doesn't exist yet.** An inbound event only starts a journey when its `userId` matches an existing Courier user. On `user.created` there is nothing to match, so the profile has to be written first.

**Courier doesn't verify Clerk's signature.** Courier's inbound URL is its own credential and accepts any JSON sent to it. Verify the signature in your own endpoint before forwarding the event, because that is what stops a forged sign-up.

So the shape is Clerk to your route to Courier. Your route is where verification happens and where the profile is created.

## Set it up

**1. Install the packages**

```bash theme={null}
npm install @clerk/backend @trycourier/courier
```

Put both secrets in your environment. Clerk shows the signing secret when you create the endpoint in the next step.

```bash .env.local theme={null}
COURIER_API_KEY=YOUR_COURIER_API_KEY
CLERK_WEBHOOK_SIGNING_SECRET=whsec_...
```

**2. Write the route handler**

`verifyWebhook` checks the Svix signature Clerk sends and throws when it fails. Verify before you read anything out of the body.

```tsx app/api/clerk/route.ts lines theme={null}
import { verifyWebhook } from "@clerk/backend/webhooks";
import Courier from "@trycourier/courier";

const courier = new Courier({ apiKey: process.env.COURIER_API_KEY! });

export async function POST(request: Request) {
  let evt;
  try {
    // Throws on a bad signature or a replayed request.
    evt = await verifyWebhook(request);
  } catch {
    return new Response("Invalid signature", { status: 400 });
  }

  if (evt.type !== "user.created") {
    return new Response("Ignored", { status: 200 });
  }

  const { id, email_addresses, primary_email_address_id, first_name } = evt.data;

  // Match the primary id rather than taking [0]. A user with several
  // addresses can have the primary at any index.
  const email = email_addresses?.find((e) => e.id === primary_email_address_id)
    ?.email_address;

  if (!email) {
    return new Response("No email on user", { status: 200 });
  }

  // Use Clerk's id as the Courier user id so both systems agree.
  await courier.profiles.create(id, {
    profile: { email, given_name: first_name ?? undefined },
  });

  await courier.send.message({
    message: {
      to: { user_id: id },
      template: "nt_01kx4h2jdafq8bk9aftxak4b40",
      data: { name: first_name ?? "there" },
    },
  });

  return new Response("OK", { status: 200 });
}
```

**Clerk's `id` becomes the Courier `user_id`.** One identifier across both systems means every later send addresses the user without a lookup table.

**A non-matching event returns `200`.** Clerk retries anything that isn't a success, so returning an error for an event you deliberately ignore creates a retry loop.

**3. Point Clerk at the route**

In the Clerk dashboard, under **Configure → Webhooks**, add an endpoint for your route's public URL and subscribe it to **`user.created`**.

Copy the signing secret Clerk shows into `CLERK_WEBHOOK_SIGNING_SECRET`.

> [!NOTE]
>
> Clerk needs a public HTTPS URL, so `localhost` won't receive events. Use a tunnel such as `ngrok` while developing, and Clerk's **Testing** tab to replay an event without signing up each time.

## Verify

**1. Send a test event**

Use the **Testing** tab in Clerk's webhook settings to send a `user.created` event. Your route should answer `200`.

**2. Check the profile exists**

Read it back with [Get a Profile](/docs/api-reference/user-profiles/get-a-profile), using the Clerk user id. The email you expect should be on it.

**3. Check the message went out**

Open [Logs](https://app.courier.com/logs) and confirm the send. A `SENT` status means the provider accepted it.

If the profile exists but nothing sent, the send is the problem rather than the webhook. [Debug delivery
GUIDE](/docs/guides/debug-delivery) works that half.

## Adapt it for other events

The same handler shape covers the rest of Clerk's catalog. Switch on `evt.type` and keep one route:

| Clerk event | What to do |
| :- | :- |
| `user.created` | Create the profile, send a welcome |
| `user.updated` | Update the profile so an email change reaches the right inbox |
| `user.deleted` | Delete the profile, per [erasure&#xA;DOC](/docs/workspaces/compliance#data-access-and-deletion-requests) |
| `organizationMembership.created` | Add the user to a [tenant&#xA;DOC](/docs/tenants/overview) |

That last row is the one to reach for in a B2B app. Clerk organizations and Courier tenants model the same thing, so keeping them in step means branding and preferences follow the user automatically.


# Send a welcome message from Firebase Auth
Source: https://www.courier.com/docs/guides/notify-from-firebase-auth

Send a welcome message from a Cloud Function on the Firebase user-created event.

Firebase Auth has no webhook. It runs your code instead, as a Cloud Function on the user-created event.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["User signs up"] --> B["Cloud Function"]
    B --> C["Create profile"]
    C --> D["Welcome message"]
```

## Prerequisites

* [A Courier Test API key](https://app.courier.com/~/test/platform/api-keys)
* A Firebase project with Authentication enabled, and the Firebase CLI
* A published [template
  DOC](/docs/design/templates/overview) to send

## Use the non-blocking trigger

Firebase gives you two ways to run code when a user is created, and for a welcome message the older one is the right one.

**`functions.auth.user().onCreate()`** is a 1st-gen trigger. It runs after the user exists, asynchronously, and nothing you do in it can affect the signup. There is no 2nd-gen equivalent, and Firebase says so plainly: 2nd gen doesn't support Authentication triggers. The two generations coexist in one file, so this isn't a reason to avoid 2nd gen elsewhere.

**`beforeUserCreated`** is the 2nd-gen blocking function, and it is the wrong tool here for three reasons:

* It **requires upgrading the project** to Firebase Authentication with Identity Platform.
* It **must respond within 7 seconds**, after which Firebase returns an error and the client operation fails. A slow send would block a signup.
* Deleting the function without unregistering its trigger **prevents all users from authenticating**.

Blocking is for deciding whether someone may sign up. Sending a welcome isn't that, and a notification outage should never stop a registration.

## Set it up

**1. Install the dependencies**

In your functions directory:

```bash theme={null}
npm install firebase-functions firebase-admin @trycourier/courier
```

**2. Store your Courier key as a secret**

Firebase keeps secrets in Cloud Secret Manager and injects them at runtime.

```bash theme={null}
firebase functions:secrets:set COURIER_API_KEY
```

Bind it to the function that needs it. Secret values are hidden until the function runs, so they can't be read at deploy time.

**3. Write the function**

The handler receives a `UserRecord`, and it uses three fields off it: `uid`, `email`, and `displayName`.

```javascript functions/index.js lines theme={null}
const functions = require("firebase-functions/v1");
const Courier = require("@trycourier/courier");

exports.sendWelcome = functions
  .runWith({ secrets: ["COURIER_API_KEY"] })
  .auth.user()
  .onCreate(async (user) => {
    const { uid, email, displayName } = user;

    if (!email) return; // phone-only and anonymous signups have none

    const courier = new Courier({ apiKey: process.env.COURIER_API_KEY });

    // Firebase's uid becomes the Courier user id, so both systems agree.
    await courier.profiles.create(uid, {
      profile: { email, name: displayName },
    });

    await courier.send.message({
      message: {
        to: { user_id: uid },
        template: "nt_01kx4h2jdafq8bk9aftxak4b40",
        data: { name: displayName ?? "there" },
      },
    });
  });
```

The `runWith` call is what grants access to the secret, which then arrives on `process.env`. Importing from `firebase-functions/v1` explicitly keeps this working alongside 2nd-gen functions in the same file.

**Anonymous and phone-only signups have no `email`, and the trigger fires for both.** Returning early stops a crash on the first anonymous session.

**4. Deploy**

```bash theme={null}
firebase deploy --only functions:sendWelcome
```

## Verify

**1. Create a user**

Sign up through your app, or add one from **Authentication → Users** in the Firebase console.

**2. Read the function log**

```bash theme={null}
firebase functions:log --only sendWelcome
```

The trigger is asynchronous, so a failure appears here and nowhere else. It won't surface to the user.

**3. Confirm the send**

Open [Logs](https://app.courier.com/logs) in Courier and confirm the message.

## What the trigger covers

This trigger covers more sign-up routes than Auth0's equivalent.

| Sign-up route | Fires |
| :- | :- |
| Email and password | Yes |
| A federated provider, including Google, on first sign-in | Yes |
| Anonymous session | Yes, with no `email` |
| Created through the Admin SDK | Yes |
| A custom token | **No** |

The custom-token gap is the one to plan around. If you mint your own tokens for an existing identity system, this trigger never runs, and the profile write belongs wherever you create that user instead.


# Send a push from Firestore
Source: https://www.courier.com/docs/guides/notify-from-firestore

Turn a Firestore document write into a push that falls back to email.

A document lands in Firestore and someone should know. This guide sends a push, and an email instead when the push can't land.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["Firestore write"] --> B["Cloud Function"]
    B --> C{"Push delivers?"}
    C -->|Yes| D["Push arrives"]
    C -->|No| E["Email instead"]
```

## Prerequisites

* [A Courier Test API key](https://app.courier.com/~/test/platform/api-keys)
* [Push already working
  GUIDE](/docs/guides/set-up-mobile-push), with FCM connected and device tokens syncing
* A published [template
  DOC](/docs/design/templates/overview) with push and email content

## What this adds over calling FCM yourself

You already have Firebase, so calling FCM from the same function is one line shorter. Here's what the extra hop buys:

**You address a person, not a device.** FCM needs a registration token. Courier needs a `user_id`, and resolves the tokens itself, including the case where someone has three devices and one stale token.

**A failed push becomes an email.** FCM can tell you a token was rejected. It can't then reach the person another way. One `routing` line does.

**Preferences apply without a conditional.** If the recipient muted this notification type, Courier filters it. With raw FCM that check is code you write and maintain at every call site.

**One log covers both channels.** A push that failed and an email that succeeded are the same message in [Logs](https://app.courier.com/logs), not two systems to correlate.

If none of those matter for a given notification, call FCM directly. They usually start mattering around the second channel.

## Set it up

**1. Install and store the key**

In your functions directory:

```bash theme={null}
npm install firebase-functions @trycourier/courier
firebase functions:secrets:set COURIER_API_KEY
```

**2. Write the trigger**

This is a 2nd-gen Firestore trigger. The path carries a wildcard, and its value arrives on `event.params`.

```javascript functions/index.js lines theme={null}
const { onDocumentCreated } = require("firebase-functions/v2/firestore");
const Courier = require("@trycourier/courier");

exports.onNewComment = onDocumentCreated(
  { document: "documents/{docId}/comments/{commentId}", secrets: ["COURIER_API_KEY"] },
  async (event) => {
    const snapshot = event.data;
    if (!snapshot) return; // deleted before the function ran

    const comment = snapshot.data();
    const { docId } = event.params;

    const courier = new Courier({ apiKey: process.env.COURIER_API_KEY });

    await courier.send.message({
      message: {
        to: { user_id: comment.recipientId },
        template: "nt_01kx4h2jdafq8bk9aftxak4b40",
        // Try push. If it cannot land, send the email instead.
        routing: { method: "single", channels: ["push", "email"] },
        data: {
          author: comment.authorName,
          excerpt: comment.text.slice(0, 140),
          document_id: docId,
        },
      },
    });
  },
);
```

**`routing: { method: "single", channels: ["push", "email"] }`** walks the list and stops at the first channel that works. Push first, email as its failover. Swap to `all` and both go out every time.

**`if (!snapshot) return`** guards the case where the document is gone by the time the function runs. Firestore triggers aren't transactional with the write.

**3. Deploy**

```bash theme={null}
firebase deploy --only functions:onNewComment
```

## Verify

**1. Write a document**

Add a comment document under a path matching the trigger, from your app or the Firebase console.

**2. Check the function ran**

```bash theme={null}
firebase functions:log --only onNewComment
```

**3. Confirm which channel delivered**

Open [Logs](https://app.courier.com/logs). The timeline names the channel that delivered. To prove the fallback, remove the user's device tokens and write again. The same send should arrive by email.

## Adapt it for other writes

| Trigger | What to send |
| :- | :- |
| `onDocumentCreated` | The new thing happened. A comment, an order, an invite |
| `onDocumentUpdated` | Compare `event.data.before` to `event.data.after` and send only when something meaningful moved |
| `onDocumentDeleted` | A cancellation or removal confirmation |

The update case is the one to be careful with. A trigger on every write fires on fields nobody cares about, so compare before and after and return early. That is the difference between a useful alert and a reason to mute your app.

For fan-out, when many people are watching the document rather than one, address a list instead of a user. [Notify everyone watching
GUIDE](/docs/guides/notify-everyone-watching) covers that shape.


# Start a journey from Segment
Source: https://www.courier.com/docs/guides/notify-from-segment

Turn Segment track events into Courier journeys without writing send code.

Turn the events you already track into notifications, without writing any send code.

Connect Courier as a Segment destination and start a journey from a matching event. Segment forwards each event, its `userId` locates the recipient, and its `properties` become the journey's `data`.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["App event"] --> B["Segment"]
    B --> C["Courier destination"]
    C --> D{"Conditions pass?"}
    D -->|Yes| E["Journey sends"]
    D -->|No| F["No run"]
```

## Prerequisites

* A Segment workspace sending Track, Identify, or Group events
* [A Courier account](https://app.courier.com/signup)
* [A journey to run
  DOC](/docs/journeys/overview)

## Set it up

**1. Connect Courier as a Segment destination**

In Segment, add Courier as a destination and point it at your workspace. See the [Segment integration
DOC](/docs/integrations/cdp/segment) for the connection details.

**2. Create a journey with a Segment trigger**

In the console, [build a journey
DOC](/docs/journeys/build) and choose the **Segment** trigger. Select the source event (for example `Order Completed`). No schema is required. Courier receives whatever Segment sends.

**3. Narrow with conditions (optional)**

Add trigger conditions to run only for the events you want, for example `properties.total > 100`. Only events that pass all conditions start the journey.

**4. Design the flow and publish**

Add send nodes and any delays or branches, referencing the event data as variables, then publish. See [Journeys
DOC](/docs/journeys/overview) for the runtime model.

## Verify

**1. Fire the event**

Trigger the event in your app, or replay it from Segment, and confirm a run appears in the journey's **Logs** tab.

**2. Check the data came through**

Open the run and confirm the event's properties arrived as its `data`. A send node rendering empty variables usually means the property names differ from what the template expects.

**3. Confirm the message delivered**

Step through the run to the send node, then find the message in [Logs](https://app.courier.com/logs).

> [!NOTE]
>
> A Segment `track` event's `userId` must be a valid Courier user for the journey to run. Identify users to Courier first, or make sure the `userId` matches a stored profile.


# Send a dunning email from Stripe
Source: https://www.courier.com/docs/guides/notify-from-stripe

Turn Stripe's invoice.payment_failed webhook into an email that gets the card updated.

A card fails and the subscription lapses. This guide turns `invoice.payment_failed` into an email that gets the card updated.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["Payment fails"] --> B["Stripe webhook"]
    B --> C{"Signature valid?"}
    C -->|Yes| D["Find the user"]
    D --> E["Dunning email"]
    C -->|No| F["Reject"]
```

## Prerequisites

* [A Courier Test API key](https://app.courier.com/~/test/platform/api-keys)
* A Stripe account, and somewhere to host an HTTPS route
* A published [template
  DOC](/docs/design/templates/overview) for the dunning email

## Set it up

**1. Install the packages**

```bash theme={null}
npm install stripe @trycourier/courier
```

```bash .env.local theme={null}
COURIER_API_KEY=YOUR_COURIER_API_KEY
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
```

**2. Write the route handler**

Stripe signs the **raw bytes** of the request. Read the body as text and hand that exact string to `constructEvent`, because parsing it to JSON first changes it and verification fails.

```tsx app/api/stripe/route.ts lines theme={null}
import Stripe from "stripe";
import Courier from "@trycourier/courier";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const courier = new Courier({ apiKey: process.env.COURIER_API_KEY! });

export async function POST(request: Request) {
  // The raw string, not request.json(). Signature verification needs the
  // bytes exactly as Stripe sent them.
  const body = await request.text();
  const signature = request.headers.get("stripe-signature")!;

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!,
    );
  } catch {
    return new Response("Invalid signature", { status: 400 });
  }

  if (event.type !== "invoice.payment_failed") {
    return new Response("Ignored", { status: 200 });
  }

  const invoice = event.data.object as Stripe.Invoice;

  await courier.send.message({
    message: {
      to: { email: invoice.customer_email ?? undefined },
      template: "nt_01kx4h2jdafq8bk9aftxak4b40",
      data: {
        amount_due: (invoice.amount_due / 100).toFixed(2),
        currency: invoice.currency.toUpperCase(),
        update_url: invoice.hosted_invoice_url,
        attempt: invoice.attempt_count,
      },
    },
  });

  return new Response("OK", { status: 200 });
}
```

`hosted_invoice_url` is the field that makes this email work. It is a Stripe-hosted page where the customer pays or updates the card, so your template needs no billing UI of its own.

**3. Address the right recipient**

The snippet above sends to `invoice.customer_email`, which is the quickest path and needs no profile.

It also means Courier has no [profile
DOC](/docs/recipients/overview) to apply, so the recipient's [preferences
DOC](/docs/recipients/preferences/overview) and locale aren't considered. For a billing email that is often the point, since dunning is transactional and should reach people who muted marketing.

When you do want the profile, store your own user id on the Stripe customer and read it back:

```tsx app/api/stripe/route.ts theme={null}
// When you create the Stripe customer, stamp your own id on it.
await stripe.customers.create({
  email: user.email,
  metadata: { app_user_id: user.id },
});

// Then in the handler, resolve it and address the profile instead.
const customer = await stripe.customers.retrieve(invoice.customer as string);
const userId = !customer.deleted ? customer.metadata.app_user_id : undefined;

await courier.send.message({
  message: {
    to: userId ? { user_id: userId } : { email: invoice.customer_email ?? undefined },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { update_url: invoice.hosted_invoice_url },
  },
});
```

Stamping the id at customer-creation time is the part to get right. Retrofitting the mapping later means reconciling two systems that never agreed on an identifier.

**4. Point Stripe at the route**

In the Stripe Dashboard, open **Workbench → Webhooks**, create an event destination for your route's public URL, and subscribe it to **`invoice.payment_failed`**. Reveal the signing secret and copy it into `STRIPE_WEBHOOK_SECRET`.

Subscribe only to the events you handle. Stripe warns that listening to everything puts avoidable load on your endpoint.

## Verify

**1. Forward events to localhost**

```bash theme={null}
stripe listen --forward-to localhost:3000/api/stripe
```

The command prints a signing secret for this session. Use that one while testing.

**2. Trigger a failure**

```bash theme={null}
stripe trigger invoice.payment_failed
```

**3. Confirm the send**

Open [Logs](https://app.courier.com/logs). You should see one message with the amount and a `hosted_invoice_url` in its data.

If the route answers `400`, the body was modified before verification. That is the most common cause, and reading it with `request.text()` rather than `request.json()` fixes it.

## Make it reliable

Stripe retries a failed delivery for up to three days, so a handler that throws will be called again. Three habits keep that from causing damage.

**Return `2xx` before slow work.** Stripe times out a slow endpoint and counts it as failed. For anything heavier than a single send, acknowledge first and queue the work.

**Expect duplicates.** The same event can arrive more than once. Stripe's guidance is to record the `event.id` values you have processed and skip repeats. Courier's [idempotency key
DOC](/docs/reference/api-overview#idempotency) covers the other half, so pass `event.id` as the key and a replay can't send twice.

**Don't depend on ordering.** Stripe makes no ordering guarantee, so `invoice.payment_failed` may arrive before the event you expected to precede it.

## Adapt it for other events

| Stripe event | What to send |
| :- | :- |
| `invoice.payment_failed` | Dunning, with the hosted invoice link |
| `invoice.payment_succeeded` | A receipt, or a recovery confirmation |
| `customer.subscription.trial_will_end` | A trial-ending nudge, three days out |
| `customer.subscription.deleted` | A win-back, or an offboarding sequence |

The trial row pairs well with a [journey
DOC](/docs/journeys/overview). Stripe fires once, three days ahead, and the journey handles the follow-ups from there.


# Send a welcome email from Supabase
Source: https://www.courier.com/docs/guides/notify-from-supabase

Turn a Supabase Database Webhook on a new row into a welcome email, with a shared secret.

Supabase fires a Database Webhook when a row changes. Mirror new signups into a table and one becomes a welcome email.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["New row"] --> B["Database Webhook"]
    B --> C{"Secret matches?"}
    C -->|Yes| D["Create profile"]
    D --> E["Welcome email"]
    C -->|No| F["Reject"]
```

## Prerequisites

* [A Courier Test API key](https://app.courier.com/~/test/platform/api-keys)
* A Supabase project, and somewhere to host an HTTPS route
* A published [template
  DOC](/docs/design/templates/overview) to send

## Secure it with a shared secret

Supabase Database Webhooks are built on `pg_net`, and they **don't sign the payload**. Clerk uses Svix and Stripe signs the raw bytes, so both let you prove a request came from them. Supabase gives you custom HTTP headers instead.

That means the check is yours to add, and it isn't optional. Your route will sit on a public URL, and without a secret anyone who finds it can post a fake signup.

Generate a long random value, add it as a header on the webhook, and compare it in the handler with a constant-time comparison.

## Set it up

**1. Mirror new signups into a public table**

Point the webhook at a table in `public`, not at `auth.users` directly.

The `auth` schema belongs to the `supabase_auth_admin` role, which holds only the permissions it needs for authentication. A trigger firing there and reaching outside the schema hits `permission denied for schema auth`. Most Supabase apps already keep a `profiles` table for exactly this reason.

```sql theme={null}
create table public.profiles (
  id uuid primary key references auth.users on delete cascade,
  email text,
  full_name text
);

-- security definer runs as the function's owner, so it may write to public.
create function public.handle_new_user()
returns trigger
language plpgsql
security definer set search_path = ''
as $$
begin
  insert into public.profiles (id, email, full_name)
  values (new.id, new.email, new.raw_user_meta_data ->> 'full_name');
  return new;
end;
$$;

create trigger on_auth_user_created
  after insert on auth.users
  for each row execute function public.handle_new_user();
```

`security definer` is the load-bearing line. Without it the trigger runs as `supabase_auth_admin` and can't write to `public`.

**2. Create the webhook**

In the Supabase Dashboard, go to **Database → Webhooks** and create one:

* **Table**: `public.profiles`
* **Events**: `Insert`
* **Type**: HTTP Request, `POST`, pointing at your route
* **HTTP Headers**: add `x-webhook-secret` with your random value

Supabase sends this payload, whatever the table:

```json theme={null}
{
  "type": "INSERT",
  "table": "profiles",
  "schema": "public",
  "record": { "id": "…", "email": "…", "full_name": "…" },
  "old_record": null
}
```

`record` is the new row and `old_record` is the previous one, which is `null` on an insert.

**3. Write the route handler**

Compare the secret before doing anything else, and use `timingSafeEqual` rather than `===` so the comparison doesn't leak the value a character at a time.

```tsx app/api/supabase/route.ts lines theme={null}
import { timingSafeEqual } from "node:crypto";
import Courier from "@trycourier/courier";

const courier = new Courier({ apiKey: process.env.COURIER_API_KEY! });

function secretMatches(received: string | null) {
  const expected = process.env.SUPABASE_WEBHOOK_SECRET!;
  if (!received || received.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

export async function POST(request: Request) {
  if (!secretMatches(request.headers.get("x-webhook-secret"))) {
    return new Response("Unauthorized", { status: 401 });
  }

  const { type, table, record } = await request.json();

  if (type !== "INSERT" || table !== "profiles") {
    return new Response("Ignored", { status: 200 });
  }

  // Supabase's uuid becomes the Courier user id, so both systems agree.
  await courier.profiles.create(record.id, {
    profile: { email: record.email, name: record.full_name },
  });

  await courier.send.message({
    message: {
      to: { user_id: record.id },
      template: "nt_01kx4h2jdafq8bk9aftxak4b40",
      data: { name: record.full_name ?? "there" },
    },
  });

  return new Response("OK", { status: 200 });
}
```

The trigger already flattened `raw_user_meta_data` into a column, so the handler reads `record.full_name` rather than digging through the auth payload.

**4. Add the environment values**

```bash .env.local theme={null}
COURIER_API_KEY=YOUR_COURIER_API_KEY
SUPABASE_WEBHOOK_SECRET=the-same-random-value
```

## Verify

**1. Create a user**

Sign up through your app, or add a user from **Authentication → Users** in the Supabase Dashboard.

**2. Check the webhook ran**

Supabase records each delivery with its response code under the webhook in **Database → Webhooks**. A `401` means the secret doesn't match.

**3. Confirm the send**

Open [Logs](https://app.courier.com/logs) and confirm the message.

## Adapt it for your own tables

The payload shape is the same for every table in `public`. That makes the same handler useful well beyond signup.

| Table and event | What to send |
| :- | :- |
| `profiles` INSERT | Welcome |
| `orders` INSERT | Order confirmation |
| `orders` UPDATE | A shipping update, comparing `record` to `old_record` |
| `comments` INSERT | Notify everyone [watching&#xA;GUIDE](/docs/guides/notify-everyone-watching) the parent record |

`old_record` carries the previous values, so your handler decides whether a change is worth a notification. Firing on every update turns a useful alert into noise.


# Guides
Source: https://www.courier.com/docs/guides/overview

Step-by-step walkthroughs that end with a working send, inbox, journey, or migration.

Each guide takes one job from nothing to working.

[Docs
DOC](/docs/overview) explains how a piece of Courier behaves. A guide strings several pieces together. Every guide opens with what you need, walks numbered steps, and closes by verifying the result.

## Send your first message

> **[Email](/docs/guides/send-your-first-email)**
>
> Connect a provider, verify a domain, reach a real inbox.

> **[In-app](/docs/guides/send-your-first-in-app-message)**
>
> Ship the inbox, then send to the channel it renders.

> **[Mobile push](/docs/guides/set-up-mobile-push)**
>
> Connect FCM and APNs, sync device tokens, send custom data.

> **[SMS](/docs/guides/send-your-first-sms)**
>
> Connect a provider, add a number, deliver a text.

> **[Slack](/docs/guides/send-your-first-slack-message)**
>
> Install a Slack app, store its token, send a DM.

## Build a notification

> **[Personalize with variables](/docs/guides/personalize-a-message)**
>
> Fill one template with each recipient's own data.

> **[Onboarding sequence](/docs/guides/build-an-onboarding-sequence)**
>
> A multi-day welcome flow with delays and a branch.

> **[Daily digest](/docs/guides/send-a-daily-digest)**
>
> Roll a flood of events into one scheduled message.

> **[Send from AI](/docs/guides/send-from-an-ai-agent)**
>
> Let an agent send over the MCP server.

## Send to many people

> **[Send to a list](/docs/guides/announce-to-a-list)**
>
> One message to a saved List or Audience.

> **[Notify watchers](/docs/guides/notify-everyone-watching)**
>
> Reach everyone following a document, project, or ticket.

> **[Send in bulk](/docs/guides/send-in-bulk)**
>
> Thousands of recipients you supply yourself.

> **[Import users](/docs/guides/import-your-users)**
>
> Get profiles into Courier and keep them current.

## Send when something happens

> **[From Clerk](/docs/guides/notify-from-clerk)**
>
> Turn a sign-up into a profile and a welcome message.

> **[From Supabase](/docs/guides/notify-from-supabase)**
>
> Fire a send when a row lands in your database.

> **[From Firebase Auth](/docs/guides/notify-from-firebase-auth)**
>
> Send from a Cloud Function when a user is created.

> **[From Firestore](/docs/guides/notify-from-firestore)**
>
> Turn a document write into a push, with email fallback.

> **[From Stripe](/docs/guides/notify-from-stripe)**
>
> Turn a failed payment into an email that recovers it.

> **[From Auth0](/docs/guides/notify-from-auth0)**
>
> Call Courier from an Action, with no route to host.

> **[From Segment](/docs/guides/notify-from-segment)**
>
> Start a journey from an event you already track.

## Let users choose

> **[Preference center](/docs/guides/build-a-preference-center)**
>
> Let users choose what they receive, and where.

> **[Across tenants](/docs/guides/notify-across-tenants)**
>
> Give every customer org its own branding and defaults.

> **[Customer editing](/docs/guides/let-customers-edit-notifications)**
>
> Hand each customer an editor for their own emails.

## Go live

> **[Go live](/docs/guides/go-live)**
>
> Promote a change from Test to Production safely.

> **[Your sending domain](/docs/guides/send-from-your-domain)**
>
> Verify a domain, then set the address email comes from.

> **[Track delivery](/docs/guides/track-delivery)**
>
> Push Courier events into your own systems.

> **[Debug delivery](/docs/guides/debug-delivery)**
>
> Find why an email didn't arrive.

## Move to Courier

> **[Migrate to Courier](/docs/guides/migrate/overview)**
>
> Map your current concepts to Courier's, then move recipients, content, and sends.

> **[React v7 to v8+](/docs/sdk-libraries/courier-react-v8-migration-guide)**
>
> Move Inbox, Toast, and Preferences onto the v8+ component set.


# Personalize a message
Source: https://www.courier.com/docs/guides/personalize-a-message

Fill one template with each recipient's data using variables, and handle missing values.

Write one order-confirmation template, then let every send fill it with that customer's name, items, and total.

## Prerequisites

* [A Courier API key](https://app.courier.com/settings/api-keys)
* [A template with an email channel
  DOC](/docs/design/templates/overview)
* [A profile holding `first_name` and `timezone`
  DOC](/docs/recipients/overview)

## Personalize the message

**1. Write the template**

Put this in an email block in [Design Studio
DOC](/docs/design/templates/design-studio), or create the template in code with the [Templates API
DOC](/docs/design/templates/api):

```handlebars theme={null}
Hi {{default profile.first_name "there"}},

{{#each items}}
{{capitalize this.name}}: {{format "$%.2f" this.price}}
{{/each}}

Total: {{format "$%.2f" (add (default subtotal 0) (default tax 0))}}
{{#if placed_at}}Placed {{datetime-format placed_at "%b %d, %Y" profile.timezone}}{{/if}}
```

Four helpers are doing the work:

| Helper | What it handles |
| - | - |
| `default` | A new customer has no `first_name` yet, so this prints `there` instead of nothing |
| `each` | Walks the `items` array. Inside the loop, `this` is the current item |
| `format` | [sprintf](https://en.wikipedia.org/wiki/Printf). Use it for currency, with the `$` in the format string |
| `add` | Send the parts and let the template add them up, so a change is an edit and not a deploy. Wrap each one in `default`, because `add` on a missing value yields `NaN` and fails the send |

`datetime-format` takes the timestamp, a [strftime](https://en.wikipedia.org/wiki/C_date_and_time_functions#strftime) format, and a timezone. Passing `profile.timezone` means every customer reads the time in their own zone. Guard it with `#if` rather than `default`, since an empty string isn't a date either.

Anything prefixed with `profile.` comes from the stored profile. Everything else comes from `data` on the send.

**2. Send the data it fills in**

```javascript Node.js highlight={5-13} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: {
      placed_at: '2026-05-15T18:30:00Z',
      subtotal: 74.98,
      tax: 6.19,
      items: [
        { name: 'wireless mouse', price: 29.99 },
        { name: 'usb-c hub', price: 44.99 },
      ],
    },
  },
});
```

```python Python highlight={5-13} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "placed_at": "2026-05-15T18:30:00Z",
            "subtotal": 74.98,
            "tax": 6.19,
            "items": [
                {"name": "wireless mouse", "price": 29.99},
                {"name": "usb-c hub", "price": 44.99},
            ],
        },
    },
)
```

```bash cURL highlight={8-16} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "placed_at": "2026-05-15T18:30:00Z",
        "subtotal": 74.98,
        "tax": 6.19,
        "items": [
          { "name": "wireless mouse", "price": 29.99 },
          { "name": "usb-c hub", "price": 44.99 }
        ]
      }
    }
  }'
```

```ruby Ruby highlight={5-13} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      placed_at: "2026-05-15T18:30:00Z",
      subtotal: 74.98,
      tax: 6.19,
      items: [
        { name: "wireless mouse", price: 29.99 },
        { name: "usb-c hub", price: 44.99 }
      ]
    }
  }
)
```

```go Go highlight={9-17} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"placed_at": "2026-05-15T18:30:00Z",
			"subtotal":  74.98,
			"tax":       6.19,
			"items": []any{
				map[string]any{"name": "wireless mouse", "price": 29.99},
				map[string]any{"name": "usb-c hub", "price": 44.99},
			},
		},
	},
})
```

```java Java highlight={5-11} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "placed_at", "2026-05-15T18:30:00Z",
            "subtotal", 74.98,
            "tax", 6.19,
            "items", java.util.List.of(
                java.util.Map.of("name", "wireless mouse", "price", 29.99),
                java.util.Map.of("name", "usb-c hub", "price", 44.99)))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={5-13} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => [
      'placed_at' => '2026-05-15T18:30:00Z',
      'subtotal' => 74.98,
      'tax' => 6.19,
      'items' => [
        ['name' => 'wireless mouse', 'price' => 29.99],
        ['name' => 'usb-c hub', 'price' => 44.99],
      ],
    ],
  ],
);
```

```csharp C# highlight={7-18} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "placed_at", JsonSerializer.SerializeToElement("2026-05-15T18:30:00Z") },
            { "subtotal", JsonSerializer.SerializeToElement(74.98) },
            { "tax", JsonSerializer.SerializeToElement(6.19) },
            { "items", JsonSerializer.SerializeToElement(new[]
                {
                    new { name = "wireless mouse", price = 29.99 },
                    new { name = "usb-c hub", price = 44.99 },
                })
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40" \
  --message.data '{"placed_at": "2026-05-15T18:30:00Z", "subtotal": 74.98, "tax": 6.19, "items": [{"name": "wireless mouse", "price": 29.99}, {"name": "usb-c hub", "price": 44.99}]}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with a wireless mouse and a usb-c hub.
```

## Verify

**1. Read what arrived**

```text theme={null}
Hi Sarah,

Wireless mouse: $29.99
Usb-c hub: $44.99

Total: $81.17
Placed May 15, 2026
```

**2. Compare it against the data you sent**

Open [Logs](https://app.courier.com/logs), find the `requestId`, and read the rendered message next to the `data` that produced it.

> [!WARNING]
>
> Check the delivered message, not the designer's preview. The preview substitutes variables but doesn't run helpers, so `format` and `datetime-format` can look wrong there and render correctly when sent.

## Handle a missing value

A variable you only print is safe to omit: a missing single-brace variable renders as the literal `{tax}`, and a missing Handlebars `var` renders empty. The greeting's `default` helper turns that empty render into "there" instead of a blank name.

A variable a **helper computes with** isn't safe. Send the template above without `tax` and `add` produces `NaN`, `format` throws, and the whole message fails with `undefined is NaN`. The status is `UNDELIVERABLE`, and nothing is delivered on any channel. The send still returns `202` with a `requestId`, so the only place this surfaces is the message status.

Two helpers in this template need guarding, and they need different guards:

| Helper | Missing value | Guard |
| - | - | - |
| `add`, and any `format` fed by it | yields `NaN`, then throws | `default` to `0` |
| `datetime-format` | throws `Cannot read properties of undefined` | `#if` around the line |
| `each` | renders nothing, safe | none needed |

The total above applies that guard:

```handlebars theme={null}
Total: {{format "$%.2f" (add (default subtotal 0) (default tax 0))}}
```

To fail loudly on the printed kind too, turn on **Throw on variable not found** in the template's Advanced settings. It catches a single-brace `{tax}` left in the rendered output, not a `{{tax}}` that rendered empty, so the `default` above is still what protects you. [When a variable is missing
DOC](/docs/design/templates/variables#when-a-variable-is-missing) has the full behavior.

> [!TIP]
>
> Branch on what you know with `condition`, which takes its operator as a string: `{{#if (condition plan "==" "pro")}}Your Pro order ships free.{{/if}}`


# Send a daily digest
Source: https://www.courier.com/docs/guides/send-a-daily-digest

Collapse many notifications into one scheduled message with a topic digest.

Collapse a flood of individual notifications into one message a user will actually read.

Instead of ten emails about ten comments, a digest holds each event and delivers them together on the user's chosen schedule.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["Event fires"] --> B{"Digest schedule?"}
    B -->|Yes| C["Held as DIGESTED"]
    C -->|On schedule| D["One digest sent"]
    B -->|No| E["Sent now"]
```

## Prerequisites

* A subscription topic
* [A preference center
  GUIDE](/docs/guides/build-a-preference-center)
* The published templates that feed the digest
* [A Courier API key](https://app.courier.com/settings/api-keys)

## Pick a batching mechanism

| Mechanism | What it does | Use it when |
| - | - | - |
| **Topic digest schedules** | Individual sends to a topic are held and released as one digest on the user's chosen schedule. | Users should control frequency (daily, weekly, custom) per topic. |
| **Add to digest node** | A journey node adds the event to a subscription topic's digest, released on the topic's schedule. | You want to feed a digest from inside a journey. |
| **Batch node** | A journey node collects events at a point in the flow and releases them together by item count or a wait window. | You need a time-window or count-based batch, not a topic schedule. |

The rest of this guide sets up a **topic digest**, the most common path.

## What is set where

Every piece of a digest can be set over the API, so a backend can script the whole setup:

| Piece | Where it is set |
| - | - |
| Subscription topic, and the templates linked to it | API or console |
| Linked digest template, schedules, categories | API or console |
| The topic carried on a send | API |
| A user's subscription status and channel routing | API |
| A user's digest schedule | API, or the user in the preference center |

A topic's whole digest configuration is carried on the `digest` object of [Create Topic in Section](/docs/api-reference/preference-topics/create-topic-in-section) and its replace and read counterparts, so the setup below can be scripted end to end.

## Set up a topic digest

**1. Link the individual templates**

In the [preferences editor](https://app.courier.com/~/test/platform/preferences) (**Platform → Preferences**), open the subscription topic that should be digestable. Link the individual notification templates that feed it, for example `task-assigned` and `comment-added`. When a user is on a digest schedule for the topic, these sends are held instead of delivered, and the log shows them as `DIGESTED`.

**2. Design and link a digest template**

Build a template that renders the collected events, then set it as the topic's **Linked Digest Template**. Users on a digest schedule receive this template instead of the individual notifications. Removing the linked template disables digesting for the topic.

**3. Add schedules**

Add at least one schedule (see [Schedules](#schedules) below). Include an **Instant** option so users can opt out of digesting. Each schedule you add appears as a choice in the preference center.

**4. Group with categories (optional)**

Categories separate event types within one digest, such as tasks against comments. Each category's **retain** rule decides which events appear: first 10, last 10, or 10 highest or lowest by a `sort_key`.

## Bind the send to the topic

A send is only a digest candidate when it carries a subscription topic. Nothing is held without one, whatever the topic is configured to do.

Link the topic on the template, as `notification.subscription.topic_id` on [Create Notification Template](/docs/api-reference/templates/create-notification-template), and every send through that template inherits it. To set the topic on one send instead, pass it on the message:

```json theme={null}
{
  "message": {
    "preferences": { "subscription_topic_id": "pt_01kx4h2jdafq8bk9a26x0kvd1t" }
  }
}
```

## Which schedule a user is on

A user picks their schedule in the preference center, and that choice is what decides whether their sends are held. To set it from your backend, pass `digest_schedule_id` on [Update or create user Preferences for a Subscription Topic](/docs/api-reference/user-preferences/update-or-create-user-preferences-for-a-subscription-topic). The user's next send follows that schedule:

```json theme={null}
{
  "topic": { "status": "OPTED_IN", "digest_schedule_id": "sch_01m26nhsf7fzxr5kngwf8p0b2c" }
}
```

Leave `digest_schedule_id` out to keep the user's current choice, or send `null` to put them back on the topic default. An id that isn't a schedule on the topic returns `400`. Reads of the user's preferences return `digest_schedule_id` once they have one.

A user who has never picked a schedule isn't left out of digesting. They fall back to the topic's default schedule, or to the topic's first schedule when none is marked default.

That fallback is the usual reason a freshly scripted test never digests. Adding **Instant** as the default means every API-created user delivers immediately, and the log shows ordinary delivery rather than `DIGESTED`. To exercise the digest path, make a non-instant schedule the topic default, or put the test user on one with `digest_schedule_id` first.

## Verify

**1. Confirm sends are held**

Put a test user on a non-instant schedule for the topic, as described in [Which schedule a user is on
DOC](#which-schedule-a-user-is-on), and send an individual notification. Confirm the log shows it `DIGESTED` rather than delivered.

**2. Confirm the digest releases**

Wait for the schedule, or release it early with the [release call](#release-or-inspect-a-digest), and confirm the digest template delivers with the collected items.

**3. Confirm Instant still delivers immediately**

Switch the test user to the Instant schedule and send again. The message should deliver on its own instead of being held.

## Schedules

A schedule sets when digests release. Each entry in `digest.schedules` has a `frequency`: `instant`, `daily`, `weekdays`, `weekly`, `custom_days`, or `monthly`. Every frequency except `instant` needs a 24-hour `time`. `weekly` also needs `day_of_week`, `custom_days` needs `days_of_week`, and `monthly` needs `day_of_month`. For Tuesday and Thursday:

```json theme={null}
{
  "frequency": "custom_days",
  "days_of_week": ["tuesday", "thursday"],
  "time": "09:00",
  "timezone": "America/New_York",
  "is_default": true
}
```

Set `timezone` to an IANA zone on the schedule and Courier releases at that wall-clock time (DST aware). Without a `timezone`, the schedule time is read as UTC. The schedule timezone is the schedule's own, not each recipient's profile timezone.

A missing field or an unknown `frequency` returns `400` and leaves the topic's schedules as they were. Mark the schedule users start on with `is_default: true` rather than relying on its position.

A stored schedule that reads back with a `schedule_id` and no `frequency` doesn't fire. Replace it with one of the six frequencies above.

The `schedules` array replaces what is stored. Pass a schedule's `schedule_id` to keep it, and any schedule you leave out is deleted.

## How digested items reach the template

When a digest releases, Courier passes the collected events as the message data, keyed by category, so your template iterates them:

```json theme={null}
{
  "task_updates": {
    "count": 25,
    "items": [
      { "task_updates": { "task_title": "Review landing page copy", "assignee_name": "Sarah Bennett" } }
    ]
  }
}
```

Each item is the full `data` object from one send, so it repeats the category key: an item's title is `task_updates.task_title`, not `task_title`. Each category carries a `count` (the total) and its `items` (chosen by the retain rule, up to the category's `limit`, which defaults to 10 and can be set from 1 to 100). An event whose top-level `data` key matches no category isn't held. Courier delivers it immediately as an individual message. The `digest` key is used only when the topic has no categories.

Anything past the limit is discarded rather than carried into the next digest. A release consumes every event collected so far and renders only `limit` of them.

### Loop over the items

Iterate the items with a **list block** whose loop is set to the category path, not with a Handlebars `each` in a text block. Both render, but only the list block can be opened again in the template designer. A text block holding `{{#each}}` is drawn there as a row of broken variable chips, because the designer reads the loop keywords as variable names.

The loop path is evaluated as an expression against the message data, so it always starts with `data`, whatever the template's scope:

```json theme={null}
{
  "type": "list",
  "list_type": "unordered",
  "loop": "data.task_updates.items",
  "elements": [
    {
      "type": "list-item",
      "elements": [{ "type": "string", "content": "{{$.item.task_updates.task_title}} for {{$.item.task_updates.assignee_name}}" }]
    }
  ]
}
```

Inside the loop, each item is `$.item` and its position is `$.index`. Those are loop context, not data paths, so they are written the same way in every template.

The category total outside the loop is the one place the template's `scope` changes what you write:

| Template | Loop path | Total |
| - | - | - |
| `scope: "strict"` | `data.task_updates.items` | `{{data.task_updates.count}}` |
| default scope | `data.task_updates.items` | `{{task_updates.count}}` |

The wrong form renders as an empty string rather than an error. Set `scope: "strict"` on a digest template and use `data.` for both: one convention instead of two, matching how the rest of the template is written.

`count` is the number of events collected, which can be larger than the number of items you loop over. Items are capped by the category's `limit`, and the total still reports everything that arrived.

**Everything except `count` describes a single item.** A digest render has no slot for a value that belongs to the batch. So a fact that is identical on every event, such as a build number, still arrives once per item. That makes it tempting to read the first one with `data.task_updates.items.[0].task_updates.build` and print it outside the loop.

Read it inside the loop as `$.item.task_updates.build` instead. The `[0]` form reads only the first event, so the value drops out of the whole digest whenever that event lacks the field.

## Release or inspect a digest

Schedules are part of the topic's `digest` object, so they are created with the topic. You can also release a topic's digest early, release one user's digest, and list a schedule's instances. [Release a recipient's digest](/docs/api-reference/digests/release-a-recipients-digest) sends one user's held digest now, the quickest way to see what a digest renders. Pass their `user_id` in the body, plus `tenant_id` if they were sent to as part of a tenant. To release everyone on a schedule, [Release a digest early](/docs/api-reference/digests/release-a-digest-early) fires the digest now:

> [!NOTE]
>
> Schedule ids come back on the topic, as `digest.schedules[].schedule_id`, from the create, replace and single-topic read calls.
>
> Newer ids look like `sch_01m26nhsf7fzxr5kngwf8p0b2c` and drop straight into a URL. Ids created before that format look like `sch/{uuid}` and contain a literal slash, so those must be written as `%2F` in a raw URL. The SDKs escape either form for you. Existing ids are never migrated, so a topic can hold both.

```javascript Node.js theme={null}
await client.digests.schedules.release('sch_01m26nhsf7fzxr5kngwf8p0b2c');
```

```python Python theme={null}
client.digests.schedules.release(
    "sch_01m26nhsf7fzxr5kngwf8p0b2c",
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/digests/schedules/sch_01m26nhsf7fzxr5kngwf8p0b2c/trigger \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
result = courier.digests.schedules.release("sch_01m26nhsf7fzxr5kngwf8p0b2c")
```

```go Go theme={null}
err := client.Digests.Schedules.Release(context.TODO(), "sch_01m26nhsf7fzxr5kngwf8p0b2c")
```

```java Java theme={null}
client.digests().schedules().release("sch_01m26nhsf7fzxr5kngwf8p0b2c");
```

```php PHP theme={null}
$result = $client->digests->schedules->release('sch_01m26nhsf7fzxr5kngwf8p0b2c');
```

```csharp C# theme={null}
ScheduleReleaseParams parameters = new() { ScheduleID = "sch_01m26nhsf7fzxr5kngwf8p0b2c" };

await client.Digests.Schedules.Release(parameters);
```

```bash CLI theme={null}
courier digests:schedules release \
  --api-key "$COURIER_API_KEY" \
  --schedule-id sch_01m26nhsf7fzxr5kngwf8p0b2c
```

```text MCP theme={null}
With Courier MCP, release the queued digest for my daily schedule now.
```

[List digest instances](/docs/api-reference/digests/list-digest-instances) shows what is queued and released:

```javascript Node.js theme={null}
const digestInstanceListResponse = await client.digests.schedules.listInstances('sch_01m26nhsf7fzxr5kngwf8p0b2c');
```

```python Python theme={null}
digest_instance_list_response = client.digests.schedules.list_instances(
    schedule_id="sch_01m26nhsf7fzxr5kngwf8p0b2c",
)
```

```bash cURL theme={null}
curl -X GET https://api.courier.com/digests/schedules/sch_01m26nhsf7fzxr5kngwf8p0b2c/instances \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
digest_instance_list_response = courier.digests.schedules.list_instances("sch_01m26nhsf7fzxr5kngwf8p0b2c")
```

```go Go theme={null}
digestInstanceListResponse, err := client.Digests.Schedules.ListInstances(
	context.TODO(),
	"sch_01m26nhsf7fzxr5kngwf8p0b2c",
	courier.DigestScheduleListInstancesParams{},
)
```

```java Java theme={null}
DigestInstanceListResponse digestInstanceListResponse = client.digests().schedules().listInstances("sch_01m26nhsf7fzxr5kngwf8p0b2c");
```

```php PHP theme={null}
$digestInstanceListResponse = $client->digests->schedules->listInstances('sch_01m26nhsf7fzxr5kngwf8p0b2c');
```

```csharp C# theme={null}
ScheduleListInstancesParams parameters = new() { ScheduleID = "sch_01m26nhsf7fzxr5kngwf8p0b2c" };

var digestInstanceListResponse = await client.Digests.Schedules.ListInstances(parameters);
```

```bash CLI theme={null}
courier digests:schedules list-instances \
  --api-key "$COURIER_API_KEY" \
  --schedule-id sch_01m26nhsf7fzxr5kngwf8p0b2c
```

```text MCP theme={null}
With Courier MCP, list the digest instances queued on my daily schedule.
```


# Send from an AI agent
Source: https://www.courier.com/docs/guides/send-from-an-ai-agent

Let an AI agent send notifications through the Courier MCP server with a scoped API key.

Let an AI agent send notifications for you, deciding who to tell and when.

The agent calls `send_message_template` over the MCP server. The template holds the content, and Courier handles channel selection, failover, and delivery.

## What to use it for

* **Test a send while you build.** Fire a real notification from your editor, with no script to write and no console to open. It is the fastest way to watch a template render against real data.
* **Alert on your own work.** A deploy lands or a nightly job fails, and the agent tells whoever owns it.
* **Let the agent choose.** An agent triaging tickets or watching a queue decides who to notify, and when.
* **Send a one-off.** Reach one customer without building a screen for it.

> [!TIP]
>
> For testing, connect the agent with a **Test** environment key. Test's built-in email provider only delivers to the address you signed up with, so until you connect your own provider, an agent can't reach a real customer by mistake.

## Prerequisites

* An MCP-capable agent (Claude Code, Cursor, or Codex)
* [A Courier account](https://app.courier.com/signup)
* [A Courier API key](https://app.courier.com/settings/api-keys)
* [A user profile with contact info, or the inbox channel
  GUIDE](/docs/guides/import-your-users)
* [A published template
  DOC](/docs/design/templates/overview)

## Connect and send

**1. Connect the Courier MCP server**

Add the Courier MCP server to your agent with your environment API key. Connect once, and the agent can call every Courier tool.

```bash Claude Code theme={null}
claude mcp add --transport http courier https://mcp.courier.com --header api_key:YOUR_COURIER_API_KEY
```

```json Cursor theme={null}
{
  "mcpServers": {
    "courier": {
      "url": "https://mcp.courier.com",
      "headers": { "api_key": "YOUR_COURIER_API_KEY" }
    }
  }
}
```

```toml Codex theme={null}
[mcp_servers.courier]
url = "https://mcp.courier.com"
http_headers = { "api_key" = "YOUR_COURIER_API_KEY" }
```

See the [full list of tools and supported agents
DOC](/docs/resources/mcp).

**2. Ask the agent to send**

Prompt the agent in plain language. It calls `send_message_template` to do it:

```text theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 for build 1.4.2.
```

The agent resolves the recipient, looks up the template, and sends. The content stays in the template, so the agent decides *when* and *who* without composing the message.

Once providers are configured, ask for email or push. Courier picks the channel and fails over as needed.

## Verify

**1. Read back the requestId**

The agent returns a `requestId`. Open [Logs](https://app.courier.com/logs) and find that request.

**2. Confirm it delivered**

Expand the message timeline and confirm the provider accepted it.

**3. Try a second channel**

Ask the agent to send on another channel. A channel with no configured provider shows as `UNROUTABLE` and Courier skips it, so start with the inbox channel, which needs no setup.


# Send from your own domain
Source: https://www.courier.com/docs/guides/send-from-your-domain

Set the default from address, then override it for one template or one send.

Set the address your email comes from, then override it for one template or one send.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["Verify domain"] --> B["Integration default"]
    B --> C{"Different sender?"}
    C -->|Per template| D["Template From"]
    C -->|Per send| E["Send override"]
```

Set the integration default once. Reach for the other two only when a template or a single message needs a different sender.

## Prerequisites

* A domain you control, with access to its DNS records
* [A connected email provider
  DOC](/docs/integrations/email/overview)
* [The Courier integrations page](https://app.courier.com/integrations)

## Set the sender

**1. Verify the domain at your provider**

Courier doesn't verify domains. Your email provider does, and it enforces the result when the message goes out.

Add the DKIM and SPF records your provider asks for, then wait for it to mark the domain verified. [SendGrid's Sender Authentication](https://app.sendgrid.com/settings/sender_auth) and [Amazon SES verified identities](https://console.aws.amazon.com/ses/home#/verified-identities) are the two most common.

An unverified domain fails at the provider, not in Courier. The message lands in [Logs](https://app.courier.com/logs) as undeliverable with the provider's error attached.

**2. Set the From Address on the integration**

Open your provider in [Integrations](https://app.courier.com/integrations) and set **From Address** to an address on the verified domain. Every email through that provider uses it unless something below overrides it.

Some providers also have a **From Name** field. Where there is none, put the display name in the address itself.

```text theme={null}
Acme Support <support@acme-corp.com>
```

## Override it for one template

Open the template's email channel and fill **From** in the subject bar. It takes the same `Name <email>` form, and it accepts [variables
DOC](/docs/design/templates/variables), so one template can send as a different address per message.

Reply-To, CC, and BCC sit beside it. [Channel overrides
DOC](/docs/send/overrides) covers all four.

## Override it for one send

A [Send a message](/docs/api-reference/send/send-a-message) request carries `message.channels.email.override.from`, which replaces the sender for that message alone, whichever email provider ends up sending it.

```javascript Node.js highlight={9-11} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    channels: {
      email: {
        override: {
          from: "Acme Support <support@acme-corp.com>",
        },
      },
    },
  },
});
```

```python Python highlight={9-11} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "channels": {
            "email": {
                "override": {
                    "from": "Acme Support <support@acme-corp.com>",
                },
            },
        },
    },
)
```

```bash cURL highlight={12-14} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "channels": {
        "email": {
          "override": {
            "from": "Acme Support <support@acme-corp.com>"
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={9-11} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    channels: {
      email: {
        override: {
          from: "Acme Support <support@acme-corp.com>"
        }
      }
    }
  }
)
```

```go Go highlight={11-13} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Channels: shared.MessageChannelsParam{
			"email": shared.ChannelParam{
				Override: map[string]any{
					"from": "Acme Support <support@acme-corp.com>",
				},
			},
		},
	},
})
```

```java Java highlight={7-8} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .channels(MessageChannels.builder()
            .putAdditionalProperty("email", JsonValue.from(
                java.util.Map.of("override", java.util.Map.of(
                    "from", "Acme Support <support@acme-corp.com>"))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-11} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'channels' => [
      'email' => [
        'override' => [
          'from' => 'Acme Support <support@acme-corp.com>',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={13-16} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Channels = new Dictionary<string, Channel>
        {
            {
                "email",
                new Channel
                {
                    Override = new Dictionary<string, JsonElement>()
                    {
                        { "from", JsonSerializer.SerializeToElement("Acme Support <support@acme-corp.com>") },
                    },
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.channels '{"email": {"override": {"from": "Acme Support <support@acme-corp.com>"}}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 from Acme Support <support@acme-corp.com>.
```

## How the levels resolve

Every email provider resolves the sender the same way, taking the first one set:

| Order | Where it comes from | Scope |
| - | - | - |
| 1 | `message.channels.email.override.from` | One message |
| 2 | The template's email **From** field | Every send of that template |
| 3 | **From Address** on the provider integration | Every email through that provider |

If none of the three is set, the send fails with an error. Courier doesn't fall back to a default address.

A few providers also accept a sender inside a provider override, such as `message.providers.postmark.override.config.fromAddress`. That form is provider-specific, and where it sits in the order above varies by provider, so check the provider's page before relying on it.

## Verify

Send a test, open the message in [Logs](https://app.courier.com/logs), and read the **Raw** tab. It shows the request Courier made to the provider, which is the only place the final sender appears. Courier applies overrides after rendering, so the Rendered tab shows the pre-override value.

## FAQ

> **Why is my template's From field ignored on Gmail?**
>
> Gmail sends as the authorized inbox, so the From address is always the connected Google account. A template From field has no effect there. Set the display name with the integration's **From Name**, and change the address by authorizing a different inbox.

> **My provider has no From Name field. How do I set a display name?**
>
> Put it in the address: `Acme Support <support@acme-corp.com>`. Most email providers have no separate name field, so this form is how you set a display name.

> **Can a brand control the sender?**
>
> [Brands
> DOC](/docs/design/brands) carry visual styling only, with no sender field of any kind. The sending address is provider and template configuration.

> **Is a branded tracking domain the same thing?**
>
> Link and open tracking uses a separate CNAME to Courier's tracking infrastructure, set up independently of your sending domain. See [tracking
> DOC](/docs/monitor/tracking#custom-tracking-domain).


# Send in bulk
Source: https://www.courier.com/docs/guides/send-in-bulk

Send to thousands of recipients you supply with a bulk job you can review before it runs.

Send one notification to thousands of recipients you supply yourself, with a job you can abandon before anything goes out.

Looping over Send API calls has no undo. A bulk job does. You build it across as many ingestion calls as you need, and nothing sends until you run it. An ingestion that fails halfway has delivered nothing, so abandon that job and build a fresh one.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["Create the job"] --> B["Ingest recipients"]
    B --> C{"Everyone in?"}
    C -->|Yes| D["Run the job"]
    D --> E["Poll for progress"]
    C -->|No| B
```

## Prerequisites

* [A published template, or an event ID mapped to one
  DOC](/docs/design/templates/overview)
* Your deduplicated recipient list, with an email or phone for each
* [A Courier API key](https://app.courier.com/settings/api-keys)

## Run a bulk job

**Create** the job with the notification and any shared data, **ingest** recipients into it, then **run** it once and poll for progress. Ingestion is open-ended and the job doesn't expire while you fill it. Running is a one-way door.

**1. Create the job**

[Create a bulk job](/docs/api-reference/bulk/create-a-bulk-job) defines the job with an `event` and any global data that applies to everyone. The required `event` is either a [notification ID
DOC](/docs/design/templates/overview) or a custom event ID mapped to a notification.

```javascript Node.js highlight={3} theme={null}
const { jobId } = await client.bulk.createJob({
  message: {
    event: 'welcome-email',
    data: { company_name: 'Acme Corp' },
  },
});
```

```python Python highlight={3} theme={null}
response = client.bulk.create_job(
    message={
        "event": "welcome-email",
        "data": {"company_name": "Acme Corp"},
    }
)
```

```bash cURL highlight={6} theme={null}
curl -X POST https://api.courier.com/bulk \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "event": "welcome-email",
      "data": { "company_name": "Acme Corp" }
    }
  }'
```

```ruby Ruby highlight={2} theme={null}
response = courier.bulk.create_job(
  message: { event: "welcome-email", data: { company_name: "Acme Corp" } }
)
```

```go Go highlight={3} theme={null}
response, err := client.Bulk.NewJob(context.TODO(), courier.BulkNewJobParams{
	Message: courier.InboundBulkMessageParam{
		Event: "welcome-email",
		Data: map[string]any{
			"company_name": "Acme Corp",
		},
	},
})
```

```java Java highlight={3} theme={null}
BulkCreateJobParams params = BulkCreateJobParams.builder()
    .message(InboundBulkMessage.builder()
        .event("welcome-email")
        .data(InboundBulkMessage.Data.builder()
            .putAdditionalProperty("company_name", JsonValue.from("Acme Corp"))
            .build())
        .build())
    .build();
BulkCreateJobResponse response = client.bulk().createJob(params);
```

```php PHP highlight={3} theme={null}
$response = $client->bulk->createJob(
  message: [
    'event' => 'welcome-email',
    'data' => ['company_name' => 'Acme Corp'],
  ],
);
```

```csharp C# highlight={5} theme={null}
BulkCreateJobParams parameters = new()
{
    Message = new()
    {
        Event = "welcome-email",
        Data = new Dictionary<string, JsonElement>()
        {
            { "company_name", JsonSerializer.SerializeToElement("Acme Corp") }
        },
    },
};

var response = await client.Bulk.CreateJob(parameters);
```

```bash CLI highlight={3} theme={null}
courier bulk create-job \
  --api-key "$COURIER_API_KEY" \
  --message '{"event":"welcome-email","data":{"company_name":"Acme Corp"}}'
```

```text MCP theme={null}
With Courier MCP, create a bulk job for my welcome-email event with Acme Corp as global data.
```

Returns `201 Created` with the job ID you use for every call that follows:

```json theme={null}
{ "jobId": "1-61e9dd53-b5bb6c863b7ffbe83ad4b28d" }
```

You can also pass `brand`, `locale`, and `override`. To send something other than the notification attached to the event, add `template`. `event` stays required.

> [!TIP]
>
> **Make a retry safe.**\\
>
> Send an `Idempotency-Key` header and a retry replays the original result. A repeated create returns the first `jobId` instead of opening a second job.

**2. Ingest your recipients**

[Add users](/docs/api-reference/bulk/add-users) adds recipients to the job. Identify each one in `to`, and put their personal variables in `data`, which merges into the job's global `message.data`.

```javascript Node.js highlight={6,11} theme={null}
await client.bulk.addUsers('JOB_ID', {
  users: [
    {
      to: { user_id: 'user_123' },
      profile: { email: 'sarah@acme-corp.com' },
      data: { name: 'Sarah Bennett' },
    },
    {
      to: { user_id: 'user_456' },
      profile: { email: 'kai@acme-corp.com' },
      data: { name: 'Kai Turner' },
    },
  ],
});
```

```python Python highlight={7,12} theme={null}
client.bulk.add_users(
    job_id="JOB_ID",
    users=[
        {
            "to": {"user_id": "user_123"},
            "profile": {"email": "sarah@acme-corp.com"},
            "data": {"name": "Sarah Bennett"},
        },
        {
            "to": {"user_id": "user_456"},
            "profile": {"email": "kai@acme-corp.com"},
            "data": {"name": "Kai Turner"},
        },
    ],
)
```

```bash cURL highlight={9,14} theme={null}
curl -X POST https://api.courier.com/bulk/JOB_ID \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "to": { "user_id": "user_123" },
        "profile": { "email": "sarah@acme-corp.com" },
        "data": { "name": "Sarah Bennett" }
      },
      {
        "to": { "user_id": "user_456" },
        "profile": { "email": "kai@acme-corp.com" },
        "data": { "name": "Kai Turner" }
      }
    ]
  }'
```

```ruby Ruby highlight={6,9} theme={null}
result = courier.bulk.add_users(
  "JOB_ID",
  users: [
    { to: { user_id: "user_123" },
      profile: { email: "sarah@acme-corp.com" },
      data: { name: "Sarah Bennett" } },
    { to: { user_id: "user_456" },
      profile: { email: "kai@acme-corp.com" },
      data: { name: "Kai Turner" } },
  ]
)
```

```go Go highlight={8,12} theme={null}
err := client.Bulk.AddUsers(
	context.TODO(),
	"JOB_ID",
	courier.BulkAddUsersParams{
		Users: []courier.InboundBulkMessageUserParam{{
			To:      shared.UserRecipientParam{UserID: courier.String("user_123")},
			Profile: map[string]any{"email": "sarah@acme-corp.com"},
			Data:    map[string]any{"name": "Sarah Bennett"},
		}, {
			To:      shared.UserRecipientParam{UserID: courier.String("user_456")},
			Profile: map[string]any{"email": "kai@acme-corp.com"},
			Data:    map[string]any{"name": "Kai Turner"},
		}},
	},
)
```

```java Java highlight={8,15} theme={null}
BulkAddUsersParams params = BulkAddUsersParams.builder()
    .jobId("JOB_ID")
    .addUser(InboundBulkMessageUser.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .profile(InboundBulkMessageUser.Profile.builder()
            .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
            .build())
        .data(JsonValue.from(Map.of("name", "Sarah Bennett")))
        .build())
    .addUser(InboundBulkMessageUser.builder()
        .to(UserRecipient.builder().userId("user_456").build())
        .profile(InboundBulkMessageUser.Profile.builder()
            .putAdditionalProperty("email", JsonValue.from("kai@acme-corp.com"))
            .build())
        .data(JsonValue.from(Map.of("name", "Kai Turner")))
        .build())
    .build();
client.bulk().addUsers(params);
```

```php PHP highlight={7,12} theme={null}
$result = $client->bulk->addUsers(
  'JOB_ID',
  users: [
    [
      'to' => ['userID' => 'user_123'],
      'profile' => ['email' => 'sarah@acme-corp.com'],
      'data' => ['name' => 'Sarah Bennett'],
    ],
    [
      'to' => ['userID' => 'user_456'],
      'profile' => ['email' => 'kai@acme-corp.com'],
      'data' => ['name' => 'Kai Turner'],
    ],
  ],
);
```

```csharp C# highlight={13,22} theme={null}
BulkAddUsersParams parameters = new()
{
    JobID = "JOB_ID",
    Users =
    [
        new()
        {
            To = new() { UserID = "user_123" },
            Profile = new Dictionary<string, JsonElement>()
            {
                { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") }
            },
            Data = JsonSerializer.SerializeToElement(new { name = "Sarah Bennett" }),
        },
        new()
        {
            To = new() { UserID = "user_456" },
            Profile = new Dictionary<string, JsonElement>()
            {
                { "email", JsonSerializer.SerializeToElement("kai@acme-corp.com") }
            },
            Data = JsonSerializer.SerializeToElement(new { name = "Kai Turner" }),
        },
    ],
};

await client.Bulk.AddUsers(parameters);
```

```bash CLI highlight={4-5} theme={null}
courier bulk add-users \
  --api-key "$COURIER_API_KEY" \
  --job-id JOB_ID \
  --user '{"to":{"user_id":"user_123"},"profile":{"email":"sarah@acme-corp.com"},"data":{"name":"Sarah Bennett"}}' \
  --user '{"to":{"user_id":"user_456"},"profile":{"email":"kai@acme-corp.com"},"data":{"name":"Kai Turner"}}'
```

```text MCP theme={null}
With Courier MCP, add these recipients to my bulk job, each with their own name variable.
```

Returns `200 OK`, where `total` is the running count for the whole job rather than the current call:

```json theme={null}
{
  "errors": [],
  "total": 2
}
```

> [!NOTE]
>
> **Provider routing reads `profile.email`, not `to.email`.**\\
>
> Put each recipient's address in `profile.email` so the job delivers to it.

Each recipient accepts four fields:

* `to.user_id`, who they are
* `profile`, inline contact data
* `data`, per-recipient variables
* `preferences`, per-recipient overrides

Call this endpoint as often as you need, keeping each batch to around 1000 recipients. Larger batches can fail with a `502` instead of a validation error, so split big lists across several calls.

> [!WARNING]
>
> **Ingestion doesn't deduplicate.**\\
>
> The same `user_id` ingested twice becomes two messages, so deduplicate your list before you ingest it.

**3. Run the job**

Once everyone is in, [Run a job](/docs/api-reference/bulk/run-a-job) triggers the send. Courier fans out and delivers to each recipient.

```javascript Node.js theme={null}
await client.bulk.runJob('JOB_ID');
```

```python Python theme={null}
client.bulk.run_job(job_id="JOB_ID")
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/bulk/JOB_ID/run \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
courier.bulk.run_job("JOB_ID")
```

```go Go theme={null}
err := client.Bulk.RunJob(context.TODO(), "JOB_ID")
```

```java Java theme={null}
client.bulk().runJob("JOB_ID");
```

```php PHP theme={null}
$client->bulk->runJob('JOB_ID');
```

```csharp C# theme={null}
await client.Bulk.RunJob(new BulkRunJobParams { JobID = "JOB_ID" });
```

```bash CLI theme={null}
courier bulk run-job \
  --api-key "$COURIER_API_KEY" \
  --job-id JOB_ID
```

```text MCP theme={null}
With Courier MCP, run my bulk job.
```

Returns `202 Accepted` with an empty body, and the job starts processing in the background.

> [!NOTE]
>
> **A job runs once.**\\
>
> Running it again returns `400 BulkJobDuplicateInvocationError`. To reach more recipients, create a new job.

**4. Track progress**

[Get a job](/docs/api-reference/bulk/get-a-job) returns the job's counts and overall status.

```javascript Node.js theme={null}
const { job } = await client.bulk.retrieveJob('JOB_ID');

console.log(job.status, `${job.enqueued}/${job.received} enqueued`);
```

```python Python theme={null}
response = client.bulk.retrieve_job(job_id="JOB_ID")

print(response.job.status, response.job.enqueued, response.job.received)
```

```bash cURL theme={null}
curl https://api.courier.com/bulk/JOB_ID \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
response = courier.bulk.retrieve_job("JOB_ID")

puts(response.job.status, response.job.enqueued, response.job.received)
```

```go Go theme={null}
response, err := client.Bulk.GetJob(context.TODO(), "JOB_ID")
if err != nil {
	panic(err.Error())
}

fmt.Printf("%+v\n", response.Job)
```

```java Java theme={null}
BulkRetrieveJobResponse response = client.bulk().retrieveJob("JOB_ID");
```

```php PHP theme={null}
$response = $client->bulk->retrieveJob('JOB_ID');

var_dump($response);
```

```csharp C# theme={null}
var response = await client.Bulk.RetrieveJob(new BulkRetrieveJobParams { JobID = "JOB_ID" });

Console.WriteLine(response);
```

```bash CLI theme={null}
courier bulk retrieve-job \
  --api-key "$COURIER_API_KEY" \
  --job-id JOB_ID
```

```text MCP theme={null}
With Courier MCP, show me the status and counts for my bulk job.
```

```json theme={null}
{
  "job": {
    "definition": {
      "event": "welcome-email"
    },
    "enqueued": 2,
    "failures": 0,
    "received": 2,
    "status": "COMPLETED"
  }
}
```

* `received`: recipients ingested.
* `enqueued`: messages that reached the delivery pipeline.
* `failures`: errors hit while processing.
* `status`: `CREATED`, `PROCESSING`, `COMPLETED`, or `ERROR`.

> [!NOTE]
>
> **`COMPLETED` and `ERROR` are both terminal.**\\
>
> Stop polling on either one. A job that ends in `ERROR` stays there.

## Verify

**1. Confirm the counts line up**

Poll the job until it reaches `COMPLETED`, then check that `enqueued` matches `received` and `failures` is zero.

**2. Spot-check a recipient**

Page through the job's users with `client.bulk.listUsers`. Leave `cursor` off the first request, then keep passing `paging.cursor` back while `paging.more` is `true`. Each entry carries a `recipient`, a `status` of `PENDING`, `ENQUEUED`, or `ERROR`, and a `messageId` once enqueued.

**3. Trace one message end to end**

A `messageId` is the same ID a regular send returns, so look one up in [message logs
DOC](/docs/monitor/overview) and confirm it delivered.

To skip polling, [track delivery
GUIDE](/docs/guides/track-delivery) with an outbound webhook and handle `message:updated`, which fires on every status change for every message the job produced.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Job completes, no email arrives | Address was in `to.email` | Move it to `profile.email` |
| `400 The 'event' parameter is required` | Create body has no `event` | Add a notification ID or event ID |
| `400 BulkJobDuplicateInvocationError` | Job already ran | Create a new job for more recipients |
| `502` on ingest | Batch too large | Send around 1000 recipients per call |
| Status doesn't reach `COMPLETED` | Job ended in `ERROR` | Treat `ERROR` as terminal too |
| Someone got the same notification twice | Ingested twice | Deduplicate before ingesting |


# Send your first email
Source: https://www.courier.com/docs/guides/send-your-first-email

Connect an email provider and your own domain, then send a real email and verify it.

Every workspace can email you on day one. Reaching anyone else takes your own provider and your own domain.

> [!NOTE]
>
> Only need to prove the API works? The [quickstart
> DOC](/docs/get-started/send-a-message) sends an email in one call with no provider setup, reaching your signup address only.

## Prerequisites

* [A Courier Test API key](https://app.courier.com/~/test/platform/api-keys)
* An account with an email provider, such as [SendGrid](https://sendgrid.com/), [Postmark](https://postmarkapp.com/), or [Resend](https://resend.com/)
* A domain you can add DNS records to

## Send it

**1. Connect your own provider**

Add your provider from [Integrations](https://app.courier.com/integrations/catalog) and paste its API key. [Email providers
DOC](/docs/integrations/email/overview) lists every one, and each page carries that provider's credential fields.

Integrations are per environment, so connect it in the same environment your API key belongs to. A provider added in Production does nothing for a Test key.

> [!NOTE]
>
> The **Courier Test Email Provider** stays connected alongside yours. Once you add your own, [channel priority
> DOC](/docs/send/routing#channel-priority) decides which one sends, so set yours first.

**2. Verify your sending domain**

Your provider has to prove it may send as you. That means DKIM and SPF records on your domain, added at your DNS host and verified in the provider's dashboard.

Skipping this is the single biggest cause of mail landing in spam. An unauthenticated message from a domain that publishes no policy is exactly what a receiving server is built to distrust.

[Send from your own domain
GUIDE](/docs/guides/send-from-your-domain) walks the records and setting the From address.

**3. Put an email address on the profile**

Email addresses a recipient by `email`. Nothing else is required.

```javascript Node.js highlight={2} theme={null}
await client.profiles.create("user_123", {
  profile: { email: "sarah@acme-corp.com" },
});
```

```python Python highlight={3} theme={null}
client.profiles.create(
    "user_123",
    profile={"email": "sarah@acme-corp.com"},
)
```

```bash cURL highlight={4} theme={null}
curl -X POST https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile": { "email": "sarah@acme-corp.com" } }'
```

```ruby Ruby highlight={3} theme={null}
courier.profiles.create(
  "user_123",
  profile: {email: "sarah@acme-corp.com"}
)
```

```go Go highlight={2} theme={null}
_, err := client.Profiles.New(context.TODO(), "user_123", courier.ProfileNewParams{
	Profile: map[string]any{"email": "sarah@acme-corp.com"},
})
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .build())
    .build();

client.profiles().create(params);
```

```php PHP highlight={3} theme={null}
$client->profiles->create(
  'user_123',
  profile: ['email' => 'sarah@acme-corp.com'],
);
```

```csharp C# highlight={7} theme={null}
await client.Profiles.Create(
    "user_123",
    new()
    {
        Profile = new Dictionary<string, JsonElement>
        {
            { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
        },
    }
);
```

```bash CLI highlight={3} theme={null}
courier profiles create user_123 \
  --api-key "$COURIER_API_KEY" \
  --profile '{"email": "sarah@acme-corp.com"}'
```

```text MCP theme={null}
With Courier MCP, set the email sarah@acme-corp.com on user_123.
```

Addressing a profile rather than an address is what lets [preferences
DOC](/docs/recipients/preferences/overview) apply and what keeps one send working when the person changes their address. [Users
DOC](/docs/recipients/overview#what-each-channel-needs) covers the field every other channel reads.

**4. Send the email**

Route to `email` and Courier picks the provider you connected.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    routing: { method: "single", channels: ["email"] },
    content: { title: "Your order shipped", body: "It should arrive Thursday." },
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "routing": {"method": "single", "channels": ["email"]},
        "content": {"title": "Your order shipped", "body": "It should arrive Thursday."},
    },
)
```

```bash cURL highlight={7} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "routing": { "method": "single", "channels": ["email"] },
      "content": { "title": "Your order shipped", "body": "It should arrive Thursday." }
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {user_id: "user_123"},
    routing: {method: "single", channels: ["email"]},
    content: {title: "Your order shipped", body: "It should arrive Thursday."}
  }
)
```

```go Go highlight={8} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("email")}},
		},
		Content: courier.SendMessageParamsMessageContentUnion{
			OfElementalContentSugar: &shared.ElementalContentSugarParam{
				Title: "Your order shipped",
				Body:  "It should arrive Thursday.",
			},
		},
	},
})
```

```java Java highlight={6} theme={null}
SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("email")))
        .build())
    .content(ElementalContentSugar.builder()
        .title("Your order shipped")
        .body("It should arrive Thursday.")
        .build())
    .build();

client.send().message(SendMessageParams.builder().message(message).build());
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'routing' => ['method' => 'single', 'channels' => ['email']],
    'content' => ['title' => 'Your order shipped', 'body' => 'It should arrive Thursday.'],
  ],
);
```

```csharp C# highlight={6} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Routing = new() { Method = "single", Channels = ["email"] },
        Content = new ElementalContentSugar
        {
            Title = "Your order shipped",
            Body = "It should arrive Thursday.",
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.routing '{"method": "single", "channels": ["email"]}' \
  --message.content '{"title": "Your order shipped", "body": "It should arrive Thursday."}'
```

```text MCP theme={null}
With Courier MCP, email user_123 to say their order shipped.
```

Email uses `title` as the subject line and `body` as the message, so both do work here. SMS ignores the title, which is why the same shorthand carries them together.

## Verify

**1. Check your email**

The message arrives from the address you set on the integration.

**2. Read the status**

Open [Logs](https://app.courier.com/logs). `SENT` means your provider accepted it. `DELIVERED` means the recipient's mail server did.

**3. Confirm it came from your provider**

Open the message and check the provider on the send event. If it says Courier Test Email Provider, channel priority is still preferring it over yours.

`DELIVERED` with nothing in your mail client usually means spam or a corporate gateway rather than a failed send. [Debug delivery
GUIDE](/docs/guides/debug-delivery) works that case from Logs outward.

## What changes in production

**A bounce isn't a retry.** An `UNDELIVERABLE` message with a `BOUNCED` reason means the provider rejected the recipient, and Courier doesn't try again. A hard bounce means the address doesn't exist.

**Suppression lists belong to the provider, not to Courier.** After a bounce or complaint, most providers stop accepting that address. Nothing you send reaches it until you remove it there.

**Add a backup provider.** Two email providers on the channel means an outage at one fails over rather than failing. [Routing and failover
DOC](/docs/send/routing#failover) covers the order.

**Unsubscribes belong in preferences.** An `UNSUBSCRIBED` or `OPT_IN_REQUIRED` reason means [preferences
DOC](/docs/recipients/preferences/overview) stopped the send, which is the system working. Wire your provider's unsubscribe webhook to them rather than keeping a second list.


# Send your first in-app message
Source: https://www.courier.com/docs/guides/send-your-first-in-app-message

Add the Courier Inbox to your app, then send a message to the inbox channel.

In-app is a channel like email or SMS. The difference is that the message shows up inside your app, so you build the UI first.

That UI runs on eight platforms, so it has a tab of its own. Everything below lives in [In-App
DOC](/docs/in-app/overview).

## Add it to your app

> **[Add an inbox](/docs/in-app/add-an-inbox)**
>
> Put the notification center in your app.

> **[Sign users in](/docs/in-app/authenticate-users)**
>
> Your backend gives the SDK a token. Start here.

> **[Add an inbox to Next.js](/docs/guides/add-an-inbox-to-nextjs)**
>
> Every step, written for the App Router.

> **[Pick your platform](/docs/in-app/overview)**
>
> React, Vue, Angular, iOS, Android, Flutter, and more.

## Then send a message

> **[Send to the inbox](/docs/in-app/send-to-the-inbox)**
>
> The send call, in every language.

> **[How the inbox behaves](/docs/in-app/how-the-inbox-behaves)**
>
> Live updates, and how long a message stays.

## Add more to your app

> **[Add toasts](/docs/in-app/add-toasts)**
>
> Pop a message up the moment it arrives.

> **[Add a preference center](/docs/in-app/add-a-preference-center)**
>
> Let users choose what they get.

[A Test key](https://app.courier.com/~/test/platform/api-keys) is enough for all of it. The inbox works in Test with no provider connected. Email is the only other channel that does.


# Send your first Slack message
Source: https://www.courier.com/docs/guides/send-your-first-slack-message

Create a Slack app, store its token on the recipient's profile, and send a direct message.

Slack needs one thing the other channels don't: an app you create, installed into the workspace you want to post in.

Once its bot token is on a profile, a Slack message is the same send as an email.

## Prerequisites

* [A Courier Test API key](https://app.courier.com/~/test/platform/api-keys)
* A Slack workspace you can install an app into
* A published [template
  DOC](/docs/design/templates/overview) with a Slack channel

## The token belongs to the recipient

Most providers hold one credential on the integration. Slack passes its bot token **with each recipient**, on `to.slack.access_token`. Install the Slack integration once, then store a token per user or per customer.

One Courier workspace can post into many customers' Slack workspaces this way, because each recipient carries the token for the workspace it belongs to.

## Send it

**1. Install the integration and create a Slack app**

Add **Slack** from [Integrations](https://app.courier.com/integrations/catalog) in Courier.

Then create the app on Slack's side. At [api.slack.com/apps](https://api.slack.com/apps), choose **Create an App**, then **From scratch**, and pick your workspace.

Under **OAuth & Permissions**, add these Bot Token Scopes:

| Scope | Why |
| :- | :- |
| `chat:write` | Post messages |
| `im:write` | Open a direct message channel |
| `users:read` | Look up workspace members |
| `users:read.email` | Target a person by their email address |

Install the app to the workspace, then copy the **Bot User OAuth Token**. It starts with `xoxb-`.

[The Slack integration page
DOC](/docs/integrations/direct-message/slack) has the screenshots for each step.

**2. Put the token and a target on the profile**

Store the token alongside how you want to reach the person. Courier accepts three targets, and uses the first one it finds in this order: `channel`, then `user_id`, then `email`. [Users
DOC](/docs/recipients/overview#what-each-channel-needs) covers profile storage for every channel.

```json Profile theme={null}
{
  "profile": {
    "slack": {
      "access_token": "xoxb-your-bot-token",
      "email": "sarah@acme-corp.com"
    }
  }
}
```

Which target to pick is a real decision rather than a preference:

| Target | Reach it with | Trade-offs |
| :- | :- | :- |
| `email` | The address they use in Slack | Simplest, and breaks if their Slack email differs from yours |
| `user_id` | Their Slack member id, `U…` | Stable across email changes, and needs a lookup once |
| `channel` | A channel id, `C…` | Posts to a room rather than a person |

Start with `email`, and move to `user_id` if a recipient's Slack email ever differs from the one on their profile. The `users:read.email` scope makes email targeting work.

**3. Send the message**

Address the user and route to the Slack provider. Courier reads `slack` off the profile.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    routing: { method: "single", channels: ["slack"] },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "routing": {"method": "single", "channels": ["slack"]},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "routing": { "method": "single", "channels": ["slack"] },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {user_id: "user_123"},
    routing: {method: "single", channels: ["slack"]},
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={8} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("slack")}},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={6} theme={null}
SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("slack")))
        .build())
    .template("nt_01kx4h2jdafq8bk9aftxak4b40")
    .build();

client.send().message(SendMessageParams.builder().message(message).build());
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'routing' => ['method' => 'single', 'channels' => ['slack']],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={6} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Routing = new() { Method = "single", Channels = ["slack"] },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.routing '{"method": "single", "channels": ["slack"]}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my welcome template to user_123 on Slack.
```

Slack content is built in the template's Slack block rather than in the send, which is why this call carries a template id and no inline content.

## Verify

**1. Check Slack**

The message arrives as a direct message from your app, not from a person.

**2. Read the status**

Open [Logs](https://app.courier.com/logs). The provider response carries Slack's own error when something fails, which is more specific than the Courier status alone.

Two failures account for most first attempts. **`not_in_channel`** means the app isn't in the channel you targeted, so invite it. **`users_not_found`** means the email on the profile doesn't match any member of that workspace, which is the usual cost of targeting by email.

## What changes in production

**A token per workspace, not per app.** Each customer installing your Slack app produces its own token. Store it on the profiles belonging to that customer, or on a [tenant
DOC](/docs/tenants/overview) if you scope by customer already.

**Tokens can be revoked.** An admin removing the app invalidates its token, and sends then fail per recipient rather than globally. Watch for `invalid_auth` in the logs and prompt a reinstall.

**Slack rate limits per app.** Its limits apply to your app rather than to Courier, so a high-volume broadcast into one workspace is the case to watch.


# Send your first SMS
Source: https://www.courier.com/docs/guides/send-your-first-sms

Connect an SMS provider, store a phone number on the profile, and send a text.

Three things stand between you and a delivered text: a connected provider, a phone number on the profile, and a send.

> [!NOTE]
>
> Unlike email, SMS has **no default provider in Test**. A new workspace can email you immediately, but a text needs your own Twilio or other SMS account connected first, which is the most common reason a first send fails.

## Prerequisites

* [A Courier Test API key](https://app.courier.com/~/test/platform/api-keys)
* An account with an SMS provider, such as [Twilio](https://www.twilio.com/), and a number that can send
* A phone you can receive a text on

## Send it

**1. Connect your SMS provider**

In [Integrations](https://app.courier.com/integrations/catalog), add your provider and paste its credentials. For Twilio that is the Account SID, Auth Token, and a Messaging Service SID or sending number.

Integrations are per environment, so connect it in the same environment your API key belongs to. A provider added in Production does nothing for a Test key.

[Twilio
DOC](/docs/integrations/sms/twilio) covers the credential fields, and [SMS providers
DOC](/docs/integrations/sms/overview) lists every alternative.

**2. Put a phone number on the profile**

SMS addresses a recipient by `phone_number`, and it must be **E.164**: a plus sign, country code, then the number, with no spaces, dashes, or brackets. [Users
DOC](/docs/recipients/overview#what-each-channel-needs) covers the field every other channel reads.

```javascript Node.js highlight={2} theme={null}
await client.profiles.create("user_123", {
  profile: { phone_number: "+12025550156" },
});
```

```python Python highlight={3} theme={null}
client.profiles.create(
    "user_123",
    profile={"phone_number": "+12025550156"},
)
```

```bash cURL highlight={4} theme={null}
curl -X POST https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile": { "phone_number": "+12025550156" } }'
```

```ruby Ruby highlight={3} theme={null}
courier.profiles.create(
  "user_123",
  profile: {phone_number: "+12025550156"}
)
```

```go Go highlight={2} theme={null}
_, err := client.Profiles.New(context.TODO(), "user_123", courier.ProfileNewParams{
	Profile: map[string]any{"phone_number": "+12025550156"},
})
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("phone_number", JsonValue.from("+12025550156"))
        .build())
    .build();

client.profiles().create(params);
```

```php PHP highlight={3} theme={null}
$client->profiles->create(
  'user_123',
  profile: ['phone_number' => '+12025550156'],
);
```

```csharp C# highlight={7} theme={null}
await client.Profiles.Create(
    "user_123",
    new()
    {
        Profile = new Dictionary<string, JsonElement>
        {
            { "phone_number", JsonSerializer.SerializeToElement("+12025550156") },
        },
    }
);
```

```bash CLI highlight={3} theme={null}
courier profiles create user_123 \
  --api-key "$COURIER_API_KEY" \
  --profile '{"phone_number": "+12025550156"}'
```

```text MCP theme={null}
With Courier MCP, set the phone number +12025550156 on user_123.
```

A number without the country code is the single most common cause of an `UNROUTABLE` SMS. `2025550156` isn't a valid recipient, and `+12025550156` is.

**3. Send the text**

Route to `sms` and Courier picks the provider you connected.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    routing: { method: "single", channels: ["sms"] },
    content: { title: "Delivery update", body: "Your order is out for delivery." },
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "routing": {"method": "single", "channels": ["sms"]},
        "content": {"title": "Delivery update", "body": "Your order is out for delivery."},
    },
)
```

```bash cURL highlight={7} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "routing": { "method": "single", "channels": ["sms"] },
      "content": { "title": "Delivery update", "body": "Your order is out for delivery." }
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {user_id: "user_123"},
    routing: {method: "single", channels: ["sms"]},
    content: {title: "Delivery update", body: "Your order is out for delivery."}
  }
)
```

```go Go highlight={8} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("sms")}},
		},
		Content: courier.SendMessageParamsMessageContentUnion{
			OfElementalContentSugar: &shared.ElementalContentSugarParam{
				Title: "Delivery update",
				Body:  "Your order is out for delivery.",
			},
		},
	},
})
```

```java Java highlight={6} theme={null}
SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("sms")))
        .build())
    .content(ElementalContentSugar.builder()
        .title("Delivery update")
        .body("Your order is out for delivery.")
        .build())
    .build();

client.send().message(SendMessageParams.builder().message(message).build());
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'routing' => ['method' => 'single', 'channels' => ['sms']],
    'content' => ['title' => 'Delivery update', 'body' => 'Your order is out for delivery.'],
  ],
);
```

```csharp C# highlight={6} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Routing = new() { Method = "single", Channels = ["sms"] },
        Content = new ElementalContentSugar
        {
            Title = "Delivery update",
            Body = "Your order is out for delivery.",
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={4} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.routing '{"method": "single", "channels": ["sms"]}' \
  --message.content '{"title": "Delivery update", "body": "Your order is out for delivery."}'
```

```text MCP theme={null}
With Courier MCP, send user_123 an SMS saying their order is out for delivery.
```

SMS ignores `title` and sends `body`, so write the body to stand alone. Other channels use both, which is why the shorthand carries them together.

## Verify

**1. Check the phone**

The text arrives from the number or messaging service you connected.

**2. Read the status**

Open [Logs](https://app.courier.com/logs). `SENT` means the provider accepted it. `DELIVERED` means the carrier confirmed it, and only some providers report that.

If the message is `UNROUTABLE`, the profile had no `phone_number` Courier could use. Check the number is E.164 and that the profile you sent to is the one you wrote. [Why a message is UNROUTABLE
DOC](/docs/send/statuses#why-a-message-is-unroutable) lists every reason.

## What changes in production

**Numbers need provisioning.** Trial accounts at most providers only text verified numbers, which is a provider restriction rather than a Courier one.

**Long messages split.** Over 160 GSM-7 characters a message becomes multiple segments and is billed per segment. Unicode, including emoji, drops the limit to 70.

**Regulations vary.** Several countries require sender registration, and the United States requires it for application-to-person traffic. Your provider handles that registration, so check its rules before a launch.

**Opt-out isn't optional.** Carriers expect STOP to work. Courier applies [preferences
DOC](/docs/recipients/preferences/overview) on every send, so wire your provider's opt-out webhook to them rather than tracking it separately.


# Set up mobile push
Source: https://www.courier.com/docs/guides/set-up-mobile-push

Connect FCM and APNs, sync device tokens with the mobile SDK, and send a test push.

A push needs three things: a provider connected in Courier, a device token on the user, and a send.

The Courier mobile SDK handles the token. Pick your platform below, work down the steps, then send a test push.

## Prerequisites

* [A Courier account](https://app.courier.com/) and an [API key](https://app.courier.com/settings/api-keys)
* Provider credentials: a Firebase service account JSON for Android, an APNs `.p8` key for iOS, or both
* A physical device, since simulators and emulators don't reliably receive push

## Set up your app

Pick your platform. Each tab is the complete path, from an empty project to a device that receives push.

**iOS**

**1. Connect APNs in Courier**

Open [Integrations](https://app.courier.com/integrations), switch to the environment you send from, and choose **Apple Push Notification Service**. Providers are per environment, so one connected in test doesn't exist in production.

Fill in four fields, then click **Install Provider**:

* **Key Id**, the identifier of your APNs key
* **Key**, the contents of the downloaded `.p8` file
* **Team Id**, your Apple Developer team identifier
* **Topic (App Bundle Id)**, the bundle ID of the app you send to

Where to find each one: [APNs integration
DOC](/docs/integrations/push/apple-push-notification).

**2. Install the SDK**

In Xcode, go to **File > Add Packages**, paste the repository URL, pick a version, and add it to your target.

```text theme={null}
https://github.com/trycourier/courier-ios
```

With CocoaPods instead, add the pod and run `pod install` from your `ios/` directory. The SDK needs iOS 15.0 or later.

```ruby theme={null}
platform :ios, '15.0'

target 'YourApp' do
  pod 'Courier_iOS'
end
```

**3. Enable push in Xcode**

Select your target, open **Signing & Capabilities**, and add **Push Notifications**.

For silent push, add **Background Modes** as well and check **Remote notifications**.

Optionally add a [Notification Service Extension
DOC](/docs/sdk-libraries/ios#notification-service-extension) to track delivery while the app is closed. It is three steps in Xcode, and the iOS SDK reference walks them.

**4. Sync the device token**

Extend `CourierDelegate` in your `AppDelegate`. The SDK registers the APNs token, refreshes it, and forwards delivery and click events.

```swift theme={null}
import Courier_iOS

@main
class AppDelegate: CourierDelegate {

    override func pushNotificationDeliveredInForeground(
        message: [AnyHashable: Any]
    ) -> UNNotificationPresentationOptions {
        return [.sound, .list, .banner, .badge]
    }

    override func pushNotificationClicked(message: [AnyHashable: Any]) {
        print("Notification clicked: \(message)")
    }
}
```

**5. Sign in the user**

Courier ties every token to a signed-in user, so no push reaches the device until you call `signIn`. Pass the `user_id` you send to, plus a JWT your backend mints (see [Authenticate users
DOC](/docs/in-app/authenticate-users)).

> [!NOTE]
>
> **The `user_id` is yours, not Courier's.**\\
>
> Use whatever your app already calls this user, such as a database id or your auth provider's `sub`. Nothing has to exist in Courier first, since signing in registers the user and their device tokens. With no auth yet, any stable string works, as long as you reuse it on every launch and send to that same id.

```swift theme={null}
await Courier.shared.signIn(userId: "user_123", accessToken: jwt)
```

Call it once, right after your own login resolves. Credentials persist on the device, so app launches don't need it. Call `signOut` on logout to delete that device's tokens from Courier.

**6. Request notification permission**

iOS shows the system dialog once. If the user denies it, they re-enable it in device Settings.

```swift theme={null}
let status = try await Courier.requestNotificationPermission()
```

Reading the status, and getting the user back after they deny: [Notification permissions
DOC](/docs/send/push/overview#notification-permissions).

Next: [send a test push](#send-a-test-push) to the `user_id` you signed in.

**Android**

**1. Connect FCM in Courier**

In your [Firebase project settings](https://console.firebase.google.com/), open **Service Accounts** and click **Generate new private key**.

Then open [Integrations](https://app.courier.com/integrations), switch to the environment you send from, and choose **Firebase Cloud Messaging**. Paste the contents of the downloaded JSON into **Service Account JSON** and click **Install Provider**. Providers are per environment, so one connected in test doesn't exist in production.

Leave **Apply Recommended Courier Mobile SDK Formatting** on. Full walkthrough: [FCM integration
DOC](/docs/integrations/push/firebase-fcm).

**2. Install the SDK**

Add the Jitpack repository in `settings.gradle`, then the dependency in your app's `build.gradle`. The SDK needs Android SDK 23 or later and Gradle 8.4 or later.

```gradle theme={null}
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
```

```gradle theme={null}
dependencies {
    implementation 'com.github.trycourier:courier-android:LATEST_VERSION'
}
```

Take `LATEST_VERSION` from [GitHub Releases](https://github.com/trycourier/courier-android/releases). Then initialize the SDK in your `Application` class so it can persist state across sessions.

```kotlin theme={null}
class YourApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Courier.initialize(this)
    }
}
```

**3. Add Firebase to your app**

From Courier Android 6.x the SDK no longer bundles Firebase Messaging, so declare it yourself.

```gradle theme={null}
dependencies {
    implementation platform('com.google.firebase:firebase-bom:33.1.2')
    implementation "com.google.firebase:firebase-messaging"
}
```

Then complete the [Firebase Android setup](https://firebase.google.com/docs/android/setup): download `google-services.json` into your app module and apply the Google Services plugin.

**4. Sync the device token**

Subclass `FirebaseMessagingService` and forward both callbacks to Courier. `onNewToken` is what registers and refreshes the token.

```kotlin theme={null}
package your.app.package

import com.courier.android.Courier
import com.courier.android.notifications.CourierPushNotificationIntent
import com.courier.android.notifications.presentNotification
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage

class CourierPushNotificationService : FirebaseMessagingService() {

    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)

        val notificationIntent = CourierPushNotificationIntent(
            context = this,
            target = MainActivity::class.java,
            payload = message
        )

        notificationIntent.presentNotification(
            title = message.data["title"] ?: message.notification?.title,
            body = message.data["body"] ?: message.notification?.body
        )

        // Call this after presenting the notification: onMessageReceived makes a
        // synchronous tracking request that would otherwise delay the notification.
        Courier.onMessageReceived(message.data)
    }

    override fun onNewToken(token: String) {
        super.onNewToken(token)
        Courier.onNewToken(token)
    }
}
```

Register the service in `AndroidManifest.xml`.

```xml theme={null}
<service
    android:name=".CourierPushNotificationService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
```

Then extend `CourierActivity` in your `MainActivity` to receive delivery and click events in the foreground.

```kotlin theme={null}
class MainActivity : CourierActivity() {
    override fun onPushNotificationDelivered(pushNotification: Map<String, String>) { }
    override fun onPushNotificationClicked(pushNotification: Map<String, String>) { }
}
```

**5. Sign in the user**

Courier ties every token to a signed-in user, so no push reaches the device until you call `signIn`. Pass the `user_id` you send to, plus a JWT your backend mints (see [Authenticate users
DOC](/docs/in-app/authenticate-users)).

> [!NOTE]
>
> **The `user_id` is yours, not Courier's.**\\
>
> Use whatever your app already calls this user, such as a database id or your auth provider's `sub`. Nothing has to exist in Courier first, since signing in registers the user and their device tokens. With no auth yet, any stable string works, as long as you reuse it on every launch and send to that same id.

```kotlin theme={null}
// From an Activity or Fragment, where lifecycleScope is available
lifecycleScope.launch {
    Courier.shared.signIn(userId = "user_123", accessToken = jwt)
}
```

Call it once, right after your own login resolves. Credentials persist on the device, so app launches don't need it. Call `signOut` on logout to delete that device's tokens from Courier.

**6. Request notification permission**

Android 13 and later (API 33) needs a runtime permission. Declare it in `AndroidManifest.xml`, then request it. The call is safe on older versions.

```xml theme={null}
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

```kotlin theme={null}
Courier.shared.requestNotificationPermission(activity)
```

Reading the status, and getting the user back after they deny: [Notification permissions
DOC](/docs/send/push/overview#notification-permissions).

Next: [send a test push](#send-a-test-push) to the `user_id` you signed in.

**Flutter**

**1. Connect your push providers**

Open [Integrations](https://app.courier.com/integrations) and switch to the environment you send from. Providers are per environment, so one connected in test doesn't exist in production.

* Android needs [Firebase Cloud Messaging
  DOC](/docs/integrations/push/firebase-fcm). Generate a private key under **Service Accounts** in Firebase, paste it into **Service Account JSON**, and click **Install Provider**.
* iOS needs [APNs
  DOC](/docs/integrations/push/apple-push-notification). Enter your **Key Id**, `.p8` **Key**, **Team Id**, and **Topic (App Bundle Id)**, then click **Install Provider**.

**2. Install the SDK**

```bash theme={null}
flutter pub add courier_flutter
```

> [!NOTE]
>
> The SDK's `intl` dependency (`>=0.19.0 <1.0.0`) conflicts with Flutter 3.32+ (Dart 3.7+), which ships `intl` 1.0. On a resolution error, pin `intl: ^0.19.0` in your `pubspec.yaml`.

**3. Set up the iOS project**

Set your deployment target to iOS 15.0 or later, then run `cd ios && pod update`.

In Xcode, select your target, open **Signing & Capabilities**, and add **Push Notifications**. Optionally add a [Notification Service Extension
DOC](/docs/sdk-libraries/ios#notification-service-extension) to track delivery while the app is closed.

In `ios/Runner/AppDelegate.swift`, inherit from `CourierFlutterDelegate`. This is what syncs the APNs token.

```swift theme={null}
import Flutter
import courier_flutter

@main
@objc class AppDelegate: CourierFlutterDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}
```

**4. Set up the Android project**

Add the Jitpack repository to `android/build.gradle`, and set `minSdkVersion 23` in `android/app/build.gradle`. Declare the Google Services plugin version in `android/settings.gradle` (`id "com.google.gms.google-services" version "4.4.2" apply false`), apply it alongside Firebase, and place `google-services.json` in `android/app/`.

```gradle theme={null}
plugins {
    id "com.google.gms.google-services"
}

dependencies {
    implementation platform("com.google.firebase:firebase-bom:34.13.0")
    implementation "com.google.firebase:firebase-messaging"
}
```

Extend `CourierFlutterActivity` in `MainActivity`.

```kotlin theme={null}
import com.courier.courier_flutter.CourierFlutterActivity

class MainActivity : CourierFlutterActivity() {
    // ...
}
```

Then subclass `FirebaseMessagingService` to sync the FCM token and present notifications.

```kotlin theme={null}
import com.courier.android.Courier
import com.courier.android.notifications.CourierPushNotificationIntent
import com.courier.android.notifications.presentNotification
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage

class YourNotificationService : FirebaseMessagingService() {

    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)

        val notificationIntent = CourierPushNotificationIntent(
            context = this,
            target = MainActivity::class.java,
            payload = message
        )

        notificationIntent.presentNotification(
            title = message.data["title"] ?: message.notification?.title,
            body = message.data["body"] ?: message.notification?.body
        )

        Courier.onMessageReceived(message.data)
    }

    override fun onNewToken(token: String) {
        super.onNewToken(token)
        Courier.onNewToken(token)
    }
}
```

Register the service in `android/app/src/main/AndroidManifest.xml`.

```xml theme={null}
<service
    android:name=".YourNotificationService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
```

**5. Sign in the user**

Courier ties every token to a signed-in user, so no push reaches the device until you call `signIn`. Pass the `user_id` you send to, plus a JWT your backend mints (see [Authenticate users
DOC](/docs/in-app/authenticate-users)).

> [!NOTE]
>
> **The `user_id` is yours, not Courier's.**\\
>
> Use whatever your app already calls this user, such as a database id or your auth provider's `sub`. Nothing has to exist in Courier first, since signing in registers the user and their device tokens. With no auth yet, any stable string works, as long as you reuse it on every launch and send to that same id.

```dart theme={null}
await Courier.shared.signIn(userId: "user_123", accessToken: jwt);
```

Call it once, right after your own login resolves. Credentials persist on the device, so app launches don't need it. Call `signOut` on logout to delete that device's tokens from Courier.

**6. Request notification permission**

iOS shows the system dialog once. Android 13 and later needs the permission declared in `android/app/src/main/AndroidManifest.xml`, and the request is a no-op below API 33.

```xml theme={null}
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

```dart theme={null}
final status = await Courier.requestNotificationPermission();
```

Reading the status, and getting the user back after they deny: [Notification permissions
DOC](/docs/send/push/overview#notification-permissions).

Next: [send a test push](#send-a-test-push) to the `user_id` you signed in.

**React Native**

**1. Connect your push providers**

Open [Integrations](https://app.courier.com/integrations) and switch to the environment you send from. Providers are per environment, so one connected in test doesn't exist in production.

* Android needs [Firebase Cloud Messaging
  DOC](/docs/integrations/push/firebase-fcm). Generate a private key under **Service Accounts** in Firebase, paste it into **Service Account JSON**, and click **Install Provider**.
* iOS needs [APNs
  DOC](/docs/integrations/push/apple-push-notification). Enter your **Key Id**, `.p8` **Key**, **Team Id**, and **Topic (App Bundle Id)**, then click **Install Provider**.

**2. Install the SDK**

```bash theme={null}
npm install @trycourier/courier-react-native
```

**3. Set up the iOS project**

Set `platform :ios, '15.0'` in your Podfile, then run `cd ios && pod install`.

In Xcode, select your target, open **Signing & Capabilities**, and add **Push Notifications**. Optionally add a [Notification Service Extension
DOC](/docs/sdk-libraries/ios#notification-service-extension) to track delivery while the app is closed.

In your Swift `AppDelegate`, hold a `CourierDelegate` and forward the APNs registration callbacks to it. This is what syncs the token.

```swift theme={null}
private let courierDelegate = CourierDelegate()

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    courierDelegate.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    courierDelegate.application(application, didFailToRegisterForRemoteNotificationsWithError: error)
}
```

> [!NOTE]
>
> An older app with an Objective-C `AppDelegate` inherits from `CourierReactNativeDelegate` instead: `@interface AppDelegate : CourierReactNativeDelegate`. On Expo, follow the [Expo setup guide on GitHub](https://github.com/trycourier/courier-react-native/blob/master/Docs/6_Expo.md), which wires Courier into `ExpoAppDelegate`.

**4. Set up the Android project**

Add the Jitpack repository to `android/build.gradle` and set `minSdkVersion = 23`. Add `classpath("com.google.gms:google-services:4.4.0")`, declare Firebase in `android/app/build.gradle`, and place `google-services.json` in `android/app/`.

```gradle theme={null}
apply plugin: "com.google.gms.google-services"

dependencies {
    implementation platform('com.google.firebase:firebase-bom:33.1.2')
    implementation "com.google.firebase:firebase-messaging"
}
```

Extend `CourierReactNativeActivity` in `MainActivity`.

```kotlin theme={null}
import com.courierreactnative.CourierReactNativeActivity

class MainActivity : CourierReactNativeActivity() {
    // ...
}
```

Then subclass `FirebaseMessagingService` to sync the FCM token and present notifications.

```java theme={null}
package your.app.package;

import androidx.annotation.NonNull;
import com.courier.android.Courier;
import com.courier.android.notifications.CourierPushNotificationIntent;
import com.courier.android.notifications.RemoteMessageExtensionsKt;
import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;

public class YourNotificationService extends FirebaseMessagingService {

    @Override
    public void onMessageReceived(@NonNull RemoteMessage message) {
        super.onMessageReceived(message);

        CourierPushNotificationIntent notificationIntent = new CourierPushNotificationIntent(
            this,
            0,
            MainActivity.class,
            message
        );

        String title = message.getData().get("title");
        String body = message.getData().get("body");

        RemoteMessageExtensionsKt.presentNotification(
            notificationIntent,
            title,
            body,
            android.R.drawable.ic_dialog_info,
            "Notification Service"
        );

        // Call this after presenting the notification: it makes a synchronous tracking request.
        Courier.Companion.onMessageReceived(message.getData());
    }

    @Override
    public void onNewToken(@NonNull String token) {
        super.onNewToken(token);
        Courier.Companion.onNewToken(token);
    }
}
```

Register the service in `AndroidManifest.xml`.

```xml theme={null}
<service
    android:name=".YourNotificationService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
```

**5. Sign in the user**

Courier ties every token to a signed-in user, so no push reaches the device until you call `signIn`. Pass the `user_id` you send to, plus a JWT your backend mints (see [Authenticate users
DOC](/docs/in-app/authenticate-users)).

> [!NOTE]
>
> **The `user_id` is yours, not Courier's.**\\
>
> Use whatever your app already calls this user, such as a database id or your auth provider's `sub`. Nothing has to exist in Courier first, since signing in registers the user and their device tokens. With no auth yet, any stable string works, as long as you reuse it on every launch and send to that same id.

```typescript theme={null}
await Courier.shared.signIn({ userId: "user_123", accessToken: jwt });
```

Call it once, right after your own login resolves. Credentials persist on the device, so app launches don't need it. Call `signOut` on logout to delete that device's tokens from Courier.

**6. Request notification permission**

iOS shows the system dialog once. Android 13 and later needs the permission declared in `AndroidManifest.xml`.

```xml theme={null}
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

```typescript theme={null}
const status = await Courier.requestNotificationPermission();
```

Reading the status, and getting the user back after they deny: [Notification permissions
DOC](/docs/send/push/overview#notification-permissions).

Next: [send a test push](#send-a-test-push) to the `user_id` you signed in.

> [!NOTE]
>
> The SDK holds a token it receives before anyone signs in and uploads it at sign-in, so you never race the callback. Signing in a different user signs the previous one out first.

> [!TIP]
>
> To register tokens from a server or outside the SDK, use the [Device Tokens API](/docs/api-reference/device-tokens/add-a-token-to-a-user) directly. The [push notifications overview
> DOC](/docs/integrations/push/overview) covers the token model.

## Send a test push

First [design a template
DOC](/docs/design/templates/overview) with a **Push** channel and publish it. Then send it to the `user_id` you signed in, routing to the push channel. Courier resolves the user's tokens and delivers through each connected provider.

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    routing: { method: 'single', channels: ['push'] },
  },
});

console.log(requestId);
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {"method": "single", "channels": ["push"]},
    },
)
print(response.request_id)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": { "method": "single", "channels": ["push"] }
    }
  }'
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "single", channels: ["push"] }
  }
)

puts(response)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("push")}},
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(JsonValue.from(java.util.Map.of(
            "method", "single",
            "channels", java.util.List.of("push"))))
        .build())
    .build();
client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => ['method' => 'single', 'channels' => ['push']],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new Routing { Method = Method.Single, Channels = ["push"] },
    },
};

await client.Send.Message(parameters);
```

```bash CLI theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","routing":{"method":"single","channels":["push"]}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on the push channel only.
```

## Verify

The notification appears on the device you registered. For a silent payload, confirm your app handled it in the background instead. Open the message in [Logs](https://app.courier.com/logs). A delivered push shows the provider it went through and the token it targeted. If it didn't deliver, the log names the reason: no token, expired token, or provider not configured.

> [!NOTE]
>
> `channels: ["push"]` picks a single push provider in failover order and stops at the first success. To reach both iOS and Android on one send, set the push channel's `routing_method` to `all` and install both providers. See [reach every device on push
> DOC](/docs/send/routing#reach-every-device-on-push).

## Delivery and click tracking

Courier tracks push delivery and clicks for you. Every push carries a `trackingUrl`, and the SDK posts back to it as the notification arrives and again when the user taps it. Both events land in [Logs](https://app.courier.com/logs) with no code of your own.

The wiring from [Set up your app](#set-up-your-app) is what reports them:

| Event | Reported by | Works when |
| :- | :- | :- |
| Delivered (iOS) | `CourierDelegate` | your app is in the foreground |
| Delivered (iOS) | the Notification Service Extension | your app is backgrounded or closed |
| Delivered (Android) | `FirebaseMessagingService` | any state, including killed |
| Clicked | `CourierDelegate`, `CourierActivity` | any state |

Two provider defaults keep that accurate, and a new workspace has both on. **Attach Mutable Content** on [APNs
DOC](/docs/integrations/push/apple-push-notification) is what lets the extension run at all. **Apply Recommended Courier Mobile SDK Formatting** on [FCM
DOC](/docs/integrations/push/firebase-fcm) ships the push as `data`, so Android wakes for it. [How the data arrives per provider
DOC](/docs/send/push/custom-data#how-the-data-arrives-per-provider) shows both payloads.

> [!NOTE]
>
> If you handle notifications outside the Courier hooks, post delivery and click events yourself with `client.tracking.postTrackingUrl`. Each SDK page carries the call: [iOS
> DOC](/docs/sdk-libraries/ios#url-tracking), [Android
> DOC](/docs/sdk-libraries/android#url-tracking), [Flutter
> DOC](/docs/sdk-libraries/flutter#url-tracking), and [React Native
> DOC](/docs/sdk-libraries/react-native#url-tracking).


# Track delivery with webhooks
Source: https://www.courier.com/docs/guides/track-delivery

Receive every delivery event in your own system through an outbound webhook.

Get every delivery event in your own system, so status lives with the rest of your data.

An outbound webhook posts Courier events to an endpoint you own. Use it to log deliveries, sync status to your database, or kick off downstream work.

## What you'll build

```mermaid theme={null}
flowchart LR
    A["Message sent"] --> B["Status changes"]
    B --> C["Courier signs it"]
    C --> D["Your endpoint verifies"]
```

## Prerequisites

* A public HTTPS endpoint that accepts a `POST` and returns `2xx`
* [The Courier console for the environment you want events from](https://app.courier.com/settings)
* [The event types and payloads
  DOC](/docs/monitor/webhooks/events)

## Set up the webhook

**1. Create the webhook destination**

Create destinations in the console, not through the API. Open [Settings](https://app.courier.com/settings) in the environment you want (test or production), find **Outbound Webhooks**, and add a destination with your endpoint URL. Name it so you can tell destinations apart later. Courier generates a signing secret (`whsec_...`). Copy it and store it as a secret in your app. You use it to verify requests really came from Courier.

> [!WARNING]
>
> A destination fires only for the environment it was created in, so create one in test and one in production if you need both.

**2. Verify the signature and handle events**

Courier signs every request with a `courier-signature` header. Verify it against the **raw** request body before you trust the payload. Then branch on the event `type`. A destination receives every event type, so filter to the ones you care about.

```javascript theme={null}
import crypto from "crypto";
import express from "express";

const app = express();

// Capture the raw body so the signature matches the exact bytes Courier hashed.
app.post("/courier-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("courier-signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const expected = crypto
    .createHmac("sha256", process.env.COURIER_WEBHOOK_SECRET)
    .update(`${parts.t}.${req.body.toString("utf8")}`, "utf8")
    .digest("hex");

  const digest = Buffer.from(expected, "hex");
  const provided = Buffer.from(parts.signature ?? "", "hex");

  // timingSafeEqual throws unless both buffers are the same length. Compare
  // lengths first, or a forged signature becomes a 500 instead of a 401, and
  // Courier retries a 500.
  const valid =
    provided.length === digest.length && crypto.timingSafeEqual(digest, provided);
  if (!valid) return res.sendStatus(401);

  const { type, data } = JSON.parse(req.body.toString("utf8"));
  if (type === "message:updated") {
    // Sync the delivery status to your system.
    console.log(data.id, data.status);
  }

  res.sendStatus(200); // Acknowledge fast; do slow work asynchronously.
});
```

## Verify

**1. Send a message and watch for the event**

Send in the same environment the destination belongs to. Within moments your endpoint receives a `message:updated` event as the message moves through `ENQUEUED`, `SENT`, and `DELIVERED`.

**2. Confirm a valid signature passes**

Log the result of the signature comparison. If it never passes, check that you're hashing the raw body, not a re-serialized object.

**3. Confirm a tampered body fails**

Replay a request with one byte of the body changed and confirm your handler returns `401`.

## Skip the consumer

Webhooks drive your own logic. To forward events to a monitoring platform without building a consumer, connect an outbound integration in the console:

* [Datadog
  DOC](/docs/integrations/observability/datadog)
* [New Relic
  DOC](/docs/integrations/observability/new-relic)
* [OpenTelemetry
  DOC](/docs/integrations/observability/open-telemetry)
* A CDP such as [Segment
  DOC](/docs/integrations/cdp/segment) or [Rudderstack
  DOC](/docs/integrations/cdp/rudderstack)


# Add a preference center
Source: https://www.courier.com/docs/in-app/add-a-preference-center

Embed the Courier Preferences component so users pick their topics and channels.

**Try it live:**

> **[Preferences demo](https://inbox-demo.courier.com/inbox-demo?layout=courier-preferences)**
>
> See the preferences center in action.

Courier Preferences is an embeddable UI where a signed-in user picks the topics they receive and how each is delivered. It uses the same SDKs and `signIn` as the inbox. If you already have the inbox, preferences is one more component.

![The Courier preferences center with its default styling: a topic section with per-topic toggles and an expanded channel picker for email, push, and SMS](https://mintcdn.com/courier-4f1f25dc/Ia7FGvhsFU_5CtOa/assets/preferences-default.webp?fit=max\&auto=format\&n=Ia7FGvhsFU_5CtOa\&q=85\&s=d31b2fb8c91c01bd97f26b09d0ecb4bc)

The Courier preferences center with its default styling.

> [!WARNING]
>
> The component renders empty unless the user's JWT has `read:preferences write:preferences` in its scope string, as [Authenticate users
> DOC](/docs/in-app/authenticate-users) covers.

## Set up

Install the SDK for your framework:

```bash React theme={null}
npm install @trycourier/courier-react
# On React 17? Use @trycourier/courier-react-17 instead (identical API):
# npm install @trycourier/courier-react-17
```

```bash Web Components theme={null}
npm install @trycourier/courier-ui-preferences
```

```bash Vue theme={null}
npm install @trycourier/courier-vue
```

```bash Angular theme={null}
npm install @trycourier/courier-angular
```

```bash iOS theme={null}
# Swift Package Manager: add https://github.com/trycourier/courier-ios
# or CocoaPods:
pod 'Courier_iOS'
```

```bash Android theme={null}
# In settings.gradle add the JitPack repo, then the dependency in build.gradle:
# maven { url 'https://jitpack.io' }
# implementation 'com.github.trycourier:courier-android:<version>'
```

```bash Flutter theme={null}
flutter pub add courier_flutter
```

```bash React Native theme={null}
npm install @trycourier/courier-react-native
# then, for iOS:
cd ios && pod install
```

On mobile, the SDK also needs native project setup before it renders: [iOS
DOC](/docs/sdk-libraries/ios#installation), [Android
DOC](/docs/sdk-libraries/android#installation), [Flutter
DOC](/docs/sdk-libraries/flutter#installation), and [React Native
DOC](/docs/sdk-libraries/react-native#installation).

Then [authenticate the user
DOC](/docs/in-app/authenticate-users) and render the preferences component:

```jsx React theme={null}
import { CourierPreferences } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

export default function Preferences() {
  return <CourierPreferences />;
}
```

```html Web Components theme={null}
<courier-preferences id="preferences"></courier-preferences>

<script type="module">
  import { Courier } from "@trycourier/courier-ui-preferences";

  Courier.shared.signIn({ userId, jwt });
</script>
```

```vue Vue theme={null}
<script setup lang="ts">
import { CourierPreferences } from "@trycourier/courier-vue";
</script>

<template>
  <CourierPreferences />
</template>
```

```ts Angular theme={null}
import { Component } from "@angular/core";
import { CourierPreferencesComponent } from "@trycourier/courier-angular";

@Component({
  selector: "app-preferences",
  standalone: true,
  imports: [CourierPreferencesComponent],
  template: `<courier-preferences></courier-preferences>`,
})
export class PreferencesComponent {}
```

```swift iOS theme={null}
// Use CourierPreferences (UIKit) or CourierPreferencesView (SwiftUI).
// Both take a display mode; see the SDK reference for the options.
import Courier_iOS

// UIKit
view.addSubview(CourierPreferences(mode: .channels(CourierUserPreferencesChannel.allCases)))

// SwiftUI
CourierPreferencesView(mode: .channels(CourierUserPreferencesChannel.allCases))
```

```kotlin Android theme={null}
// Render the CourierPreferences view from com.courier.android.ui.preferences
// XML: <com.courier.android.ui.preferences.CourierPreferences ... />
val preferences = findViewById<CourierPreferences>(R.id.courierPreferences)
```

```dart Flutter theme={null}
import 'package:courier_flutter/ui/preferences/courier_preferences.dart';

// Render the preferences widget (see the SDK reference for mode options)
CourierPreferences(mode: ChannelsMode(channels: CourierUserPreferencesChannel.allCases));
```

```jsx React Native theme={null}
import { CourierPreferencesView } from "@trycourier/courier-react-native";

export default function Preferences() {
  return <CourierPreferencesView />;
}
```

Full SDK references: [React
DOC](/docs/sdk-libraries/courier-react-web), [Web Components
DOC](/docs/sdk-libraries/courier-web-components), [Vue
DOC](/docs/sdk-libraries/courier-vue-web), [Angular
DOC](/docs/sdk-libraries/courier-angular-web), [iOS
DOC](/docs/sdk-libraries/ios), [Android
DOC](/docs/sdk-libraries/android), [Flutter
DOC](/docs/sdk-libraries/flutter), [React Native
DOC](/docs/sdk-libraries/react-native).

## Choose a display mode

The mobile components take a `mode` that sets how much control the user gets:

* **Topic mode**: one on/off toggle per subscription topic. The simplest option, and the usual choice.
* **Channels mode**: per-channel controls within each topic, so a user can keep a topic but receive it by email only.

```swift iOS theme={null}
CourierPreferencesView(mode: .topic)
CourierPreferencesView(mode: .channels([.push, .sms, .email]))
```

```kotlin Android theme={null}
// `mode` is a property on the view, not a constructor argument
preferences.mode = CourierPreferences.Mode.Topic
preferences.mode = CourierPreferences.Mode.Channels(
  listOf(CourierPreferenceChannel.PUSH, CourierPreferenceChannel.SMS, CourierPreferenceChannel.EMAIL)
)
```

```dart Flutter theme={null}
CourierPreferences(mode: TopicMode())
CourierPreferences(mode: ChannelsMode(channels: [
  CourierUserPreferencesChannel.push,
  CourierUserPreferencesChannel.sms,
  CourierUserPreferencesChannel.email,
]))
```

```jsx React Native theme={null}
<CourierPreferencesView mode={{ type: "topic" }} />
<CourierPreferencesView mode={{ type: "channels", channels: ["push", "sms", "email"] }} />
```

> [!NOTE]
>
> The web components don't take a display mode. They always render topics with their channel controls. Their `mode` prop is the **theme** mode: `"light"`, `"dark"`, or `"system"`. See [Customize preferences
> DOC](/docs/in-app/customize-preferences#theme).

You configure topics and sections in the [preference center editor
GUIDE](/docs/guides/build-a-preference-center#configure-the-topics). For how Courier enforces these choices at send time, see [how preferences resolve
DOC](/docs/recipients/preferences/overview).

## Props

`<CourierPreferences />` in React, Vue, and Angular. The web component takes the same
values as kebab-case attributes, and `courier-preferences` is the element name.

| Prop | Type | Description |
| - | - | - |
| `lightTheme` | `CourierPreferencesTheme` | Theme applied in light mode. |
| `darkTheme` | `CourierPreferencesTheme` | Theme applied in dark mode. |
| `mode` | `CourierComponentThemeMode` | Force light or dark instead of following the system. |
| `title` | string | Heading above the topic list. |
| `subtitle` | string | Line under the heading. |
| `brandId` | string | Render with a specific Brand's styling. |
| `channelLabels` | `Record<string, string>` | Rename a channel in the UI, `{ msteams: "Teams" }`. |
| `previewData` | `CourierPreferencePage` | Render injected data instead of fetching. No sign-in or network needed. |
| `isLoading` | boolean | Force the loading skeleton, for while your app fetches data it will inject. |
| `draft` | boolean | Render the unpublished working draft instead of the published page. |
| `onError` | `(error: Error) => void` | Called when the component fails to load or save. |
| `style` | `CSSProperties` | Inline styles on the wrapper. |

The web component also exposes `setLightTheme`, `setDarkTheme`, `setMode`,
`setChannelLabels`, `setPreviewData`, and `setLoading` on the element, for hosts that hold a
ref rather than re-rendering with new props.

### Channel labels

`channelLabels` renames a channel wherever the component lists it. Keys you leave out keep
their default label, and a channel with no default shows its key with the first letter
capitalized.

| Channel key | Default label |
| - | - |
| `direct_message` | Chat |
| `email` | Email |
| `push` | Push |
| `sms` | SMS |
| `webhook` | Webhook |
| `inbox` | In-App |

```js theme={null}
const prefs = document.querySelector("courier-preferences");

prefs.setChannelLabels({ email: "E-mail", push: "Mobile push", sms: "Text message" });
```

## Verify

**1. Sign in with preference scopes**

Sign in a user whose JWT includes `read:preferences write:preferences`.

**2. Open the preferences screen**

Open the screen that renders the preferences component.

**3. Confirm topics persist**

Your workspace's preference topics appear, and toggling one persists after a reload.


# Add the Courier Inbox
Source: https://www.courier.com/docs/in-app/add-an-inbox

Install the SDK, sign the user in, and render the inbox component on any platform.

**Try it live:**

> **[Inbox](https://inbox-demo.courier.com/inbox-demo)**
>
> The full inbox component.

> **[Popup menu](https://inbox-demo.courier.com/inbox-demo?layout=courier-inbox-popup-menu)**
>
> The inbox as an icon-button popup.

![Left, the Courier Inbox as a full-height panel with an unread count in its header, listing notifications with unread dots and per-message action buttons. Right, the same inbox collapsed to its icon button with an unread dot.](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/inbox-split.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=e6779c156f90b270f34f4fedf5d9e3fa)

Both layouts in the default theme: the full inbox on the left, the popup's icon button on the right.

Your backend generates the `jwt` in these snippets with your Courier API key. For the full flow, scope strings, and token refresh, see [Authenticate users
DOC](/docs/in-app/authenticate-users).

## Prerequisites

* [A Courier account](https://app.courier.com/signup)
* [A Courier API key](https://app.courier.com/settings/api-keys)
* [A backend endpoint that issues a Courier JWT
  DOC](/docs/in-app/authenticate-users)
* A message sent to that user on the `inbox` channel

## Set up

**1. Install the SDK**

Install the SDK for your framework.

```bash React theme={null}
npm install @trycourier/courier-react
# On React 17? Use @trycourier/courier-react-17 instead (identical API):
# npm install @trycourier/courier-react-17
```

```bash Web Components theme={null}
npm install @trycourier/courier-ui-inbox
```

```bash Vue theme={null}
npm install @trycourier/courier-vue
```

```bash Angular theme={null}
npm install @trycourier/courier-angular
```

```bash iOS theme={null}
# Swift Package Manager: add https://github.com/trycourier/courier-ios
# or CocoaPods:
pod 'Courier_iOS'
```

```bash Android theme={null}
# In settings.gradle add the JitPack repo, then the dependency in build.gradle:
# maven { url 'https://jitpack.io' }
# implementation 'com.github.trycourier:courier-android:<version>'
```

```bash Flutter theme={null}
flutter pub add courier_flutter
```

```bash React Native theme={null}
npm install @trycourier/courier-react-native
# then, for iOS:
cd ios && pod install
```

On mobile, the SDK also needs native project setup before it renders: [iOS
DOC](/docs/sdk-libraries/ios#installation), [Android
DOC](/docs/sdk-libraries/android#installation), [Flutter
DOC](/docs/sdk-libraries/flutter#installation), and [React Native
DOC](/docs/sdk-libraries/react-native#installation).

**2. Authenticate and render**

Call `signIn` with a `userId` and a JWT from your backend, then mount the inbox component.

```jsx React highlight={8} theme={null}
import { useEffect } from "react";
import { useCourier, CourierInbox } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    courier.shared.signIn({ userId, jwt });
  }, []);

  return <CourierInbox />;
}
```

```html Web Components highlight={7} theme={null}
<!-- Works with any framework, or none -->
<courier-inbox id="inbox"></courier-inbox>

<script type="module">
  import { Courier } from "@trycourier/courier-ui-inbox";

  Courier.shared.signIn({ userId, jwt });
</script>
```

```vue Vue highlight={8} theme={null}
<script setup lang="ts">
import { onMounted } from "vue";
import { CourierInbox, useCourier } from "@trycourier/courier-vue";

const courier = useCourier();

onMounted(() => {
  courier.shared.signIn({ userId, jwt });
});
</script>

<template>
  <CourierInbox />
</template>
```

```ts Angular highlight={14} theme={null}
import { AfterViewInit, Component, inject } from "@angular/core";
import { CourierInboxComponent, CourierService } from "@trycourier/courier-angular";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [CourierInboxComponent],
  template: `<courier-inbox></courier-inbox>`,
})
export class AppComponent implements AfterViewInit {
  private readonly courier = inject(CourierService);

  ngAfterViewInit(): void {
    this.courier.signIn({ userId, jwt });
  }
}
```

```swift iOS highlight={4} theme={null}
import Courier_iOS

// Authenticate the user
await Courier.shared.signIn(userId: userId, accessToken: jwt)

// UIKit
view.addSubview(CourierInbox())

// SwiftUI
CourierInboxView()
```

```kotlin Android highlight={1,3} theme={null}
// Authenticate the user (signIn is a suspend function)
lifecycleScope.launch {
  Courier.shared.signIn(userId = userId, accessToken = jwt)
}

// Render the inbox @Composable
CourierInbox()
```

```dart Flutter highlight={5} theme={null}
import 'package:courier_flutter/courier_flutter.dart';
import 'package:courier_flutter/ui/inbox/courier_inbox.dart';

// Authenticate the user
await Courier.shared.signIn(accessToken: jwt, userId: userId);

// Render the inbox widget
CourierInbox();
```

```jsx React Native highlight={4} theme={null}
import Courier, { CourierInboxView } from "@trycourier/courier-react-native";

// Authenticate the user
await Courier.shared.signIn({ accessToken: jwt, userId });

// Render the inbox component
return <CourierInboxView />;
```

> [!NOTE]
>
> `CourierInbox` fills its container's width and takes its height from the parent, so size the parent or set a `height`. For a fixed-size widget, use the [popup menu](#render-as-a-popup-menu) below.

Full SDK references: [React
DOC](/docs/sdk-libraries/courier-react-web), [Web Components
DOC](/docs/sdk-libraries/courier-web-components), [Vue
DOC](/docs/sdk-libraries/courier-vue-web), [Angular
DOC](/docs/sdk-libraries/courier-angular-web), [iOS
DOC](/docs/sdk-libraries/ios), [Android
DOC](/docs/sdk-libraries/android), [Flutter
DOC](/docs/sdk-libraries/flutter), [React Native
DOC](/docs/sdk-libraries/react-native).

### Render as a popup menu

On the web SDKs, the inbox can render as a popup menu instead of an inline list. The icon button opens the panel and carries an unread badge. Its default icon is an inbox glyph, themeable through `theme.popup.button.icon.svg`. Authentication is identical: keep the same `signIn` and swap the component. Popup menus aren't available on mobile.

![The Courier Inbox popup menu: an icon button with an unread badge above the open notification panel, which shows its own unread count in the header](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/inbox-popup-menu.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=f80d8917f34f11d1af0abdd9fa9ed966)

The inbox as a popup menu: an icon button with an unread badge, and the panel it opens.

```jsx React theme={null}
import { CourierInboxPopupMenu } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

// Swap <CourierInbox /> for the popup menu
return <CourierInboxPopupMenu />;
```

```html Web Components theme={null}
<courier-inbox-popup-menu></courier-inbox-popup-menu>
```

```vue Vue theme={null}
<script setup lang="ts">
import { CourierInboxPopupMenu } from "@trycourier/courier-vue";
</script>

<template>
  <CourierInboxPopupMenu />
</template>
```

```ts Angular theme={null}
import { Component } from "@angular/core";
import { CourierInboxPopupMenuComponent } from "@trycourier/courier-angular";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [CourierInboxPopupMenuComponent],
  template: `<courier-inbox-popup-menu></courier-inbox-popup-menu>`,
})
export class AppComponent {}
```

> [!NOTE]
>
> Every platform, including mobile, exposes the message data and actions directly, so [Custom UI
> DOC](/docs/in-app/build-a-custom-inbox) shows how to build your own.

#### Size and position the popup

![Three Courier Inbox popup menus side by side, each opening from a different corner of its trigger button and at a different width and height](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/courier-inbox-popupmenu-position.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=9d731ae80029544028a91cd535ebf38c)

The popup menu at three different alignments, widths, and offsets.

`popupAlignment` picks which corner the panel opens from, and the four CSS offsets nudge it from there. Set only the offsets that the alignment uses: a `top-*` alignment reads `top`, a `bottom-*` alignment reads `bottom`, and the horizontal half reads `left` or `right` to match.

| Prop | Default | Description |
| - | - | - |
| `popupAlignment` | `"top-left"` | One of `top`, `center`, or `bottom`, paired with `left`, `center`, or `right`. Nine values. |
| `popupWidth` | `"440px"` | Width of the panel. Any CSS length. |
| `popupHeight` | `"440px"` | Height of the panel. Any CSS length. |
| `top` `right` `bottom` `left` | `40px` and `0px` | CSS offsets from the aligned corner, overriding the built-in pair. |

```jsx theme={null}
<CourierInboxPopupMenu
  popupAlignment="top-left"
  popupWidth="340px"
  popupHeight="400px"
  top="44px"
  left="44px"
/>
```

An unrecognized `popupAlignment` is ignored rather than rejected, and the panel keeps the alignment it had. Check the spelling against the nine values if a change appears to do nothing.

#### Open and close the popup in code

The popup menu element exposes `showPopup()` and `closePopup()`. Both animate the panel the way the button does, so use them to open the inbox from a link or a keyboard shortcut. On React, Vue, and Angular, call them through a ref to the underlying element.

```js theme={null}
const popup = document.querySelector("courier-inbox-popup-menu");

popup.showPopup();
popup.closePopup();
```

#### Give the inline inbox a height

`<CourierInbox />` defaults to `height="auto"` and grows with its messages. In a fixed-height container that means the page scrolls instead of the list, so set a height when the inbox sits inside a panel or sidebar.

```jsx theme={null}
<CourierInbox height="50vh" />
```

> [!NOTE]
>
> **Content Security Policy.**\\
>
> The inbox calls Courier directly from the browser, so a site with a CSP has to allow these. `connect-src` needs `https://api.courier.com`, `https://inbox.courier.com`, `wss://realtime.courier.io`, and `wss://realtime.courier.com`. For the EU datacenter, use `https://api.eu.courier.com`, `https://inbox.eu.courier.io`, and `wss://realtime.eu.courier.io`. The components style themselves inline, so `style-src` needs `'unsafe-inline'`.

> [!NOTE]
>
> **Hosted preference center.**\\
>
> If you embed the hosted preference center in an iframe, `frame-src` needs `https://view.notificationcenter.app`.

## Verify

**1. Sign in and open the inbox**

Sign in a user and open the screen that renders the inbox.

**2. Send a test message**

[Send a message
DOC](/docs/in-app/send-to-the-inbox) to that user on the `inbox` channel.

**3. Confirm it appears**

The message appears in the inbox in real time, and the unread count updates.

An inbox that stays empty usually has an expired or unscoped token. Check its `exp` and scopes with [Authenticate users
DOC](/docs/in-app/authenticate-users).


# Add toasts
Source: https://www.courier.com/docs/in-app/add-toasts

Render toast popups for new inbox messages and handle clicks on the web SDKs.

Toasts share the inbox's feed and [authentication
DOC](/docs/in-app/authenticate-users).

**Try it live:**

> **[Toast demo](https://inbox-demo.courier.com/inbox-demo?layout=courier-toast)**
>
> See toasts pop up for new messages.

Toasts are transient popups that appear when a new message arrives. Render them on their own or alongside the inbox.

![A Courier toast for a newly delivered message, with the message title, body, and Accept and Pass actions](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/toast-default.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=d8dde1dc885025b113f253dc1b0518c2)

A Courier toast appearing for a new message

> [!NOTE]
>
> The built-in toast is web-only. On iOS, Android, Flutter, and React Native, listen for new messages and show your own UI (mobile tabs below). Or use [push notifications
> DOC](/docs/integrations/push/apple-push-notification).

## Set up

Install the SDK for your framework:

```bash React theme={null}
npm install @trycourier/courier-react
# On React 17? Use @trycourier/courier-react-17 instead (identical API):
# npm install @trycourier/courier-react-17
```

```bash Web Components theme={null}
npm install @trycourier/courier-ui-toast
```

```bash Vue theme={null}
npm install @trycourier/courier-vue
```

```bash Angular theme={null}
npm install @trycourier/courier-angular
```

```bash iOS theme={null}
# Swift Package Manager: add https://github.com/trycourier/courier-ios
# or CocoaPods:
pod 'Courier_iOS'
```

```bash Android theme={null}
# In settings.gradle add the JitPack repo, then the dependency in build.gradle:
# maven { url 'https://jitpack.io' }
# implementation 'com.github.trycourier:courier-android:<version>'
```

```bash Flutter theme={null}
flutter pub add courier_flutter
```

```bash React Native theme={null}
npm install @trycourier/courier-react-native
# then, for iOS:
cd ios && pod install
```

On mobile, the SDK also needs native project setup before it renders: [iOS
DOC](/docs/sdk-libraries/ios#installation), [Android
DOC](/docs/sdk-libraries/android#installation), [Flutter
DOC](/docs/sdk-libraries/flutter#installation), and [React Native
DOC](/docs/sdk-libraries/react-native#installation).

Then [authenticate the user
DOC](/docs/in-app/authenticate-users) with the same `signIn` as the inbox and render the component. The web SDKs use the built-in `CourierToast`. On mobile, listen for new messages and show your own UI:

```jsx React theme={null}
import { CourierToast } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

export default function App() {
  // Renders toasts for new messages on the authenticated user's feed
  return <CourierToast />;
}
```

```html Web Components theme={null}
<courier-toast></courier-toast>

<script type="module">
  import { Courier } from "@trycourier/courier-ui-toast";

  Courier.shared.signIn({ userId, jwt });
</script>
```

```vue Vue theme={null}
<script setup lang="ts">
import { CourierToast } from "@trycourier/courier-vue";
</script>

<template>
  <CourierToast />
</template>
```

```ts Angular theme={null}
import { Component } from "@angular/core";
import { CourierToastComponent } from "@trycourier/courier-angular";

@Component({
  selector: "app-toast",
  standalone: true,
  imports: [CourierToastComponent],
  template: `<courier-toast></courier-toast>`,
})
export class ToastComponent {}
```

```swift iOS theme={null}
// No built-in toast on iOS: listen for new messages and show your own UI
let listener = await Courier.shared.addInboxListener(
  onMessageEvent: { message, index, feed, event in
    if event == .added {
      showMyToast(message) // your own toast UI
    }
  }
)
```

```kotlin Android theme={null}
// No built-in toast on Android: listen and show your own UI
// addInboxListener is a suspend function; call it from a coroutine
lifecycleScope.launch {
  val listener = Courier.shared.addInboxListener(
    onMessageEvent = { message, index, feed, event ->
      if (event == InboxMessageEvent.ADDED) {
        showMyToast(message) // your own toast UI
      }
    }
  )
}
```

```dart Flutter theme={null}
// No built-in toast on Flutter: listen and show your own UI
final listener = await Courier.shared.addInboxListener(
  onMessageEvent: (message, index, feed, event) {
    if (event == InboxMessageEvent.added) {
      showMyToast(message); // your own toast UI
    }
  },
);
```

```jsx React Native theme={null}
// No built-in toast on React Native: listen and show your own UI
const listener = await Courier.shared.addInboxListener({
  onMessageEvent: (message, index, feed, event) => {
    if (event === "added") {
      showMyToast(message); // your own toast UI
    }
  },
});
```

Full SDK references: [React
DOC](/docs/sdk-libraries/courier-react-web), [Web Components
DOC](/docs/sdk-libraries/courier-web-components), [Vue
DOC](/docs/sdk-libraries/courier-vue-web), [Angular
DOC](/docs/sdk-libraries/courier-angular-web), [iOS
DOC](/docs/sdk-libraries/ios), [Android
DOC](/docs/sdk-libraries/android), [Flutter
DOC](/docs/sdk-libraries/flutter), [React Native
DOC](/docs/sdk-libraries/react-native).

## Handle clicks

A toast fires two events: one when the body is clicked, and one for each [action button
DOC](/docs/design/templates/design-studio#buttons) the message carries. Action buttons do nothing by default. You decide where they go.

![A Courier toast notification with two action buttons below the message body](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/courier-toast-action-buttons.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=483d244496cf995bd58018ab1eeea56b)

A toast with action buttons. Each button raises its own click event.

```jsx React theme={null}
<CourierToast
  onToastItemClick={({ message }) => {
    console.log("Toast clicked:", message);
  }}
  onToastItemActionClick={({ message, action }) => {
    window.open(action.href);
  }}
/>
```

```html Web Components theme={null}
<courier-toast id="my-toast"></courier-toast>

<script type="module">
  import { Courier, CourierToastDatastore } from "@trycourier/courier-ui-toast";

  const toast = document.getElementById("my-toast");

  toast.onToastItemClick(({ message }) => {
    window.open(message.actions[0].href);
  });

  toast.onToastItemActionClick(({ message, action }) => {
    window.open(action.href);
    CourierToastDatastore.shared.removeMessage(message);
  });
</script>
```

```vue Vue theme={null}
<CourierToast
  :on-toast-item-click="({ message }) => console.log('Toast clicked:', message)"
  :on-toast-item-action-click="({ action }) => window.open(action.href)"
/>
```

```ts Angular theme={null}
// <courier-toast (toastItemClick)="onClick($event)"
//                (toastItemActionClick)="onActionClick($event)"></courier-toast>

onClick({ message }: CourierToastItemClickEvent) { /* ... */ }
onActionClick({ action }: CourierToastItemActionClickEvent) { window.open(action.href); }
```

Both events carry the `InboxMessage`. The action event also carries the clicked `InboxAction`. Every callback the component accepts is in [Props
DOC](/docs/in-app/add-toasts#props) below.

> [!NOTE]
>
> Mobile has no built-in toast. Handle clicks in the UI you render from the inbox listener above.

## Props

`<CourierToast />` in React, Vue, and Angular. The web component takes the same values as
kebab-case attributes, and `courier-toast` is the element name.

| Prop | Type | Default | Description |
| - | - | - | - |
| `lightTheme` | `CourierToastTheme` | | Theme applied in light mode. |
| `darkTheme` | `CourierToastTheme` | | Theme applied in dark mode. |
| `mode` | `CourierComponentThemeMode` | `"system"` | Force light or dark instead of following the system. |
| `autoDismiss` | boolean | `false` | Dismiss each toast on a timer, with a countdown bar across the top. |
| `autoDismissTimeoutMs` | number | `5000` | How long a toast stays up when `autoDismiss` is on. |
| `dismissButton` | `"visible"`, `"hidden"`, `"hover"`, `"auto"` | `"auto"` | When the close button shows. |
| `onToastItemClick` | `(props) => void` | | Called when a toast is clicked. |
| `onToastItemActionClick` | `(props) => void` | | Called when a toast's action button is clicked. |
| `renderToastItem` | `(props) => Element` | | Replace the whole toast. See [Custom UI&#xA;DOC](/docs/in-app/customize-toasts#custom-ui). |
| `renderToastItemContent` | `(props) => Element` | | Replace the toast's content, keeping its frame. |
| `onReady` | `(ready: boolean) => void` | | Called once the component can accept messages. |
| `style` | `CSSProperties` | `position: fixed`, `width: 380px`, `top: 30px`, `right: 30px`, `z-index: 999` | Inline styles on the stack. Overriding one key keeps the rest. |

`dismissButton` defaults to `"auto"`, which means the button is always visible while
`autoDismiss` is off and appears on hover once it is on. `"hidden"` removes it, which
leaves a toast with no manual way out, so pair it with `autoDismiss`.

The web component also exposes `enableAutoDismiss`, `disableAutoDismiss`,
`setAutoDismissTimeoutMs`, `setDismissButton`, `setMode`, `setLightTheme`, and
`setDarkTheme` on the element, for hosts that hold a ref rather than re-rendering with new
props.

### What auto-dismiss actually does

**Only the top toast counts down.** The rest of the stack is held paused until it becomes
the top one, so three toasts at a 5 second timeout clear over 15 seconds rather than
together.

**Hovering anywhere on the stack pauses every countdown**, and leaving it resumes them, so
a toast a reader is part-way through doesn't vanish under the cursor. The countdown bar
pauses with it.

### Waiting for the component with onReady

A toast can arrive before the component has mounted, and a custom render function
registered too early is dropped. Both show up as toasts that never appear, or that appear
unstyled. Sign in from `onReady` when either applies.

```jsx theme={null}
const [toastReady, setToastReady] = useState(false);

useEffect(() => {
  if (toastReady) {
    courier.shared.signIn({ userId: "user_123", jwt });
  }
}, [toastReady]);

return <CourierToast onReady={setToastReady} renderToastItem={(props) => <CustomToast {...props} />} />;
```

## Show or dismiss a toast in code

`CourierToastDatastore` holds the messages the toast component shows. Add one to raise a toast without sending anything, which is the fastest way to style a toast while you build. Remove one to dismiss its toast. The datastore is a singleton in `@trycourier/courier-ui-toast`, which the React, Vue, and Angular SDKs install for you.

```js theme={null}
import { CourierToastDatastore } from "@trycourier/courier-ui-toast";

// Raise a toast locally. messageId is required.
CourierToastDatastore.shared.addMessage({
  messageId: "preview-1",
  title: "Your export is ready",
  body: "Download it from the Reports page.",
  actions: [{ content: "Open Reports", href: "/reports" }],
});

// Dismiss it
CourierToastDatastore.shared.removeMessage({ messageId: "preview-1" });
```

`removeMessage` matches on `messageId`, not object identity, so a fresh object carrying the same id dismisses the toast. A message added this way lives only in the browser, so the inbox doesn't show it and a reload clears it.

## Verify

**1. Open a screen with the toast component**

Sign in a user. Keep the app open on a screen that renders the toast component (or your mobile listener).

**2. Send a test message**

[Send a message
DOC](/docs/in-app/send-to-the-inbox) to that user on the `inbox` channel.

**3. Confirm the toast**

A toast pops up for the new message.


# Authenticate users with a JWT
Source: https://www.courier.com/docs/in-app/authenticate-users

Mint a scoped JWT on your backend and sign the user in to any Courier client SDK.

> [!NOTE]
>
> This is the auth model for every Courier client SDK. One sign-in covers Inbox, Toasts, the preference center, and mobile push tokens.

Courier's client SDKs authenticate with a **JWT** (JSON Web Token). Your backend mints a short-lived, scoped token with your Courier API key, and the SDK signs the user in with it. Inbox and Toasts read the same scopes. The preference center and mobile push each add their own. [Add an inbox
DOC](/docs/in-app/add-an-inbox) covers embedding the components first.

## How the JWT flow works

The private API key that signs a JWT stays on your server, so your backend mints every token, never client code:

**1. Your app calls your backend**

When a user signs in, your app requests a token from your backend (for example, `GET /api/courier-jwt`).

**2. Your backend calls Courier**

Your backend uses your [workspace API key](https://app.courier.com/settings/api-keys) to call the [Issue Token endpoint](/docs/api-reference/authentication/create-a-jwt) with the scopes the user needs. Keys are per [environment
DOC](/docs/workspaces/environments). Use the one matching the environment you're issuing tokens for.

**3. Your backend returns the JWT to the client**

The client passes the token to the SDK through `signIn({ userId, jwt })`.

## 1. Issue a token

Call [Create a JWT](/docs/api-reference/authentication/create-a-jwt) from your backend with your API key and a scope string:

```javascript Node.js theme={null}
const { token } = await client.auth.issueToken({
  scope: "user_id:user_123 inbox:read:messages inbox:write:events",
  expires_in: "2 days",
});
```

```python Python theme={null}
response = client.auth.issue_token(
    scope="user_id:user_123 inbox:read:messages inbox:write:events",
    expires_in="2 days",
)
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.courier.com/auth/issue-token \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "scope": "user_id:user_123 inbox:read:messages inbox:write:events",
    "expires_in": "2 days"
  }'
```

```ruby Ruby theme={null}
response = courier.auth.issue_token(
  scope: "user_id:user_123 inbox:read:messages inbox:write:events",
  expires_in: "2 days"
)
```

```go Go theme={null}
response, err := client.Auth.IssueToken(context.TODO(), courier.AuthIssueTokenParams{
  Scope:     "user_id:user_123 inbox:read:messages inbox:write:events",
  ExpiresIn: "2 days",
})
```

```java Java theme={null}
AuthIssueTokenParams params = AuthIssueTokenParams.builder()
    .scope("user_id:user_123 inbox:read:messages inbox:write:events")
    .expiresIn("2 days")
    .build();

var response = client.auth().issueToken(params);
```

```php PHP theme={null}
$response = $client->auth->issueToken(
    scope: 'user_id:user_123 inbox:read:messages inbox:write:events',
    expiresIn: '2 days',
);
```

```csharp C# theme={null}
var response = await client.Auth.IssueToken(new AuthIssueTokenParams
{
    Scope = "user_id:user_123 inbox:read:messages inbox:write:events",
    ExpiresIn = "2 days"
});
```

```bash CLI theme={null}
courier auth issue-token \
  --scope "user_id:user_123 inbox:read:messages inbox:write:events" \
  --expires-in "2 days"
```

```text MCP theme={null}
With Courier MCP, issue a two-day inbox token for user_123.
```

### Scopes

`scope` is one space-separated string. Copy the line for what you're building, and swap in your user's id.

> [!NOTE]
>
> **The `user_id` is yours, not Courier's.**\\
>
> Use whatever your app already calls this user, such as a database id or your auth provider's `sub`. Nothing has to exist in Courier first, since signing in registers the user. The same id goes in two places, `user_id:` in the scope and the `userId` you pass to `signIn`, and they have to match.

```text Inbox and Toasts theme={null}
user_id:user_123 inbox:read:messages inbox:write:events
```

```text Add the preference center theme={null}
user_id:user_123 inbox:read:messages inbox:write:events read:preferences write:preferences
```

```text Add mobile push theme={null}
user_id:user_123 inbox:read:messages inbox:write:events write:user-tokens
```

```text Everything theme={null}
user_id:user_123 inbox:read:messages inbox:write:events read:preferences write:preferences write:user-tokens read:brands
```

Every string starts with `user_id:` and the two inbox scopes. What each one grants:

| Scope | Grants |
| :- | :- |
| `user_id:user_123` | Binds the token to one user. Always required. |
| `inbox:read:messages` | Read the user's inbox messages. |
| `inbox:write:events` | Mark messages read, opened, archived. |
| `read:preferences` `write:preferences` | The embedded [preference center&#xA;DOC](/docs/in-app/add-a-preference-center). |
| `write:user-tokens` | Sync [push tokens&#xA;DOC](/docs/integrations/push/overview) from a mobile client. |
| `read:brands` | Apply a [brand&#xA;DOC](/docs/design/brands) to the rendered inbox. |

For every scope value, see the [`scope` parameter in the Issue Token API reference](/docs/api-reference/authentication/create-a-jwt#body-scope).

## 2. Sign in on the client

Signing in tells the SDK which user it is fetching messages for. Until it runs, the components render empty.

Pass the JWT to `signIn` when your app starts or the user logs in:

```jsx React highlight={9} theme={null}
import { useEffect } from "react";
import { useCourier } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    // jwt is the token your backend issued in step 1
    courier.shared.signIn({ userId, jwt });
  }, []);

  // ... render <CourierInbox /> or <CourierToast />
}
```

```html Web Components highlight={5} theme={null}
<script type="module">
  import { Courier } from "@trycourier/courier-ui-inbox";

  // jwt is the token your backend issued in step 1
  Courier.shared.signIn({ userId, jwt });
</script>
```

```vue Vue highlight={9} theme={null}
<script setup lang="ts">
import { onMounted } from "vue";
import { useCourier } from "@trycourier/courier-vue";

const courier = useCourier();

onMounted(() => {
  // jwt is the token your backend issued in step 1
  courier.shared.signIn({ userId, jwt });
});
</script>
```

```ts Angular highlight={10} theme={null}
import { Component, OnInit, inject } from "@angular/core";
import { CourierService } from "@trycourier/courier-angular";

@Component({ selector: "app-root", standalone: true, template: `...` })
export class AppComponent implements OnInit {
  private readonly courier = inject(CourierService);

  ngOnInit(): void {
    // jwt is the token your backend issued in step 1
    this.courier.signIn({ userId, jwt });
  }
}
```

```swift iOS highlight={5} theme={null}
import Courier_iOS

// jwt is the token your backend issued in step 1
func authenticate() async {
  await Courier.shared.signIn(userId: userId, accessToken: jwt)
}
```

```kotlin Android highlight={1,4} theme={null}
// signIn is a suspend function; call it from a coroutine
lifecycleScope.launch {
  // jwt is the token your backend issued in step 1
  Courier.shared.signIn(userId = userId, accessToken = jwt)
}
```

```dart Flutter highlight={3} theme={null}
// jwt is the token your backend issued in step 1
Future<void> authenticate() async {
  await Courier.shared.signIn(accessToken: jwt, userId: userId);
}
```

```jsx React Native highlight={7} theme={null}
import { useEffect } from "react";
import Courier from "@trycourier/courier-react-native";

export default function App() {
  useEffect(() => {
    // jwt is the token your backend issued in step 1
    Courier.shared.signIn({ accessToken: jwt, userId });
  }, []);

  // ... render <CourierInboxView />
}
```

## 3. Read the signed-in user

Every platform exposes the current user and a listener that fires on sign-in and sign-out. Use the listener to clear app state on sign-out, or to re-render once credentials are restored on launch.

```jsx React theme={null}
import { useCourier } from "@trycourier/courier-react";

const { auth } = useCourier();
auth.userId;  // undefined when signed out
```

```html Web Components theme={null}
<script type="module">
  import { Courier } from "@trycourier/courier-ui-inbox";

  const listener = Courier.shared.addAuthenticationListener(({ userId }) => {
    console.log(userId ?? "No user signed in");
  });

  listener.remove();
</script>
```

```vue Vue theme={null}
<script setup lang="ts">
import { useCourier } from "@trycourier/courier-vue";

const courier = useCourier();
courier.auth.value.userId;  // undefined when signed out
</script>
```

```ts Angular theme={null}
import { CourierService } from "@trycourier/courier-angular";

// auth$ emits on every sign-in and sign-out
this.courier.auth$.subscribe(({ userId }) => {
  console.log(userId ?? "No user signed in");
});
```

```swift iOS theme={null}
Task {
  let userId = await Courier.shared.userId
  let isSignedIn = await Courier.shared.isUserSignedIn

  let listener = await Courier.shared.addAuthenticationListener { userId in
    print(userId ?? "No user signed in")
  }

  listener.remove()
}
```

```kotlin Android theme={null}
val userId = Courier.shared.userId
val isSignedIn = Courier.shared.isUserSignedIn

val listener = Courier.shared.addAuthenticationListener { userId ->
  print(userId ?: "No user signed in")
}

listener.remove()
```

```dart Flutter theme={null}
final userId = await Courier.shared.userId;
final tenantId = await Courier.shared.tenantId;
final isSignedIn = await Courier.shared.isUserSignedIn;

final listener = await Courier.shared.addAuthenticationListener((userId) {
  print(userId ?? "No user signed in");
});

await listener.remove();
```

```jsx React Native theme={null}
const userId = await Courier.shared.getUserId();
const tenantId = await Courier.shared.getTenantId();
const isSignedIn = await Courier.shared.isUserSignedIn();

const listener = await Courier.shared.addAuthenticationListener({
  onUserChanged: (userId) => console.log("User changed:", userId),
});

await listener.remove();
```

> [!NOTE]
>
> On mobile, credentials **persist across app sessions**. The SDK restores the last signed-in user on launch, so no cold start needs `signIn`. Call it again only when the user changes or the token expires.

## 4. Sign out

Call `signOut` when the user logs out of your app. It clears stored credentials, disconnects the real-time socket, and on mobile stops associating push tokens with that user.

```jsx React theme={null}
const { auth } = useCourier();
auth.signOut();
```

```js Web Components theme={null}
Courier.shared.signOut();
```

```vue Vue theme={null}
const courier = useCourier();
courier.auth.value.signOut();
```

```ts Angular theme={null}
this.courier.signOut();
```

```swift iOS theme={null}
Task {
  await Courier.shared.signOut()
}
```

```kotlin Android theme={null}
lifecycleScope.launch {
  Courier.shared.signOut()
}
```

```dart Flutter theme={null}
await Courier.shared.signOut();
```

```jsx React Native theme={null}
await Courier.shared.signOut();
```

## 5. Refresh tokens

Set `expires_in` to match your session length, and refresh the token before it expires so an open tab keeps loading messages.

The SDKs do **not** refresh tokens. Before the current token expires, mint a new JWT on your backend and call `signIn` again with it.

> [!WARNING]
>
> `expires_in` is optional, and omitting it mints a token that **never expires**. Always set it. A leaked token with no `exp` grants that user's inbox forever. The only fix is rotating the API key that signed it.

## Connect to the EU datacenter

Every client SDK talks to Courier's **US** hosts by default. For a user whose notifications you send through the [EU datacenter
DOC](/docs/workspaces/datacenters), pass EU URLs as `apiUrls` when you sign in:

```jsx React highlight={6} theme={null}
import { getCourierApiUrlsForRegion } from "@trycourier/courier-react";

courier.shared.signIn({
  userId,
  jwt,
  apiUrls: getCourierApiUrlsForRegion("eu"),
});
```

```js Web Components highlight={6} theme={null}
import { Courier, EU_COURIER_API_URLS } from "@trycourier/courier-ui-inbox";

Courier.shared.signIn({
  userId,
  jwt,
  apiUrls: EU_COURIER_API_URLS,
});
```

```vue Vue highlight={6} theme={null}
import { getCourierApiUrlsForRegion } from "@trycourier/courier-vue";

courier.shared.signIn({
  userId,
  jwt,
  apiUrls: getCourierApiUrlsForRegion("eu"),
});
```

```ts Angular highlight={6} theme={null}
import { getCourierApiUrlsForRegion } from "@trycourier/courier-angular";

this.courier.signIn({
  userId,
  jwt,
  apiUrls: getCourierApiUrlsForRegion("eu"),
});
```

```swift iOS highlight={4} theme={null}
await Courier.shared.signIn(
  userId: userId,
  accessToken: jwt,
  apiUrls: .eu
)
```

```kotlin Android highlight={4} theme={null}
Courier.shared.signIn(
  accessToken = jwt,
  userId = userId,
  apiUrls = CourierClient.ApiUrls.eu()
)
```

```dart Flutter highlight={4} theme={null}
await Courier.shared.signIn(
  accessToken: jwt,
  userId: userId,
  apiUrls: CourierApiUrls.eu,
);
```

```jsx React Native highlight={6} theme={null}
import { getCourierApiUrlsForRegion } from "@trycourier/courier-react-native";

await Courier.shared.signIn({
  userId,
  accessToken: jwt,
  apiUrls: getCourierApiUrlsForRegion("eu"),
});
```

Creating a `CourierClient` yourself? Its constructor takes the same option:

```ts JavaScript highlight={6} theme={null}
import { CourierClient, EU_COURIER_API_URLS } from "@trycourier/courier-js";

const client = new CourierClient({
  userId,
  jwt,
  apiUrls: EU_COURIER_API_URLS,
});
```

```swift iOS highlight={4} theme={null}
let client = CourierClient(
  jwt: jwt,
  userId: userId,
  apiUrls: .eu
)
```

```kotlin Android highlight={4} theme={null}
val client = CourierClient(
  jwt = jwt,
  userId = userId,
  apiUrls = CourierClient.ApiUrls.eu()
)
```

```dart Flutter highlight={4} theme={null}
final client = CourierClient(
  jwt: jwt,
  userId: userId,
  apiUrls: CourierApiUrls.eu,
);
```

```jsx React Native highlight={6} theme={null}
import { CourierClient, getCourierApiUrlsForRegion } from "@trycourier/courier-react-native";

const client = new CourierClient({
  userId,
  jwt,
  apiUrls: getCourierApiUrlsForRegion("eu"),
});
```

The web packages re-export three helpers from `@trycourier/courier-js`:

| Helper | Returns |
| :- | :- |
| `EU_COURIER_API_URLS` | Frozen EU preset. |
| `DEFAULT_COURIER_API_URLS` | Frozen US preset, the default. |
| `getCourierApiUrlsForRegion(region)` | A mutable **copy** for `"us"` or `"eu"`, so you can override a single host. |

> [!WARNING]
>
> Mint the JWT against the **same region** as the client. For EU, your backend must call `https://api.eu.courier.com/auth/issue-token`. A US-issued token won't authenticate against EU hosts.

For the `CourierApiUrls` type shape, see [Courier JS models
DOC](/docs/sdk-libraries/courier-js-web#courierapiurls).

## Troubleshooting

**The inbox loads but shows no messages.** The connection succeeds either way, so check these four causes in order. Decode the JWT at [jwt.io](https://www.jwt.io) for the first three:

1. **`exp` is in the future.** An expired token returns an empty inbox. See [Refresh tokens](#5-refresh-tokens).
2. **`scope` includes `inbox:read:messages` and `inbox:write:events`.** Without them the connection succeeds and the feed is empty.
3. **The `user_id:` in the scope matches the `userId` you pass to `signIn`.** A mismatch reads an empty inbox belonging to whoever the token names.
4. **The `tenantId` matches the send.** A `tenantId` filters the feed, and the unread count, to that tenant. A message sent without a tenant, or in a different one, won't appear. Signing in without a `tenantId` shows only messages sent without a tenant. See [scope the inbox to a tenant
   DOC](/docs/in-app/send-to-the-inbox#scope-the-inbox-to-a-tenant).

**Preferences editor is empty or read-only.** Add `read:preferences write:preferences` to the scope string.

**Push tokens never appear on the user.** Add `write:user-tokens` to the scope string. [Set up push notifications
GUIDE](/docs/guides/set-up-mobile-push#set-up-your-app) covers the registration that follows.

**Everything 401s for an EU user.** The token and the client must be in the same datacenter. Confirm your backend mints against `https://api.eu.courier.com/auth/issue-token` and the client passes EU [`apiUrls`](#connect-to-the-eu-datacenter).

## FAQ

> **Why does the inbox connect but show no messages?**
>
> The token signed in but lacks read access. Confirm the [scope string](#scopes) includes `inbox:read:messages` and `inbox:write:events`, and that `exp` hasn't passed.

> **Do Inbox and Toasts need separate tokens?**
>
> They read the same feed, so one `signIn` with the same JWT and scopes covers both.

> **I'm on an older inbox SDK with a different auth setup.**
>
> Older SDK versions used a different authentication method. To move to JWT, see the [courier-react v8 migration guide
> DOC](/docs/sdk-libraries/courier-react-v8-migration-guide).


# Build a custom inbox
Source: https://www.courier.com/docs/in-app/build-a-custom-inbox

Swap parts of the inbox for your own renderers, or build the whole UI on the SDK's data layer.

Two levels of custom rendering, in increasing order of control.

**Replace parts** of the built-in inbox, its list item, header, or states, while it keeps managing the list, sync, and pagination. Web SDKs only. Or **build your own UI** from the message data and actions directly, which every platform supports including mobile.

Reach for the first when the default inbox is nearly right and one element isn't. Reach for the second when your app already has a list component you want to keep. [Customize the inbox
DOC](/docs/in-app/customize-the-inbox) covers theming, which handles most cases without either.

## Replace parts of the inbox

> [!NOTE]
>
> Render slots are **web SDKs only** (React, Vue, Angular, Web Components). On iOS, Android, Flutter, and React Native, use theming or build your own UI below.

Provide a renderer for any slot: `header`, `listItem`, `emptyState`, `loadingState`, `errorState`, or `paginationItem`. Each renderer receives the relevant message or state. Slots you leave out use the built-in element.

![A Courier Inbox with a custom header reading Notifications and a 2 new badge, and custom list items showing sender avatars and roles](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/inbox-custom-render.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=4c6e12b95ec5a7a7c5f0c97adcb3d6a8)

An inbox with a custom header and custom list items, while the SDK still manages the list.

```jsx React theme={null}
<CourierInbox
  renderListItem={(props) => <MyRow message={props?.message} />}
  renderHeader={(props) => <MyHeader feeds={props?.feeds} />}
  renderEmptyState={() => <MyEmptyState />}
/>
```

```js Web Components theme={null}
const inbox = document.getElementById("inbox");

// Each factory returns an HTMLElement
inbox.setListItem((props) => renderRow(props));
inbox.setHeader((props) => renderHeader(props));
inbox.setEmptyState(() => renderEmpty());
```

```vue Vue theme={null}
<template>
  <CourierInbox
    :renderListItem="(props) => renderRow(props)"
    :renderHeader="(props) => renderHeader(props)"
  />
</template>
```

```html Angular theme={null}
<courier-inbox>
  <ng-template #listItem let-props>
    <!-- your custom row; props.message is available -->
  </ng-template>
  <ng-template #header let-props>
    <!-- your custom header -->
  </ng-template>
</courier-inbox>
```

| Slot | React / Vue prop | Web component setter | Angular template |
| :- | :- | :- | :- |
| Header | `renderHeader` | `setHeader` | `#header` |
| List item | `renderListItem` | `setListItem` | `#listItem` |
| Empty state | `renderEmptyState` | `setEmptyState` | `#emptyState` |
| Loading state | `renderLoadingState` | `setLoadingState` | `#loadingState` |
| Error state | `renderErrorState` | `setErrorState` | `#errorState` |
| Pagination item | `renderPaginationItem` | `setPaginationItem` | `#paginationItem` |
| Popup menu button | `renderMenuButton` | `setMenuButton` | `#menuButton` |

The popup menu button slot exists only on the popup menu component. Every other slot works on both the inline inbox and the popup. `removeHeader()` on the web component drops the header entirely instead of replacing it.

The inbox loads the next page when the reader scrolls to the bottom, so a custom pagination item may only flash on screen.

### What each renderer receives

The header and the menu button get the feed and tab state, so a custom header can show the selected tab and its unread count. The state slots get the `datasetId` of the tab they are rendering, and the error state also gets the `error`. The list item gets `{ message, index }`.

```ts theme={null}
// Header: { feeds }. Menu button: { totalUnreadCount, feeds }.
type CourierInboxHeaderFeed = {
  feedId: string;
  title: string;
  iconSVG?: string;
  isSelected: boolean;
  tabs: {
    datasetId: string;
    title: string;
    unreadCount: number;
    isSelected: boolean;
    filter: { tags?: string[]; archived?: boolean; status?: "read" | "unread" };
  }[];
};
```

![A plain HTML button reading Open the Inbox Popup with the unread message count, in place of the default inbox icon button](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/courier-inbox-menu-button.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=3ab3027e69f8721c784106d3c518d554)

A custom popup menu button that renders the unread count as text.

```js theme={null}
const popup = document.querySelector("courier-inbox-popup-menu");

popup.setMenuButton(({ totalUnreadCount }) => {
  const button = document.createElement("button");
  button.textContent = `Notifications (${totalUnreadCount})`;
  return button;
});
```

## Build your own UI

You don't have to render `CourierInbox` at all. Every SDK exposes the message data and actions directly, so you can build the whole UI while the SDK keeps everything synced. The setup is the same everywhere:

1. Start the feed.
2. Render your own UI from the messages.
3. Toggle read (or archive) on interaction.
4. Tear down the listener when the view goes away.

The one difference is how the feed starts:

* **Web SDKs**: nothing loads automatically. Register the feeds, open the realtime connection, then load: `registerFeeds(defaultFeeds())` → `listenForUpdates()` → `load()`.
* **Mobile SDKs**: adding an inbox listener loads the first page for you, if you have [signed the user in
  DOC](/docs/in-app/add-an-inbox) first. (`refreshInbox()` is only for pull-to-refresh.)

```jsx React theme={null}
import { useEffect } from "react";
import { useCourier, defaultFeeds } from "@trycourier/courier-react"; // or "@trycourier/courier-react-17"

function CustomInbox() {
  const { inbox } = useCourier();

  // 1. Start the feed (nothing loads automatically; the hook cleans up on unmount)
  useEffect(() => {
    inbox.registerFeeds(defaultFeeds());
    inbox.listenForUpdates();
    inbox.load();
  }, []);

  // 2. Render the default feed's messages
  const messages = inbox.feeds["all_messages"]?.messages ?? [];
  return (
    <ul>
      {messages.map((message) => (
        // 3. Toggle read on tap
        <li
          key={message.messageId}
          onClick={() => (message.read ? inbox.unreadMessage(message) : inbox.readMessage(message))}
        >
          {message.title}
        </li>
      ))}
    </ul>
  );
}
```

```js Web Components theme={null}
import {
  CourierInboxDatastore,
  CourierInboxDataStoreListener,
  defaultFeeds,
  markAsRead,
  markAsUnread,
} from "@trycourier/courier-ui-inbox";

const store = CourierInboxDatastore.shared;

// 1. Subscribe, then start the feed (nothing loads automatically)
const listener = new CourierInboxDataStoreListener({
  onDataSetChange: (dataset) => render(dataset.messages), // 2. Build your own UI
});
store.addDataStoreListener(listener);
store.registerFeeds(defaultFeeds());
await store.listenForUpdates();
await store.load();

// 3. Toggle read on tap
message.read ? markAsUnread(message) : markAsRead(message);

// 4. Tear down
store.removeDataStoreListener(listener);
```

```vue Vue theme={null}
<script setup lang="ts">
import { onMounted } from "vue";
import { useCourier, defaultFeeds } from "@trycourier/courier-vue";

const { inbox } = useCourier(); // inbox is a ref

// 1. Start the feed (nothing loads automatically; the composable cleans up on unmount)
onMounted(() => {
  inbox.value.registerFeeds(defaultFeeds());
  inbox.value.listenForUpdates();
  inbox.value.load();
});

// 3. Toggle read on tap
function toggle(message) {
  message.read ? inbox.value.unreadMessage(message) : inbox.value.readMessage(message);
}
</script>

<template>
  <!-- 2. Render the default feed's messages -->
  <ul>
    <li
      v-for="message in inbox.feeds['all_messages']?.messages ?? []"
      :key="message.messageId"
      @click="toggle(message)"
    >
      {{ message.title }}
    </li>
  </ul>
</template>
```

```ts Angular theme={null}
import { Component, inject, OnInit, OnDestroy } from "@angular/core";
import { CourierService, defaultFeeds, type InboxMessage } from "@trycourier/courier-angular";

@Component({ /* ... */ })
export class CustomInbox implements OnInit, OnDestroy {
  private readonly courier = inject(CourierService);
  messages: InboxMessage[] = [];
  private sub?: { unsubscribe(): void };

  async ngOnInit() {
    // 2. Render: inbox$ emits the reactive state
    this.sub = this.courier.inbox$.subscribe(
      (state) => (this.messages = state.feeds["all_messages"]?.messages ?? [])
    );
    // 1. Start the feed (nothing loads automatically)
    this.courier.registerFeeds(defaultFeeds());
    await this.courier.listenForUpdates();
    await this.courier.load();
  }

  // 3. Toggle read on tap
  toggle(message: InboxMessage) {
    message.read ? this.courier.unreadMessage(message) : this.courier.readMessage(message);
  }

  // 4. Tear down
  ngOnDestroy() {
    this.sub?.unsubscribe();
  }
}
```

```swift iOS theme={null}
// 1. Start: adding a listener loads the first page (sign in first)
let listener = await Courier.shared.addInboxListener(
  onMessagesChanged: { messages, canPaginate, feed in
    render(messages) // 2. Build your own UI
  }
)

// 3. Toggle read on tap
if message.isRead {
  try await message.markAsUnread()
} else {
  try await message.markAsRead()
}

// 4. Tear down
listener.remove()
```

```kotlin Android theme={null}
// 1. Start: adding a listener loads the first page (sign in first).
//    addInboxListener is a suspend function; call it from a coroutine.
lifecycleScope.launch {
  val listener = Courier.shared.addInboxListener(
    onMessagesChanged = { messages, canPaginate, feed ->
      render(messages) // 2. Build your own UI
    }
  )
  // 4. Tear down when the view goes away: listener.remove()
}

// 3. Toggle read on tap
if (message.isRead) message.markAsUnread() else message.markAsRead()
```

```dart Flutter theme={null}
// 1. Start: adding a listener loads the first page (sign in first)
final listener = await Courier.shared.addInboxListener(
  onMessagesChanged: (messages, canPaginate, feed) {
    render(messages); // 2. Build your own UI
  },
);

// 3. Toggle read on tap
message.isRead ? await message.markAsUnread() : await message.markAsRead();

// 4. Tear down
await listener.remove();
```

```jsx React Native theme={null}
// 1. Start: adding a listener loads the first page (sign in first)
const listener = await Courier.shared.addInboxListener({
  onMessagesChanged: (messages, canPaginate, feed) => {
    render(messages); // 2. Build your own UI
  },
});

// 3. Toggle read on tap
message.isRead
  ? await Courier.shared.unreadMessage({ messageId: message.messageId })
  : await Courier.shared.readMessage({ messageId: message.messageId });

// 4. Tear down
await listener.remove();
```

The listener (and the web `useCourier` hook) also reports loading, errors, unread count, and pagination state. See [Data and actions](#data-and-actions) for the full surface. On the mobile SDKs and Web Components, remove the listener when your view is torn down. The React, Vue, and Angular wrappers do this for you.

## Data and actions

The pattern above uses a subset of what each SDK exposes. Here is the full surface: the **data** you read (messages, unread count, pagination state) and the **actions** you call (mark read, archive, paginate, refresh). The built-in inbox calls these for you.

On the web, read the data from the `useCourier` hook (React and Vue), the `CourierInboxDatastore` (Web Components), or the `CourierService` (Angular). On mobile, an inbox listener pushes the data to you and the actions take a `messageId`.

```jsx React theme={null}
const { inbox } = useCourier();

// DATA (values you read)

// All feeds, keyed by datasetId (each: messages + pagination state)
inbox.feeds;
// Total unread across every feed
inbox.totalUnreadCount;
// Last error, if any
inbox.error;
// Each InboxMessage: messageId, title, body, preview, actions, data,
// created, read, opened, archived, tags

// ACTIONS (functions you call)

// Mark read / unread
inbox.readMessage(message);
inbox.unreadMessage(message);
// Track click / open
inbox.clickMessage(message);
inbox.openMessage(message);
// Archive / unarchive
inbox.archiveMessage(message);
inbox.unarchiveMessage(message);
// Mark every message read
inbox.readAllMessages();
// Set the page size
inbox.setPaginationLimit(50);
// Load the next page of a feed
inbox.fetchNextPageOfMessages({ datasetId });
// Define which feeds/tabs to load
inbox.registerFeeds(feeds);
// (Re)load the feeds
inbox.load({ canUseCache: true });
// Start the realtime connection
inbox.listenForUpdates();
```

```js Web Components theme={null}
import { Courier, CourierInboxDatastore } from "@trycourier/courier-ui-inbox";
const store = CourierInboxDatastore.shared;

// DATA (values you read)

// All feeds, keyed by datasetId
store.getDatasets();
// One feed's dataset
store.getDatasetById(datasetId);
// Total unread across every feed
store.totalUnreadCount;
// React to changes
store.addDataStoreListener(listener);
// Stop reacting (cleanup)
store.removeDataStoreListener(listener);

// ACTIONS (functions you call)

// Mark read / unread
store.readMessage({ message });
store.unreadMessage({ message });
// Track click / open
store.clickMessage({ message });
store.openMessage({ message });
// Archive / unarchive
store.archiveMessage({ message });
store.unarchiveMessage({ message });
// Bulk: read all, archive all, archive read
store.readAllMessages();
store.archiveAllMessages();
store.archiveReadMessages();
// Inject a message into the store
store.addMessage(message);
// Load the next page of a feed
store.fetchNextPageOfMessages({ datasetId });
// Define which feeds/tabs to load
store.registerFeeds(feeds);
// (Re)load the feeds
store.load({ canUseCache: true });
// Badge counts without loading messages
store.loadUnreadCountsForTabs(tabIds);
// Start the realtime connection
store.listenForUpdates();
// Set the page size
Courier.shared.paginationLimit = 50;
```

```ts Vue theme={null}
const { inbox } = useCourier();
const store = inbox.value; // inbox is a ref

// DATA (values you read)

// All feeds, keyed by datasetId (each: messages + pagination state)
store.feeds;
// Total unread across every feed
store.totalUnreadCount;
// Last error, if any
store.error;

// ACTIONS (functions you call)

// Mark read / unread
store.readMessage(message);
store.unreadMessage(message);
// Track click / open
store.clickMessage(message);
store.openMessage(message);
// Archive / unarchive
store.archiveMessage(message);
store.unarchiveMessage(message);
// Mark every message read
store.readAllMessages();
// Set the page size
store.setPaginationLimit(50);
// Load the next page of a feed
store.fetchNextPageOfMessages({ datasetId });
// Define which feeds/tabs to load
store.registerFeeds(feeds);
// (Re)load the feeds
store.load({ canUseCache: true });
// Start the realtime connection
store.listenForUpdates();
```

```ts Angular theme={null}
import { inject } from "@angular/core";
import { CourierService } from "@trycourier/courier-angular";
const courier = inject(CourierService);

// DATA: subscribe to inbox$ (CourierInboxState)
courier.inbox$.subscribe((state) => {
  // All feeds, keyed by datasetId
  state.feeds;
  // Total unread across every feed
  state.totalUnreadCount;
  // Last error, if any
  state.error;
});

// ACTIONS (take a bare message, not { message })

// Mark read / unread
courier.readMessage(message);
courier.unreadMessage(message);
// Track click / open
courier.clickMessage(message);
courier.openMessage(message);
// Archive / unarchive
courier.archiveMessage(message);
courier.unarchiveMessage(message);
// Mark every message read
courier.readAllMessages();
// Set the page size
courier.setPaginationLimit(50);
// Load the next page of a feed
courier.fetchNextPageOfMessages({ datasetId });
// Define which feeds/tabs to load
courier.registerFeeds(feeds);
// (Re)load the feeds
courier.load({ canUseCache: true });
// Start the realtime connection
courier.listenForUpdates();

// For the full datastore surface (bulk archive, direct dataset reads), use
// CourierInboxDatastore.shared from "@trycourier/courier-ui-inbox":
//   store.archiveAllMessages(); store.archiveReadMessages();
//   store.getDatasets(); store.getDatasetById(datasetId); store.totalUnreadCount;
```

```swift iOS theme={null}
// Subscribe for live data
let listener = await Courier.shared.addInboxListener(
  onLoading: { isRefresh in /* spinner */ },
  onError: { error in /* handle */ },
  onUnreadCountChanged: { count in /* badge */ },
  onTotalCountChanged: { totalCount, feed in /* count */ },
  onMessagesChanged: { messages, canPaginate, feed in /* render */ },
  onPageAdded: { messages, canPaginate, isFirstPage, feed in /* append */ },
  onMessageEvent: { message, index, feed, event in /* .added / .read / .archived ... */ }
)

// DATA (values you read)

// Messages in the main feed
Courier.shared.feedMessages         // [InboxMessage]
// Messages in the archived feed
Courier.shared.archivedMessages     // [InboxMessage]
// Current page size
Courier.shared.inboxPaginationLimit // Int
// Each InboxMessage: messageId, title, body, preview, subtitle,
// isRead, isOpened, isArchived, created, actions

// ACTIONS (async throws; take a messageId)

// Mark read / unread
try await Courier.shared.readMessage(messageId)
try await Courier.shared.unreadMessage(messageId)
// Track click / open
try await Courier.shared.clickMessage(messageId)
try await Courier.shared.openMessage(messageId)
// Archive (no unarchive on iOS)
try await Courier.shared.archiveMessage(messageId)
// Mark every message read
try await Courier.shared.readAllInboxMessages()
// Set the page size
Courier.shared.setPaginationLimit(50)
// Load the next page (.feed or .archive)
try await Courier.shared.fetchNextInboxPage(.feed)
// Refresh from the server
await Courier.shared.refreshInbox()
// Stop listening (cleanup)
listener.remove()
// Or from a message instance:
// markAsRead() / markAsUnread() / markAsOpened() / markAsClicked() / markAsArchived()
```

```kotlin Android theme={null}
// Subscribe for live data (addInboxListener is a suspend function)
lifecycleScope.launch {
  val listener = Courier.shared.addInboxListener(
    onLoading = { isRefresh -> /* spinner */ },
    onError = { error -> /* handle */ },
    onUnreadCountChanged = { count -> /* badge */ },
    onTotalCountChanged = { totalCount, feed -> /* count */ },
    onMessagesChanged = { messages, canPaginate, feed -> /* render */ },
    onPageAdded = { messages, canPaginate, isFirstPage, feed -> /* append */ },
    onMessageEvent = { message, index, feed, event -> /* InboxMessageEvent.ADDED / .READ ... */ }
  )
}

// DATA (values you read)

// Messages in the main feed
Courier.shared.feedMessages          // List<InboxMessage>
// Messages in the archived feed
Courier.shared.archivedMessages      // List<InboxMessage>
// Current page size (1..100)
Courier.shared.inboxPaginationLimit
// Each InboxMessage: messageId, title, body, preview, subtitle,
// isRead, isOpened, isArchived, created, actions

// ACTIONS (suspend; take a messageId)

// Mark read / unread
Courier.shared.readMessage(messageId)
Courier.shared.unreadMessage(messageId)
// Track click / open
Courier.shared.clickMessage(messageId)
Courier.shared.openMessage(messageId)
// Archive (no unarchive on Android)
Courier.shared.archiveMessage(messageId)
// Mark every message read
Courier.shared.readAllInboxMessages()
// Set the page size
Courier.shared.inboxPaginationLimit = 50
// Load the next page (.FEED or .ARCHIVE)
Courier.shared.fetchNextInboxPage(InboxMessageFeed.FEED)
// Refresh from the server
Courier.shared.refreshInbox()
// Tear down and reconnect
Courier.shared.restartInbox()
// Stop the connection
Courier.shared.closeInbox()
// Stop listening (cleanup)
listener.remove()
// Or from a message:
// markAsRead() / markAsUnread() / markAsOpened() / markAsClicked() / markAsArchived()
// Or from one of its actions:
// message.actions?.firstOrNull()?.markAsClicked()
```

```dart Flutter theme={null}
// Subscribe for live data
final listener = await Courier.shared.addInboxListener(
  onLoading: (isRefresh) { /* spinner */ },
  onError: (error) { /* handle */ },
  onUnreadCountChanged: (count) { /* badge */ },
  onTotalCountChanged: (feed, totalCount) { /* count (note: feed first) */ },
  onMessagesChanged: (messages, canPaginate, feed) { /* render */ },
  onPageAdded: (messages, canPaginate, isFirstPage, feed) { /* append */ },
  onMessageEvent: (message, index, feed, event) { /* InboxMessageEvent.added / .read ... */ },
);

// DATA (Futures you await)

// Messages in the main feed
await Courier.shared.feedMessages;         // List<InboxMessage>
// Messages in the archived feed
await Courier.shared.archivedMessages;     // List<InboxMessage>
// Current page size (default 32)
await Courier.shared.inboxPaginationLimit;
// Each InboxMessage: messageId, title, body, preview, subtitle,
// isRead, isOpened, isArchived, created, actions

// ACTIONS (async; take a messageId)

// Mark read / unread
await Courier.shared.readMessage(messageId: id);
await Courier.shared.unreadMessage(messageId: id);
// Track click / open
await Courier.shared.clickMessage(messageId: id);
await Courier.shared.openMessage(messageId: id);
// Archive (no unarchive on Flutter)
await Courier.shared.archiveMessage(messageId: id);
// Mark every message read
await Courier.shared.readAllInboxMessages();
// Set the page size
await Courier.shared.setInboxPaginationLimit(limit: 50);
// Load the next page (InboxFeed.feed or InboxFeed.archive)
await Courier.shared.fetchNextInboxPage(feed: InboxFeed.feed);
// Refresh from the server
await Courier.shared.refreshInbox();
// Stop listening (cleanup)
await listener.remove();
// Or from a message:
// await message.markAsRead() / markAsUnread() / markAsOpened() / markAsClicked() / markAsArchived()
```

```jsx React Native theme={null}
// Subscribe for live data
const listener = await Courier.shared.addInboxListener({
  onLoading: (isRefresh) => { /* spinner */ },
  onError: (error) => { /* handle */ },
  onUnreadCountChanged: (count) => { /* badge */ },
  onTotalCountChanged: (totalCount, feed) => { /* count */ },
  onMessagesChanged: (messages, canPaginate, feed) => { /* render */ },
  onPageAdded: (messages, canPaginate, isFirstPage, feed) => { /* append */ },
  onMessageEvent: (message, index, feed, event) => { /* "added" | "read" | "archived" ... */ },
});

// DATA (values you read)

// Current page size (default 32)
await Courier.shared.getInboxPaginationLimit();
// Feed messages arrive via the listener's onMessagesChanged / onPageAdded
// Each InboxMessage: messageId, title, body, preview, subtitle,
// isRead, isOpened, isArchived, created, actions

// ACTIONS (async; take { messageId })

// Mark read / unread
await Courier.shared.readMessage({ messageId });
await Courier.shared.unreadMessage({ messageId });
// Track click / open
await Courier.shared.clickMessage({ messageId });
await Courier.shared.openMessage({ messageId });
// Archive (no unarchive on React Native)
await Courier.shared.archiveMessage({ messageId });
// Mark every message read
await Courier.shared.readAllInboxMessages();
// Set the page size
await Courier.shared.setInboxPaginationLimit(50);
// Load the next page ("feed" or "archive")
await Courier.shared.fetchNextPageOfMessages({ inboxMessageFeed: "feed" });
// Refresh from the server
await Courier.shared.refreshInbox();
// Stop listening (cleanup)
await listener.remove();
// Or from a message:
// await message.markAsRead() / markAsUnread() / markAsOpened() / markAsClicked() / markAsArchived()
```


# Customize the preference center
Source: https://www.courier.com/docs/in-app/customize-preferences

Theme the preferences component or build your own UI on the client methods behind it.

[Add a preference center
DOC](/docs/in-app/add-a-preference-center) covers embedding it. Theme it or build your own UI on the same methods, below.

## Theme

Theme the preferences center with `lightTheme` / `darkTheme` (a `CourierPreferencesTheme`). Set `mode` to `"light"`, `"dark"`, or `"system"`.

The default is `"system"`, which follows the user's OS setting.

![The Courier preferences center with a custom purple theme applied to its topic toggles and channel checkboxes](https://mintcdn.com/courier-4f1f25dc/Ia7FGvhsFU_5CtOa/assets/preferences-theme.webp?fit=max\&auto=format\&n=Ia7FGvhsFU_5CtOa\&q=85\&s=dd2922b0b7016216719db53e6cb53b1d)

The Courier preferences center with a custom theme.

```jsx React highlight={3-4,6} theme={null}
import { CourierPreferences } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

const lightTheme = { /* CourierPreferencesTheme */ };
const darkTheme = { /* CourierPreferencesTheme */ };

<CourierPreferences lightTheme={lightTheme} darkTheme={darkTheme} mode="system" />;
```

```html Web Components highlight={7-8} theme={null}
<courier-preferences id="preferences"></courier-preferences>

<script type="module">
  import { Courier } from "@trycourier/courier-ui-preferences";

  const preferences = document.getElementById("preferences");
  preferences.setLightTheme({ /* CourierPreferencesTheme */ });
  preferences.setDarkTheme({ /* CourierPreferencesTheme */ });
</script>
```

```vue Vue highlight={4-5,9} theme={null}
<script setup lang="ts">
import { CourierPreferences } from "@trycourier/courier-vue";

const lightTheme = { /* CourierPreferencesTheme */ };
const darkTheme = { /* CourierPreferencesTheme */ };
</script>

<template>
  <CourierPreferences :lightTheme="lightTheme" :darkTheme="darkTheme" mode="system" />
</template>
```

```ts Angular highlight={8,11-12} theme={null}
import { Component } from "@angular/core";
import { CourierPreferencesComponent, CourierPreferencesTheme } from "@trycourier/courier-angular";

@Component({
  selector: "app-preferences",
  standalone: true,
  imports: [CourierPreferencesComponent],
  template: `<courier-preferences [lightTheme]="lightTheme" [darkTheme]="darkTheme" mode="system"></courier-preferences>`,
})
export class PreferencesComponent {
  lightTheme: CourierPreferencesTheme = { /* ... */ };
  darkTheme: CourierPreferencesTheme = { /* ... */ };
}
```

```swift iOS highlight={4-5,11-12} theme={null}
// UIKit
let preferences = CourierPreferences(
  mode: .channels(CourierUserPreferencesChannel.allCases),
  lightTheme: CourierPreferencesTheme(/* ... */),
  darkTheme: CourierPreferencesTheme(/* ... */)
)

// SwiftUI
CourierPreferencesView(
  mode: .channels(CourierUserPreferencesChannel.allCases),
  lightTheme: CourierPreferencesTheme(/* ... */),
  darkTheme: CourierPreferencesTheme(/* ... */)
)
```

```kotlin Android highlight={4-5} theme={null}
// `mode` and the themes are properties on the view, not constructor arguments
val preferences = findViewById<CourierPreferences>(R.id.courierPreferences)
preferences.mode = CourierPreferences.Mode.Channels(CourierPreferenceChannel.allCases)
preferences.lightTheme = CourierPreferencesTheme(/* ... */)
preferences.darkTheme = CourierPreferencesTheme(/* ... */)
```

```dart Flutter highlight={3-4} theme={null}
CourierPreferences(
  mode: ChannelsMode(channels: CourierUserPreferencesChannel.allCases),
  lightTheme: CourierPreferencesTheme(/* ... */),
  darkTheme: CourierPreferencesTheme(/* ... */),
);
```

```jsx React Native theme={null}
<CourierPreferencesView theme={{ light: { /* ... */ }, dark: { /* ... */ } }} />;
```

On the web the theme is a `CourierPreferencesTheme`, identical across React, Vue, Angular, and the Web Components, so it is documented once below. The native SDKs have their own: [iOS
DOC](/docs/sdk-libraries/ios#preferences-theme), [Android
DOC](/docs/sdk-libraries/android#preferences-theme), [Flutter
DOC](/docs/sdk-libraries/flutter#preferences-theme), and [React Native
DOC](/docs/sdk-libraries/react-native#preferences-theme).

### CourierPreferencesTheme reference

Every property is optional. Set `primaryColor` alone and it carries the accent through the toggles, radios, and chips, which is usually the whole change.

```ts theme={null}
type CourierPreferencesTheme = {
  primaryColor?: string;             // accent, defaults to the inbox blue
  title?: FontTheme;                 // the page heading
  subtitle?: FontTheme;              // the line under it
  container?: { font?: FontTheme };  // inherited by everything inside

  loading?: {
    animation?: {
      barColor?: string;
      barHeight?: string;
      barBorderRadius?: string;
      duration?: string;             // one shimmer cycle, e.g. '2s'
    };
  };

  // error and empty take the same shape
  error?: InfoStateTheme;
  empty?: InfoStateTheme;

  section?: {
    title?: FontTheme;
    description?: FontTheme;
    backgroundColor?: string;
  };

  topic?: {
    backgroundColor?: string;
    border?: string;
    borderRadius?: string;
    title?: FontTheme;
    description?: FontTheme;
    statusLabel?: FontTheme;
    toggle?: {
      trackColor?: string;
      trackActiveColor?: string;
      thumbColor?: string;
      borderRadius?: string;
    };
  };

  digest?: {
    font?: FontTheme;                // unselected schedule options
    selectedFont?: FontTheme;
    iconColor?: string;              // the trailing calendar icon
    radio?: {
      ringColor?: string;            // unselected ring
      checkedColor?: string;         // selected ring and inner dot
      font?: FontTheme;
      selectedFont?: FontTheme;
    };
  };

  channelChip?: {
    font?: FontTheme;
    selectedFont?: FontTheme;
    divider?: string;                // CSS border shorthand, above the chips
    checkbox?: {
      checkedColor?: string;         // border and fill when checked
      font?: FontTheme;
      selectedFont?: FontTheme;
    };
  };
};

type FontTheme = { family?: string; weight?: string; size?: string; color?: string };

type InfoStateTheme = {
  title?: { text?: string; font?: FontTheme };
  button?: {
    text?: string;                   // 'Retry' on the error state by default
    font?: FontTheme;
    backgroundColor?: string;
    hoverBackgroundColor?: string;
    border?: string;
    borderRadius?: string;
  };
};
```

**This isn't the same shape as the inbox theme.** Preferences is a flat set of regions
(`section`, `topic`, `digest`, `channelChip`) with a single `primaryColor` on top, while
the inbox theme is a `popup` and `inbox` tree. A theme object written for one isn't
partially valid for the other. It applies nothing.

Two fields exist but do nothing today: `loading.font`, kept for compatibility because the
loading state renders as a skeleton, and the deprecated `CourierPreferencesStatusTheme`.

## Custom UI

The preferences component doesn't take render slots yet. To render preferences in your own UI, read and write topics through the preferences client. The same methods exist on every platform. Web frameworks expose them through `useCourier()` (React/Vue) or the injected service (Angular). Everywhere else uses `Courier.shared.client.preferences`:

```jsx React theme={null}
import { useCourier } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

const { preferences } = useCourier();

// Read the user's topics, then write a change (client is set after signIn)
const { items } = await preferences.getUserPreferences();

await preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["inbox", "email"],
});
```

```js Web Components theme={null}
// Read the user's topics, then write a change (client is set after signIn)
const { items } = await Courier.shared.client?.preferences.getUserPreferences();

await Courier.shared.client?.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["inbox", "email"],
});
```

```ts Vue theme={null}
import { useCourier } from "@trycourier/courier-vue";

// `preferences` is plain (no .value)
const { preferences } = useCourier();

const { items } = await preferences.getUserPreferences();

await preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["inbox", "email"],
});
```

```ts Angular theme={null}
import { inject } from "@angular/core";
import { CourierService } from "@trycourier/courier-angular";

const courier = inject(CourierService);

const { items } = await courier.getUserPreferences();

await courier.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["inbox", "email"],
});
```

```swift iOS theme={null}
// `client` is available after signIn: Courier.shared.client
let prefs = try await client.preferences.getUserPreferences(paginationCursor: nil)

try await client.preferences.putUserPreferenceTopic(
  topicId: "TOPIC_ID",
  status: .optedIn,
  hasCustomRouting: true,
  customRouting: [.push]
)
```

```kotlin Android theme={null}
// `client` is available after signIn: Courier.shared.client
val prefs = client.preferences.getUserPreferences(paginationCursor = null)

client.preferences.putUserPreferenceTopic(
  topicId = "TOPIC_ID",
  status = CourierPreferenceStatus.OPTED_IN,
  hasCustomRouting = true,
  customRouting = listOf(CourierPreferenceChannel.PUSH)
)
```

```dart Flutter theme={null}
// Await the client, available after signIn
final client = await Courier.shared.client;

final prefs = await client.preferences.getUserPreferences(paginationCursor: null);

await client.preferences.putUserPreferenceTopic(
  topicId: "TOPIC_ID",
  status: CourierUserPreferencesStatus.optedIn,
  hasCustomRouting: true,
  customRouting: [CourierUserPreferencesChannel.push],
);
```

```typescript React Native theme={null}
// Get the client, available after signIn
const client = await Courier.shared.getClient();

const prefs = await client.preferences.getUserPreferences({
  paginationCursor: undefined,
});

await client.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: CourierUserPreferencesStatus.OptedIn,
  hasCustomRouting: true,
  customRouting: [CourierUserPreferencesChannel.Push],
});
```

See your platform's SDK reference for the exact signatures.

## Methods behind the component

The component reads and writes through `courier.shared.preferences`, so a UI you build
yourself calls the same client. `useCourier()` returns the client in React.

| Method | Returns |
| - | - |
| `getUserPreferences({ paginationCursor? })` | `CourierUserPreferences`, the user's topics and their statuses. |
| `getUserPreferenceTopic({ topicId })` | `CourierUserPreferencesTopic` for one topic. |
| `putUserPreferenceTopic({ topicId, status, hasCustomRouting, customRouting, digestSchedule? })` | The updated topic. |
| `getPreferencePage({ accountId?, brandId?, draft? })` | `CourierPreferencePage`, the published section and topic layout, or the draft. |
| `getDigestSchedules({ topicId })` | The digest schedule options a topic offers. |

**`putUserPreferenceTopic` replaces the topic's routing rather than merging into it.** Send
`hasCustomRouting` and the full `customRouting` array together, because omitting a channel
removes it.

```tsx theme={null}
const courier = useCourier();

const prefs = await courier.shared.preferences.getUserPreferences();
await courier.shared.preferences.putUserPreferenceTopic({
  topicId: "order-updates",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["email"],
});
```


# Customize the inbox
Source: https://www.courier.com/docs/in-app/customize-the-inbox

Theme the inbox, handle clicks and actions, or replace parts of the UI.

The inbox ships with a default look and is fully themeable. [Add an inbox
DOC](/docs/in-app/add-an-inbox) covers embedding it first.

## Theme

Theme the inbox with `lightTheme` / `darkTheme` (a `CourierInboxTheme`), and set `mode` to `"light"`, `"dark"`, or `"system"`. The default is `"system"`, which follows the user's OS setting.

![The Courier Inbox with a custom purple theme applied to its unread count badge, unread dots, and action buttons](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/inbox-theme.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=38d817f4fa2390404ab22ade2d22f612)

A Courier Inbox with a custom theme.

```jsx React highlight={3-4,6} theme={null}
import { CourierInbox } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

const lightTheme = { /* CourierInboxTheme */ };
const darkTheme = { /* CourierInboxTheme */ };

<CourierInbox lightTheme={lightTheme} darkTheme={darkTheme} mode="system" />;
```

```html Web Components highlight={7-8} theme={null}
<courier-inbox id="inbox"></courier-inbox>

<script type="module">
  import { Courier } from "@trycourier/courier-ui-inbox";

  const inbox = document.getElementById("inbox");
  inbox.setLightTheme({ /* CourierInboxTheme */ });
  inbox.setDarkTheme({ /* CourierInboxTheme */ });
</script>
```

```vue Vue highlight={4-5,9} theme={null}
<script setup lang="ts">
import { CourierInbox } from "@trycourier/courier-vue";

const lightTheme = { /* CourierInboxTheme */ };
const darkTheme = { /* CourierInboxTheme */ };
</script>

<template>
  <CourierInbox :lightTheme="lightTheme" :darkTheme="darkTheme" mode="system" />
</template>
```

```ts Angular highlight={8,11-12} theme={null}
import { Component } from "@angular/core";
import { CourierInboxComponent, CourierInboxTheme } from "@trycourier/courier-angular";

@Component({
  selector: "app-inbox",
  standalone: true,
  imports: [CourierInboxComponent],
  template: `<courier-inbox [lightTheme]="lightTheme" [darkTheme]="darkTheme" mode="system"></courier-inbox>`,
})
export class InboxComponent {
  lightTheme: CourierInboxTheme = { /* ... */ };
  darkTheme: CourierInboxTheme = { /* ... */ };
}
```

```swift iOS highlight={3-4,9-10} theme={null}
// UIKit
let inbox = CourierInbox(
  lightTheme: CourierInboxTheme(/* ... */),
  darkTheme: CourierInboxTheme(/* ... */)
)

// SwiftUI
CourierInboxView(
  lightTheme: CourierInboxTheme(/* ... */),
  darkTheme: CourierInboxTheme(/* ... */)
)
```

```kotlin Android highlight={3-4,8-9} theme={null}
// Jetpack Compose
CourierInbox(
  lightTheme = CourierInboxTheme(/* ... */),
  darkTheme = CourierInboxTheme(/* ... */)
)

// Views: set the properties on the CourierInbox view
inbox.lightTheme = CourierInboxTheme(/* ... */)
inbox.darkTheme = CourierInboxTheme(/* ... */)
```

```dart Flutter highlight={2-3} theme={null}
CourierInbox(
  lightTheme: CourierInboxTheme(/* ... */),
  darkTheme: CourierInboxTheme(/* ... */),
);
```

```jsx React Native theme={null}
<CourierInboxView theme={{ light: { /* ... */ }, dark: { /* ... */ } }} />;
```

On React, Vue, and Angular the theme is a prop. On iOS, Android, and Flutter it is a constructor argument. On the web component, call `setLightTheme` / `setDarkTheme`, or set the `light-theme` / `dark-theme` attributes with a JSON string.

**Full theme reference.** The web theme object (`CourierInboxTheme`) is identical across React, Vue, Angular, and the Web Components, so it is documented once in [the reference below
DOC](/docs/in-app/customize-the-inbox#courierinboxtheme-reference). The native SDKs have their own: [iOS
DOC](/docs/sdk-libraries/ios#inbox-theme), [Android
DOC](/docs/sdk-libraries/android#inbox-theme), [Flutter
DOC](/docs/sdk-libraries/flutter#inbox-theme), and [React Native
DOC](/docs/sdk-libraries/react-native#inbox-theme).

### Start from a default theme

The web SDKs export the two themes they ship, `defaultLightTheme` and `defaultDarkTheme`,
plus `mergeTheme` to layer your overrides onto one of them.

```jsx theme={null}
import { defaultLightTheme, mergeTheme, type CourierInboxTheme } from "@trycourier/courier-react";

const overrides: CourierInboxTheme = {
  inbox: { list: { item: { unreadIndicatorColor: "#8B5CF6" } } },
};

// mergeTheme takes the MODE, not a theme object
const theme = mergeTheme("light", overrides);
```

**`mergeTheme` takes a mode string, `"light"` or `"dark"`, as its first argument.** It picks
the matching default itself. Passing `defaultLightTheme` there type-checks against nothing
useful and merges onto the dark defaults, which shows up as a theme that looks right in one
mode and wrong in the other.

Merging isn't required. A theme passed straight to `lightTheme` already merges over the
defaults field by field, so reach for `mergeTheme` only when you need the resolved object,
such as reading a default colour to compute another.

### CourierInboxTheme reference

Every property is optional, and the object is identical on every web SDK.

```typescript theme={null}
export type CourierInboxTheme = {
  popup?: {
    button?: {
      icon?: { color?: string; svg?: string };
      backgroundColor?: string;
      hoverBackgroundColor?: string;
      activeBackgroundColor?: string;
      unreadDotIndicator?: {
        backgroundColor?: string;
        borderRadius?: string;
        height?: string;
        width?: string;
      };
    };
    window?: {
      backgroundColor?: string;
      borderRadius?: string;
      border?: string;
      shadow?: string;
      animation?: {
        transition?: string;
        initialTransform?: string;
        visibleTransform?: string;
      };
    };
  };
  inbox?: {
    header?: {
      backgroundColor?: string;
      shadow?: string;
      border?: string;
      feeds?: {
        button?: {
          selectedFeedIconColor?: string;
          font?: { family?: string; weight?: string; size?: string; color?: string };
          changeFeedIcon?: { color?: string; svg?: string };
          unreadCountIndicator?: {
            font?: { family?: string; weight?: string; size?: string; color?: string };
            backgroundColor?: string;
            borderRadius?: string;
            padding?: string;
          };
          hoverBackgroundColor?: string;
          activeBackgroundColor?: string;
          transition?: string;
        };
        menu?: {
          backgroundColor?: string;
          border?: string;
          borderRadius?: string;
          shadow?: string;
          animation?: {
            transition?: string;
            initialTransform?: string;
            visibleTransform?: string;
          };
          list?: {
            font?: { family?: string; weight?: string; size?: string; color?: string };
            selectedIcon?: { color?: string; svg?: string };
            hoverBackgroundColor?: string;
            activeBackgroundColor?: string;
            divider?: string;
          };
        };
        tabs?: {
          borderRadius?: string | {
            topLeft?: string;
            topRight?: string;
            bottomLeft?: string;
            bottomRight?: string;
          };
          transition?: string;
          default?: {
            backgroundColor?: string;
            hoverBackgroundColor?: string;
            activeBackgroundColor?: string;
            font?: { family?: string; weight?: string; size?: string; color?: string };
            indicatorColor?: string;
            indicatorHeight?: string;
            unreadIndicator?: {
              font?: { family?: string; weight?: string; size?: string; color?: string };
              backgroundColor?: string;
              borderRadius?: string;
              padding?: string;
            };
          };
          selected?: {
            backgroundColor?: string;
            hoverBackgroundColor?: string;
            activeBackgroundColor?: string;
            font?: { family?: string; weight?: string; size?: string; color?: string };
            indicatorColor?: string;
            indicatorHeight?: string;
            unreadIndicator?: {
              font?: { family?: string; weight?: string; size?: string; color?: string };
              backgroundColor?: string;
              borderRadius?: string;
              padding?: string;
            };
          };
        };
      };
      tabs?: {
        borderRadius?: string | {
          topLeft?: string;
          topRight?: string;
          bottomLeft?: string;
          bottomRight?: string;
        };
        transition?: string;
        default?: {
          backgroundColor?: string;
          hoverBackgroundColor?: string;
          activeBackgroundColor?: string;
          font?: { family?: string; weight?: string; size?: string; color?: string };
          indicatorColor?: string;
          indicatorHeight?: string;
          unreadIndicator?: {
            font?: { family?: string; weight?: string; size?: string; color?: string };
            backgroundColor?: string;
            borderRadius?: string;
            padding?: string;
          };
        };
        selected?: {
          backgroundColor?: string;
          hoverBackgroundColor?: string;
          activeBackgroundColor?: string;
          font?: { family?: string; weight?: string; size?: string; color?: string };
          indicatorColor?: string;
          indicatorHeight?: string;
          unreadIndicator?: {
            font?: { family?: string; weight?: string; size?: string; color?: string };
            backgroundColor?: string;
            borderRadius?: string;
            padding?: string;
          };
        };
      };
      actions?: {
        button?: {
          icon?: { color?: string; svg?: string };
          backgroundColor?: string;
          hoverBackgroundColor?: string;
          activeBackgroundColor?: string;
        };
        markAllRead?: { icon?: { color?: string; svg?: string }; text?: string };
        archiveAll?: { icon?: { color?: string; svg?: string }; text?: string };
        archiveRead?: { icon?: { color?: string; svg?: string }; text?: string };
        animation?: {
          transition?: string;
          initialTransform?: string;
          visibleTransform?: string;
        };
        menu?: {
          backgroundColor?: string;
          border?: string;
          borderRadius?: string;
          shadow?: string;
          animation?: {
            transition?: string;
            initialTransform?: string;
            visibleTransform?: string;
          };
          list?: {
            font?: { family?: string; weight?: string; size?: string; color?: string };
            selectedIcon?: { color?: string; svg?: string };
            hoverBackgroundColor?: string;
            activeBackgroundColor?: string;
            divider?: string;
          };
        };
      };
    };
    list?: {
      backgroundColor?: string;
      scrollbar?: {
        trackBackgroundColor?: string;
        thumbColor?: string;
        thumbHoverColor?: string;
        width?: string;
        height?: string;
        borderRadius?: string;
      };
      item?: {
        unreadIndicatorColor?: string;
        backgroundColor?: string;
        hoverBackgroundColor?: string;
        activeBackgroundColor?: string;
        transition?: string;
        title?: { family?: string; weight?: string; size?: string; color?: string };
        subtitle?: { family?: string; weight?: string; size?: string; color?: string };
        time?: { family?: string; weight?: string; size?: string; color?: string };
        archiveIcon?: { color?: string; svg?: string };
        divider?: string;
        actions?: {
          backgroundColor?: string;
          hoverBackgroundColor?: string;
          activeBackgroundColor?: string;
          border?: string;
          borderRadius?: string;
          shadow?: string;
          font?: { family?: string; weight?: string; size?: string; color?: string };
        };
        menu?: {
          enabled?: boolean;
          backgroundColor?: string;
          border?: string;
          borderRadius?: string;
          shadow?: string;
          animation?: {
            transition?: string;
            initialTransform?: string;
            visibleTransform?: string;
          };
          longPress?: { displayDuration?: number; vibrationDuration?: number };
          item?: {
            hoverBackgroundColor?: string;
            activeBackgroundColor?: string;
            borderRadius?: string;
            read?: { color?: string; svg?: string };
            unread?: { color?: string; svg?: string };
            archive?: { color?: string; svg?: string };
            unarchive?: { color?: string; svg?: string };
          };
        };
      };
    };
    loading?: {
      animation?: {
        barColor?: string;
        barHeight?: string;
        barBorderRadius?: string;
        duration?: string;
      };
      divider?: string;
    };
    empty?: {
      title?: {
        font?: { family?: string; weight?: string; size?: string; color?: string };
        text?: string;
      };
      button?: {
        font?: { family?: string; weight?: string; size?: string; color?: string };
        text?: string;
        shadow?: string;
        border?: string;
        borderRadius?: string;
        backgroundColor?: string;
        hoverBackgroundColor?: string;
        activeBackgroundColor?: string;
      };
    };
    error?: {
      title?: {
        font?: { family?: string; weight?: string; size?: string; color?: string };
        text?: string;
      };
      button?: {
        font?: { family?: string; weight?: string; size?: string; color?: string };
        text?: string;
        shadow?: string;
        border?: string;
        borderRadius?: string;
        backgroundColor?: string;
        hoverBackgroundColor?: string;
        activeBackgroundColor?: string;
      };
    };
  };
};
```

## Handle interaction

Respond to interactions with your own callbacks instead of the SDK's default navigation. Every platform exposes the same two interactions:

* **Message click** fires when a user taps a message. Receives the `message` and its `index`.
* **Action click** fires when a user taps a message's action button. Receives the tapped `action` alongside the `message` and `index`.

```jsx React theme={null}
<CourierInbox
  onMessageClick={({ message, index }) => openInApp(message)}
  onMessageActionClick={({ message, action, index }) => handleAction(message, action)}
/>
```

```js Web Components theme={null}
const inbox = document.getElementById("inbox");

inbox.onMessageClick(({ message, index }) => openInApp(message));
inbox.onMessageActionClick(({ message, action, index }) => handleAction(message, action));

// Or listen for the equivalent DOM events (detail carries the same payload):
// inbox.addEventListener("message-click", (e) => openInApp(e.detail.message));
// inbox.addEventListener("message-action-click", (e) => handleAction(e.detail.message, e.detail.action));
```

```vue Vue theme={null}
<template>
  <CourierInbox
    :onMessageClick="({ message, index }) => openInApp(message)"
    :onMessageActionClick="({ message, action, index }) => handleAction(message, action)"
  />
</template>
```

```html Angular theme={null}
<courier-inbox
  (messageClick)="openInApp($event.message)"
  (messageActionClick)="handleAction($event.message, $event.action)">
</courier-inbox>
```

```swift iOS theme={null}
// UIKit (CourierInbox) and SwiftUI (CourierInboxView) take the same callbacks
CourierInboxView(
  didClickInboxMessageAtIndex: { message, index in openInApp(message) },
  didClickInboxActionForMessageAtIndex: { action, message, index in handleAction(message, action) }
)
```

```kotlin Android theme={null}
inbox.setOnClickMessageListener { message, index -> openInApp(message) }
inbox.setOnClickActionListener { action, message, index -> handleAction(message, action) }
```

```dart Flutter theme={null}
CourierInbox(
  onMessageClick: (message, index) => openInApp(message),
  onActionClick: (action, message, index) => handleAction(message, action),
);
```

```jsx React Native theme={null}
<CourierInboxView
  onClickInboxMessageAtIndex={(message, index) => openInApp(message)}
  onClickInboxActionForMessageAtIndex={(action, message, index) => handleAction(message, action)}
/>
```

The callback names differ by platform but the payloads line up. React, Vue, and Angular deliver these as props (`onMessage*`) or outputs (`messageClick`). The payload is a single object: `{ message, index }`, or `{ message, action, index }` for actions. The web component exposes matching `onMessage*` methods, or `message-*` DOM events with the same payload on `event.detail`. On iOS, Android, Flutter, and React Native they are constructor arguments, view parameters, or setters, with positional arguments. **Action click passes the `action` first**, then the `message` and `index`.

### Long press

Every platform reports a long press, web included. It fires only on devices that send
touch events, so a desktop pointer never triggers it and you still need a click handler
for the same intent.

```jsx React theme={null}
<CourierInbox onMessageLongPress={({ message, index }) => showActions(message)} />
```

```js Web Components theme={null}
const inbox = document.getElementById("inbox");

inbox.onMessageLongPress(({ message, index }) => showActions(message));
```

```vue Vue theme={null}
<template>
  <CourierInbox :onMessageLongPress="({ message, index }) => showActions(message)" />
</template>
```

```html Angular theme={null}
<courier-inbox (messageLongPress)="showActions($event.message)"></courier-inbox>
```

```swift iOS theme={null}
CourierInboxView(
  didLongPressInboxMessageAtIndex: { message, index in message.markAsArchived() }
)
```

```kotlin Android theme={null}
// Jetpack Compose takes it as an argument
CourierInbox(
  onLongPressMessageListener = { message, index -> message.markAsArchived() }
)

// On the XML view, it is a setter
inbox.setOnLongPressMessageListener { message, index -> message.markAsArchived() }
```

The payload matches message click: an object on the web SDKs, positional arguments on
mobile. Both popup menu components take the same handler.

**On the web, long press depends on the message menu being enabled.** The gesture opens
the per-message action menu, and the handler runs as part of that. A theme that sets
`inbox.list.item.menu.enabled` to `false` suppresses the gesture, so the callback doesn't
fire. Two theme fields tune it:

| Field | Default | What it does |
| - | - | - |
| `inbox.list.item.menu.longPress.displayDuration` | `4000` | How long the menu stays open, in milliseconds. |
| `inbox.list.item.menu.longPress.vibrationDuration` | `50` | Haptic length, in milliseconds. Ignored where `navigator.vibrate` is unavailable. |

The hold threshold is 650ms and isn't themeable. A recognized long press suppresses the
click that would otherwise follow it, so the two handlers never both run.

### Scroll

iOS and Android report the list's scroll offset, so you can shrink a header or hide a
badge as the reader moves. The web SDKs have no equivalent: listen on the scrolling
element yourself.

```swift iOS theme={null}
CourierInboxView(
  didScrollInbox: { scrollView in header.collapse(scrollView.contentOffset.y) }
)
```

```kotlin Android theme={null}
// Jetpack Compose takes it as an argument
CourierInbox(
  onScrollInboxListener = { offsetInDp -> header.collapse(offsetInDp) }
)

// On the XML view, it is a setter
inbox.setOnScrollInboxListener { offsetInDp -> header.collapse(offsetInDp) }
```

The offset is a `UIScrollView` on iOS and a dp value on Android.

## Header and message actions

The web inbox carries two sets of built-in actions. The header menu marks or archives in bulk, and each message has its own read and archive toggles. `setActions()` picks the header actions and `setListItemActions()` picks the per-message ones. Each entry can override its icon, and a header action can override its label.

```js theme={null}
const inbox = document.getElementById("inbox");

// Header menu: only "Mark all read", with a custom label
inbox.setActions([
  { id: "readAll", text: "Mark everything read" },
]);

// Per-message toggles: read/unread only, no archive
inbox.setListItemActions([
  { id: "read_unread" },
]);
```

| Set | Action ids | Override fields |
| - | - | - |
| Header, `setActions()` | `readAll`, `archiveRead`, `archiveAll` | `iconSVG`, `text` |
| Message, `setListItemActions()` | `read_unread`, `archive_unarchive` | `readIconSVG`, `unreadIconSVG`, `archiveIconSVG`, `unarchiveIconSVG` |

An empty array removes every action in that set. The defaults are all of them, returned by `defaultActions()` and `defaultListItemActions()`, which every web SDK exports so you can start from the full list and filter it. On React, Vue, and Angular, call the two setters through a ref to the underlying element.

## Custom UI

Theming changes how the built-in inbox looks. To change what it renders, see [Build a custom inbox UI
DOC](/docs/in-app/build-a-custom-inbox). It covers both levels: replacing individual slots such as the list item or header, and reading the message data and actions to build the UI yourself.

## FAQ

> **How do I match the inbox to my brand?**
>
> Supply a `lightTheme` and `darkTheme` as `CourierInboxTheme` values and set colors, typography, and spacing there. See [Theme](#theme) and your platform's SDK reference for the full field list.

> **Can I force light or dark instead of following the OS?**
>
> Set `mode` to `"light"` or `"dark"`. Leave it as `"system"` (the default) to follow the user's OS setting. See [Theme](#theme).

> **Can I render my own message rows?**
>
> See [Custom UI](#custom-ui): replace parts of the built-in inbox on the web SDKs, or build the whole UI yourself on any platform.

> **What is the difference between replacing parts and building my own UI?**
>
> [Replacing parts
> DOC](/docs/in-app/build-a-custom-inbox#replace-parts-of-the-inbox) keeps the built-in inbox and swaps individual slots, on the web SDKs only. [Building your own UI
> DOC](/docs/in-app/build-a-custom-inbox#build-your-own-ui) replaces the whole thing and works on every platform, including mobile.

> **Can I replace parts of the inbox on mobile?**
>
> Not yet, that is a web-SDK feature. On mobile, theme the built-in component or [build your own UI
> DOC](/docs/in-app/build-a-custom-inbox#build-your-own-ui) from the listener.

> **Do I still get real-time sync with a custom UI?**
>
> The SDK keeps the feed synced and calls your renderer or listener on every change. See [How the inbox behaves
> DOC](/docs/in-app/how-the-inbox-behaves).


# Customize toasts
Source: https://www.courier.com/docs/in-app/customize-toasts

Theme toasts or replace the toast item with your own component.

[Add toasts
DOC](/docs/in-app/add-toasts) covers rendering them. Toasts are a web component, so theming and custom rendering are web-only.

## Theme

Theme toasts with `lightTheme` / `darkTheme` (a `CourierToastTheme`). Set `mode` to `"light"`, `"dark"`, or `"system"`. The default is `"system"`, which follows the user's OS setting.

![A Courier toast with a custom purple theme applied to its action buttons](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/toast-theme.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=22b5e2ae9ff8bbc7e82dd97a87f474b0)

A Courier toast with a custom theme.

```jsx React highlight={3-4,6} theme={null}
import { CourierToast } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

const lightTheme = { /* CourierToastTheme */ };
const darkTheme = { /* CourierToastTheme */ };

<CourierToast lightTheme={lightTheme} darkTheme={darkTheme} mode="system" />;
```

```html Web Components highlight={7-8} theme={null}
<courier-toast id="toast"></courier-toast>

<script type="module">
  import { Courier } from "@trycourier/courier-ui-toast";

  const toast = document.getElementById("toast");
  toast.setLightTheme({ /* CourierToastTheme */ });
  toast.setDarkTheme({ /* CourierToastTheme */ });
</script>
```

```vue Vue highlight={4-5,9} theme={null}
<script setup lang="ts">
import { CourierToast } from "@trycourier/courier-vue";

const lightTheme = { /* CourierToastTheme */ };
const darkTheme = { /* CourierToastTheme */ };
</script>

<template>
  <CourierToast :lightTheme="lightTheme" :darkTheme="darkTheme" mode="system" />
</template>
```

```ts Angular highlight={8,11-12} theme={null}
import { Component } from "@angular/core";
import { CourierToastComponent, CourierToastTheme } from "@trycourier/courier-angular";

@Component({
  selector: "app-toast",
  standalone: true,
  imports: [CourierToastComponent],
  template: `<courier-toast [lightTheme]="lightTheme" [darkTheme]="darkTheme" mode="system"></courier-toast>`,
})
export class ToastComponent {
  lightTheme: CourierToastTheme = { /* ... */ };
  darkTheme: CourierToastTheme = { /* ... */ };
}
```

The object is the same on React, Vue, Angular, and the Web Components, so it is documented once below.

> [!NOTE]
>
> A toast item has a default border: `1px solid #E5E5E5` in light mode, `1px solid #3A3A3A` in dark. Override it with `item.border`.

### CourierToastTheme reference

Every property is optional, and it is a shallower object than the inbox theme: one `item` key, not a tree of `popup` and `inbox`.

**The theme has no `toast` wrapper.** Pass `{ item: { ... } }` directly. A theme nested under a `toast` key has no effect, and the toast keeps its default look.

```ts theme={null}
type CourierToastTheme = {
  item?: {
    backgroundColor?: string;
    hoverBackgroundColor?: string;
    activeBackgroundColor?: string;
    autoDismissBarColor?: string;      // the countdown bar
    title?: FontTheme;
    body?: FontTheme;
    icon?: IconTheme & { visible?: boolean };
    dismissIcon?: IconTheme & { visible?: boolean };
    shadow?: string;
    border?: string;
    borderRadius?: string;
    actions?: ActionVariantTheme & {
      button?: ActionVariantTheme;     // style: 'button', the filled default
      secondary?: ActionVariantTheme;  // style: 'secondary', outlined
      tertiary?: ActionVariantTheme;   // style: 'tertiary', borderless
      link?: ActionVariantTheme;       // style: 'link', inline text
    };
  };
};

type FontTheme = { family?: string; weight?: string; size?: string; color?: string };
type IconTheme = { color?: string; svg?: string };

type ActionVariantTheme = {
  backgroundColor?: string;
  hoverBackgroundColor?: string;
  activeBackgroundColor?: string;
  border?: string;
  borderRadius?: string;
  shadow?: string;
  textDecoration?: string;
  padding?: string;
  font?: FontTheme;
};
```

**`actions` carries a default at its top level and one override per style.** Fields set
directly on `actions` apply to every action button. The `button`, `secondary`, `tertiary`,
and `link` keys layer over that, each for actions asking for that look. So set shared
padding once on `actions`, and only the colours per variant.

Setting `icon.visible` to `false` drops the icon and the space it reserved, for toasts that
read better as text alone.

> [!NOTE]
>
> The built-in toast is **web-only**. On iOS, Android, Flutter, and React Native, listen for new messages and style your own UI. See [Add toasts
> DOC](/docs/in-app/add-toasts).

## Custom UI

On the web SDKs, toasts support the same custom rendering as the inbox.

### Replace the toast item

Swap the toast item for your own element while the SDK keeps managing the feed:

```jsx React theme={null}
<CourierToast renderToastItem={(props) => <MyToast message={props?.message} />} />
```

```js Web Components theme={null}
const toast = document.querySelector("courier-toast");
toast.setToastItem((props) => renderToast(props));
```

```vue Vue theme={null}
<CourierToast :renderToastItem="(props) => renderToast(props)" />
```

```html Angular theme={null}
<courier-toast>
  <ng-template #toastItem let-props>
    <!-- your custom toast; props.message is available -->
  </ng-template>
</courier-toast>
```

A replaced item still dismisses itself on the `autoDismiss` timer. The renderer receives `autoDismiss` and `autoDismissTimeoutMs` alongside the `message`, so your element can draw its own countdown.

### Replace only the content

Replace the content instead of the item to change only what sits inside a toast. The SDK keeps drawing the frame, the countdown bar, and the dismiss button, and still fires `onToastItemClick`.

![A Courier toast whose content area shows a custom icon, a bold title, a body line, and a custom close button, inside the default toast frame](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/courier-toast-custom-item-content.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=c92c48ff62db652c8fd2d15e9e470b7a)

A toast with custom content inside the default frame.

```jsx React theme={null}
<CourierToast renderToastItemContent={(props) => <MyToastContent message={props.message} />} />
```

```js Web Components theme={null}
const toast = document.querySelector("courier-toast");
toast.setToastItemContent((props) => renderContent(props));
```

```vue Vue theme={null}
<CourierToast :renderToastItemContent="(props) => renderContent(props)" />
```

```html Angular theme={null}
<courier-toast>
  <ng-template #toastItemContent let-props>
    <!-- your custom content; props.message is available -->
  </ng-template>
</courier-toast>
```

### Show your own popup

Skip the component: subscribe to the datastore and react to new messages with `onMessageAdd`. The datastore comes from `@trycourier/courier-ui-inbox` on every framework. Only the lifecycle wiring differs.

```jsx React highlight={6} theme={null}
import { useEffect } from "react";
import { CourierInboxDatastore, CourierInboxDataStoreListener } from "@trycourier/courier-ui-inbox";

useEffect(() => {
  const listener = new CourierInboxDataStoreListener({
    onMessageAdd: (message, index, datasetId) => showMyPopup(message),
  });
  CourierInboxDatastore.shared.addDataStoreListener(listener);

  return () => CourierInboxDatastore.shared.removeDataStoreListener(listener);
}, []);
```

```js Web Components highlight={4} theme={null}
import { CourierInboxDatastore, CourierInboxDataStoreListener } from "@trycourier/courier-ui-inbox";

const listener = new CourierInboxDataStoreListener({
  onMessageAdd: (message, index, datasetId) => showMyPopup(message),
});
CourierInboxDatastore.shared.addDataStoreListener(listener);
```

```vue Vue highlight={6} theme={null}
<script setup lang="ts">
import { onMounted, onUnmounted } from "vue";
import { CourierInboxDatastore, CourierInboxDataStoreListener } from "@trycourier/courier-ui-inbox";

const listener = new CourierInboxDataStoreListener({
  onMessageAdd: (message, index, datasetId) => showMyPopup(message),
});

onMounted(() => CourierInboxDatastore.shared.addDataStoreListener(listener));
onUnmounted(() => CourierInboxDatastore.shared.removeDataStoreListener(listener));
</script>
```

```ts Angular highlight={7} theme={null}
import { Component, OnDestroy, OnInit } from "@angular/core";
import { CourierInboxDatastore, CourierInboxDataStoreListener } from "@trycourier/courier-ui-inbox";

@Component({ /* ... */ })
export class ToastPopupComponent implements OnInit, OnDestroy {
  private listener = new CourierInboxDataStoreListener({
    onMessageAdd: (message, index, datasetId) => this.showMyPopup(message),
  });

  ngOnInit() {
    CourierInboxDatastore.shared.addDataStoreListener(this.listener);
  }

  ngOnDestroy() {
    CourierInboxDatastore.shared.removeDataStoreListener(this.listener);
  }
}
```

See [Customize the inbox
DOC](/docs/in-app/build-a-custom-inbox) for the full inbox datastore surface.


# Inbox runtime behavior
Source: https://www.courier.com/docs/in-app/how-the-inbox-behaves

Real-time updates, message retention, and expiry once a user is signed in.

## Real-time updates

Once a user signs in, the inbox opens a realtime connection. New messages appear live. Read, opened, and archived states sync across every device where that user is signed in.

The connection uses the same authenticated session, so a valid JWT is all it needs. The socket has no separate authentication.

The same live feed drives a custom UI. See [Custom UI
DOC](/docs/in-app/build-a-custom-inbox) to build your own inbox, with pagination, on any platform.

## Message retention

A message stays in the feed until it is archived or expires. A message sent with an expiration (`expiresAt`) drops from the feed when that time passes. Read and archive states persist across sessions and devices.

## Troubleshooting

**Updates aren't live.** Check that the user is signed in with an unexpired JWT. An expired token ends the session, and no updates arrive until you sign in again with a fresh token. See [Authenticate users
DOC](/docs/in-app/authenticate-users).

**Custom UI shows stale data.** Read from the datastore and respond to its change events. Don't cache a one-time snapshot.

## FAQ

> **Do real-time updates work with JWT authentication?**
>
> The real-time connection uses the same [authenticated session
> DOC](/docs/in-app/authenticate-users), with no separate authentication for the socket. See [Real-time updates](#real-time-updates).

> **Can I build a fully custom inbox UI?**
>
> See [Custom UI
> DOC](/docs/in-app/build-a-custom-inbox). Build the whole UI on any platform, or on the web SDKs keep the built-in inbox and swap individual parts.

> **How long do messages stay in the inbox?**
>
> Until they are archived or reach their expiration. A message sent with an `expiresAt` drops from the feed when that time passes. Without one, it persists. See [Message retention](#message-retention).


# In-app Inbox
Source: https://www.courier.com/docs/in-app/inbox

Add a real-time notification center to your web and mobile apps. Courier hosts the feed, and you choose how much of the UI you build.

Courier Inbox is the notification center behind the bell icon in your web and mobile apps, where users catch up on mentions, approvals, and alerts.

![The Courier Inbox on web and mobile. On the web, a notification panel opens from a bell icon with All and Unread tabs, Mark all as read, and mentions and comments from teammates. On an iPhone, the same feed as a native Inbox screen grouped into Today and Yesterday, with a weekly roundup card and an Inbox tab badge](https://mintcdn.com/courier-4f1f25dc/NuGEFnWVhb1xgv6w/assets/inbox-web-and-mobile.webp?fit=max\&auto=format\&n=NuGEFnWVhb1xgv6w\&q=85\&s=2ada33b29536484b7791aa8364062c78)

## What is Courier Inbox

Users see what needs their attention without leaving your product, and messages stay there until the user reads or archives them.

It comes in two parts: SDKs that render the inbox in your web and mobile apps, and a backend Courier hosts for you.

* **A prebuilt inbox you embed.** Add the inbox component to your app. Unread counts, Unread and Archived views, in-message actions, and pagination work out of the box.
* **Full control over how it looks.** Theme it to match your brand, replace the header or list items with your own components, or build a custom UI on the same feed.
* **A hosted backend.** Courier stores each user's messages and delivers them in real time. Read and archive state stays in sync across every device the user is signed in on.

## How it works

1. **Embed** the inbox in your app with a Courier SDK.
2. **Send** a message to the `inbox` channel, the same way you'd send an email.
3. **Courier delivers** it in real time to every device the user is signed in on, and keeps read and archive state in sync.

## Choose how much you build

Every option runs on the same feed. Courier stores the messages, delivers them in real time, and tracks read and archive state. What changes is how much of the interface is yours. Start with the prebuilt inbox, and move further only when your design needs it.

| | What you do | What Courier handles | Best for |
| :- | :- | :- | :- |
| **[Prebuilt inbox&#xA;DOC](/docs/in-app/customize-the-inbox)** | Drop in the component. Set colors, fonts, and light and dark themes. | The whole UI: list, tabs, unread badge, actions, and pagination. | Shipping fast |
| **[Custom components&#xA;DOC](/docs/in-app/build-a-custom-inbox#replace-parts-of-the-inbox)** | Render your own header, list items, or empty, loading, and error states. | Everything you don't replace, plus fetching, paging, and updates. | Matching your design system |
| **[Custom UI&#xA;DOC](/docs/in-app/build-a-custom-inbox#build-your-own-ui)** | Build the entire interface from the SDK's messages and actions. | The data: messages, unread counts, read and archive actions, and real-time sync. | Full control |

Custom components work in the web SDKs. On mobile, theme the prebuilt inbox or build a custom UI.

## SDKs

**Web:** [React
DOC](/docs/sdk-libraries/courier-react-web) · [Vue
DOC](/docs/sdk-libraries/courier-vue-web) · [Angular
DOC](/docs/sdk-libraries/courier-angular-web) · [Web Components
DOC](/docs/sdk-libraries/courier-web-components)

**Mobile:** [iOS
DOC](/docs/sdk-libraries/ios) · [Android
DOC](/docs/sdk-libraries/android) · [React Native
DOC](/docs/sdk-libraries/react-native) · [Flutter
DOC](/docs/sdk-libraries/flutter)

## Start building

> **[Add an inbox](/docs/in-app/add-an-inbox)**
>
> Install an SDK, sign the user in, and render the inbox.

> **[Send to the inbox](/docs/in-app/send-to-the-inbox)**
>
> Send your first message to the `inbox` channel.

Want a working app first? Follow a quickstart for [React
GUIDE](/docs/guides/add-an-inbox-to-react), [Next.js
GUIDE](/docs/guides/add-an-inbox-to-nextjs), or [Astro
GUIDE](/docs/guides/add-an-inbox-to-astro).


# In-app notifications
Source: https://www.courier.com/docs/in-app/overview

The Courier Inbox, toasts, and preferences UI on every client SDK, plus mobile push.

Courier gives your app three pieces of UI, all rendered by the client SDKs:

* **[Inbox
  DOC](/docs/in-app/inbox)**, an embeddable in-app notification center.
* **[Toasts
  DOC](/docs/in-app/toasts)**, lightweight popups synced to the same feed.
* **[Preferences
  DOC](/docs/in-app/preference-center)**, where users pick which topics they receive, and how.

All three sync in real time across a user's devices and share one authentication and theming model.

The same SDKs handle **mobile push**. One `signIn` call registers the device token APNs and FCM deliver to, so push rides the session you set up here.

![The Courier Inbox with an unread count badge in its header, listing notifications with unread dots, relative timestamps, and View all, Download, and Approve actions](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/inbox-card.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=9834fcc8c1fb404a4da412d96163c473)

The Courier Inbox: unread indicators, relative timestamps, and per-message action buttons.

> [!NOTE]
>
> In-app renders inside your open app. Push is delivered by the operating system, so it arrives when your app is closed. They are separate channels, and one message can send to both. [Set up push notifications
> GUIDE](/docs/guides/set-up-mobile-push) covers the push side.

## Choose your SDK

Install the SDK for your platform. Web Components work with any framework, or none.

| Platform | Package | Install |
| :- | :- | :- |
| [React&#xA;DOC](/docs/sdk-libraries/courier-react-web) (18+) | `@trycourier/courier-react` (v9) | npm / yarn |
| [React 17&#xA;DOC](/docs/sdk-libraries/courier-react-web) | `@trycourier/courier-react-17` (v9) | npm / yarn |
| [Web Components&#xA;DOC](/docs/sdk-libraries/courier-web-components) (any framework) | `@trycourier/courier-ui-inbox` (v2) | npm / yarn |
| [Vue&#xA;DOC](/docs/sdk-libraries/courier-vue-web) | `@trycourier/courier-vue` (v1) | npm / yarn |
| [Angular&#xA;DOC](/docs/sdk-libraries/courier-angular-web) | `@trycourier/courier-angular` (v1) | npm / yarn |
| [iOS&#xA;DOC](/docs/sdk-libraries/ios) | `courier-ios` | Swift Package Manager / CocoaPods |
| [Android&#xA;DOC](/docs/sdk-libraries/android) | `courier-android` | Gradle |
| [Flutter&#xA;DOC](/docs/sdk-libraries/flutter) | `courier_flutter` | pub |
| [React Native&#xA;DOC](/docs/sdk-libraries/react-native) | `@trycourier/courier-react-native` | npm / yarn |

> [!NOTE]
>
> `@trycourier/react-inbox`, `react-provider`, and the `components` bundle are deprecated. See the [courier-react v8 migration guide
> DOC](/docs/sdk-libraries/courier-react-v8-migration-guide) to move to `@trycourier/courier-react` or `@trycourier/courier-ui-inbox`.

Every SDK follows the same three steps: send a token to the client, call `signIn`, then render the inbox.

```jsx React highlight={9} theme={null}
import { useEffect } from "react";
import { useCourier, CourierInbox } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    // Authenticate the user
    courier.shared.signIn({ userId, jwt });
  }, []);

  // Render the Inbox component
  return <CourierInbox />;
}
```

```html Web Components highlight={7} theme={null}
<courier-inbox id="inbox"></courier-inbox>

<script type="module">
  import { Courier } from "@trycourier/courier-ui-inbox";

  // Authenticate the user
  Courier.shared.signIn({ userId, jwt });
</script>
```

```vue Vue highlight={9} theme={null}
<script setup lang="ts">
import { onMounted } from "vue";
import { CourierInbox, useCourier } from "@trycourier/courier-vue";

const courier = useCourier();

onMounted(() => {
  // Authenticate the user
  courier.shared.signIn({ userId, jwt });
});
</script>

<template>
  <CourierInbox />
</template>
```

```ts Angular highlight={4} theme={null}
import { CourierService } from "@trycourier/courier-angular";

// Authenticate the user
this.courier.signIn({ userId, jwt });

// Render: <courier-inbox></courier-inbox>
```

```swift iOS highlight={4} theme={null}
import Courier_iOS

// Authenticate the user
await Courier.shared.signIn(userId: userId, accessToken: jwt)

// UIKit
view.addSubview(CourierInbox())

// SwiftUI
CourierInboxView()
```

```kotlin Android highlight={1,3} theme={null}
// Authenticate the user (signIn is a suspend function)
lifecycleScope.launch {
  Courier.shared.signIn(userId = userId, accessToken = jwt)
}

// Render the Inbox @Composable
CourierInbox()
```

```dart Flutter highlight={4} theme={null}
import 'package:courier_flutter/ui/inbox/courier_inbox.dart';

// Authenticate the user
await Courier.shared.signIn(accessToken: jwt, userId: userId);

// Render the inbox widget
CourierInbox();
```

```jsx React Native highlight={4} theme={null}
import Courier, { CourierInboxView } from "@trycourier/courier-react-native";

// Authenticate the user
await Courier.shared.signIn({ accessToken: jwt, userId });

// Render the inbox component
<CourierInboxView />;
```

## How it fits together

### A customizable UI

Courier Inbox ships a notification center out of the box. Theme it with `CourierInboxTheme`, supply your own views while the SDK still manages messages, or build a custom UI on the low-level APIs.

### Real-time and synced across devices

Messages arrive in real time on web and mobile. Every state change (read, opened, archived) syncs instantly across a user's signed-in devices.

### Notification-center essentials, built in

Out of the box you get:

* Unread counts and badges.
* Read and archive actions.
* Message-level buttons.
* Pagination and infinite scroll.

## FAQ

> **What is the difference between in-app and push notifications?**
>
> In-app (Inbox and Toasts) renders inside your running app. Push comes from the operating system through APNs or FCM, so it arrives even when your app is closed. They're separate channels, and one message can send to both. Connect your [APNs
> DOC](/docs/integrations/push/apple-push-notification) or [FCM
> DOC](/docs/integrations/push/firebase-fcm) credentials under Integrations.

> **What is the difference between Inbox and Toasts?**
>
> Inbox is the persistent notification center listing a user's messages. Toasts are transient popups that appear when a new message arrives, synced to the same feed. Both use the same authentication (`signIn`) and theming. See [Add toasts
> DOC](/docs/in-app/add-toasts).

> **Which frameworks and platforms are supported?**
>
> React, React 17, Vue, Angular, Web Components (any framework or none), iOS, Android, Flutter, and React Native. See the [table above](#choose-your-sdk) for the package name per platform.

> **How do I authenticate users?**
>
> Your backend generates a JWT with your Courier API key and passes it to the client, which calls `signIn({ userId, jwt })`. See [Inbox authentication
> DOC](/docs/in-app/authenticate-users) for the full flow and scope strings.

> **Can I send to the inbox and other channels at the same time?**
>
> Add `inbox` alongside other channels in your message's routing. Courier delivers to each channel by your routing rules. Cross-channel syncing can mark the Inbox message read when the user opens the email. See [Send to the inbox
> DOC](/docs/in-app/send-to-the-inbox).


# Preference center
Source: https://www.courier.com/docs/in-app/preference-center

Let users choose which notifications they get, and on which channels, from inside your app or on a page Courier hosts.

A preference center lets users choose which of your notifications they get, and how each one reaches them.

![The Courier preference center with its default styling: a topic section with per-topic toggles and an expanded channel picker for email, push, and SMS](https://mintcdn.com/courier-4f1f25dc/Ia7FGvhsFU_5CtOa/assets/preferences-default.webp?fit=max\&auto=format\&n=Ia7FGvhsFU_5CtOa\&q=85\&s=d31b2fb8c91c01bd97f26b09d0ecb4bc)

## What is a preference center

Users turn notification topics on or off, like product updates or weekly digests, and pick how each one reaches them: email, push, SMS, and more.

Courier enforces those choices on every send. When a user opts out of a topic, Courier stops delivering it, across every channel, with no checks in your code.

## How it works

1. **Create topics** in the [Preferences Editor
   DOC](/docs/recipients/preferences/preferences-editor), like Account alerts or Marketing, and set each one's default.
2. **Assign each template** to a topic with its [Subscription Topic
   DOC](/docs/design/templates/template-settings) setting, so Courier knows which messages each choice covers.
3. **Show the preference center** to users, in your app or on the hosted page.
4. **Courier checks preferences** at send time, and delivers only what each user opted into, on the channels they chose.

Set a topic's default to Required for messages users can't turn off, like security alerts.

## Embedded or hosted

Both read and write the same preferences, so a change in one shows up in the other.

| | [Embedded component&#xA;DOC](/docs/in-app/add-a-preference-center) | [Hosted page&#xA;GUIDE](/docs/guides/build-a-preference-center#hosted-page) |
| :- | :- | :- |
| Where it lives | Inside your app, next to your other settings | A Courier URL, unique to each user |
| What you build | Add one component with a Courier SDK | Nothing |
| How users get there | Your app's settings screen | A preferences link in your emails |
| Styling | Fully themeable, or build your own UI | Your brand, heading, and description |
| Get started | [Add a preference center&#xA;DOC](/docs/in-app/add-a-preference-center) | [Set up the hosted page&#xA;GUIDE](/docs/guides/build-a-preference-center#hosted-page) |

A common setup uses both: the component in your settings screen, and the hosted link in email footers so users can update preferences without signing in.

## SDKs

**Web:** [React
DOC](/docs/sdk-libraries/courier-react-web) · [Vue
DOC](/docs/sdk-libraries/courier-vue-web) · [Angular
DOC](/docs/sdk-libraries/courier-angular-web) · [Web Components
DOC](/docs/sdk-libraries/courier-web-components)

**Mobile:** [iOS
DOC](/docs/sdk-libraries/ios) · [Android
DOC](/docs/sdk-libraries/android) · [React Native
DOC](/docs/sdk-libraries/react-native) · [Flutter
DOC](/docs/sdk-libraries/flutter)

The preference center uses the same SDKs and sign-in as the [inbox
DOC](/docs/in-app/inbox). If you already have the inbox, it's one more component.

## Go further

> **[Customize preferences](/docs/in-app/customize-preferences)**
>
> Theme the component or build your own UI.

> **[How preferences resolve](/docs/recipients/preferences/overview)**
>
> What Courier checks at send time.


# Send to the inbox
Source: https://www.courier.com/docs/in-app/send-to-the-inbox

Route a message to the inbox channel, tag it for a tab, and scope it to a tenant.

Start with [Add an inbox
DOC](/docs/in-app/add-an-inbox) and [Authenticate users
DOC](/docs/in-app/authenticate-users).

A message reaches the inbox when you include `inbox` in its routing channels.

The inbox is a channel like `email` or `push`, so the same [Send API](/docs/api-reference/send/send-a-message) call delivers to it.

![A just-delivered message in the Courier Inbox, unread and timestamped Now, with the header unread count reading 1](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/inbox-delivered.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=5dddc3c19bf3e5ceacc822c70a457ca3)

A message delivered to the Courier Inbox after a send.

## Route a message to the inbox

This send references a published template with an In-App channel, so create one before you run it.

```javascript Node.js theme={null}
const response = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    routing: { method: "single", channels: ["inbox"] },
  },
});

console.log(response.requestId);
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"name": "Sarah Bennett"},
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "name": "Sarah Bennett" },
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    routing: { method: "single", channels: ["inbox"] }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
  Message: courier.SendMessageParamsMessage{
    To: courier.SendMessageParamsMessageToUnion{
      OfUserRecipient: &shared.UserRecipientParam{
        UserID: courier.String("user_123"),
      },
    },
    Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
    Data: map[string]any{"name": "Sarah Bennett"},
    Routing: courier.SendMessageParamsMessageRouting{
      Method: string(shared.MessageRoutingMethodSingle),
      Channels: []shared.MessageRoutingChannelUnionParam{
        {OfString: courier.String("inbox")},
      },
    },
  },
})
```

```java Java theme={null}
SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .template("nt_01kx4h2jdafq8bk9aftxak4b40")
    .data(SendMessageParams.Message.Data.builder()
        .putAdditionalProperty("name", JsonValue.from("Sarah Bennett"))
        .build())
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("inbox")))
        .build())
    .build();

SendMessageResponse response = client.send().message(
    SendMessageParams.builder().message(message).build());
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => "user_123"],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'data' => ['name' => "Sarah Bennett"],
    'routing' => ['method' => "single", 'channels' => ["inbox"]],
  ],
);
```

```csharp C# theme={null}
var response = await client.Send.Message(new SendMessageParams
{
    Message = new Message
    {
        To = new To(new UserRecipient { UserID = "user_123" }),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") }
        },
        Routing = new Routing
        {
            Method = Method.Single,
            Channels = new List<MessageRoutingChannel> { new MessageRoutingChannel("inbox") }
        }
    }
});
```

```bash CLI theme={null}
courier send message --message '{
  "to": { "user_id": "user_123" },
  "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
  "data": { "name": "Sarah Bennett" },
  "routing": { "method": "single", "channels": ["inbox"] }
}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on the inbox channel.
```

The inbox shows the template's **In-App** channel, so build that channel when you [design a template
DOC](/docs/design/templates/overview). For the send call itself, see [Send a message
DOC](/docs/send/overview).

The SDK receives everything in `data` with the message. Fields your template references (like `{{ name }}`) are interpolated. The rest passes through untouched, which is useful for deep linking to a screen when the user taps a message.

Inbox messages also drive toasts. Render the toast component and a popup appears for each new message on the feed. See [Add toasts
DOC](/docs/in-app/add-toasts).

## Tag a message for a tab

Inbox tabs filter on tags, and a message gets its tags from `metadata.tags` on the send. A tab defined with `filter: { tags: ["order"] }` shows the messages you tag here.

```javascript Node.js highlight={6} theme={null}
const response = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    metadata: { tags: ["order"] },
    routing: { method: "single", channels: ["inbox"] },
  },
});
```

```python Python highlight={6} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"name": "Sarah Bennett"},
        "metadata": {"tags": ["order"]},
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)
```

```bash cURL highlight={8} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "metadata": { "tags": ["order"] },
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'
```

```ruby Ruby highlight={6} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    metadata: { tags: ["order"] },
    routing: { method: "single", channels: ["inbox"] }
  }
)
```

```go Go highlight={9-11} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
  Message: courier.SendMessageParamsMessage{
    To: courier.SendMessageParamsMessageToUnion{
      OfUserRecipient: &shared.UserRecipientParam{
        UserID: courier.String("user_123"),
      },
    },
    Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
    Metadata: courier.SendMessageParamsMessageMetadata{
      Tags: []string{"order"},
    },
    Routing: courier.SendMessageParamsMessageRouting{
      Method: string(shared.MessageRoutingMethodSingle),
      Channels: []shared.MessageRoutingChannelUnionParam{
        {OfString: courier.String("inbox")},
      },
    },
  },
})
```

```java Java highlight={5-7} theme={null}
SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .template("nt_01kx4h2jdafq8bk9aftxak4b40")
    .metadata(SendMessageParams.Message.Metadata.builder()
        .tags(List.of("order"))
        .build())
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("inbox")))
        .build())
    .build();

SendMessageResponse response = client.send().message(
    SendMessageParams.builder().message(message).build());
```

```php PHP highlight={5} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => "user_123"],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'metadata' => ['tags' => ["order"]],
    'routing' => ['method' => "single", 'channels' => ["inbox"]],
  ],
);
```

```csharp C# highlight={7} theme={null}
var response = await client.Send.Message(new SendMessageParams
{
    Message = new Message
    {
        To = new To(new UserRecipient { UserID = "user_123" }),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Metadata = new() { Tags = ["order"] },
        Routing = new Routing
        {
            Method = Method.Single,
            Channels = new List<MessageRoutingChannel> { new MessageRoutingChannel("inbox") }
        }
    }
});
```

```bash CLI highlight={4} theme={null}
courier send message --message '{
  "to": { "user_id": "user_123" },
  "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
  "metadata": { "tags": ["order"] },
  "routing": { "method": "single", "channels": ["inbox"] }
}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on the inbox channel, tagged order.
```

A message carries at most 9 tags, and each tag is a string of up to 30 characters. Exceeding either limit fails the send with a validation error on `metadata.tags`.

Tags reach the client on every inbox message, so a custom UI can read them too. [Tabs and feeds
DOC](/docs/in-app/tabs-and-feeds) covers defining the tabs that filter on them.

## Scope the inbox to a tenant

To show only one [tenant
DOC](/docs/tenants/overview)'s messages, pass `tenantId` at sign-in. You set it once on the client, and it applies to every component, every read, and the realtime connection. Without a `tenantId`, the inbox shows only messages sent without a tenant.

```jsx React theme={null}
courier.shared.signIn({ userId, jwt, tenantId: "acme" });
```

```html Web Components theme={null}
<script type="module">
  Courier.shared.signIn({ userId, jwt, tenantId: "acme" });
</script>
```

```vue Vue theme={null}
courier.shared.signIn({ userId, jwt, tenantId: "acme" });
```

```ts Angular theme={null}
this.courier.signIn({ userId, jwt, tenantId: "acme" });
```

```swift iOS theme={null}
await Courier.shared.signIn(userId: userId, tenantId: "acme", accessToken: jwt)
```

```kotlin Android theme={null}
// signIn is a suspend function; call it from a coroutine
lifecycleScope.launch {
  Courier.shared.signIn(userId = userId, tenantId = "acme", accessToken = jwt)
}
```

```dart Flutter theme={null}
await Courier.shared.signIn(accessToken: jwt, userId: userId, tenantId: "acme");
```

```jsx React Native theme={null}
await Courier.shared.signIn({ accessToken: jwt, userId, tenantId: "acme" });
```

Send to that tenant's inbox by setting `context.tenant_id` on the recipient. The message is visible only when the user signs in with the same tenant. (A bare `tenant_id` in `to`, with no `user_id`, fans out to every member of the tenant instead.)

```javascript Node.js highlight={3} theme={null}
await client.send.message({
  message: {
    to: { user_id: "user_123", context: { tenant_id: "acme" } },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    routing: { method: "single", channels: ["inbox"] },
  },
});
```

```python Python highlight={3} theme={null}
client.send.message(
    message={
        "to": {"user_id": "user_123", "context": {"tenant_id": "acme"}},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"name": "Sarah Bennett"},
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)
```

```bash cURL highlight={6} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123", "context": { "tenant_id": "acme" } },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "name": "Sarah Bennett" },
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'
```

```ruby Ruby highlight={3} theme={null}
courier.send_.message(
  message: {
    to: { user_id: "user_123", context: { tenant_id: "acme" } },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    routing: { method: "single", channels: ["inbox"] }
  }
)
```

```go Go highlight={6} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
  Message: courier.SendMessageParamsMessage{
    To: courier.SendMessageParamsMessageToUnion{
      OfUserRecipient: &shared.UserRecipientParam{
        UserID:  courier.String("user_123"),
        Context: shared.MessageContextParam{TenantID: courier.String("acme")},
      },
    },
    Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
    Data: map[string]any{"name": "Sarah Bennett"},
    Routing: courier.SendMessageParamsMessageRouting{
      Method: string(shared.MessageRoutingMethodSingle),
      Channels: []shared.MessageRoutingChannelUnionParam{
        {OfString: courier.String("inbox")},
      },
    },
  },
})
```

```java Java highlight={5} theme={null}
SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder()
            .userId("user_123")
            .context(MessageContext.builder().tenantId("acme").build())
            .build()))
    .template("nt_01kx4h2jdafq8bk9aftxak4b40")
    .data(SendMessageParams.Message.Data.builder()
        .putAdditionalProperty("name", JsonValue.from("Sarah Bennett"))
        .build())
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("inbox")))
        .build())
    .build();

client.send().message(SendMessageParams.builder().message(message).build());
```

```php PHP highlight={3} theme={null}
$client->send->message(
  message: [
    'to' => ['userID' => "user_123", 'context' => ['tenantID' => "acme"]],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'data' => ['name' => "Sarah Bennett"],
    'routing' => ['method' => "single", 'channels' => ["inbox"]],
  ],
);
```

```csharp C# highlight={8} theme={null}
await client.Send.Message(new SendMessageParams
{
    Message = new Message
    {
        To = new To(new UserRecipient
        {
            UserID = "user_123",
            Context = new MessageContext { TenantID = "acme" }
        }),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") }
        },
        Routing = new Routing
        {
            Method = Method.Single,
            Channels = new List<MessageRoutingChannel> { new MessageRoutingChannel("inbox") }
        }
    }
});
```

```bash CLI highlight={2} theme={null}
courier send message --message '{
  "to": { "user_id": "user_123", "context": { "tenant_id": "acme" } },
  "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
  "data": { "name": "Sarah Bennett" },
  "routing": { "method": "single", "channels": ["inbox"] }
}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 in the acme tenant's inbox.
```

## FAQ

> **Why is my inbox message not arriving?**
>
> Confirm all three:
>
> * The environment has the Courier Inbox provider. It's already set up in production and test. Add it only in a custom environment or if it was deleted.
> * The message routing includes `channels: ["inbox"]`.
> * The recipient `user_id` matches the `userId` you [signed in with
>   DOC](/docs/in-app/authenticate-users).

> **Do toasts need separate setup from the inbox?**
>
> Toasts read the same feed and use the same `signIn`. Render `CourierToast` (or `<courier-toast>`) anywhere in your app after sign-in. See [Add toasts
> DOC](/docs/in-app/add-toasts).

> **Can one user see different inboxes per tenant?**
>
> Sign in with a `tenantId` to scope the inbox to that tenant. Sign in again with a different `tenantId` to switch. The scope is client-level, not per-component. See [Scope the inbox to a tenant](#scope-the-inbox-to-a-tenant).


# Inbox tabs and feeds
Source: https://www.courier.com/docs/in-app/tabs-and-feeds

Filter the inbox into tabs by tag, read state, archive state, or date, and group them into feeds.

A tab is a filtered view of the same message stream. A feed groups tabs, so the inbox can offer several sets of them.

Start where your app already is: a tab is a saved query, not a separate mailbox. Nothing routes a message to a tab at send time. Every tab reads the same messages and shows the ones its filter matches, which is why one message can appear in several tabs at once.

![The Courier Inbox header showing a row of tabs reading All, Unread, Read, Important, and Archived, with the All tab selected and carrying an unread count](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/courier-react-tabs.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=8a929734bd24c3b7962948dd2d21aec8)

One feed offering five tabs, each a different filter over the same messages.

```jsx React theme={null}
import { CourierInbox, type CourierInboxFeed } from "@trycourier/courier-react";

const feeds: CourierInboxFeed[] = [
  {
    feedId: "notifications",
    title: "Notifications",
    tabs: [
      { datasetId: "all", title: "All", filter: {} },
      { datasetId: "unread", title: "Unread", filter: { status: "unread" } },
      { datasetId: "important", title: "Important", filter: { tags: ["important"] } },
      { datasetId: "archived", title: "Archived", filter: { archived: true } },
    ],
  },
];

export default function App() {
  return <CourierInbox feeds={feeds} />;
}
```

```js Web Components theme={null}
const inbox = document.getElementById("inbox");

inbox.setFeeds([
  {
    feedId: "notifications",
    title: "Notifications",
    tabs: [
      { datasetId: "all", title: "All", filter: {} },
      { datasetId: "unread", title: "Unread", filter: { status: "unread" } },
      { datasetId: "important", title: "Important", filter: { tags: ["important"] } },
      { datasetId: "archived", title: "Archived", filter: { archived: true } },
    ],
  },
]);
```

```vue Vue theme={null}
<script setup lang="ts">
import { CourierInbox, type CourierInboxFeed } from "@trycourier/courier-vue";

const feeds: CourierInboxFeed[] = [
  {
    feedId: "notifications",
    title: "Notifications",
    tabs: [
      { datasetId: "all", title: "All", filter: {} },
      { datasetId: "unread", title: "Unread", filter: { status: "unread" } },
      { datasetId: "important", title: "Important", filter: { tags: ["important"] } },
      { datasetId: "archived", title: "Archived", filter: { archived: true } },
    ],
  },
];
</script>

<template>
  <CourierInbox :feeds="feeds" />
</template>
```

```ts Angular theme={null}
import { Component } from "@angular/core";
import { CourierInboxComponent, type CourierInboxFeed } from "@trycourier/courier-angular";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [CourierInboxComponent],
  template: `<courier-inbox [feeds]="feeds"></courier-inbox>`,
})
export class AppComponent {
  feeds: CourierInboxFeed[] = [
    {
      feedId: "notifications",
      title: "Notifications",
      tabs: [
        { datasetId: "all", title: "All", filter: {} },
        { datasetId: "unread", title: "Unread", filter: { status: "unread" } },
        { datasetId: "important", title: "Important", filter: { tags: ["important"] } },
        { datasetId: "archived", title: "Archived", filter: { archived: true } },
      ],
    },
  ];
}
```

**Tabs and feeds are web only.** React, Vue, Angular, and the Web Components take them. The iOS, Android, Flutter, and React Native inboxes render a single list, so build the equivalent switch in your own UI with [the data and actions
DOC](/docs/in-app/build-a-custom-inbox#data-and-actions).

## What each field does

A feed is a container. It creates nothing on its own, and only its tabs load messages.

| Feed field | Type | Description |
| - | - | - |
| `feedId` | string | Identifies the feed, and selects it programmatically. Unique across feeds. |
| `title` | string | The name shown in the inbox header. |
| `iconSVG` | string | Optional icon markup for the feed button. |
| `tabs` | `CourierInboxTab[]` | The tabs this feed offers. |

| Tab field | Type | Description |
| - | - | - |
| `datasetId` | string | Identifies the tab's dataset in the datastore. Unique across every tab in every feed. |
| `title` | string | The name shown on the tab. |
| `filter` | `CourierInboxDatasetFilter` | Which messages the tab shows. Required, and `{}` means every unarchived message. |

**`datasetId` has to be unique across all feeds, not only within one.** Tabs are flattened into one set of datasets when the inbox registers them. Two tabs sharing an ID become a single dataset that both render, showing identical messages under two names. Slugify the title and prefix it with the feed's, as in `jobs-unread`.

## Filter a tab

Set fields are AND'd together. Several `tags` match as OR, so a message carrying any one of them is included.

| Filter field | Type | Description |
| - | - | - |
| `tags` | `string[]` | Messages carrying any of these tags. |
| `archived` | boolean | `true` shows only archived messages. `false` or unset shows only unarchived ones. |
| `status` | `'read'` or `'unread'` | Limit to one read state. Unset applies neither. |
| `from` | string | ISO 8601 datetime. Only messages created at or after it, as in `new Date().toISOString()`. |

Tags come from the send side. [Tag a message for a tab
DOC](/docs/in-app/send-to-the-inbox#tag-a-message-for-a-tab) covers putting them on a message, and a tag has to be on the message before it arrives, because a filter can't add one later.

`from` is how you keep an existing user's backlog out of a newly added tab. Pin it to the moment the tab shipped and the tab starts empty rather than full of history.

## Several feeds

Give the inbox more than one feed and the header gains a picker. Each feed brings its own tabs.

![The Courier Inbox feed picker open, listing All, Jobs, My Posts, and Mentions as selectable feeds](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/courier-react-feeds.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=8572aafd2ff6ef8c5410a838acb11479)

Four feeds in the header picker, each with its own set of tabs.

```jsx theme={null}
const feeds: CourierInboxFeed[] = [
  { feedId: "all", title: "All", tabs: [{ datasetId: "all", title: "All", filter: {} }] },
  { feedId: "jobs", title: "Jobs", tabs: [{ datasetId: "jobs-all", title: "All", filter: { tags: ["job"] } }] },
  {
    feedId: "my-posts",
    title: "My Posts",
    tabs: [
      { datasetId: "posts-all", title: "All", filter: {} },
      { datasetId: "posts-comments", title: "Comments", filter: { tags: ["comment"] } },
      { datasetId: "posts-reactions", title: "Reactions", filter: { tags: ["reaction"] } },
    ],
  },
];
```

The chrome adapts to what you pass. One feed hides the feed picker. A feed holding one tab hides the tab bar and moves that tab's unread count next to the feed name. So a single unfiltered feed and tab renders as a plain list, which is what an inbox with no `feeds` at all shows.

## Select a feed or tab in code

The inbox element exposes `selectFeed(feedId)` and `selectTab(datasetId)`, and reports changes back through `onFeedChange` and `onTabChange`. Both take the ids you defined above.

```js theme={null}
const inbox = document.getElementById("inbox");

inbox.selectFeed("jobs");
inbox.selectTab("jobs-all");

inbox.currentFeedId;   // "jobs"
inbox.getFeeds();      // the feeds array you set
await inbox.refresh(); // reload from Courier, skipping the cache
```

On React, Vue, and Angular these are methods on the underlying element rather than props, so reach them through a ref. To change what the tabs contain instead of which one is showing, pass a new `feeds` array and the inbox re-registers.

`refresh()` refetches from Courier instead of reading the cached copy. Real-time updates already keep the list current, so call it only when you want a fresh copy on demand, such as from a refresh button.

## Unread counts

Each tab carries its own unread count, and `totalUnreadCount` on the datastore counts every message rather than the selected tab's. A tab filtered to `status: 'unread'` empties as the reader works through it, because a message that leaves the filter leaves the tab.


# Toasts
Source: https://www.courier.com/docs/in-app/toasts

Pop up new inbox messages the moment they arrive, so users notice them while they're working in your app.

Toasts pop up in your app the moment a new message arrives for the user.

![A toast in the top-right corner of a projects app reading Simon mentioned you, The updated designs are ready for review, with a View project link and a close button, stacked on top of two earlier toasts](https://mintcdn.com/courier-4f1f25dc/WypmE3UMoFoAPKi4/assets/toast-in-product.webp?fit=max\&auto=format\&n=WypmE3UMoFoAPKi4\&q=85\&s=ad5df54a0e741ad224a27b835a660012)

## What are toasts

A toast is a short popup in the corner of your app. It stays until they close it, or dismisses itself on a timer if you turn on auto-dismiss.

Toasts don't have their own messages. They run on the same feed as the [inbox
DOC](/docs/in-app/inbox), so every message you send to the `inbox` channel can pop up as a toast. You don't send anything extra.

## How toasts work with the inbox

The toast and the inbox play different roles with the same message:

* **The toast** gets attention right now. It appears the moment the message arrives, and goes away once it's closed or dismissed.
* **The inbox** keeps the record. The message stays there after the toast is gone, so the user can come back to it later.

Use them together, or render toasts on their own if your app doesn't have an inbox.

## How it works

1. **Add** the toast component to your app with a Courier SDK.
2. **Send** a message to the `inbox` channel.
3. **Courier delivers** it in real time, and the toast pops up while the user has your app open.

The prebuilt toast stacks multiple messages, can dismiss itself on a timer, and supports action buttons and light and dark themes. Theme it to match your brand, or render your own toast component.

## Web and mobile

The prebuilt toast is part of the web SDKs: [React
DOC](/docs/sdk-libraries/courier-react-web) · [Vue
DOC](/docs/sdk-libraries/courier-vue-web) · [Angular
DOC](/docs/sdk-libraries/courier-angular-web) · [Web Components
DOC](/docs/sdk-libraries/courier-web-components)

On [iOS
DOC](/docs/sdk-libraries/ios), [Android
DOC](/docs/sdk-libraries/android), [React Native
DOC](/docs/sdk-libraries/react-native), and [Flutter
DOC](/docs/sdk-libraries/flutter), listen for new inbox messages and show them in your own UI. To reach users when your app is closed, send [push
DOC](/docs/send/push/overview) as well.

## Start building

> **[Add toasts](/docs/in-app/add-toasts)**
>
> Render toasts and handle clicks.

> **[Customize toasts](/docs/in-app/customize-toasts)**
>
> Theme them or use your own component.


# Customer data platforms
Source: https://www.courier.com/docs/integrations/cdp/overview

Sync profiles and trigger journeys from Segment or RudderStack events.

Customer Data Platforms (CDPs) collect, unify, and activate customer data across your tech stack.

Courier integrates with CDPs to sync user profiles and trigger notifications from customer events. Once connected, you can:

* **Sync profiles automatically** - Courier creates and updates user profiles in real time from your CDP data
* **Trigger notifications from events** - Events like purchases, sign-ups, or usage milestones trigger Courier workflows
* **Personalize across channels** - Use CDP data to pick the channel and personalize content per user

## Available integrations

> **[Segment](/docs/integrations/cdp/segment)**
>
> Send events to Courier and track notification events in Segment

> **[RudderStack](/docs/integrations/cdp/rudderstack)**
>
> Sync events with Courier and send notification data to RudderStack


# Sync events between RudderStack and Courier
Source: https://www.courier.com/docs/integrations/cdp/rudderstack

Route RudderStack events into Courier journeys, and stream message events back.

RudderStack events flow into Courier, and Courier events flow back out. Outbound sends need your RudderStack write key and data plane URL.

## RudderStack to Courier

RudderStack supports Courier as a destination. Configure it inside RudderStack, connect one or more sources, and events start flowing into Courier.

Inbound events appear on the RudderStack integration page in Courier Studio. Map them there to trigger notification workflows. An `identify` event can trigger an automation that welcomes a new user.

**Supported RudderStack events:**

* Group
* Identify
* Track

### Configuration

Go to RudderStack destination and search for Courier.

![Search Courier Destination](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/search-courier-destination.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=90d4218be9e5e8680833c6f68647356b)

Connect one or more sources

![Connect Sources to Courier Destination](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/connect-sources-to-courier-destination.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=67583f119b75a1d9540bfa17b5e1a81a)

Add Courier API Key

![Add Courier API Key](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/courier-api-key.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=886618759b0e6e79db69bf2d52ac6d85)

### Event trigger

Trigger events through the sources you connected, or by calling RudderStack endpoints directly.

The Courier destination supports `group`, `identify` and `track` events. They appear on the RudderStack integration page in Courier Studio.

See the [RudderStack Node SDK documentation](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-node-sdk/#sending-events) for sending events to your RudderStack instance.

![Courier Inbound from RudderStack](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/courier-inbound-rudderstack.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=e35ee5c0a1c9ecb69d42044beb1d5780)

### Supported events

#### Identify

Identify events create or update a Courier user profile. The `userId` becomes the user identifier. The `traits` map to user profile attributes.

#### Track

Track events can trigger an automation or supply an inline automations payload. The `properties` in the payload map to Courier.

#### Group

Group events can create an account or trigger an automation. The `groupId` becomes the Account ID. The `userId`, or `anonymousId` if `userId` is absent, becomes the User Identifier.

### Event mapping

Map a received event to an existing automation, or create a new automation with the event as its trigger.

Click the plus (+) icon under link automations, then pick an existing automation template or create one.

Scope properties by the `courier.automation` object. To map userId to refs, send this to RudderStack:

```json Rudderstack Courier Automation Property Example theme={null}
{
  "event": "user-checkout",
  "type": "track",
  "properties": {
    "courier": {
      "automation": {
        "data": {
          "userId": "user_123"
        }
      }
    }
  }
}
```

Mapped automation would look like this:

![RudderStack Mapped Automation V2](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/rudderstack-mapped-automation-v2.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=4c6829df778df223b59b4cae6f023526)

[Learn more about Journeys >
DOC](/docs/journeys/build)

***

## Courier to RudderStack

Courier generates events during workflow execution (for instance, a "message sent" event when a message is delivered). These events can be sent outbound to RudderStack, which can further unlock other use cases and wire up other destinations inside RudderStack.

### Configuration

Add a source in RudderStack that will receive events from Courier (for example, a Node.js source). Once the source is created, copy the write key and data plane URL to the Courier RudderStack integration page.

![RudderStack Source Config](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/rudderstack-source-config.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=46b9ae9eecfa17003715b3ab2aa4f7b9)

RudderStack Source Config

![Courier RudderStack Source Config](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/courier-rudderstack-source-config.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=3de29db6af69d5977bba516917030be0)

Courier RudderStack Source Config

### Event sourcing

Courier will start sending generated events (like Message Sent) to your RudderStack instance. These should show up on your RudderStack source page.

![Courier to RudderStack Events](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/courier-to-rudderstack-events.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=43c18c8c0964dda02840940df9c15c5c)

Courier to RudderStack Events

***

## Example use cases

* User sync from RudderStack to Courier
* Welcoming new users based on sign-up tracking
* Nudging users to upgrade to a paid tier based on usage tracking


# Sync events between Segment and Courier
Source: https://www.courier.com/docs/integrations/cdp/segment

Send Segment identify and track events into Courier, and stream message events back.

## Segment to Courier

Courier's Segment destination sends data from your web or mobile app into Courier.

Events appear on the [Segment integration page](https://app.courier.com/integrations/catalog/segment) in Courier Studio, where you map them to notification workflows. For example, an `analytics.identify` event can trigger an automation that welcomes a new user.

[Start a journey from Segment
GUIDE](/docs/guides/notify-from-segment) walks that setup end to end.

**Supported Segment events:**

* `analytics.group`
* `analytics.identify`
* `analytics.track`

### Connecting Segment

**1. Open the Segment Destinations catalog**

In the Segment app, open the [Destinations](https://segment.com/docs/connections/destinations) catalog page.

**2. Add a destination**

Click **Add Destination**.

**3. Select the Courier destination**

Search the catalog for Courier and select the Courier destination.

**4. Choose a source**

Choose the Source that sends data to the Courier destination.

**5. Get your Courier API Key**

On the [Courier Integrations Page](https://app.courier.com/integrations), search for Segment and open it to get the Courier API Key. If no key is there, copy the Auth Token from the API Keys section of the [Courier Settings Page](https://app.courier.com/settings).

**6. Enter the API Key in Segment**

In Segment, enter the Courier API Key or Auth Token in the Courier destination's API Key field.

**7. Validate the setup**

Open the destination's "Event Tester" in Segment and click "Send Event" at the bottom of the page. In Courier Studio, refresh or wait a few seconds. The test event appears in the list if setup succeeded.

### Identify calls

Segment Identify calls connect a user to their actions (Segment events) and record traits about them.
Segment identifies the user by User ID, and the call can carry traits such as name and email.
Courier uses those traits to update recipient profiles over time. See the [Segment Identify spec](https://segment.com/docs/connections/spec/identify/) and [Courier Profiles API](/docs/api-reference/user-profiles/get-a-profile) for details.

Example payload

```json theme={null}
{
  "messageId": "segment-test-message-iskh4123",
  "timestamp": "2024-05-21T18:00:18.913Z",
  "type": "identify",
  "email": "sarah@acme-corp.com",
  "traits": {
    "trait1": 2,
    "email": "sarah@acme-corp.com"
  },
  "userId": "user_123"
}
```

### Track calls

Segment Track calls record actions your users perform, along with any properties on those actions. See the [Segment Track spec](https://segment.com/docs/connections/spec/track/) for details.

Track events appear in Courier with a `track/` prefix. Courier reads data from the track's `properties` object. Map track events to Courier journeys to send notifications from them.

An example Segment API call:

```javascript theme={null}
analytics.track('Login Button Clicked', {
  messageId: "segment-test-message-a8rmf",
  timestamp: "2021-12-07T08:41:59.410Z",
  type: "track",
  email: "sarah@acme-corp.com",
  projectId: "4GgKeBoVJkT9EZL4vAmduv",
  properties: {
    property1: 1,
    property2: "test",
    property3: true
  },
  userId: "user_123",
  event: "Segment Test Event Name"
})
```

Courier receives that call as a track event:

```json theme={null}
{
  "messageId": "segment-test-message-a8rmf",
  "timestamp": "2021-12-07T08:41:59.410Z",
  "type": "track",
  "email": "sarah@acme-corp.com",
  "projectId": "4GgKeBoVJkT9EZL4vAmduv",
  "properties": {
    "property1": 1,
    "property2": "test",
    "property3": true
  },
  "userId": "user_123",
  "event": "Segment Test Event Name"
}
```

Courier maps that object into its data object:

```json theme={null}
{
  "data": {
    "property1": 1,
    "property2": "test",
    "property3": true
  }
}
```

### Troubleshooting

A persistent "No Segment events received yet." message usually means Segment couldn't set up your Courier workspace as a destination. To get the test event through:

1. Confirm the API Key was copied into Segment exactly.
2. Check where the `email` property sits in Segment's test JSON object. On an identify call it belongs inside the `traits` object, not at the top level. Move it and resend the test event.
3. If it still fails, reach out to Courier Support.

***

## Courier to Segment

Configure Courier as a Segment Source, and Courier message and audience events flow back into Segment for analytics.

### Setting up Courier as a Segment source

**1. Open the Sources page**

In Segment, open the *Sources* page under "Connections".

**2. Select your framework**

Select your framework, for example Node.js.

**3. Obtain a write key**

Segment then shows instructions for adding it to that codebase. Copy the write key from this page.

**4. Paste the write key into Courier**

In Courier's Segment configuration, paste your [Segment Write Key](https://segment.com/docs/connections/find-writekey/) into the *Segment write key* field.

Courier starts sending updates to Segment once the write key is saved.

### Courier events sent to Segment

With Courier as a Segment source, Segment can track these events:

#### Message events

* `Message Clicked`
* `Message Delivered`
* `Message Opened`
* `Message Sent`
* `Message Undeliverable`
* `Message Unroutable`

#### Audience events

* `Audience User Matched`
* `Audience User Unmatched`

#### Preferences events

* `User Subscribed`
* `User Unsubscribed`


# Send Chat API messages through Courier
Source: https://www.courier.com/docs/integrations/direct-message/chat

Connect the Chat API and address a recipient by phone number or chat ID on the profile.

> [!WARNING]
>
> The Chat API service (`chat-api.com`) may no longer be maintained. Check its status before you integrate.

## Prerequisites

* [A Chat API account with an instance](https://chat-api.com/)
* Your Chat API instance ID and token

## Setup

**1. Get your Chat API credentials**

In Chat API, open your [instance dashboard](https://app.chat-api.com/) and copy the instance ID and token.

**2. Configure in Courier**

Open the [Chat API integration](https://app.courier.com/integrations/catalog/chat-api) in Courier, enter your instance ID and token, then save.

## Profile requirements

Chat API addresses the recipient by phone number or chat ID, so the profile you send to needs a `chat_api` object. Store either one once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

**Phone number**

The number in the recipient's WhatsApp account.

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    chat_api: {
      phone_number: '12345678',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "chat_api": {
            "phone_number": "12345678",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "chat_api": {
        "phone_number": "12345678"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    chat_api: {
      phone_number: "12345678"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"chat_api": map[string]any{
				"phone_number": "12345678",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("chat_api", JsonValue.from(java.util.Map.of(
            "phone_number", "12345678")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'chat_api' => [
    'phone_number' => '12345678',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "chat_api": {
            "phone_number": "12345678"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"chat_api":{"phone_number":"12345678"}}'
```

```text MCP theme={null}
With Courier MCP, save the Chat API phone number 12345678 on user_123.
```

**Chat id**

The id of an existing conversation.

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    chat_api: {
      chat_id: 'recipient-chat-id',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "chat_api": {
            "chat_id": "recipient-chat-id",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "chat_api": {
        "chat_id": "recipient-chat-id"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    chat_api: {
      chat_id: "recipient-chat-id"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"chat_api": map[string]any{
				"chat_id": "recipient-chat-id",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("chat_api", JsonValue.from(java.util.Map.of(
            "chat_id", "recipient-chat-id")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'chat_api' => [
    'chat_id' => 'recipient-chat-id',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "chat_api": {
            "chat_id": "recipient-chat-id"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"chat_api":{"chat_id":"recipient-chat-id"}}'
```

```text MCP theme={null}
With Courier MCP, save the Chat API chat id recipient-chat-id on user_123.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "chat_api": { "phone_number": "12345678" } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `chat_api` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `chat_api`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      chat_api: {
        phone_number: "12345678",
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-6} theme={null}
response = client.send.message(
    message={
        "to": {
            "chat_api": {
                "phone_number": "12345678",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-9} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "chat_api": {
          "phone_number": "12345678"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
response = courier.send_.message(
  message: {
    to: {
      chat_api: {
        phone_number: "12345678"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"chat_api": {"phone_number": "12345678"}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("chat_api", JsonValue.from(Map.of(
            "phone_number", "12345678")))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-6} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'chat_api' => [
        'phone_number' => '12345678',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"chat_api": {"phone_number": "12345678"}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"chat_api": {"phone_number": "12345678"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the chat API number 12345678.
```

## Template

In the notification's integration settings, set a quoted message ID and mentioned phone numbers.

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A provider override changes the request body or swaps credentials at send time. `body` takes any field Chat API's `/sendMessage` endpoint supports. `config` swaps the instance ID, token, or API URL.

This example swaps the credentials:

```javascript Node.js highlight={13-20} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      chat_api: {
        phone_number: "12345678",
      },
    },
    data: {
      name: "Sarah Bennett",
    },
    providers: {
      "chat-api": {
        override: {
          config: {
            instanceId: "RUNTIME_INSTANCE_ID",
            token: "RUNTIME_TOKEN",
          },
        },
      },
    },
  },
});
```

```python Python highlight={13-20} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "chat_api": {
                "phone_number": "12345678",
            },
        },
        "data": {
            "name": "Sarah Bennett",
        },
        "providers": {
            "chat-api": {
                "override": {
                    "config": {
                        "instanceId": "RUNTIME_INSTANCE_ID",
                        "token": "RUNTIME_TOKEN",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={16-23} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "chat_api": {
          "phone_number": "12345678"
        }
      },
      "data": {
        "name": "Sarah Bennett"
      },
      "providers": {
        "chat-api": {
          "override": {
            "config": {
              "instanceId": "RUNTIME_INSTANCE_ID",
              "token": "RUNTIME_TOKEN"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={13-20} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      chat_api: {
        phone_number: "12345678"
      }
    },
    data: {
      name: "Sarah Bennett"
    },
    providers: {
      "chat-api": {
        override: {
          config: {
            instanceId: "RUNTIME_INSTANCE_ID",
            token: "RUNTIME_TOKEN"
          }
        }
      }
    }
  }
)
```

```go Go highlight={17-24} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "chat_api": {
    "phone_number": "12345678"
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
		Providers: shared.MessageProvidersParam{
			"chat-api": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"instanceId": "RUNTIME_INSTANCE_ID",
						"token": "RUNTIME_TOKEN",
					},
				},
			},
		},
	},
})
```

```java Java highlight={15-20} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("chat_api", JsonValue.from(java.util.Map.of(
                "phone_number", "12345678"
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett"
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("chat-api", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "instanceId", "RUNTIME_INSTANCE_ID",
                        "token", "RUNTIME_TOKEN"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={13-20} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'chat_api' => [
        'phone_number' => '12345678',
      ],
    ],
    'data' => [
      'name' => 'Sarah Bennett',
    ],
    'providers' => [
      'chat-api' => [
        'override' => [
          'config' => [
            'instanceId' => 'RUNTIME_INSTANCE_ID',
            'token' => 'RUNTIME_TOKEN',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={25-40} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "chat_api": {
                    "phone_number": "12345678"
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "chat-api",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "instanceId": "RUNTIME_INSTANCE_ID",
                            "token": "RUNTIME_TOKEN"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"chat_api": {"phone_number": "12345678"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}' \
  --message.providers '{"chat-api": {"override": {"config": {"instanceId": "RUNTIME_INSTANCE_ID", "token": "RUNTIME_TOKEN"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this Chat API number, swapping the instance id and token.
```

## Provider details

```text theme={null}
chat-api
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send Discord messages through Courier
Source: https://www.courier.com/docs/integrations/direct-message/discord

Connect a Discord bot and send to users or channels by ID, with embed overrides.

## Prerequisites

* [A Discord bot](https://discord.com/developers/docs/intro)
* [Your Discord bot token](https://discord.com/developers/applications)

## Setup

Open the [Discord integration](https://app.courier.com/integrations/catalog/discord) in Courier, enter your bot token, then save.

### Scopes

Update the `bot` scope with these permissions:

* `View Channels`
* `Send Messages`
* Optional: `Read Message History` to send a message as a reply to another message

See [Discord's guide to adding scopes and permissions](https://discord.com/developers/docs/getting-started#adding-scopes-and-permissions).

Open the generated invite URL. It adds the bot to the server with the permissions you chose.

## Profile requirements

Discord addresses the recipient by user ID or channel ID, under `discord` on the profile. Store either one once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

**Direct message**

**1. Open User Settings**

Go to User Settings on Discord (next to profile on the bottom left).

**2. Enable Developer Mode**

Open Advanced settings and enable Developer Mode .

**3. Copy the user ID**

Right click on the user and copy the user ID.

This isn't the user tag. The user you're trying to message must be a member of a server the bot is installed in.

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    discord: {
      user_id: '617099137532932107',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "discord": {
            "user_id": "617099137532932107",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "discord": {
        "user_id": "617099137532932107"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    discord: {
      user_id: "617099137532932107"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"discord": map[string]any{
				"user_id": "617099137532932107",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("discord", JsonValue.from(java.util.Map.of(
            "user_id", "617099137532932107")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'discord' => [
    'user_id' => '617099137532932107',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "discord": {
            "user_id": "617099137532932107"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"discord":{"user_id":"617099137532932107"}}'
```

```text MCP theme={null}
With Courier MCP, save the Discord user id 617099137532932107 on user_123.
```

**Channel**

**1. Open User Settings**

Go to User Settings on Discord (next to profile on the bottom left).

**2. Enable Developer Mode**

Open Advanced settings and enable Developer Mode .

**3. Copy the channel ID**

Right click on the channel and copy the channel ID.

The bot must be installed in the server to send to the channel.

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    discord: {
      channel_id: '768866348853383208',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "discord": {
            "channel_id": "768866348853383208",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "discord": {
        "channel_id": "768866348853383208"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    discord: {
      channel_id: "768866348853383208"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"discord": map[string]any{
				"channel_id": "768866348853383208",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("discord", JsonValue.from(java.util.Map.of(
            "channel_id", "768866348853383208")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'discord' => [
    'channel_id' => '768866348853383208',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "discord": {
            "channel_id": "768866348853383208"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"discord":{"channel_id":"768866348853383208"}}'
```

```text MCP theme={null}
With Courier MCP, save the Discord channel id 768866348853383208 on user_123.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "discord": { "user_id": "617099137532932107" } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `discord` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `discord`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      discord: {
        user_id: "617099137532932107",
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-6} theme={null}
response = client.send.message(
    message={
        "to": {
            "discord": {
                "user_id": "617099137532932107",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-9} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "discord": {
          "user_id": "617099137532932107"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
response = courier.send_.message(
  message: {
    to: {
      discord: {
        user_id: "617099137532932107"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"discord": {"user_id": "617099137532932107"}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("discord", JsonValue.from(Map.of(
            "user_id", "617099137532932107")))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-6} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'discord' => [
        'user_id' => '617099137532932107',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"discord": {"user_id": "617099137532932107"}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"discord": {"user_id": "617099137532932107"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the Discord user 617099137532932107.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A provider override changes what Courier sends to Discord's [Create Message](https://discord.com/developers/docs/resources/channel#create-message) endpoint. Overrides are deep-merged into the request. Fields you set replace their counterparts, and everything you leave out is still sent. For example, add an embed.

```javascript Node.js highlight={5-7,10-19} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      discord: {
        channel_id: "768866348853383208",
      },
    },
    providers: {
      discord: {
        override: {
          body: {
            embed: {
              title: "Hello, Embed!",
              description: "This is an embedded message.",
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={5-7,10-19} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "discord": {
                "channel_id": "768866348853383208",
            },
        },
        "providers": {
            "discord": {
                "override": {
                    "body": {
                        "embed": {
                            "title": "Hello, Embed!",
                            "description": "This is an embedded message.",
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={8-10,13-22} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "discord": {
          "channel_id": "768866348853383208"
        }
      },
      "providers": {
        "discord": {
          "override": {
            "body": {
              "embed": {
                "title": "Hello, Embed!",
                "description": "This is an embedded message."
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={5-7,10-19} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      discord: {
        channel_id: "768866348853383208"
      }
    },
    providers: {
      discord: {
        override: {
          body: {
            embed: {
              title: "Hello, Embed!",
              description: "This is an embedded message."
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={4-6,14-23} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "discord": {
    "channel_id": "768866348853383208"
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"discord": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"embed": map[string]any{
							"title": "Hello, Embed!",
							"description": "This is an embedded message.",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-8,12-19} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("discord", JsonValue.from(java.util.Map.of(
                "channel_id", "768866348853383208"
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("discord", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "embed", java.util.Map.of(
                            "title", "Hello, Embed!",
                            "description", "This is an embedded message."
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={5-7,10-19} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'discord' => [
        'channel_id' => '768866348853383208',
      ],
    ],
    'providers' => [
      'discord' => [
        'override' => [
          'body' => [
            'embed' => [
              'title' => 'Hello, Embed!',
              'description' => 'This is an embedded message.',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={11-13,21-38} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "discord": {
                    "channel_id": "768866348853383208"
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "discord",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "embed": {
                              "title": "Hello, Embed!",
                              "description": "This is an embedded message."
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3,5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"discord": {"channel_id": "768866348853383208"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"discord": {"override": {"body": {"embed": {"title": "Hello, Embed!", "description": "This is an embedded message."}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to Discord channel 768866348853383208 with a body override.
```

## Provider details

```text theme={null}
discord
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send Facebook Messenger messages through Courier
Source: https://www.courier.com/docs/integrations/direct-message/facebook-messenger

Connect a Facebook Page and address a recipient by facebookPSID on the profile.

## Prerequisites

* [A Facebook Page with Messenger enabled](https://www.facebook.com/pages/create)
* [A Facebook App with the Messenger platform](https://developers.facebook.com/apps/)
* Your Page Access Token

## Setup

**1. Generate a Page Access Token**

In Meta, open [your apps](https://developers.facebook.com/apps/), add Messenger to the app, and generate a Page Access Token for the page you send from.

**2. Configure in Courier**

Open the [Facebook Messenger integration](https://app.courier.com/integrations/catalog/facebook-messenger) in Courier, enter your Page Access Token, then save.

## Profile requirements

Facebook Messenger addresses the recipient by Page-Scoped ID, so the profile you send to needs a `facebookPSID`. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    facebookPSID: '1254477777772919',
  },
});
```

```python Python highlight={4} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "facebookPSID": "1254477777772919",
    },
)
```

```bash cURL highlight={7} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "facebookPSID": "1254477777772919"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    facebookPSID: "1254477777772919"
  }
)
```

```go Go highlight={6} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"facebookPSID": "1254477777772919",
		},
	},
)
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("facebookPSID", JsonValue.from("1254477777772919"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'facebookPSID' => '1254477777772919',
]);
```

```csharp C# highlight={6} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "facebookPSID", JsonSerializer.SerializeToElement("1254477777772919") },
    },
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"facebookPSID":"1254477777772919"}'
```

```text MCP theme={null}
With Courier MCP, create a profile for user_123 with the facebookPSID 1254477777772919.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "facebookPSID": "1254477777772919" }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `facebookPSID` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to a PSID**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      facebookPSID: "1254477777772919",
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "facebookPSID": "1254477777772919",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "facebookPSID": "1254477777772919"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      facebookPSID: "1254477777772919"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={3} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"facebookPSID": "1254477777772919"}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("facebookPSID", JsonValue.from("1254477777772919"))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'facebookPSID' => '1254477777772919',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"facebookPSID": "1254477777772919"}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"facebookPSID": "1254477777772919"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the Facebook PSID 1254477777772919.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A provider override changes the request body Courier sends to Messenger, or swaps the Page Access Token and API URL.

### Body overrides

You can override any of the fields in the request body that Courier sends to the Messenger [Send API](https://developers.facebook.com/docs/messenger-platform/reference/send-api/).

```javascript Node.js highlight={8-14} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      facebookPSID: "1254477777772919",
    },
    providers: {
      "facebook-messenger": {
        override: {
          body: {
            messaging_type: "UPDATE",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-14} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "facebookPSID": "1254477777772919",
        },
        "providers": {
            "facebook-messenger": {
                "override": {
                    "body": {
                        "messaging_type": "UPDATE",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-17} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "facebookPSID": "1254477777772919"
      },
      "providers": {
        "facebook-messenger": {
          "override": {
            "body": {
              "messaging_type": "UPDATE"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-14} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      facebookPSID: "1254477777772919"
    },
    providers: {
      "facebook-messenger": {
        override: {
          body: {
            messaging_type: "UPDATE"
          }
        }
      }
    }
  }
)
```

```go Go highlight={12-18} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "facebookPSID": "1254477777772919"
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"facebook-messenger": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"messaging_type": "UPDATE",
					},
				},
			},
		},
	},
})
```

```java Java highlight={10-14} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("facebookPSID", JsonValue.from("1254477777772919"))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("facebook-messenger", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "messaging_type", "UPDATE"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-14} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'facebookPSID' => '1254477777772919',
    ],
    'providers' => [
      'facebook-messenger' => [
        'override' => [
          'body' => [
            'messaging_type' => 'UPDATE',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={19-33} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "facebookPSID": "1254477777772919"
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "facebook-messenger",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "messaging_type": "UPDATE"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"facebookPSID": "1254477777772919"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"facebook-messenger": {"override": {"body": {"messaging_type": "UPDATE"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this Messenger PSID and override the message body.
```

### Config overrides

You can swap the Page Access Token or API URL at send time:

```javascript Node.js highlight={8-14} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      facebookPSID: "1254477777772919",
    },
    providers: {
      "facebook-messenger": {
        override: {
          config: {
            access_token: "RUNTIME_PAGE_ACCESS_TOKEN",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-14} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "facebookPSID": "1254477777772919",
        },
        "providers": {
            "facebook-messenger": {
                "override": {
                    "config": {
                        "access_token": "RUNTIME_PAGE_ACCESS_TOKEN",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-17} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "facebookPSID": "1254477777772919"
      },
      "providers": {
        "facebook-messenger": {
          "override": {
            "config": {
              "access_token": "RUNTIME_PAGE_ACCESS_TOKEN"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-14} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      facebookPSID: "1254477777772919"
    },
    providers: {
      "facebook-messenger": {
        override: {
          config: {
            access_token: "RUNTIME_PAGE_ACCESS_TOKEN"
          }
        }
      }
    }
  }
)
```

```go Go highlight={12-18} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "facebookPSID": "1254477777772919"
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"facebook-messenger": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"access_token": "RUNTIME_PAGE_ACCESS_TOKEN",
					},
				},
			},
		},
	},
})
```

```java Java highlight={10-14} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("facebookPSID", JsonValue.from("1254477777772919"))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("facebook-messenger", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "access_token", "RUNTIME_PAGE_ACCESS_TOKEN"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-14} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'facebookPSID' => '1254477777772919',
    ],
    'providers' => [
      'facebook-messenger' => [
        'override' => [
          'config' => [
            'access_token' => 'RUNTIME_PAGE_ACCESS_TOKEN',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={19-33} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "facebookPSID": "1254477777772919"
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "facebook-messenger",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "access_token": "RUNTIME_PAGE_ACCESS_TOKEN"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"facebookPSID": "1254477777772919"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"facebook-messenger": {"override": {"config": {"access_token": "RUNTIME_PAGE_ACCESS_TOKEN"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this Messenger PSID with a different page access token.
```

## Provider details

```text theme={null}
facebook-messenger
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send Microsoft Teams messages through Courier
Source: https://www.courier.com/docs/integrations/direct-message/microsoft-teams

Connect a Teams bot, send to users and channels, reply in threads, and send Adaptive Cards.

Create a Microsoft Teams app with a bot. The bot lets Courier send notifications to Teams channels and users.

## Prerequisites

* [An account on the Microsoft Teams Developer Portal](https://dev.teams.microsoft.com/)
* [An Azure portal account with App Registration permissions](https://portal.azure.com/)
* An administrator to grant API permissions, but only to address recipients by `email` or `channel_name`
* [A Courier workspace](https://app.courier.com/)

You build three things: an Azure app registration for authentication, a Teams app to install, and a bot that sends. Courier only ever holds one set of credentials, the bot's.

## Setup

Steps 1 through 8 are the whole setup for addressing a recipient by `conversation_id`, `channel_id`, or `user_id`. Step 9 adds Graph API permissions, which need an administrator, and only `email` and `channel_name` need them.

> **Step 1: Create the Teams app**
>
> 1. Navigate to the [Microsoft Teams Developer Portal](https://dev.teams.microsoft.com/).
> 2. Click **Create a new app**.
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-new-app.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=29ac21e615f40613ba6e930244e54e11)
>
> Teams App Creation
>
> 3. Enter a name for your app and click **Add**.
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-name-the-app.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=cd1df9a2e290ab51364400508fe4d32a)
>
> Naming the new app
>
> > [!TIP]
> >
> > Add `_app` to your app name to tell it apart from your bot. This matters most if you manage several apps or bots.
>
> 4. Save the generated **App ID** for later.

> **Step 2: Create the Azure app**
>
> 1. Open the [Azure Portal](https://portal.azure.com/).
> 2. Go to **Azure Active Directory > App registrations**.
>
> ![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/azure-app-registration.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=20a30b3ebee6271a79d4f619edc179c7)
>
> Azure App Registration
>
> 3. Click **New registration**.
> 4. Configure the registration:
>    * **Name**: Use the same name as your Teams Developer Portal app
>    * **Supported account types**: Select **"Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)"**. The Azure default is single-tenant, which causes 401 authentication errors with Bot Framework.
>    * **Redirect URI**: Keep the default setting
>
> ![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/azure-app-config.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=ab401a99e1c1f05bdcbff67ca4786171)
>
> Azure App Configuration
>
> 5. Click **Register**.
> 6. Save your **Application (client) ID** for later.
>
> ![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/azure-app-id.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=53c4dffd804d2551705e44ca1d5f79bf)
>
> Grab your Azure AppID

> **Step 3: Link the Teams app to the Azure app**
>
> 1. Return to the [Microsoft Teams Developer Portal](https://dev.teams.microsoft.com/).
> 2. Go to **Configure > Basic Information**.
> 3. Scroll to the bottom of the page to the **Application (client) ID** field.
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-azure-app-linking.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=bffeafa1262079dbfa6dcdc384e5237f)
>
> Teams and Azure app linking
>
> 4. Paste the Application (client) ID you saved from Step 2.
>
> 5. Click **Save**.
>
> > [!NOTE]
> >
> > This Application (client) ID comes from your Azure App Registration (Step 2). Courier uses different credentials (Step 5), from the Bot's Azure App Registration (Step 4).

> **Step 4: Create the bot and set permissions**
>
> 1. In the [Microsoft Teams Developer Portal](https://dev.teams.microsoft.com/), go to **Tools > Bot Management**.
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-create-bot.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=091d6b656bd70c9f6ad0bd6c95984726)
>
> Create new bot for Teams
>
> 2. Click **+ New Bot** and provide a unique name.
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-name-the-bot.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=ed10b56602dde10f3963432ea911bae9)
>
> Naming your new bot
>
> > [!TIP]
> >
> > Use a distinct name for your bot to avoid confusion with your app.
>
> 3. Return to **Apps > \[Your App Name] > Configure > App Features**
> 4. Click the **Bot** item
> 5. Select **Select an existing bot**
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-bot-selection.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=3d3dcc5e729758e1f33ef51cf4fb2b59)
>
> Select your newly created bot
>
> 6. Choose the bot you created
> 7. Configure the bot settings:
>    * Under **What can your bot do?**, select:
>      * ✓ Only send notifications (one-way conversations)
>    * Under **Select the scopes where people can use your bot**, select:
>      * ✓ Personal (for 1:1 notifications)
>      * ✓ Team (for channel notifications)
>      * ✓ Group Chat (for group chat notifications)
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-bot-scopes.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=107ed039cec0dda8a7769fb78ae7c4e3)
>
> Select the scope for your bot
>
> 8. Click **Save**
>
> 9. **Configure API permissions**, only to address recipients by `email` or `channel_name`. Courier calls Microsoft Graph to turn those into an id, and that call needs an administrator's consent. Skip this step if you send by `conversation_id`, `channel_id`, or `user_id`.
>    * Return to the [Azure Portal](https://portal.azure.com/).
>    * Go to **App registrations > \[Your Bot Name] > API permissions**
>    * Add these Microsoft Graph permissions as **Application permissions**:
>      * `ChannelSettings.Read.All`
>      * `TeamSettings.Read.All`
>      * `User.Read.All`
>    * Ask an administrator to click **Grant admin consent for \[your\_domain]**
>
> ![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/azure-permissions.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=1e23b305ce1f5b857c6b7b9448b6e172)
>
> Add API permissions
>
> 10. **Generate bot credentials**:
>     * In Azure, go to **App registrations > \[Your Bot Name] > Certificates & secrets**
>     * Click **+ New client secret**
>
> ![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/azure-new-secret.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=c451215aad303d9851e4597e1f0c4bbf)
>
> Create a new client secret
>
> * Name it and select an expiration period
> * Click **Create**
> * **Important**: copy and store the generated secret value immediately
> * Go to the **Overview** section
> * Copy and store the **Application (client) ID** alongside your secret
>
> ![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/azure-bot-id.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=dccd34022310be95d82aa7fc7583a38e)
>
> Get the ApplicationID from Azure (i.e. BotID)

> **Step 5: Configure in Courier**
>
> 1. Head to the [Teams Integration](https://app.courier.com/integrations/catalog/msteams) in Courier.
> 2. Enter your Azure credentials from Step 4 (see the callout below for which field goes where):
>
> ![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/courier-adding-teams.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=cddaabb2d6dc644f7cacc6baef5db76b)
>
> Add teams to your Courier Account
>
> 3. Click **Install Provider**.
>
> > [!WARNING]
> >
> > **Courier's field names don't match Azure's.**\\
> >
> > Paste your Azure **Application (client) ID** into **App ID**. Your **client secret value**, the Value and not the Secret ID, goes into **App Password**. Both come from the Azure Bot App Registration in Step 4.
>
> > [!NOTE]
> >
> > Find both values in the Azure Bot App Registration from Step 4:
> >
> > * [Azure Portal](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps) > **App registrations > \[Your Bot Name]**: *"Application (client) ID"*
> > * [Azure Portal](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps) > **App registrations > \[Your Bot Name] > Certificates & secrets**: *"Client secrets"*

> **Step 6: Install the app and test**
>
> **Install the App in Teams:**
>
> 1. Return to [Apps > your app](https://dev.teams.microsoft.com/apps)
> 2. Click **Publish**. When prompted, select **"Download the app package"**
>    * **Note:** fill in both the short and long app descriptions under **Configure > Basic information**. The app manifest requires them, and the app fails to install in Teams without them.
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-publish-app.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=9f11985484a9a6e6dadffd9fa8afe614)
>
> Publish your app
>
> 3. Go to [Microsoft Teams](https://teams.microsoft.com/)
> 4. Go to **Apps** and select **"Manage your apps"** at the bottom
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-manage-app.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=536cd52cafcc745ecaa2fd5f1ff9e46b)
>
> Manage your app
>
> 5. Click **"Upload an app"** and select your downloaded app package
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-upload-app.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=ff648c0fb54689ba0c36a7dd29c18ee4)
>
> Upload your app
>
> 6. When prompted, click **"Add"**
>
> > [!WARNING]
> >
> > **Uploading the app only covers 1:1 messaging.** Channel messages fail with a 401 until the app is installed in each team, even with correct credentials.
>
> To install it, open the target team in Microsoft Teams and click the **...** menu beside its name. Choose **Manage team**, open the **Apps** tab, find your app, and click **Add**.
>
> 7. Courier can now send messages to your channels and team members
>
> **Get channel identifiers (for testing):**
>
> 1. Open [Microsoft Teams](https://teams.microsoft.com/)
> 2. Hover over a channel, click the ellipsis icon, and select **"Copy link"**.
> 3. You get a URL like: `https://teams.microsoft.com/l/channel/19%3A5140d7460868414cac958ac76a0a94d0%40thread.skype/slack-teams-test?groupId=feb55fc1-9e00-40f3-93b8-f7d14703f4dd&tenantId=dabd1935-56a4-4305-938e-0840e2e84515`
> 4. Paste it into a URL decoder such as [Eric Meyer's dencoder](https://meyerweb.com/eric/tools/dencoder/)
> 5. Copy the **group ID**, the team's identifier. Here: `feb55fc1-9e00-40f3-93b8-f7d14703f4dd`
> 6. Copy the **channel name**. Here: `slack-teams-test`
> 7. Copy the **tenant ID**. Here: `dabd1935-56a4-4305-938e-0840e2e84515`
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-get-channel-name.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=7b1a00a45610e8aaec55a3ec9f1faa77)
>
> Get channel name
>
> **Send a test message:**
>
> 1. Return to [Courier](https://app.courier.com/assets/templates) and create a new template.
> 2. Select the Teams provider you configured in Step 5
> 3. In the **"Design"** tab, write a basic text message. See [how templates work
>    DOC](/docs/design/templates/overview) for the designer.
> 4. Click the **Preview** tab. Create a **"Test event"**, a request you can use to send a message.
> 5. Click **"Create test event"** and enter this, using your own values:
>
> ```json TestEvent theme={null}
> {
>   "courier": {},
>   "data": {},
>   "profile": {
>     "ms_teams": {
>       "team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>       "channel_name": "slack-teams-test",
>       "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
>       "service_url": "https://smba.trafficmanager.net/amer"
>     }
>   },
>   "override": {},
>   "meta": {}
> }
> ```
>
> 6. Click **"Publish"**
> 7. Go to the **Send** tab. Click **"Send Test"**

## Profile requirements

The recipient's profile needs an `ms_teams` object with:

* `service_url`, optional. Defaults to `https://smba.trafficmanager.net/amer`, so set it only if your tenant is outside the Americas.
* `tenant_id`, required for `email` and `channel_name` (see [Using a tenant\_id](#using-a-tenant_id)). Courier also reads it from the `service_url` path.
* One of these identifiers:
  * `user_id`
  * `email`
  * `channel_id`
  * `conversation_id`
  * Combination of `team_id` and `channel_name`
  * Thread reply fields: `reply_to_activity_id` and `conversation_id`

```json user_id highlight={5} theme={null}
{
  "message": {
    "to": {
      "ms_teams": {
        "user_id": "<user_id>",
        "tenant_id": "<tenant_id>",
        "service_url": "https://smba.trafficmanager.net/amer"
      }
    }
  }
}
```

```json email highlight={5} theme={null}
{
  "message": {
    "to": {
      "ms_teams": {
        "email": "<user_email>",
        "tenant_id": "<tenant_id>",
        "service_url": "https://smba.trafficmanager.net/amer"
      }
    }
  }
}
```

```json conversation_id highlight={5} theme={null}
{
  "message": {
    "to": {
      "ms_teams": {
        "conversation_id": "<conversation_id>",
        "tenant_id": "<tenant_id>",
        "service_url": "https://smba.trafficmanager.net/amer"
      }
    }
  }
}
```

```json team_id+channel_name highlight={5-6} theme={null}
{
  "message": {
    "to": {
      "ms_teams": {
        "team_id": "<team_id>",
        "channel_name": "<channel_name>",
        "tenant_id": "<tenant_id>",
        "service_url": "https://smba.trafficmanager.net/amer"
      }
    }
  }
}
```

```json thread_reply highlight={5-6} theme={null}
{
  "message": {
    "to": {
      "ms_teams": {
        "reply_to_activity_id": "<activity_id>",
        "conversation_id": "<conversation_id>",
        "tenant_id": "<tenant_id>",
        "service_url": "https://smba.trafficmanager.net/amer"
      }
    }
  }
}
```

> [!NOTE]
>
> Open [teams.microsoft.com/?tenantId](https://teams.microsoft.com/?tenantId) and copy `tenantId` from the redirected URL. If it is missing, use the three-dot menu beside your Team, choose **Get link to team**, and read it from that URL.
>
> ![Locate Tenant ID in Microsoft Teams](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-tenant-id.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=1fff5413adb4e6c92eeccd5cb5264331)

> [!NOTE]
>
> For users in the Americas region, the standard service URL is `https://smba.trafficmanager.net/amer`.

> [!NOTE]
>
> To send with `email` or `channel_name`, your bot needs these Microsoft Graph API permissions:
>
> * `ChannelSettings.Read.All` (requires admin consent)
> * `TeamSettings.Read.All` (requires admin consent)
> * `User.Read.All`
>
> Courier uses them to resolve the `user_id` or `channel_id` through the Microsoft Graph API.

### Using a tenant\_id

Courier requires `tenant_id` for the two shapes that need a Microsoft Graph lookup:

* `email`, which Courier resolves to a user id
* `channel_name`, which Courier resolves to a channel id

Without it, those sends fail with `tenant_id is required when using 'email' or 'channel_name' for lookups`. Send it on a `user_id` too, since Teams needs it to open a personal conversation.

Courier also reads `tenant_id` from the `service_url` path segments. Set it on `service_url`, as a body parameter, or both when the values match.

```bash theme={null}
service_url: https://smba.trafficmanager.net/amer/{tenant_id}
tenant_id: {tenant_id}
```

> [!NOTE]
>
> `tenant_id` appears on `provider:sent` and `provider:delivered` event payloads only when the request includes it, because that is the only time Courier knows it. Replies still work without it.

When your bot is registered in a different Azure tenant from the recipient's, add `source_tenant_id` for the bot's home tenant. `tenant_id` still routes the message, and `source_tenant_id` authenticates the bot. Setting it without `tenant_id` fails.

Store whichever shape you picked on the profile. Store the `ms_teams` object once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3-7} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    ms_teams: {
      user_id: '<user_id>',
      tenant_id: '<tenant_id>',
      service_url: 'https://smba.trafficmanager.net/amer',
    },
  },
});
```

```python Python highlight={4-8} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "ms_teams": {
            "user_id": "<user_id>",
            "tenant_id": "<tenant_id>",
            "service_url": "https://smba.trafficmanager.net/amer",
        },
    },
)
```

```bash cURL highlight={7-11} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "ms_teams": {
        "user_id": "<user_id>",
        "tenant_id": "<tenant_id>",
        "service_url": "https://smba.trafficmanager.net/amer"
      }
    }
  }'
```

```ruby Ruby highlight={4-8} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    ms_teams: {
      user_id: "<user_id>",
      tenant_id: "<tenant_id>",
      service_url: "https://smba.trafficmanager.net/amer"
    }
  }
)
```

```go Go highlight={6-10} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"ms_teams": map[string]any{
				"user_id": "<user_id>",
				"tenant_id": "<tenant_id>",
				"service_url": "https://smba.trafficmanager.net/amer",
			},
		},
	},
)
```

```java Java highlight={4-7} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("ms_teams", JsonValue.from(java.util.Map.of(
            "user_id", "<user_id>",
            "tenant_id", "<tenant_id>",
            "service_url", "https://smba.trafficmanager.net/amer")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-6} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'ms_teams' => [
    'user_id' => '<user_id>',
    'tenant_id' => '<tenant_id>',
    'service_url' => 'https://smba.trafficmanager.net/amer',
  ],
]);
```

```csharp C# highlight={7-11} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "ms_teams": {
            "user_id": "<user_id>",
            "tenant_id": "<tenant_id>",
            "service_url": "https://smba.trafficmanager.net/amer"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"ms_teams":{"user_id":"<user_id>","tenant_id":"<tenant_id>","service_url":"https://smba.trafficmanager.net/amer"}}'
```

```text MCP theme={null}
With Courier MCP, save the Microsoft Teams user id and tenant id on user_123.
```

The other four shapes go on the profile the same way. Swap the identifier and keep `tenant_id` and `service_url`.

Then send to `user_id` and Courier resolves the address.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `ms_teams` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `ms_teams`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={4-8} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      ms_teams: {
        email: "sarah@acme-corp.com",
        service_url: "https://smba.trafficmanager.net/amer",
        tenant_id: "dabd1935-56a4-4305-938e-0840e2e84515",
      },
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-8} theme={null}
response = client.send.message(
    message={
        "to": {
            "ms_teams": {
                "email": "sarah@acme-corp.com",
                "service_url": "https://smba.trafficmanager.net/amer",
                "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-11} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "ms_teams": {
          "email": "sarah@acme-corp.com",
          "service_url": "https://smba.trafficmanager.net/amer",
          "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-8} theme={null}
response = courier.send_.message(
  message: {
    to: {
      ms_teams: {
        email: "sarah@acme-corp.com",
        service_url: "https://smba.trafficmanager.net/amer",
        tenant_id: "dabd1935-56a4-4305-938e-0840e2e84515"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5-9} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfMsTeamsRecipient: &shared.MsTeamsRecipientParam{
				MsTeams: shared.MsTeamsParamOfSendToMsTeamsEmail(
					"sarah@acme-corp.com",
					"https://smba.trafficmanager.net/amer",
					"dabd1935-56a4-4305-938e-0840e2e84515",
				),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={4-8} theme={null}
client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(MsTeamsRecipient.builder()
            .msTeams(SendToMsTeamsEmail.builder()
                .email("sarah@acme-corp.com")
                .serviceUrl("https://smba.trafficmanager.net/amer")
                .tenantId("dabd1935-56a4-4305-938e-0840e2e84515")
                .build())
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-8} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'ms_teams' => [
        'email' => 'sarah@acme-corp.com',
        'service_url' => 'https://smba.trafficmanager.net/amer',
        'tenant_id' => 'dabd1935-56a4-4305-938e-0840e2e84515',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={7-12} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new MsTeamsRecipient
        {
            MsTeams = new SendToMsTeamsEmail
            {
                Email = "sarah@acme-corp.com",
                ServiceUrl = "https://smba.trafficmanager.net/amer",
                TenantID = "dabd1935-56a4-4305-938e-0840e2e84515",
            },
        },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"ms_teams": {"email": "sarah@acme-corp.com", "service_url": "https://smba.trafficmanager.net/amer", "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com on Microsoft Teams.
```

## Thread replies

Courier can post a message as a reply to an existing channel message instead of a new root-level message. Every send returns reference data in the `provider:sent` event, an `activityId` and a `conversationId`. Use those values to reply to that message in a thread.

> **Thread reply overview**
>
> **The flow:**
>
> 1. Send a root-level message to any Teams channel
>
> 2. Look up the sent event (via API, webhook, or Courier UI) to get the `activityId` and `conversationId`
>
> 3. Use those identifiers to send channel thread replies
>
> * **Channels only.** A Microsoft platform limit: thread replies work in channels, not in 1:1 or group chats. Standard, private, and shared channels all work.
> * **Reference data required.** You need the `activityId` and `conversationId` from a previous message's `provider:sent` event.
> * **Validation.** Courier rejects invalid field combinations with a clear error.
>
> **Example workflow**
>
> **1. Send the initial message**
>
> ```javascript Node.js theme={null}
> const { requestId } = await courier.send.message({
>   message: {
>     template: "nt_01kx4h2jdafq8bk9aftxak4b40",
>     to: {
>       ms_teams: {
>         tenant_id: "your-tenant-id",
>         service_url: "https://smba.trafficmanager.net/amer",
>         team_id: "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>         channel_name: "general",
>       },
>     },
>   },
> });
> ```
>
> ```python Python theme={null}
> response = client.send.message(
>     message={
>         "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
>         "to": {
>             "ms_teams": {
>                 "tenant_id": "your-tenant-id",
>                 "service_url": "https://smba.trafficmanager.net/amer",
>                 "team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>                 "channel_name": "general",
>             },
>         },
>     },
> )
> ```
>
> ```bash cURL wrap theme={null}
> curl -X POST https://api.courier.com/send \
>   -H "Authorization: Bearer $COURIER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "message": {
>       "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
>       "to": {
>         "ms_teams": {
>           "tenant_id": "your-tenant-id",
>           "service_url": "https://smba.trafficmanager.net/amer",
>           "team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>           "channel_name": "general"
>         }
>       }
>     }
>   }'
> ```
>
> ```ruby Ruby theme={null}
> response = courier.send_.message(
>   message: {
>     template: "nt_01kx4h2jdafq8bk9aftxak4b40",
>     to: {
>       ms_teams: {
>         tenant_id: "your-tenant-id",
>         service_url: "https://smba.trafficmanager.net/amer",
>         team_id: "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>         channel_name: "general"
>       }
>     }
>   }
> )
> ```
>
> ```go Go theme={null}
> // This provider addresses the recipient with fields outside the typed
> // UserRecipient model, so pass the recipient as raw JSON.
> to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
>   "ms_teams": {
>     "tenant_id": "your-tenant-id",
>     "service_url": "https://smba.trafficmanager.net/amer",
>     "team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>     "channel_name": "general"
>   }
> }`))
>
> response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
> 	Message: courier.SendMessageParamsMessage{
> 		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
> 		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
> 	},
> })
> ```
>
> ```java Java theme={null}
> SendMessageParams params = SendMessageParams.builder()
>     .message(SendMessageParams.Message.builder()
>         // This provider addresses the recipient with fields outside the
>         // typed UserRecipient model, so pass them as additional properties.
>         .to(UserRecipient.builder()
>             .putAdditionalProperty("ms_teams", JsonValue.from(java.util.Map.of(
>                 "tenant_id", "your-tenant-id",
>                 "service_url", "https://smba.trafficmanager.net/amer",
>                 "team_id", "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>                 "channel_name", "general"
>             )))
>             .build())
>         .template("nt_01kx4h2jdafq8bk9aftxak4b40")
>         .build())
>     .build();
> SendMessageResponse response = client.send().message(params);
> ```
>
> ```php PHP theme={null}
> $response = $client->send->message(
>   message: [
>     'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
>     'to' => [
>       'ms_teams' => [
>         'tenant_id' => 'your-tenant-id',
>         'service_url' => 'https://smba.trafficmanager.net/amer',
>         'team_id' => 'feb55fc1-9e00-40f3-93b8-f7d14703f4dd',
>         'channel_name' => 'general',
>       ],
>     ],
>   ],
> );
> ```
>
> ```csharp C# theme={null}
> SendMessageParams parameters = new()
> {
>     Message = new()
>     {
>         // This provider addresses the recipient with fields outside the
>         // typed UserRecipient model, so build it from raw JSON.
>         To = UserRecipient.FromRawUnchecked(
>             JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
>                 """
>                 {
>                   "ms_teams": {
>                     "tenant_id": "your-tenant-id",
>                     "service_url": "https://smba.trafficmanager.net/amer",
>                     "team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>                     "channel_name": "general"
>                   }
>                 }
>                 """
>             )
>         ),
>         Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
>     },
> };
>
> var response = await client.Send.Message(parameters);
> ```
>
> ```bash CLI wrap theme={null}
> courier send message \
>   --api-key "$COURIER_API_KEY" \
>   --message.to '{"ms_teams": {"tenant_id": "your-tenant-id", "service_url": "https://smba.trafficmanager.net/amer", "team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd", "channel_name": "general"}}' \
>   --message.template nt_01kx4h2jdafq8bk9aftxak4b40
> ```
>
> ```text MCP theme={null}
> With Courier MCP, send my template to the general channel in my Teams team.
> ```
>
> **2. Get reference data from the provider:sent event**
>
> The `provider:sent` event carries the reference data. Read it from:
>
> * **Courier API**: query message details for the `provider:sent` event data
> * **Courier UI**: view message details in the Messages section of your dashboard
> * **Webhooks** (if configured): receive the reference data on every send
>
> Example reference data from the `provider:sent` event:
>
> ```json theme={null}
> {
>   "reference": {
>     "activityId": "1756945821955",
>     "conversationId": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype"
>   }
> }
> ```
>
> **3. Send the thread reply**
>
> ```javascript Node.js theme={null}
> const { requestId } = await courier.send.message({
>   message: {
>     template: "nt_01kx4h2jdafq8bk9aftxak4b40",
>     to: {
>       ms_teams: {
>         tenant_id: "your-tenant-id",
>         service_url: "https://smba.trafficmanager.net/amer",
>         reply_to_activity_id: "1756945821955",
>         conversation_id: "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
>       },
>     },
>   },
> });
> ```
>
> ```python Python theme={null}
> response = client.send.message(
>     message={
>         "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
>         "to": {
>             "ms_teams": {
>                 "tenant_id": "your-tenant-id",
>                 "service_url": "https://smba.trafficmanager.net/amer",
>                 "reply_to_activity_id": "1756945821955",
>                 "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
>             },
>         },
>     },
> )
> ```
>
> ```bash cURL wrap theme={null}
> curl -X POST https://api.courier.com/send \
>   -H "Authorization: Bearer $COURIER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "message": {
>       "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
>       "to": {
>         "ms_teams": {
>           "tenant_id": "your-tenant-id",
>           "service_url": "https://smba.trafficmanager.net/amer",
>           "reply_to_activity_id": "1756945821955",
>           "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype"
>         }
>       }
>     }
>   }'
> ```
>
> ```ruby Ruby theme={null}
> response = courier.send_.message(
>   message: {
>     template: "nt_01kx4h2jdafq8bk9aftxak4b40",
>     to: {
>       ms_teams: {
>         tenant_id: "your-tenant-id",
>         service_url: "https://smba.trafficmanager.net/amer",
>         reply_to_activity_id: "1756945821955",
>         conversation_id: "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype"
>       }
>     }
>   }
> )
> ```
>
> ```go Go theme={null}
> // This provider addresses the recipient with fields outside the typed
> // UserRecipient model, so pass the recipient as raw JSON.
> to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
>   "ms_teams": {
>     "tenant_id": "your-tenant-id",
>     "service_url": "https://smba.trafficmanager.net/amer",
>     "reply_to_activity_id": "1756945821955",
>     "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype"
>   }
> }`))
>
> response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
> 	Message: courier.SendMessageParamsMessage{
> 		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
> 		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
> 	},
> })
> ```
>
> ```java Java theme={null}
> SendMessageParams params = SendMessageParams.builder()
>     .message(SendMessageParams.Message.builder()
>         // This provider addresses the recipient with fields outside the
>         // typed UserRecipient model, so pass them as additional properties.
>         .to(UserRecipient.builder()
>             .putAdditionalProperty("ms_teams", JsonValue.from(java.util.Map.of(
>                 "tenant_id", "your-tenant-id",
>                 "service_url", "https://smba.trafficmanager.net/amer",
>                 "reply_to_activity_id", "1756945821955",
>                 "conversation_id", "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype"
>             )))
>             .build())
>         .template("nt_01kx4h2jdafq8bk9aftxak4b40")
>         .build())
>     .build();
> SendMessageResponse response = client.send().message(params);
> ```
>
> ```php PHP theme={null}
> $response = $client->send->message(
>   message: [
>     'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
>     'to' => [
>       'ms_teams' => [
>         'tenant_id' => 'your-tenant-id',
>         'service_url' => 'https://smba.trafficmanager.net/amer',
>         'reply_to_activity_id' => '1756945821955',
>         'conversation_id' => '19:a52e21710de34c65b9f2e09ededaad2a@thread.skype',
>       ],
>     ],
>   ],
> );
> ```
>
> ```csharp C# theme={null}
> SendMessageParams parameters = new()
> {
>     Message = new()
>     {
>         // This provider addresses the recipient with fields outside the
>         // typed UserRecipient model, so build it from raw JSON.
>         To = UserRecipient.FromRawUnchecked(
>             JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
>                 """
>                 {
>                   "ms_teams": {
>                     "tenant_id": "your-tenant-id",
>                     "service_url": "https://smba.trafficmanager.net/amer",
>                     "reply_to_activity_id": "1756945821955",
>                     "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype"
>                   }
>                 }
>                 """
>             )
>         ),
>         Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
>     },
> };
>
> var response = await client.Send.Message(parameters);
> ```
>
> ```bash CLI wrap theme={null}
> courier send message \
>   --api-key "$COURIER_API_KEY" \
>   --message.to '{"ms_teams": {"tenant_id": "your-tenant-id", "service_url": "https://smba.trafficmanager.net/amer", "reply_to_activity_id": "1756945821955", "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype"}}' \
>   --message.template nt_01kx4h2jdafq8bk9aftxak4b40
> ```
>
> ```text MCP theme={null}
> With Courier MCP, reply in that Teams thread using the activity id from the first message.
> ```

> **Thread reply configuration**
>
> **Getting reference data**
>
> With webhooks configured, Courier delivers the reference data on every send:
>
> ```json theme={null}
> {
>   "type": "message:updated",
>   "data": {
>     "id": "1-61f9dd53-b5c6969eb23c4aad6fce2ef7",
>     "status": "SENT",
>     "providers": {
>       "msteams": {
>         "reference": {
>           "activityId": "1756945821955",
>           "conversationId": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype"
>         }
>       }
>     }
>   }
> }
> ```
>
> **Thread reply requirements**
>
> 1. **Required fields:**
>    * `reply_to_activity_id`: the activity ID from the original message's reference data
>    * `conversation_id`: The conversation ID from the original message's reference data
>    * `tenant_id`: your Microsoft Teams tenant ID
>    * `service_url`: your Teams service URL (optional, uses the default if omitted)
> 2. **Field restrictions:**
>    With `reply_to_activity_id`, you **can't** include:
>
>    * `channel_id` or `channel_name` + `team_id` (channel targeting fields)
>    * `user_id` or `email` (user targeting fields)
>
>    The `conversation_id` determines the thread location automatically.
>
> **Error handling**
>
> Common threading errors and their fixes:
>
> * **"Thread replies require 'conversation\_id'"**: include the `conversation_id` from the original message's reference data.
> * **"Thread replies cannot use channel targeting fields"**: remove `channel_id`, `channel_name`, and `team_id`.
> * **"Thread replies cannot use user targeting fields"**: remove `user_id` and `email`.

## Microsoft Teams channel ID reference

When sending messages to a Teams channel through Courier, the `conversationId` returned in delivered event webhooks is the channel ID. They are the same value.

> **Understanding the relationship**
>
> In the Microsoft Teams Bot Framework, a channel's identifier is its conversation ID. The Bot Framework returns that identifier in the response, and Courier surfaces it as `conversation_context.conversationId` in delivered event webhooks.

> **Sending an initial message**
>
> ```javascript Node.js theme={null}
> const { requestId } = await courier.send.message({
>   message: {
>     template: "nt_01kx4h2jdafq8bk9aftxak4b40",
>     to: {
>       ms_teams: {
>         team_id: "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>         channel_name: "General",
>         tenant_id: "dabd1935-56a4-4305-938e-0840e2e84515",
>         service_url: "https://smba.trafficmanager.net/amer",
>       },
>     },
>   },
> });
> ```
>
> ```python Python theme={null}
> response = client.send.message(
>     message={
>         "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
>         "to": {
>             "ms_teams": {
>                 "team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>                 "channel_name": "General",
>                 "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
>                 "service_url": "https://smba.trafficmanager.net/amer",
>             },
>         },
>     },
> )
> ```
>
> ```bash cURL wrap theme={null}
> curl -X POST https://api.courier.com/send \
>   -H "Authorization: Bearer $COURIER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "message": {
>       "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
>       "to": {
>         "ms_teams": {
>           "team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>           "channel_name": "General",
>           "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
>           "service_url": "https://smba.trafficmanager.net/amer"
>         }
>       }
>     }
>   }'
> ```
>
> ```ruby Ruby theme={null}
> response = courier.send_.message(
>   message: {
>     template: "nt_01kx4h2jdafq8bk9aftxak4b40",
>     to: {
>       ms_teams: {
>         team_id: "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>         channel_name: "General",
>         tenant_id: "dabd1935-56a4-4305-938e-0840e2e84515",
>         service_url: "https://smba.trafficmanager.net/amer"
>       }
>     }
>   }
> )
> ```
>
> ```go Go theme={null}
> // This provider addresses the recipient with fields outside the typed
> // UserRecipient model, so pass the recipient as raw JSON.
> to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
>   "ms_teams": {
>     "team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>     "channel_name": "General",
>     "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
>     "service_url": "https://smba.trafficmanager.net/amer"
>   }
> }`))
>
> response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
> 	Message: courier.SendMessageParamsMessage{
> 		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
> 		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
> 	},
> })
> ```
>
> ```java Java theme={null}
> SendMessageParams params = SendMessageParams.builder()
>     .message(SendMessageParams.Message.builder()
>         // This provider addresses the recipient with fields outside the
>         // typed UserRecipient model, so pass them as additional properties.
>         .to(UserRecipient.builder()
>             .putAdditionalProperty("ms_teams", JsonValue.from(java.util.Map.of(
>                 "team_id", "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>                 "channel_name", "General",
>                 "tenant_id", "dabd1935-56a4-4305-938e-0840e2e84515",
>                 "service_url", "https://smba.trafficmanager.net/amer"
>             )))
>             .build())
>         .template("nt_01kx4h2jdafq8bk9aftxak4b40")
>         .build())
>     .build();
> SendMessageResponse response = client.send().message(params);
> ```
>
> ```php PHP theme={null}
> $response = $client->send->message(
>   message: [
>     'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
>     'to' => [
>       'ms_teams' => [
>         'team_id' => 'feb55fc1-9e00-40f3-93b8-f7d14703f4dd',
>         'channel_name' => 'General',
>         'tenant_id' => 'dabd1935-56a4-4305-938e-0840e2e84515',
>         'service_url' => 'https://smba.trafficmanager.net/amer',
>       ],
>     ],
>   ],
> );
> ```
>
> ```csharp C# theme={null}
> SendMessageParams parameters = new()
> {
>     Message = new()
>     {
>         // This provider addresses the recipient with fields outside the
>         // typed UserRecipient model, so build it from raw JSON.
>         To = UserRecipient.FromRawUnchecked(
>             JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
>                 """
>                 {
>                   "ms_teams": {
>                     "team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd",
>                     "channel_name": "General",
>                     "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
>                     "service_url": "https://smba.trafficmanager.net/amer"
>                   }
>                 }
>                 """
>             )
>         ),
>         Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
>     },
> };
>
> var response = await client.Send.Message(parameters);
> ```
>
> ```bash CLI wrap theme={null}
> courier send message \
>   --api-key "$COURIER_API_KEY" \
>   --message.to '{"ms_teams": {"team_id": "feb55fc1-9e00-40f3-93b8-f7d14703f4dd", "channel_name": "General", "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515", "service_url": "https://smba.trafficmanager.net/amer"}}' \
>   --message.template nt_01kx4h2jdafq8bk9aftxak4b40
> ```
>
> ```text MCP theme={null}
> With Courier MCP, send my template to the general channel in my Teams team and return the conversation id.
> ```
>
> The delivered event webhook contains:
>
> ```json theme={null}
> {
>   "id": "1759342992794",
>   "conversation_context": {
>     "activityId": "1759342992794",
>     "conversationId": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype"
>   }
> }
> ```
>
> The `conversationId` value `19:a52e21710de34c65b9f2e09ededaad2a@thread.skype` is the channel ID for the "General" channel.

### Replying in a thread

To reply to this message, use both the `activityId` and `conversationId` from the webhook:

```javascript Node.js highlight={6} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      ms_teams: {
        reply_to_activity_id: "1759342992794",
        conversation_id: "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
        tenant_id: "dabd1935-56a4-4305-938e-0840e2e84515",
        service_url: "https://smba.trafficmanager.net/amer",
      },
    },
  },
});
```

```python Python highlight={6} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "ms_teams": {
                "reply_to_activity_id": "1759342992794",
                "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
                "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
                "service_url": "https://smba.trafficmanager.net/amer",
            },
        },
    },
)
```

```bash cURL highlight={9} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "ms_teams": {
          "reply_to_activity_id": "1759342992794",
          "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
          "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
          "service_url": "https://smba.trafficmanager.net/amer"
        }
      }
    }
  }'
```

```ruby Ruby highlight={6} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      ms_teams: {
        reply_to_activity_id: "1759342992794",
        conversation_id: "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
        tenant_id: "dabd1935-56a4-4305-938e-0840e2e84515",
        service_url: "https://smba.trafficmanager.net/amer"
      }
    }
  }
)
```

```go Go highlight={5} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "ms_teams": {
    "reply_to_activity_id": "1759342992794",
    "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
    "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
    "service_url": "https://smba.trafficmanager.net/amer"
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("ms_teams", JsonValue.from(java.util.Map.of(
                "reply_to_activity_id", "1759342992794",
                "conversation_id", "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
                "tenant_id", "dabd1935-56a4-4305-938e-0840e2e84515",
                "service_url", "https://smba.trafficmanager.net/amer"
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={6} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'ms_teams' => [
        'reply_to_activity_id' => '1759342992794',
        'conversation_id' => '19:a52e21710de34c65b9f2e09ededaad2a@thread.skype',
        'tenant_id' => 'dabd1935-56a4-4305-938e-0840e2e84515',
        'service_url' => 'https://smba.trafficmanager.net/amer',
      ],
    ],
  ],
);
```

```csharp C# highlight={12} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "ms_teams": {
                    "reply_to_activity_id": "1759342992794",
                    "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
                    "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
                    "service_url": "https://smba.trafficmanager.net/amer"
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"ms_teams": {"reply_to_activity_id": "1759342992794", "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype", "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515", "service_url": "https://smba.trafficmanager.net/amer"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, reply to that Teams message using its activity id and conversation id.
```

The reply's delivered event maintains the same `conversationId`:

```json theme={null}
{
  "id": "1759343317452",
  "conversation_context": {
    "activityId": "1759343317452",
    "conversationId": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype"
  }
}
```

The `conversationId` stays the same across a thread because it represents the channel. Only the `activityId` changes with each message.

> **Getting channel IDs directly from Teams**
>
> You can get a channel ID without sending a message first. In the [Teams web app](https://teams.microsoft.com/v2/), select the channel and click the ellipsis (⋯) in the upper right corner. Choose "Get link to channel" to copy a URL like:
>
> ```
> https://teams.microsoft.com/l/channel/19%3Aa52e21710de34c65b9f2e09ededaad2a%40thread.skype/General?groupId=feb55fc1-9e00-40f3-93b8-f7d14703f4dd&tenantId=dabd1935-56a4-4305-938e-0840e2e84515
> ```
>
> The channel ID appears after `/channel/` in URL-encoded format. Decode `19%3Aa52e21710de34c65b9f2e09ededaad2a%40thread.skype` to get `19:a52e21710de34c65b9f2e09ededaad2a@thread.skype`.

> **Sending directly with conversation\_id**
>
> When you know the channel ID, send with `conversation_id` instead of looking up the channel by name:
>
> ```javascript Node.js highlight={6} theme={null}
> const { requestId } = await courier.send.message({
>   message: {
>     template: "nt_01kx4h2jdafq8bk9aftxak4b40",
>     to: {
>       ms_teams: {
>         conversation_id: "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
>         tenant_id: "dabd1935-56a4-4305-938e-0840e2e84515",
>         service_url: "https://smba.trafficmanager.net/amer",
>       },
>     },
>   },
> });
> ```
>
> ```python Python highlight={6} theme={null}
> response = client.send.message(
>     message={
>         "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
>         "to": {
>             "ms_teams": {
>                 "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
>                 "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
>                 "service_url": "https://smba.trafficmanager.net/amer",
>             },
>         },
>     },
> )
> ```
>
> ```bash cURL highlight={9} wrap theme={null}
> curl -X POST https://api.courier.com/send \
>   -H "Authorization: Bearer $COURIER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "message": {
>       "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
>       "to": {
>         "ms_teams": {
>           "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
>           "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
>           "service_url": "https://smba.trafficmanager.net/amer"
>         }
>       }
>     }
>   }'
> ```
>
> ```ruby Ruby highlight={6} theme={null}
> response = courier.send_.message(
>   message: {
>     template: "nt_01kx4h2jdafq8bk9aftxak4b40",
>     to: {
>       ms_teams: {
>         conversation_id: "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
>         tenant_id: "dabd1935-56a4-4305-938e-0840e2e84515",
>         service_url: "https://smba.trafficmanager.net/amer"
>       }
>     }
>   }
> )
> ```
>
> ```go Go highlight={5} theme={null}
> // This provider addresses the recipient with fields outside the typed
> // UserRecipient model, so pass the recipient as raw JSON.
> to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
>   "ms_teams": {
>     "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
>     "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
>     "service_url": "https://smba.trafficmanager.net/amer"
>   }
> }`))
>
> response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
> 	Message: courier.SendMessageParamsMessage{
> 		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
> 		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
> 	},
> })
> ```
>
> ```java Java highlight={7} theme={null}
> SendMessageParams params = SendMessageParams.builder()
>     .message(SendMessageParams.Message.builder()
>         // This provider addresses the recipient with fields outside the
>         // typed UserRecipient model, so pass them as additional properties.
>         .to(UserRecipient.builder()
>             .putAdditionalProperty("ms_teams", JsonValue.from(java.util.Map.of(
>                 "conversation_id", "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
>                 "tenant_id", "dabd1935-56a4-4305-938e-0840e2e84515",
>                 "service_url", "https://smba.trafficmanager.net/amer"
>             )))
>             .build())
>         .template("nt_01kx4h2jdafq8bk9aftxak4b40")
>         .build())
>     .build();
> SendMessageResponse response = client.send().message(params);
> ```
>
> ```php PHP highlight={6} theme={null}
> $response = $client->send->message(
>   message: [
>     'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
>     'to' => [
>       'ms_teams' => [
>         'conversation_id' => '19:a52e21710de34c65b9f2e09ededaad2a@thread.skype',
>         'tenant_id' => 'dabd1935-56a4-4305-938e-0840e2e84515',
>         'service_url' => 'https://smba.trafficmanager.net/amer',
>       ],
>     ],
>   ],
> );
> ```
>
> ```csharp C# highlight={12} theme={null}
> SendMessageParams parameters = new()
> {
>     Message = new()
>     {
>         // This provider addresses the recipient with fields outside the
>         // typed UserRecipient model, so build it from raw JSON.
>         To = UserRecipient.FromRawUnchecked(
>             JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
>                 """
>                 {
>                   "ms_teams": {
>                     "conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype",
>                     "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515",
>                     "service_url": "https://smba.trafficmanager.net/amer"
>                   }
>                 }
>                 """
>             )
>         ),
>         Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
>     },
> };
>
> var response = await client.Send.Message(parameters);
> ```
>
> ```bash CLI highlight={3} wrap theme={null}
> courier send message \
>   --api-key "$COURIER_API_KEY" \
>   --message.to '{"ms_teams": {"conversation_id": "19:a52e21710de34c65b9f2e09ededaad2a@thread.skype", "tenant_id": "dabd1935-56a4-4305-938e-0840e2e84515", "service_url": "https://smba.trafficmanager.net/amer"}}' \
>   --message.template nt_01kx4h2jdafq8bk9aftxak4b40
> ```
>
> ```text MCP theme={null}
> With Courier MCP, send my template straight to this Teams conversation id.
> ```
>
> This skips the Graph API lookup for the channel name, so it is faster. The webhook returns the same `conversationId` because it is already the channel ID.

> **Technical details**
>
> Channel IDs follow the format `19:{guid}@thread.skype` or `19:{guid}@thread.tacv2`, depending on the Teams infrastructure version. They are stable and unique per channel within a tenant. Combined with `tenantId`, they identify a channel globally.
>
> The Bot Framework uses these channel IDs as conversation identifiers when posting to channels. Thread replies need both the `conversationId` (channel ID) and the `reply_to_activity_id` (the message being replied to). The reply URL uses the format `{conversationId};messageid={activityId}`, but the `conversationId` stored in the response is the channel ID with no suffix.

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A `config` override swaps the Azure Bot's App ID and App Password for one send:

```javascript Node.js highlight={8-15} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      msteams: {
        override: {
          config: {
            appId: "YOUR_APP_ID",
            appPassword: "YOUR_APP_PASSWORD",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-15} theme={null}
response = client.send.message(
    message={
        "to": {
          "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "msteams": {
                "override": {
                  "config": {
                    "appId": "YOUR_APP_ID",
                    "appPassword": "YOUR_APP_PASSWORD",
                  },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-18} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "user_id": "user_123"
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
          "msteams": {
            "override": {
              "config": {
                "appId": "YOUR_APP_ID",
                "appPassword": "YOUR_APP_PASSWORD"
              }
            }
          }
        }
      }
    }'
```

```ruby Ruby highlight={8-15} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "msteams" => {
        override: {
          config: {
            appId: "YOUR_APP_ID",
            appPassword: "YOUR_APP_PASSWORD"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-17} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"msteams": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"appId": "YOUR_APP_ID",
						"appPassword": "YOUR_APP_PASSWORD",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("msteams", JsonValue.from(java.util.Map.of(
                "override", java.util.Map.of("config", java.util.Map.of("appId", "YOUR_APP_ID", "appPassword", "YOUR_APP_PASSWORD")))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-15} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'providers' => [
      'msteams' => [
        'override' => [
          'config' => [
            'appId' => 'YOUR_APP_ID',
            'appPassword' => 'YOUR_APP_PASSWORD',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-18} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "msteams",
                new()
                {
                    Override = new Dictionary<string, JsonElement>()
                    {
                        { "config", JsonSerializer.SerializeToElement(new { appId = "YOUR_APP_ID", appPassword = "YOUR_APP_PASSWORD" }) },
                    },
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"msteams": {"override": {"config": {"appId": "YOUR_APP_ID", "appPassword": "YOUR_APP_PASSWORD"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 on Microsoft Teams using a different Azure bot app id.
```

## Adaptive Cards

Courier supports Microsoft Teams [Adaptive Cards](https://adaptivecards.io/) through Jsonnet blocks in Design Studio.

> **Using Jsonnet blocks**
>
> Jsonnet blocks let you customize Adaptive Cards sent through Microsoft Teams. To send your first card:
>
> **1. Add a Microsoft Teams channel**
>
> In Design Studio, add a new Microsoft Teams channel.
>
> **2. Insert a Jsonnet block**
>
> Insert a Jsonnet block within your message.
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-designer-jsonnet-block.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=ec51f7740ecd6317b5c0e518290f9e54)
>
> Jsonnet Block
>
> **3. Open the Adaptive Cards Designer**
>
> Open the [Adaptive Cards Designer](https://adaptivecards.io/designer/) and select or create a card layout.
>
> **4. Copy the card JSON into your Jsonnet block**
>
> Copy the card JSON from the "Card Payload Editor" into your Courier Jsonnet block.
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-designer-jsonnet-sample.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=2b00895da20345c3fdf1bf7bb6a47eab)
>
> Sample Jsonnet

> **Sending an Adaptive Card**
>
> Include the sample data from the Adaptive Cards Designer in your Courier message:
>
> ```javascript Node.js theme={null}
> const { requestId } = await courier.send.message({
>   message: {
>     to: {
>       user_id: "user_123",
>     },
>     template: "nt_01kx4h2jdafq8bk9aftxak4b40",
>     data: {
>       title: "Publish Adaptive Card Schema",
>       description: "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
>       creator: {
>         name: "Sarah Bennett",
>         profileImage: "https://www.acme-corp.com/avatar.png",
>       },
>       createdUtc: "2017-02-14T06:08:39Z",
>       viewUrl: "https://adaptivecards.io",
>       properties: [
>         {
>           key: "Board",
>           value: "Adaptive Cards",
>         },
>         {
>           key: "List",
>           value: "Backlog",
>         },
>         {
>           key: "Assigned to",
>           value: "Sarah Bennett",
>         },
>         {
>           key: "Due date",
>           value: "Not set",
>         },
>       ],
>     },
>   },
> });
> ```
>
> ```python Python theme={null}
> response = client.send.message(
>     message={
>         "to": {
>             "user_id": "user_123",
>         },
>         "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
>         "data": {
>             "title": "Publish Adaptive Card Schema",
>             "description": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
>             "creator": {
>                 "name": "Sarah Bennett",
>                 "profileImage": "https://www.acme-corp.com/avatar.png",
>             },
>             "createdUtc": "2017-02-14T06:08:39Z",
>             "viewUrl": "https://adaptivecards.io",
>             "properties": [
>                 {
>                     "key": "Board",
>                     "value": "Adaptive Cards",
>                 },
>                 {
>                     "key": "List",
>                     "value": "Backlog",
>                 },
>                 {
>                     "key": "Assigned to",
>                     "value": "Sarah Bennett",
>                 },
>                 {
>                     "key": "Due date",
>                     "value": "Not set",
>                 },
>             ],
>         },
>     },
> )
> ```
>
> ```bash cURL wrap theme={null}
> curl -X POST https://api.courier.com/send \
>   -H "Authorization: Bearer $COURIER_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "message": {
>       "to": {
>         "user_id": "user_123"
>       },
>       "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
>       "data": {
>         "title": "Publish Adaptive Card Schema",
>         "description": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
>         "creator": {
>           "name": "Sarah Bennett",
>           "profileImage": "https://www.acme-corp.com/avatar.png"
>         },
>         "createdUtc": "2017-02-14T06:08:39Z",
>         "viewUrl": "https://adaptivecards.io",
>         "properties": [
>           {
>             "key": "Board",
>             "value": "Adaptive Cards"
>           },
>           {
>             "key": "List",
>             "value": "Backlog"
>           },
>           {
>             "key": "Assigned to",
>             "value": "Sarah Bennett"
>           },
>           {
>             "key": "Due date",
>             "value": "Not set"
>           }
>         ]
>       }
>     }
>   }'
> ```
>
> ```ruby Ruby theme={null}
> response = courier.send_.message(
>   message: {
>     to: {
>       user_id: "user_123"
>     },
>     template: "nt_01kx4h2jdafq8bk9aftxak4b40",
>     data: {
>       title: "Publish Adaptive Card Schema",
>       description: "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
>       creator: {
>         name: "Sarah Bennett",
>         profileImage: "https://www.acme-corp.com/avatar.png"
>       },
>       createdUtc: "2017-02-14T06:08:39Z",
>       viewUrl: "https://adaptivecards.io",
>       properties: [
>         {
>           key: "Board",
>           value: "Adaptive Cards"
>         },
>         {
>           key: "List",
>           value: "Backlog"
>         },
>         {
>           key: "Assigned to",
>           value: "Sarah Bennett"
>         },
>         {
>           key: "Due date",
>           value: "Not set"
>         }
>       ]
>     }
>   }
> )
> ```
>
> ```go Go theme={null}
> response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
> 	Message: courier.SendMessageParamsMessage{
> 		To: courier.SendMessageParamsMessageToUnion{
> 			OfUserRecipient: &shared.UserRecipientParam{
> 				UserID: courier.String("user_123"),
> 			},
> 		},
> 		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
> 		Data: map[string]any{
> 			"title": "Publish Adaptive Card Schema",
> 			"description": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
> 			"creator": map[string]any{
> 				"name": "Sarah Bennett",
> 				"profileImage": "https://www.acme-corp.com/avatar.png",
> 			},
> 			"createdUtc": "2017-02-14T06:08:39Z",
> 			"viewUrl": "https://adaptivecards.io",
> 			"properties": []any{
> 				map[string]any{
> 					"key": "Board",
> 					"value": "Adaptive Cards",
> 				},
> 				map[string]any{
> 					"key": "List",
> 					"value": "Backlog",
> 				},
> 				map[string]any{
> 					"key": "Assigned to",
> 					"value": "Sarah Bennett",
> 				},
> 				map[string]any{
> 					"key": "Due date",
> 					"value": "Not set",
> 				},
> 			},
> 		},
> 	},
> })
> ```
>
> ```java Java theme={null}
> SendMessageParams params = SendMessageParams.builder()
>     .message(SendMessageParams.Message.builder()
>         .to(UserRecipient.builder().userId("user_123").build())
>         .template("nt_01kx4h2jdafq8bk9aftxak4b40")
>         .data(JsonValue.from(java.util.Map.of(
>             "title", "Publish Adaptive Card Schema",
>             "description", "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
>             "creator", java.util.Map.of(
>                 "name", "Sarah Bennett",
>                 "profileImage", "https://www.acme-corp.com/avatar.png"
>             ),
>             "createdUtc", "2017-02-14T06:08:39Z",
>             "viewUrl", "https://adaptivecards.io",
>             "properties", java.util.List.of(
>                 java.util.Map.of(
>                     "key", "Board",
>                     "value", "Adaptive Cards"
>                 ),
>                 java.util.Map.of(
>                     "key", "List",
>                     "value", "Backlog"
>                 ),
>                 java.util.Map.of(
>                     "key", "Assigned to",
>                     "value", "Sarah Bennett"
>                 ),
>                 java.util.Map.of(
>                     "key", "Due date",
>                     "value", "Not set"
>                 )
>             )
>         )))
>         .build())
>     .build();
> SendMessageResponse response = client.send().message(params);
> ```
>
> ```php PHP theme={null}
> $response = $client->send->message(
>   message: [
>     'to' => [
>       'user_id' => 'user_123',
>     ],
>     'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
>     'data' => [
>       'title' => 'Publish Adaptive Card Schema',
>       'description' => 'Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.',
>       'creator' => [
>         'name' => 'Sarah Bennett',
>         'profileImage' => 'https://www.acme-corp.com/avatar.png',
>       ],
>       'createdUtc' => '2017-02-14T06:08:39Z',
>       'viewUrl' => 'https://adaptivecards.io',
>       'properties' => [
>         [
>           'key' => 'Board',
>           'value' => 'Adaptive Cards',
>         ],
>         [
>           'key' => 'List',
>           'value' => 'Backlog',
>         ],
>         [
>           'key' => 'Assigned to',
>           'value' => 'Sarah Bennett',
>         ],
>         [
>           'key' => 'Due date',
>           'value' => 'Not set',
>         ],
>       ],
>     ],
>   ],
> );
> ```
>
> ```csharp C# theme={null}
> SendMessageParams parameters = new()
> {
>     Message = new()
>     {
>         To = new UserRecipient { UserID = "user_123" },
>         Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
>         Data = new Dictionary<string, JsonElement>()
>         {
>             { "title", JsonSerializer.SerializeToElement("Publish Adaptive Card Schema") },
>             { "description", JsonSerializer.SerializeToElement("Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.") },
>             { "creator", JsonSerializer.Deserialize<JsonElement>(
>                 """
>                 {
>                   "name": "Sarah Bennett",
>                   "profileImage": "https://www.acme-corp.com/avatar.png"
>                 }
>                 """
>             ) },
>             { "createdUtc", JsonSerializer.SerializeToElement("2017-02-14T06:08:39Z") },
>             { "viewUrl", JsonSerializer.SerializeToElement("https://adaptivecards.io") },
>             { "properties", JsonSerializer.Deserialize<JsonElement>(
>                 """
>                 [
>                   {
>                     "key": "Board",
>                     "value": "Adaptive Cards"
>                   },
>                   {
>                     "key": "List",
>                     "value": "Backlog"
>                   },
>                   {
>                     "key": "Assigned to",
>                     "value": "Sarah Bennett"
>                   },
>                   {
>                     "key": "Due date",
>                     "value": "Not set"
>                   }
>                 ]
>                 """
>             ) },
>         },
>     },
> };
>
> var response = await client.Send.Message(parameters);
> ```
>
> ```bash CLI wrap theme={null}
> courier send message \
>   --api-key "$COURIER_API_KEY" \
>   --message.to '{"user_id": "user_123"}' \
>   --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
>   --message.data '{"title": "Publish Adaptive Card Schema", "description": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.", "creator": {"name": "Sarah Bennett", "profileImage": "https://www.acme-corp.com/avatar.png"}, "createdUtc": "2017-02-14T06:08:39Z", "viewUrl": "https://adaptivecards.io", "properties": [{"key": "Board", "value": "Adaptive Cards"}, {"key": "List", "value": "Backlog"}, {"key": "Assigned to", "value": "Sarah Bennett"}, {"key": "Due date", "value": "Not set"}]}'
> ```
>
> ```text MCP theme={null}
> With Courier MCP, send my template to user user_123 as a Teams Adaptive Card.
> ```
>
> The recipient's profile needs a valid `ms_teams` object with the right fields, such as `conversation_id`. The card then appears in Microsoft Teams:
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/teams-adaptive-card.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=4966131a12a67d84ddddf3aa0ac1c136)
>
> MS Teams Adaptive Card

> **Using @mentions in Adaptive Cards**
>
> Mentions in Adaptive Cards need two things:
>
> * `<at>username</at>` in the Jsonnet block.
> * A matching `entities` object in the Adaptive Card JSON payload, with the Teams user ID of the person mentioned.
>
> A sample mention:
>
> ```json theme={null}
> {
>   "msteams": {
>     "entities": [
>       {
>         "type": "mention",
>         "text": "<at>Sarah Bennett</at>",
>         "mentioned": {
>           "id": "29:123124124124",
>           "name": "Sarah Bennett"
>         }
>       }
>     ]
>   }
> }
> ```

## Troubleshooting

### 401 Authentication error

If you see `All Bot Framework authentication methods failed` with status code 401:

1. **App not installed in the team (channel messages only)**: uploading the app to Teams covers personal messaging. For channel messaging, install the app in each team. See Step 6. This is the most common cause when user messages succeed and channel messages fail.
2. **Wrong credentials in Courier**: Courier needs the Application (client) ID and Client Secret from the Azure **Bot** App Registration (Step 4), not the Teams App ID from the Developer Portal (Step 1). These are different values.
3. **Single-tenant App Registration**: in Azure Portal > App registrations > \[Your Bot] > Authentication, set "Supported account types" to "Accounts in any organizational directory" (Multitenant). The Azure default is single-tenant, which breaks Bot Framework authentication.
4. **Expired client secret**: check the expiration date in Azure Portal > App registrations > \[Your Bot] > Certificates & secrets. If it expired, create a new secret and update Courier's Teams integration settings.
5. **Missing `tenant_id`**: include `tenant_id` in the `ms_teams` object. Without it, Courier can't attempt tenant-scoped authentication.

### Messages to users work but channel messages fail

The app is almost certainly not installed in the team that owns the target channel. See item 1 above and Step 6.

### Credential confusion between Azure app registrations

Setup creates two Azure App Registrations:

* **Step 2 App Registration**: used in the Teams Developer Portal configuration (Step 3). This is the parent application.
* **Step 4 Bot App Registration**: used in Courier's integration settings (Step 5). This provides the bot credentials.

Check the Info callouts in Steps 3 and 5 if you're unsure which credentials go where.

## Reference: Courier → recipient flowchart

```mermaid theme={null}
flowchart LR
    A["Courier"] -->|Bot ID| B["Azure bot"]
    B -->|Endpoint| C["Your bot service"]
    C -->|App ID| D["Teams app"]
    D --> E["Channel or user"]
```

## Provider details

```text theme={null}
msteams
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Chat providers
Source: https://www.courier.com/docs/integrations/direct-message/overview

Slack, Microsoft Teams, WhatsApp, Discord, and other chat providers, with their profile fields.

## Available providers

> **[Slack](/docs/integrations/direct-message/slack)**

> **[Microsoft Teams](/docs/integrations/direct-message/microsoft-teams)**

> **[Discord](/docs/integrations/direct-message/discord)**

> **[WhatsApp](/docs/integrations/direct-message/whatsapp)**

> **[Facebook Messenger](/docs/integrations/direct-message/facebook-messenger)**

> **[Viber](/docs/integrations/direct-message/viber)**

> **[Stream Chat](/docs/integrations/direct-message/stream-chat)**

> **[Chat API](/docs/integrations/direct-message/chat)**

[Slack
DOC](/docs/integrations/direct-message/slack) and [Microsoft Teams
DOC](/docs/integrations/direct-message/microsoft-teams) carry rich layouts, Block Kit and Adaptive Cards. [WhatsApp
DOC](/docs/integrations/direct-message/whatsapp) sends through Twilio and needs its templates verified first.

> [!TIP]
>
> Can't find a provider? Start a chat or email [support@courier.com](mailto:support@courier.com)

## Channel overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. Most chat providers accept these two in a provider override.

| Field | Sets |
| :- | :- |
| `body` | The message content, plus embeds, blocks, and other provider-specific fields |
| `config` | Credentials or endpoint URLs, swapped for this one send |

Each provider page documents its override schema.


# Send Slack messages through Courier
Source: https://www.courier.com/docs/integrations/direct-message/slack

Connect a Slack app with a bot token and target users by email or ID, or channels, with Block Kit.

## Prerequisites

* [A Courier account](https://app.courier.com/signup)
* [A Slack account](https://slack.com/get-started)

## Setup

> [!NOTE]
>
> * [Courier API Reference
>   DOC](/docs/reference/api-overview)
> * [Slack API Documentation](https://api.slack.com/)
> * [Slack Block Kit Builder](https://app.slack.com/block-kit-builder/)

**1. Add the Slack integration in Courier**

Go to the [Integrations page](https://app.courier.com/integrations) and select Slack. Click "Install".

![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/slack-integration.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=4e0cd39a1f8e3dde42d023e93c6d8716)

Courier Slack Integration

**2. Create and configure a Slack app**

1. Go to the [Slack Apps page](https://api.slack.com/apps) and click "Create an App".
2. Choose "From scratch", name your app, and select your development workspace.
3. Under "OAuth & Permissions", add these Bot Token Scopes: `chat:write`, `im:write`, `users:read`, `users:read.email`.
4. Click "Install App to Workspace" and authorize.
5. Copy the **Bot User OAuth Access Token** (starts with `xoxb-`).

![The OAuth and Permissions page in Slack with the bot token scopes added](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/slack-oauth-scopes.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=99d95719a2dc6d77c14ba8645478df5c)

Slack OAuth Scopes

**3. Design a Slack notification template**

Go to the Courier [Assets page](https://app.courier.com/assets/templates) and click **+ New > Message Template**.
Select Slack from your integrations.
In the sidebar, click the new Slack block to open the Slack template editor.
Add your message content.

**4. Send a test message**

Click **Preview**, then **Create Test Event**.
Enter your bot token in the **Access Token** field.
Click **Send**. Your message appears in Slack.

***

## Profile requirements

Slack addresses the recipient by channel, user id, or email, so the profile you send to needs a `slack` object holding an `access_token` and one target. Store both once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

**Channel**

The channel id, not its name. `access_token` is the bot token from your Slack app. It sits on the profile beside the target.

```javascript Node.js highlight={3-6} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    slack: {
      access_token: 'xoxb-xxxxx',
      channel: 'CL2MR6HEX',
    },
  },
});
```

```python Python highlight={4-7} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "slack": {
            "access_token": "xoxb-xxxxx",
            "channel": "CL2MR6HEX",
        },
    },
)
```

```bash cURL highlight={7-10} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "slack": {
        "access_token": "xoxb-xxxxx",
        "channel": "CL2MR6HEX"
      }
    }
  }'
```

```ruby Ruby highlight={4-7} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    slack: {
      access_token: "xoxb-xxxxx",
      channel: "CL2MR6HEX"
    }
  }
)
```

```go Go highlight={6-9} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"slack": map[string]any{
				"access_token": "xoxb-xxxxx",
				"channel": "CL2MR6HEX",
			},
		},
	},
)
```

```java Java highlight={4-6} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("slack", JsonValue.from(java.util.Map.of(
            "access_token", "xoxb-xxxxx",
            "channel", "CL2MR6HEX")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-5} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'slack' => [
    'access_token' => 'xoxb-xxxxx',
    'channel' => 'CL2MR6HEX',
  ],
]);
```

```csharp C# highlight={7-10} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "slack": {
            "access_token": "xoxb-xxxxx",
            "channel": "CL2MR6HEX"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"slack":{"access_token":"xoxb-xxxxx","channel":"CL2MR6HEX"}}'
```

```text MCP theme={null}
With Courier MCP, save the Slack channel CL2MR6HEX and my bot token on user_123.
```

**User id**

Slack opens a direct message with that user. `access_token` is the bot token from your Slack app. It sits on the profile beside the target.

```javascript Node.js highlight={3-6} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    slack: {
      access_token: 'xoxb-xxxxx',
      user_id: 'UEFNTF6QL',
    },
  },
});
```

```python Python highlight={4-7} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "slack": {
            "access_token": "xoxb-xxxxx",
            "user_id": "UEFNTF6QL",
        },
    },
)
```

```bash cURL highlight={7-10} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "slack": {
        "access_token": "xoxb-xxxxx",
        "user_id": "UEFNTF6QL"
      }
    }
  }'
```

```ruby Ruby highlight={4-7} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    slack: {
      access_token: "xoxb-xxxxx",
      user_id: "UEFNTF6QL"
    }
  }
)
```

```go Go highlight={6-9} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"slack": map[string]any{
				"access_token": "xoxb-xxxxx",
				"user_id": "UEFNTF6QL",
			},
		},
	},
)
```

```java Java highlight={4-6} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("slack", JsonValue.from(java.util.Map.of(
            "access_token", "xoxb-xxxxx",
            "user_id", "UEFNTF6QL")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-5} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'slack' => [
    'access_token' => 'xoxb-xxxxx',
    'user_id' => 'UEFNTF6QL',
  ],
]);
```

```csharp C# highlight={7-10} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "slack": {
            "access_token": "xoxb-xxxxx",
            "user_id": "UEFNTF6QL"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"slack":{"access_token":"xoxb-xxxxx","user_id":"UEFNTF6QL"}}'
```

```text MCP theme={null}
With Courier MCP, save the Slack user id UEFNTF6QL and my bot token on user_123.
```

**Email**

Slack resolves the address to a user, then direct-messages them. `access_token` is the bot token from your Slack app. It sits on the profile beside the target.

```javascript Node.js highlight={3-6} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    slack: {
      access_token: 'xoxb-xxxxx',
      email: 'sarah@acme-corp.com',
    },
  },
});
```

```python Python highlight={4-7} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "slack": {
            "access_token": "xoxb-xxxxx",
            "email": "sarah@acme-corp.com",
        },
    },
)
```

```bash cURL highlight={7-10} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "slack": {
        "access_token": "xoxb-xxxxx",
        "email": "sarah@acme-corp.com"
      }
    }
  }'
```

```ruby Ruby highlight={4-7} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    slack: {
      access_token: "xoxb-xxxxx",
      email: "sarah@acme-corp.com"
    }
  }
)
```

```go Go highlight={6-9} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"slack": map[string]any{
				"access_token": "xoxb-xxxxx",
				"email": "sarah@acme-corp.com",
			},
		},
	},
)
```

```java Java highlight={4-6} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("slack", JsonValue.from(java.util.Map.of(
            "access_token", "xoxb-xxxxx",
            "email", "sarah@acme-corp.com")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-5} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'slack' => [
    'access_token' => 'xoxb-xxxxx',
    'email' => 'sarah@acme-corp.com',
  ],
]);
```

```csharp C# highlight={7-10} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "slack": {
            "access_token": "xoxb-xxxxx",
            "email": "sarah@acme-corp.com"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"slack":{"access_token":"xoxb-xxxxx","email":"sarah@acme-corp.com"}}'
```

```text MCP theme={null}
With Courier MCP, save the Slack email sarah@acme-corp.com and my bot token on user_123.
```

> [!TIP]
>
> **Order of precedence.** Set more than one of `channel`, `user_id`, or `email` and Courier uses them in that order.

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "slack": { "access_token": "xoxb-xxxxx", "channel": "CL2MR6HEX" } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `slack` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `slack`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={4-7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      slack: {
        access_token: "xoxb-xxxxx",
        email: "sarah@acme-corp.com",
      },
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-7} theme={null}
response = client.send.message(
    message={
        "to": {
            "slack": {
                "access_token": "xoxb-xxxxx",
                "email": "sarah@acme-corp.com",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-10} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "slack": {
          "access_token": "xoxb-xxxxx",
          "email": "sarah@acme-corp.com"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-7} theme={null}
response = courier.send_.message(
  message: {
    to: {
      slack: {
        access_token: "xoxb-xxxxx",
        email: "sarah@acme-corp.com"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={4-6} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfSlackRecipient: &shared.SlackRecipientParam{
				Slack: shared.SlackParamOfSendToSlackEmail("xoxb-xxxxx", "sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={4-7} theme={null}
client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(SlackRecipient.builder()
            .slack(SendToSlackEmail.builder()
                .accessToken("xoxb-xxxxx")
                .email("sarah@acme-corp.com")
                .build())
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-7} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'slack' => [
        'access_token' => 'xoxb-xxxxx',
        'email' => 'sarah@acme-corp.com',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={7-11} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new SlackRecipient
        {
            Slack = new SendToSlackEmail
            {
                AccessToken = "xoxb-xxxxx",
                Email = "sarah@acme-corp.com",
            },
        },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"slack": {"access_token": "xoxb-xxxxx", "email": "sarah@acme-corp.com"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com on Slack.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

You can override the payload sent to Slack's [chat.postMessage](https://api.slack.com/methods/chat.postMessage) using `providers.slack.override.body`. This is useful for advanced formatting, interactivity, and threading.

### Unfurl links

```javascript Node.js highlight={8-14} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      slack: {
        override: {
          body: {
            unfurl_links: true,
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-14} theme={null}
response = client.send.message(
    message={
        "to": {
          "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "slack": {
                "override": {
                  "body": {
                    "unfurl_links": True,
                  },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-17} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "user_id": "user_123"
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
          "slack": {
            "override": {
              "body": {
                "unfurl_links": true
              }
            }
          }
        }
      }
    }'
```

```ruby Ruby highlight={8-14} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "slack" => {
        override: {
          body: {
            unfurl_links: true
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-16} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"slack": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"unfurl_links": true,
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("slack", JsonValue.from(java.util.Map.of(
                "override", java.util.Map.of("body", java.util.Map.of("unfurl_links", true)))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-14} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'providers' => [
      'slack' => [
        'override' => [
          'body' => [
            'unfurl_links' => true,
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-18} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "slack",
                new()
                {
                    Override = new Dictionary<string, JsonElement>()
                    {
                        { "body", JsonSerializer.SerializeToElement(new { unfurl_links = true }) },
                    },
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"slack": {"override": {"body": {"unfurl_links": true}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 on Slack and let links unfurl.
```

### Slack blocks (Block Kit)

Send rich, interactive layouts using [Slack blocks](https://api.slack.com/block-kit):

```javascript Node.js highlight={8-30} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      slack: {
        override: {
          body: {
            blocks: [
              {
                type: "header",
                text: {
                  type: "plain_text",
                  text: "Welcome!",
                },
              },
              {
                type: "section",
                text: {
                  type: "mrkdwn",
                  text: "This is a *section* block.",
                },
              },
            ],
            text: "Fallback plain text.",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-30} theme={null}
response = client.send.message(
    message={
        "to": {
          "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "slack": {
                "override": {
                  "body": {
                    "blocks": [
                      {
                        "type": "header",
                        "text": {
                          "type": "plain_text",
                          "text": "Welcome!",
                        },
                      },
                      {
                        "type": "section",
                        "text": {
                          "type": "mrkdwn",
                          "text": "This is a *section* block.",
                        },
                      },
                    ],
                    "text": "Fallback plain text.",
                  },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-33} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "user_id": "user_123"
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
          "slack": {
            "override": {
              "body": {
                "blocks": [
                  {
                    "type": "header",
                    "text": {
                      "type": "plain_text",
                      "text": "Welcome!"
                    }
                  },
                  {
                    "type": "section",
                    "text": {
                      "type": "mrkdwn",
                      "text": "This is a *section* block."
                    }
                  }
                ],
                "text": "Fallback plain text."
              }
            }
          }
        }
      }
    }'
```

```ruby Ruby highlight={8-30} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "slack" => {
        override: {
          body: {
            blocks: [
              {
                type: "header",
                text: {
                  type: "plain_text",
                  text: "Welcome!"
                }
              },
              {
                type: "section",
                text: {
                  type: "mrkdwn",
                  text: "This is a *section* block."
                }
              }
            ],
            text: "Fallback plain text."
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-32} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"slack": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"blocks": []any{
							map[string]any{
								"type": "header",
								"text": map[string]any{
									"type": "plain_text",
									"text": "Welcome!",
								},
							},
							map[string]any{
								"type": "section",
								"text": map[string]any{
									"type": "mrkdwn",
									"text": "This is a *section* block.",
								},
							},
						},
						"text": "Fallback plain text.",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("slack", JsonValue.from(java.util.Map.of(
                "override", java.util.Map.of("body", java.util.Map.of("blocks", java.util.List.of(java.util.Map.of("type", "header", "text", java.util.Map.of("type", "plain_text", "text", "Welcome!")), java.util.Map.of("type", "section", "text", java.util.Map.of("type", "mrkdwn", "text", "This is a *section* block."))), "text", "Fallback plain text.")))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-30} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'providers' => [
      'slack' => [
        'override' => [
          'body' => [
            'blocks' => [
              [
                'type' => 'header',
                'text' => [
                  'type' => 'plain_text',
                  'text' => 'Welcome!',
                ],
              ],
              [
                'type' => 'section',
                'text' => [
                  'type' => 'mrkdwn',
                  'text' => 'This is a *section* block.',
                ],
              ],
            ],
            'text' => 'Fallback plain text.',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-18} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "slack",
                new()
                {
                    Override = new Dictionary<string, JsonElement>()
                    {
                        { "body", JsonSerializer.SerializeToElement(new { blocks = new[] { new { type = "header", text = new { type = "plain_text", text = "Welcome!" } }, new { type = "section", text = new { type = "mrkdwn", text = "This is a *section* block." } } }, text = "Fallback plain text." }) },
                    },
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"slack": {"override": {"body": {"blocks": [{"type": "header", "text": {"type": "plain_text", "text": "Welcome!"}}, {"type": "section", "text": {"type": "mrkdwn", "text": "This is a *section* block."}}], "text": "Fallback plain text."}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 on Slack using Block Kit blocks.
```

Design and preview your blocks visually with the [Slack Block Kit Builder](https://app.slack.com/block-kit-builder/).

### Replying in a thread

To reply to a thread, set the `thread_ts` value:

```javascript Node.js highlight={8-14} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      slack: {
        override: {
          body: {
            thread_ts: "1234567890.123456",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-14} theme={null}
response = client.send.message(
    message={
        "to": {
          "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "slack": {
                "override": {
                  "body": {
                    "thread_ts": "1234567890.123456",
                  },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-17} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "user_id": "user_123"
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
          "slack": {
            "override": {
              "body": {
                "thread_ts": "1234567890.123456"
              }
            }
          }
        }
      }
    }'
```

```ruby Ruby highlight={8-14} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "slack" => {
        override: {
          body: {
            thread_ts: "1234567890.123456"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-16} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"slack": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"thread_ts": "1234567890.123456",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("slack", JsonValue.from(java.util.Map.of(
                "override", java.util.Map.of("body", java.util.Map.of("thread_ts", "1234567890.123456")))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-14} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'providers' => [
      'slack' => [
        'override' => [
          'body' => [
            'thread_ts' => '1234567890.123456',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-18} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "slack",
                new()
                {
                    Override = new Dictionary<string, JsonElement>()
                    {
                        { "body", JsonSerializer.SerializeToElement(new { thread_ts = "1234567890.123456" }) },
                    },
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"slack": {"override": {"body": {"thread_ts": "1234567890.123456"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 as a reply in an existing Slack thread.
```

### Mentioning users

Mention a user in your message using `<@USER_ID>` syntax in your template:

```
Hello <@UEFNTF6QL>, you have a new notification!
```

You can also use variables for dynamic mentions.

### Preventing unwanted mentions

Slack automatically parses text for `@name` patterns and turns them into mentions. If your message content includes text that resembles a mention but shouldn't trigger one, set [`verbatim: true`](https://docs.slack.dev/reference/block-kit/composition-objects/text-object/) on the Block Kit text object to disable this parsing.

Courier's standard template blocks (text, quote, etc.) don't expose the `verbatim` flag. To use it, either pass raw Block Kit JSON via `providers.slack.override.body.blocks` or use a [Jsonnet block
DOC](/docs/design/elemental/elements/jsonnet) in Design Studio:

```json theme={null}
{
  "type": "section",
  "text": {
    "type": "mrkdwn",
    "text": ">>> Message from @jennifer about the deployment",
    "verbatim": true
  }
}
```

### Slash command responses

If responding to a [Slash Command](https://api.slack.com/interactivity/slash-commands), use the `response_url` as an incoming webhook:

```json theme={null}
{
  "to": {
    "slack": {
      "incoming_webhook": {
        "url": "https://hooks.slack.com/commands/1234/5678"
      }
    }
  }
}
```

Set `override.slack.body.response_type` to `in_channel` or `ephemeral` as needed.

### Incoming webhooks

You can send messages to a channel using a Slack [Incoming Webhook](https://api.slack.com/messaging/webhooks):

```json theme={null}
{
  "to": {
    "slack": {
      "incoming_webhook": {
        "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}
```

### Updating notifications

To update a previously sent Slack message, set a "replacement key" (usually `ts`) in your notification template's Slack channel settings. Courier will use this key to update the message instead of posting a new one.

***

## Delivery tracking

When Courier sends a Slack message via Bot OAuth (`chat.postMessage`), it captures Slack's `ts` (message timestamp identifier) and `channel` (conversation ID) from the API response. You can use these values to thread replies, update messages, or link back to the original Slack message.

### Where delivery data appears

Slack-specific fields are returned in the `providers` array of the [Get message](/docs/api-reference/messages/get-message) response and in [`message:updated`
DOC](/docs/monitor/webhooks/events#messageupdated) webhook events:

```json theme={null}
{
  "providers": [
    {
      "provider": "slack",
      "status": "DELIVERED",
      "channel": {
        "key": "direct_message:slack",
        "name": "Slack",
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
      },
      "reference": {
        "channel": "C04EXAMPLE",
        "ts": "1630512468.000700"
      },
      "sent": 1630512468691,
      "delivered": 1630512468700
    }
  ]
}
```

| Field | Description |
| - | - |
| `providers[].reference.ts` | Slack message timestamp. Use this to [reply in a thread](#replying-in-a-thread) or [update the message](#updating-notifications). |
| `providers[].reference.channel` | Slack conversation ID where the message was posted. |
| `providers[].channel` | Courier routing metadata (template and channel key). Not the Slack channel ID. |

> [!NOTE]
>
> Slack messages are marked as `DELIVERED` immediately after sending because Slack's API confirms delivery synchronously. The `delivered` and `sent` timestamps will be very close together.

> [!NOTE]
>
> Incoming Webhook sends carry no `reference` data, since Slack's Incoming Webhook API doesn't return `ts` or `channel` in its response.

***

## Troubleshooting

* **Missing or incorrect Slack scopes:**
  * Double-check your app has all required scopes (`chat:write`, `im:write`, `users:read`, `users:read.email`, and `chat:write.public` for channels).
  * Reinstall your Slack app after updating scopes.

* **Bot not invited to channel:**
  * Make sure your Slack app/bot is a member of the channel you want to message.

* **Invalid or missing tokens:**
  * Ensure you're using the correct Bot User OAuth Access Token (starts with `xoxb-`).
  * Never use a user token or an expired token.

* **Permission errors or message not delivered:**
  * Check the [Courier Message Logs](https://app.courier.com/logs/messages) for error details and troubleshooting tips.

* **User or channel not found:**
  * Double-check the email, user\_id, or channel ID. For channels, copy the ID from the Slack URL.

* **Message truncated:**
  * Slack blocks [limit the characters](https://api.slack.com/reference/block-kit/blocks#section) in a single section to 3k characters. Courier automatically truncates Slack messages over 3k characters by removing escape and formatting characters that Slack adds after you submit the block.

If you're still stuck, reach out to Courier support at [support@courier.com](mailto:support@courier.com).

## Provider details

```text theme={null}
slack
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send Stream Chat messages through Courier
Source: https://www.courier.com/docs/integrations/direct-message/stream-chat

Connect Stream Chat with an API key and secret, and target a channel from the profile.

## Prerequisites

* [A Stream Chat account with a project](https://getstream.io/chat/)
* [Your API key, API secret, and sender ID](https://dashboard.getstream.io/)

## Setup

**1. Get your Stream Chat credentials**

In Stream, open the [dashboard](https://dashboard.getstream.io/), select your app, and copy the API key and API secret.

**2. Configure in Courier**

Open the [Stream Chat integration](https://app.courier.com/integrations/catalog/stream-chat) in Courier, enter your API key, API secret, and sender ID, then save.

## Profile requirements

Stream Chat posts a new message to a channel, or updates one that already exists. The profile you send to needs a `streamChat` object for whichever you want. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

**New message**

`channelType` and `channelId` name the channel to post into.

```javascript Node.js highlight={3-6} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    streamChat: {
      channelType: 'messaging',
      channelId: 'my-channel-id',
    },
  },
});
```

```python Python highlight={4-7} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "streamChat": {
            "channelType": "messaging",
            "channelId": "my-channel-id",
        },
    },
)
```

```bash cURL highlight={7-10} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "streamChat": {
        "channelType": "messaging",
        "channelId": "my-channel-id"
      }
    }
  }'
```

```ruby Ruby highlight={4-7} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    streamChat: {
      channelType: "messaging",
      channelId: "my-channel-id"
    }
  }
)
```

```go Go highlight={6-9} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"streamChat": map[string]any{
				"channelType": "messaging",
				"channelId": "my-channel-id",
			},
		},
	},
)
```

```java Java highlight={4-6} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("streamChat", JsonValue.from(java.util.Map.of(
            "channelType", "messaging",
            "channelId", "my-channel-id")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-5} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'streamChat' => [
    'channelType' => 'messaging',
    'channelId' => 'my-channel-id',
  ],
]);
```

```csharp C# highlight={7-10} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "streamChat": {
            "channelType": "messaging",
            "channelId": "my-channel-id"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"streamChat":{"channelType":"messaging","channelId":"my-channel-id"}}'
```

```text MCP theme={null}
With Courier MCP, save the Stream Chat messaging channel my-channel-id on user_123.
```

**Update a message**

`messageId` replaces the content of a message already posted.

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    streamChat: {
      messageId: 'my-message-id',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "streamChat": {
            "messageId": "my-message-id",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "streamChat": {
        "messageId": "my-message-id"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    streamChat: {
      messageId: "my-message-id"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"streamChat": map[string]any{
				"messageId": "my-message-id",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("streamChat", JsonValue.from(java.util.Map.of(
            "messageId", "my-message-id")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'streamChat' => [
    'messageId' => 'my-message-id',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "streamChat": {
            "messageId": "my-message-id"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"streamChat":{"messageId":"my-message-id"}}'
```

```text MCP theme={null}
With Courier MCP, save the Stream Chat message id my-message-id on user_123.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "streamChat": { "channelType": "messaging", "channelId": "my-channel-id" } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `streamChat` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `streamChat`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-8} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      streamChat: {
        channelType: "messaging",
        channelId: "my-channel-id",
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-7} theme={null}
response = client.send.message(
    message={
        "to": {
            "streamChat": {
                "channelType": "messaging",
                "channelId": "my-channel-id",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-10} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "streamChat": {
          "channelType": "messaging",
          "channelId": "my-channel-id"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-7} theme={null}
response = courier.send_.message(
  message: {
    to: {
      streamChat: {
        channelType: "messaging",
        channelId: "my-channel-id"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"streamChat": {"channelType": "messaging", "channelId": "my-channel-id"}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("streamChat", JsonValue.from(Map.of(
            "channelType", "messaging",
            "channelId", "my-channel-id")))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-7} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'streamChat' => [
        'channelType' => 'messaging',
        'channelId' => 'my-channel-id',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"streamChat": {"channelType": "messaging", "channelId": "my-channel-id"}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"streamChat": {"channelType": "messaging", "channelId": "my-channel-id"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the Stream Chat channel my-channel-id.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A provider override changes the request body, the API credentials, and the endpoint URL Courier sends to Stream Chat.

| Field | Sets |
| :- | :- |
| `body` | Any field Stream Chat's [SendMessage endpoint](https://getstream.io/chat/docs/rest/#/product%3Achat/SendMessage) accepts at `POST /channels/{type}/{id}/message`. |
| `config` | `apiKey`, `apiSecret`, `senderId`, and `baseUrl`, which defaults to `https://chat-us-east-1.stream-io-api.com`. |

```javascript Node.js highlight={14-26} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      streamChat: {
        channelType: "messaging",
        channelId: "my-channel-id",
      },
    },
    data: {
      name: "Sarah Bennett",
    },
    providers: {
      "stream-chat": {
        override: {
          body: {
            skip_push: true,
          },
          config: {
            baseUrl: "https://custom-stream-endpoint.example.com",
            apiKey: "RUNTIME_API_KEY",
            apiSecret: "RUNTIME_API_SECRET",
            senderId: "RUNTIME_SENDER_ID",
          },
        },
      },
    },
  },
});
```

```python Python highlight={14-26} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "streamChat": {
                "channelType": "messaging",
                "channelId": "my-channel-id",
            },
        },
        "data": {
            "name": "Sarah Bennett",
        },
        "providers": {
            "stream-chat": {
                "override": {
                    "body": {
                        "skip_push": True,
                    },
                    "config": {
                        "baseUrl": "https://custom-stream-endpoint.example.com",
                        "apiKey": "RUNTIME_API_KEY",
                        "apiSecret": "RUNTIME_API_SECRET",
                        "senderId": "RUNTIME_SENDER_ID",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={17-29} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "streamChat": {
          "channelType": "messaging",
          "channelId": "my-channel-id"
        }
      },
      "data": {
        "name": "Sarah Bennett"
      },
      "providers": {
        "stream-chat": {
          "override": {
            "body": {
              "skip_push": true
            },
            "config": {
              "baseUrl": "https://custom-stream-endpoint.example.com",
              "apiKey": "RUNTIME_API_KEY",
              "apiSecret": "RUNTIME_API_SECRET",
              "senderId": "RUNTIME_SENDER_ID"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={14-26} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      streamChat: {
        channelType: "messaging",
        channelId: "my-channel-id"
      }
    },
    data: {
      name: "Sarah Bennett"
    },
    providers: {
      "stream-chat": {
        override: {
          body: {
            skip_push: true
          },
          config: {
            baseUrl: "https://custom-stream-endpoint.example.com",
            apiKey: "RUNTIME_API_KEY",
            apiSecret: "RUNTIME_API_SECRET",
            senderId: "RUNTIME_SENDER_ID"
          }
        }
      }
    }
  }
)
```

```go Go highlight={18-30} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "streamChat": {
    "channelType": "messaging",
    "channelId": "my-channel-id"
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
		Providers: shared.MessageProvidersParam{
			"stream-chat": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"skip_push": true,
					},
					"config": map[string]any{
						"baseUrl": "https://custom-stream-endpoint.example.com",
						"apiKey": "RUNTIME_API_KEY",
						"apiSecret": "RUNTIME_API_SECRET",
						"senderId": "RUNTIME_SENDER_ID",
					},
				},
			},
		},
	},
})
```

```java Java highlight={16-26} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("streamChat", JsonValue.from(java.util.Map.of(
                "channelType", "messaging",
                "channelId", "my-channel-id"
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett"
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("stream-chat", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "skip_push", true
                    ),
                    "config", java.util.Map.of(
                        "baseUrl", "https://custom-stream-endpoint.example.com",
                        "apiKey", "RUNTIME_API_KEY",
                        "apiSecret", "RUNTIME_API_SECRET",
                        "senderId", "RUNTIME_SENDER_ID"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={14-26} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'streamChat' => [
        'channelType' => 'messaging',
        'channelId' => 'my-channel-id',
      ],
    ],
    'data' => [
      'name' => 'Sarah Bennett',
    ],
    'providers' => [
      'stream-chat' => [
        'override' => [
          'body' => [
            'skip_push' => true,
          ],
          'config' => [
            'baseUrl' => 'https://custom-stream-endpoint.example.com',
            'apiKey' => 'RUNTIME_API_KEY',
            'apiSecret' => 'RUNTIME_API_SECRET',
            'senderId' => 'RUNTIME_SENDER_ID',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={26-46} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "streamChat": {
                    "channelType": "messaging",
                    "channelId": "my-channel-id"
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "stream-chat",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "skip_push": true
                          },
                          "config": {
                            "baseUrl": "https://custom-stream-endpoint.example.com",
                            "apiKey": "RUNTIME_API_KEY",
                            "apiSecret": "RUNTIME_API_SECRET",
                            "senderId": "RUNTIME_SENDER_ID"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"streamChat": {"channelType": "messaging", "channelId": "my-channel-id"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}' \
  --message.providers '{"stream-chat": {"override": {"body": {"skip_push": true}, "config": {"baseUrl": "https://custom-stream-endpoint.example.com", "apiKey": "RUNTIME_API_KEY", "apiSecret": "RUNTIME_API_SECRET", "senderId": "RUNTIME_SENDER_ID"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this Stream Chat channel with a different API key and sender.
```

## Provider details

```text theme={null}
stream-chat
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send Viber messages through Courier
Source: https://www.courier.com/docs/integrations/direct-message/viber

Connect a Viber bot with an auth token and address a recipient with viber.receiver.

## Prerequisites

* [A Viber bot account](https://partners.viber.com/account/create-bot-account)
* Your Viber bot auth token
* [A webhook server that receives Viber POST requests](https://www.npmjs.com/package/viber-bot)

## Setup

Open the [Viber integration](https://app.courier.com/integrations/catalog/viber) in Courier, enter your auth token and sender name, then save.

### Webhooks server

Viber requires a registered webhooks server before you send notifications:

```bash theme={null}
curl -X POST 'https://chatapi.viber.com/pa/set_webhook' \
     -H 'Content-Type: application/json' \
     -H 'X-Viber-Auth-Token: VIBER_AUTH_TOKEN' \
     -d '{ "url": "YOUR_WEBHOOK_SERVER_URL", "event_types": ["delivered"] }'
```

The server receives Viber events: the UserIDs of users who subscribe, and delivery status events.

## Profile requirements

Viber addresses the recipient by `UserID`, which goes in `viber.receiver` on the profile. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    viber: {
      receiver: '12943673==',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "viber": {
            "receiver": "12943673==",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "viber": {
        "receiver": "12943673=="
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    viber: {
      receiver: "12943673=="
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"viber": map[string]any{
				"receiver": "12943673==",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("viber", JsonValue.from(java.util.Map.of(
            "receiver", "12943673==")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'viber' => [
    'receiver' => '12943673==',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "viber": {
            "receiver": "12943673=="
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"viber":{"receiver":"12943673=="}}'
```

```text MCP theme={null}
With Courier MCP, save the Viber receiver 12943673== on user_123.
```

The recipient needs an active [Viber](https://www.viber.com/en/) account. Viber sends the `UserID` to your webhooks server after a user messages the Viber bot.

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "viber": { "receiver": "12943673==" } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `viber` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `viber`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      viber: {
        receiver: "12943673==",
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-6} theme={null}
response = client.send.message(
    message={
        "to": {
            "viber": {
                "receiver": "12943673==",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-9} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "viber": {
          "receiver": "12943673=="
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
response = courier.send_.message(
  message: {
    to: {
      viber: {
        receiver: "12943673=="
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"viber": {"receiver": "12943673=="}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("viber", JsonValue.from(Map.of(
            "receiver", "12943673==")))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-6} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'viber' => [
        'receiver' => '12943673==',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"viber": {"receiver": "12943673=="}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"viber": {"receiver": "12943673=="}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the Viber receiver 12943673==.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A provider override changes the request body Courier sends to Viber, or swaps the auth token, sender name, and API URL.

### Body overrides

Override the request body that Courier sends to the Viber [Send Message API](https://developers.viber.com/docs/api/rest-bot-api/#send-message).

```javascript Node.js highlight={5-7,10-17} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      viber: {
        receiver: "12943673==",
      },
    },
    providers: {
      viber: {
        override: {
          body: {
            type: "picture",
            media: "https://example.com/image.jpg",
          },
        },
      },
    },
  },
});
```

```python Python highlight={5-7,10-17} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "viber": {
                "receiver": "12943673==",
            },
        },
        "providers": {
            "viber": {
                "override": {
                    "body": {
                        "type": "picture",
                        "media": "https://example.com/image.jpg",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={8-10,13-20} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "viber": {
          "receiver": "12943673=="
        }
      },
      "providers": {
        "viber": {
          "override": {
            "body": {
              "type": "picture",
              "media": "https://example.com/image.jpg"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={5-7,10-17} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      viber: {
        receiver: "12943673=="
      }
    },
    providers: {
      viber: {
        override: {
          body: {
            type: "picture",
            media: "https://example.com/image.jpg"
          }
        }
      }
    }
  }
)
```

```go Go highlight={4-6,14-21} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "viber": {
    "receiver": "12943673=="
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"viber": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"type": "picture",
						"media": "https://example.com/image.jpg",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-8,12-17} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("viber", JsonValue.from(java.util.Map.of(
                "receiver", "12943673=="
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("viber", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "type", "picture",
                        "media", "https://example.com/image.jpg"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={5-7,10-17} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'viber' => [
        'receiver' => '12943673==',
      ],
    ],
    'providers' => [
      'viber' => [
        'override' => [
          'body' => [
            'type' => 'picture',
            'media' => 'https://example.com/image.jpg',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={11-13,21-36} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "viber": {
                    "receiver": "12943673=="
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "viber",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "type": "picture",
                            "media": "https://example.com/image.jpg"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3,5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"viber": {"receiver": "12943673=="}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"viber": {"override": {"body": {"type": "picture", "media": "https://example.com/image.jpg"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this Viber receiver and override the message body.
```

### Config overrides

You can swap the auth token, sender name, or API URL at send time:

```javascript Node.js highlight={5-7,10-17} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      viber: {
        receiver: "12943673==",
      },
    },
    providers: {
      viber: {
        override: {
          config: {
            token: "RUNTIME_AUTH_TOKEN",
            name: "My Bot Name",
          },
        },
      },
    },
  },
});
```

```python Python highlight={5-7,10-17} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "viber": {
                "receiver": "12943673==",
            },
        },
        "providers": {
            "viber": {
                "override": {
                    "config": {
                        "token": "RUNTIME_AUTH_TOKEN",
                        "name": "My Bot Name",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={8-10,13-20} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "viber": {
          "receiver": "12943673=="
        }
      },
      "providers": {
        "viber": {
          "override": {
            "config": {
              "token": "RUNTIME_AUTH_TOKEN",
              "name": "My Bot Name"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={5-7,10-17} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      viber: {
        receiver: "12943673=="
      }
    },
    providers: {
      viber: {
        override: {
          config: {
            token: "RUNTIME_AUTH_TOKEN",
            name: "My Bot Name"
          }
        }
      }
    }
  }
)
```

```go Go highlight={4-6,14-21} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "viber": {
    "receiver": "12943673=="
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"viber": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"token": "RUNTIME_AUTH_TOKEN",
						"name": "My Bot Name",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-8,12-17} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("viber", JsonValue.from(java.util.Map.of(
                "receiver", "12943673=="
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("viber", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "token", "RUNTIME_AUTH_TOKEN",
                        "name", "My Bot Name"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={5-7,10-17} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'viber' => [
        'receiver' => '12943673==',
      ],
    ],
    'providers' => [
      'viber' => [
        'override' => [
          'config' => [
            'token' => 'RUNTIME_AUTH_TOKEN',
            'name' => 'My Bot Name',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={11-13,21-36} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "viber": {
                    "receiver": "12943673=="
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "viber",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "token": "RUNTIME_AUTH_TOKEN",
                            "name": "My Bot Name"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3,5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"viber": {"receiver": "12943673=="}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"viber": {"override": {"config": {"token": "RUNTIME_AUTH_TOKEN", "name": "My Bot Name"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this Viber receiver with a different auth token.
```

## Provider details

```text theme={null}
viber
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send WhatsApp messages through Courier
Source: https://www.courier.com/docs/integrations/direct-message/whatsapp

Send WhatsApp messages through Twilio with a pre-approved template.

Courier uses the [Twilio API for WhatsApp](https://twilio.com/whatsapp) as the delivery partner.

## Prerequisites

* [A Twilio account with WhatsApp enabled](https://www.twilio.com/)
* [Your Twilio Account SID and Auth Token](https://console.twilio.com/)
* A WhatsApp-enabled "From" number in Twilio

## Setup

**1. Get your Twilio credentials**

In Twilio, open the [console](https://console.twilio.com/) and copy your Account SID and Auth Token. Your WhatsApp sender is the "From" number.

**2. Configure in Courier**

Open the [WhatsApp integration](https://app.courier.com/integrations/catalog/twilio-whatsapp) in Courier, enter your Twilio Account SID, Auth Token, and "From" number, then save.

## Profile requirements

WhatsApp addresses the recipient by phone number, so the profile you send to needs a `phone_number`. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    phone_number: '+15551234567',
  },
});
```

```python Python highlight={4} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "phone_number": "+15551234567",
    },
)
```

```bash cURL highlight={7} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "phone_number": "+15551234567"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    phone_number: "+15551234567"
  }
)
```

```go Go highlight={6} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"phone_number": "+15551234567",
		},
	},
)
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("phone_number", JsonValue.from("+15551234567"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'phone_number' => '+15551234567',
]);
```

```csharp C# highlight={6} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "phone_number", JsonSerializer.SerializeToElement("+15551234567") },
    },
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"phone_number":"+15551234567"}'
```

```text MCP theme={null}
With Courier MCP, create a profile for user_123 with the phone number +15551234567.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "phone_number": "+15551234567" }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `phone_number` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to a phone number**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      phone_number: "+15551234567",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "phone_number": "+15551234567",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "phone_number": "+15551234567"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      phone_number: "+15551234567"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+15551234567"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+15551234567").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'phone_number' => '+15551234567',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+15551234567" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+15551234567"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to +15551234567 by SMS.
```

## Notification categories

WhatsApp allows these [notification categories](https://www.twilio.com/docs/whatsapp/tutorial/send-whatsapp-notification-messages-templates#whatsapp-notification-categories):

* Marketing
* Authentication
* Utility

Other categories are likely to be rejected, including:

* Account Update
* Alert Update
* Appointment Update
* Auto-Reply
* Issue Resolution
* Payment Update
* Personal Finance Update
* Reservation Update
* Shipping Update
* Ticket Update
* Transportation Update

## WhatsApp template verification

WhatsApp reviews every template against its guidelines before you can send it.

### Create the template

**Structure:** WhatsApp [message templates](https://www.twilio.com/docs/whatsapp/tutorial/send-whatsapp-notification-messages-templates) are predefined messages with placeholders for dynamic content. A template can be text, media (images, documents), or interactive (buttons, list messages).

**Categories:** Each template is [categorized](#notification-categories) by use case, such as transactional updates, customer service, or alerts.

### Submit the template for approval

**Open the console:** In the Twilio Console, go to the Messaging section.

**Create the template:** In the WhatsApp Templates section, create a template. Provide the template name, category, language, and message content. Leave out promotional material, which WhatsApp disallows in templates.

**Submit for review:** [Submit](https://www.twilio.com/docs/whatsapp/tutorial/message-template-approvals-statuses) the template for WhatsApp's review.

### WhatsApp approval process

WhatsApp checks the template against its policies. Review takes a few minutes to 24 hours.

Two outcomes:

* **Approved:** The template meets WhatsApp's guidelines. You can now send it through the Twilio API.

* **Rejected:** The template is [rejected](https://www.twilio.com/docs/whatsapp/tutorial/message-template-approvals-statuses#common-rejection-reasons) for promotional content, inappropriate language, or other policy violations. Fix the template and resubmit it.

## Approved templates with Courier

Copy the approved template's [Twilio Content SID](https://www.twilio.com/docs/whatsapp/tutorial/send-whatsapp-notification-messages-templates#creating-message-templates-and-submitting-them-for-approval), which starts with `HX`. Paste it into the WhatsApp channel settings of your Courier template. Sends then reference that approved template through the [Send API](/docs/api-reference/send/send-a-message).

![A Courier template's WhatsApp channel settings with the Twilio Content SID pasted in](https://mintcdn.com/courier-4f1f25dc/_N31KC_ZrU1lo5hN/assets/whatsapp.webp?fit=max\&auto=format\&n=_N31KC_ZrU1lo5hN\&q=85\&s=23660c5a80b264bb091a6b24b43071b3)

WhatsApp Template

On send, Courier calls Twilio with the template details. Twilio delivers the message over WhatsApp.

> [!NOTE]
>
> **Twilio renders the approved template, filled with your Courier variables.**\\
>
> Courier sends the Content SID and its variables, and Twilio renders the approved template. Your Courier template still drives routing, variables, and every other channel.

### Key considerations

**Content:** Keep template content clear and non-promotional. Include every placeholder and give sample values so reviewers have context.

**Localization:** Create and get approval for each language version of the template.

**Monitoring:** Watch template [performance](https://help.twilio.com/articles/360039737753-Recommendations-and-best-practices-for-creating-WhatsApp-Message-Templates). Frequent spam reports can cost you the ability to send. Update templates as WhatsApp guidelines change.

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A provider override changes the request body Courier sends to Twilio, or swaps the Twilio credentials and the From number.

### Body overrides

A **Content SID is required** on every WhatsApp send. Set it on the template's WhatsApp channel settings, or pass it per send as `override.body.ContentSid`. Without one the send fails with `No Content SID specified.` before reaching Twilio.

Override body keys are capitalized before they are sent, so `contentSid` and `ContentSid` are equivalent. Use an override to select an approved template at send time:

```javascript Node.js highlight={11} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+15555555555",
    },
    providers: {
      "twilio-whatsapp": {
        override: {
          body: {
            ContentSid: "HXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          },
        },
      },
    },
  },
});
```

```python Python highlight={11} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+15555555555",
        },
        "providers": {
            "twilio-whatsapp": {
                "override": {
                    "body": {
                        "ContentSid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={14} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+15555555555"
      },
      "providers": {
        "twilio-whatsapp": {
          "override": {
            "body": {
              "ContentSid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXX"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={11} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+15555555555"
    },
    providers: {
      "twilio-whatsapp": {
        override: {
          body: {
            ContentSid: "HXXXXXXXXXXXXXXXXXXXXXXXXXXX"
          }
        }
      }
    }
  }
)
```

```go Go highlight={13} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+15555555555"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"twilio-whatsapp": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"ContentSid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXX",
					},
				},
			},
		},
	},
})
```

```java Java highlight={8} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+15555555555").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("twilio-whatsapp", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "ContentSid", "HXXXXXXXXXXXXXXXXXXXXXXXXXXX"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={11} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+15555555555',
    ],
    'providers' => [
      'twilio-whatsapp' => [
        'override' => [
          'body' => [
            'ContentSid' => 'HXXXXXXXXXXXXXXXXXXXXXXXXXXX',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={17} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+15555555555" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "twilio-whatsapp",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "ContentSid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXX"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+15555555555"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"twilio-whatsapp": {"override": {"body": {"ContentSid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXX"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +15555555555 on WhatsApp with a Content SID override.
```

### Config overrides

Swap Twilio credentials or the "From" number at send time:

```javascript Node.js highlight={8-16} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+15555555555",
    },
    providers: {
      "twilio-whatsapp": {
        override: {
          config: {
            accountSid: "RUNTIME_ACCOUNT_SID",
            authToken: "RUNTIME_AUTH_TOKEN",
            from: "+14155551234",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-16} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+15555555555",
        },
        "providers": {
            "twilio-whatsapp": {
                "override": {
                    "config": {
                        "accountSid": "RUNTIME_ACCOUNT_SID",
                        "authToken": "RUNTIME_AUTH_TOKEN",
                        "from": "+14155551234",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-19} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+15555555555"
      },
      "providers": {
        "twilio-whatsapp": {
          "override": {
            "config": {
              "accountSid": "RUNTIME_ACCOUNT_SID",
              "authToken": "RUNTIME_AUTH_TOKEN",
              "from": "+14155551234"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-16} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+15555555555"
    },
    providers: {
      "twilio-whatsapp": {
        override: {
          config: {
            accountSid: "RUNTIME_ACCOUNT_SID",
            authToken: "RUNTIME_AUTH_TOKEN",
            from: "+14155551234"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-18} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+15555555555"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"twilio-whatsapp": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"accountSid": "RUNTIME_ACCOUNT_SID",
						"authToken": "RUNTIME_AUTH_TOKEN",
						"from": "+14155551234",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-12} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+15555555555").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("twilio-whatsapp", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "accountSid", "RUNTIME_ACCOUNT_SID",
                        "authToken", "RUNTIME_AUTH_TOKEN",
                        "from", "+14155551234"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-16} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+15555555555',
    ],
    'providers' => [
      'twilio-whatsapp' => [
        'override' => [
          'config' => [
            'accountSid' => 'RUNTIME_ACCOUNT_SID',
            'authToken' => 'RUNTIME_AUTH_TOKEN',
            'from' => '+14155551234',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-25} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+15555555555" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "twilio-whatsapp",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "accountSid": "RUNTIME_ACCOUNT_SID",
                            "authToken": "RUNTIME_AUTH_TOKEN",
                            "from": "+14155551234"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+15555555555"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"twilio-whatsapp": {"override": {"config": {"accountSid": "RUNTIME_ACCOUNT_SID", "authToken": "RUNTIME_AUTH_TOKEN", "from": "+14155551234"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +15555555555 on WhatsApp with different Twilio credentials.
```

## Provider details

```text theme={null}
twilio-whatsapp
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with Amply through Courier
Source: https://www.courier.com/docs/integrations/email/amply

Connect Amply with an API key and from address, then override sender and attachments per send.

## Prerequisites

* [An Amply (SendAmply) account](https://sendamply.com/)
* An Amply Access Token

## Setup

**1. Create an Amply access token**

In Amply, follow [the authentication reference](https://docs.sendamply.com/reference/authentication) to create an access token.

**2. Configure in Courier**

Open the [Amply integration](https://app.courier.com/integrations/catalog/amply) in Courier, enter your Access Token, From Email, and From Name, then save.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

A provider override changes what Courier sends to Amply's Mail Send API. This payload overrides the sender name:

```javascript Node.js highlight={8-14} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      amply: {
        override: {
          config: {
            fromName: "Acme Notifications",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-14} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "amply": {
                "override": {
                    "config": {
                        "fromName": "Acme Notifications",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-17} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "amply": {
          "override": {
            "config": {
              "fromName": "Acme Notifications"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-14} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      amply: {
        override: {
          config: {
            fromName: "Acme Notifications"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-16} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"amply": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"fromName": "Acme Notifications",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-10} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("amply", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "fromName", "Acme Notifications"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-14} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'amply' => [
        'override' => [
          'config' => [
            'fromName' => 'Acme Notifications',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-23} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "amply",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "fromName": "Acme Notifications"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"amply": {"override": {"config": {"fromName": "Acme Notifications"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and override the sender name in Amply.
```

Overrides are deep-merged into the request. Fields you set replace their counterparts, and everything you leave out is still sent. The full field list is in the [Amply API docs](https://docs.sendamply.com/reference/mail-send).

## Sending attachments

To attach a file, use this override:

```javascript Node.js highlight={13-19} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    data: {
      hello: "world",
    },
    providers: {
      amply: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
            },
          ],
        },
      },
    },
  },
});
```

```python Python highlight={13-19} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "data": {
            "hello": "world",
        },
        "providers": {
            "amply": {
                "override": {
                    "attachments": [
                        {
                            "filename": "billing.pdf",
                            "contentType": "application/pdf",
                            "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
                        },
                    ],
                },
            },
        },
    },
)
```

```bash cURL highlight={16-22} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "data": {
        "hello": "world"
      },
      "providers": {
        "amply": {
          "override": {
            "attachments": [
              {
                "filename": "billing.pdf",
                "contentType": "application/pdf",
                "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
              }
            ]
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={13-19} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    data: {
      hello: "world"
    },
    providers: {
      amply: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
            }
          ]
        }
      }
    }
  }
)
```

```go Go highlight={15-21} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"hello": "world",
		},
		Providers: shared.MessageProvidersParam{
			"amply": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"attachments": []any{
						map[string]any{
							"filename": "billing.pdf",
							"contentType": "application/pdf",
							"data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={10-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "hello", "world"
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("amply", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "attachments", java.util.List.of(
                        java.util.Map.of(
                            "filename", "billing.pdf",
                            "contentType", "application/pdf",
                            "data", "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={13-19} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'data' => [
      'hello' => 'world',
    ],
    'providers' => [
      'amply' => [
        'override' => [
          'attachments' => [
            [
              'filename' => 'billing.pdf',
              'contentType' => 'application/pdf',
              'data' => 'Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={20-26} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "hello", JsonSerializer.SerializeToElement("world") },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "amply",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "attachments": [
                            {
                              "filename": "billing.pdf",
                              "contentType": "application/pdf",
                              "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                            }
                          ]
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"hello": "world"}' \
  --message.providers '{"amply": {"override": {"attachments": [{"filename": "billing.pdf", "contentType": "application/pdf", "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"}]}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com with a PDF attachment through Amply.
```

## Provider details

```text theme={null}
amply
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with Amazon SES through Courier
Source: https://www.courier.com/docs/integrations/email/aws-ses

Connect SES with access keys or an IAM role, track delivery through SNS, and override fields.

## Prerequisites

* [An AWS SES account](https://portal.aws.amazon.com/billing/signup#/start)
* AWS access keys, or an IAM role Courier can assume
* A verified sender identity in AWS SES
* Your AWS SES region

## Setup

### Step 1: add the AWS SES integration to Courier

Before choosing an authentication method:

1. Log in to Courier

2. Navigate to the [Integrations](https://app.courier.com/integrations) page

3. Select the [AWS SES Integration](https://app.courier.com/integrations/aws-ses) to configure it

### Authentication methods

AWS SES integration in Courier supports two authentication methods:

1. AWS Access Keys

2. AWS IAM Role (Cross-Account Trust)

Choose one of the following authentication methods to get started:

### Method 1: AWS access keys

* Create an AWS SES API Key:

  1. Log in to AWS SES

  2. Navigate to "Settings" → "My Security Credentials"

  3. Go to "Access management" → "Users"

  4. On the "Users" page, select "Add user" and follow the steps to create a new IAM user with `AmazonSESFullAccess` permissions

> [!NOTE]
>
> Download the Access Key ID and Secret Access Key at user creation. AWS doesn't show the secret again.

To scope permissions tighter than `AmazonSESFullAccess`, create a custom policy. In the AWS IAM console, open **Policies → Create policy** and define it in the JSON editor:

```json theme={null}
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": ["ses:SendRawEmail", "ses:GetSendStatistics"],
        "Resource": "*"
    }
  ]
}
```

Attach it to the IAM user you created for AWS SES.

* Integrate AWS SES API Key with Courier:
  After creating the IAM user and obtaining the API keys, add them to the Courier AWS SES integration page.

### Method 2: AWS IAM role (Cross-account trust)

* Configure the minimum required IAM policy for sending emails:

```json theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ses:SendEmail",
                "ses:SendRawEmail"
            ],
            "Resource": [
              "arn:aws:ses:region:${YOUR_AWS_ACCOUNT_ID}:identity/example.com",
              "arn:aws:ses:region:${YOUR_AWS_ACCOUNT_ID}:identity/sarah@acme-corp.com"
            ]
        }
    ]
}
```

* Create an IAM Role with the following trust policy:

```json theme={null}
{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Principal": {
				"AWS": "464962053586"
			},
			"Action": "sts:AssumeRole",
			"Condition": {
				"StringEquals": {
					"sts:ExternalId": "${YOUR_COURIER_WORKSPACE_ID}"
				}
			}
		}
	]
}
```

* To work in **Courier's test environment**, add `/test` to the end of the `ExternalId` value in the role policy.

* After creating the role, copy its ARN and paste it in the "Role ARN" field in the Courier AWS SES integration settings.

> [!NOTE]
>
> When using IAM Role authentication, you'll need to replace the following placeholders:
>
> * `${YOUR_AWS_ACCOUNT_ID}`: Your AWS account ID
>
> * `${YOUR_COURIER_WORKSPACE_ID}`: Your Courier workspace ID

### Finish the setup

After configuring your chosen authentication method, complete the following steps:

#### Step 1: add a verified "from" address in Courier

1. Add a verified email address (e.g., [support@acme-corp.com](mailto:support@acme-corp.com)) to the "From Address" field in Courier.

   * Courier uses the "From" email address you set for every email sent through the AWS SES integration. You can [override this default "From" address
     DOC](/docs/send/overrides) on a per channel basis within your templates.

2. Ensure the "From" address is a verified identity in your AWS-SES account.

3. For more information on verifying identities, see [Verifying an Identity for Amazon SES Sending Authorization ](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-authorization-identity-owner-tasks-verification.html).

> [!WARNING]
>
> A new AWS SES account starts in the **SES sandbox**, which only sends to verified addresses and domains. Reaching anyone else means asking AWS to lift it: [Moving out of the Amazon SES sandbox](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/request-production-access.html).

#### Step 2: configure AWS SES region

Select your preferred AWS SES region from the dropdown menu in the Courier AWS SES integration.

#### Step 3: create and send a Courier notification using AWS SES

Refer to [Create and Send a Message
DOC](/docs/send/overview) for instructions on building your notification template and sending a message with the Courier API using cURL.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Delivery tracking

> [!NOTE]
>
> SES tracks delivery through SNS webhooks rather than polling, so without the setup below every message stays at `SENT` in your [logs
> DOC](/docs/monitor/overview).

To track delivery, set up Amazon SNS topics. Then configure AWS SES to publish delivery notifications to those topics. Every event carries the SES `MessageId`, which is what your own webhook uses to match the event to the message.

```mermaid theme={null}
flowchart LR
    A["SES sends"] --> B["Event to SNS"]
    B --> C["SNS to Courier"]
    C --> D["Status updated"]
    D --> E["Your webhook"]
```

> **Setup instructions**
>
> **1. Get Your Courier Webhook URL**
>
> You'll need your Courier Message Events webhook URL for AWS SES.
>
> Via Courier App:
>
> * Navigate to Channels → Email → AWS SES provider
> * Look for "Message Events Webhook URL" section
> * Copy the webhook URL
>
> `Important: Keep this URL secure - it authenticates webhooks from AWS to Courier.`
>
> **2. Create AWS SES Configuration Set**
>
> Configuration Sets in AWS SES enable event publishing.
>
> * Open the AWS Console and navigate to Amazon SES
> * Click Configuration Sets in the left sidebar
> * Click Create Configuration Set
> * Enter a name (e.g., `courier-delivery-tracking`)
> * Click Create
>
> **3. Add SNS Event Destination**
>
> * Click on your newly created Configuration Set
> * Navigate to the Event destinations tab
> * Click Add destination
> * Select Amazon SNS as the destination type
> * Configure the destination:
> * Event types: Select `Bounce`, `Delivery`, and `Reject`
> * SNS Topic:
>   * Choose Create new SNS topic if you don't have one
>   * Or select an existing topic
> * Topic Name (if creating new): `courier-ses-delivery-events`
> * Click `Next` and then `Add destination`
>
> **4. Configure SNS Subscription to Courier**
>
> * Navigate to Amazon SNS in AWS Console
> * Click `Topics` in the left sidebar
> * Find and click the topic you created/selected in Step 3
> * Click `Create subscription`
> * Configure the subscription:
> * Protocol: `Select HTTPS`
> * Endpoint: Paste your Courier webhook URL from Step 1
> * Enable raw message delivery: `UNCHECKED` (important)
> * Click `Create subscription`
>
> **Automatic Confirmation:** AWS will send a subscription confirmation request to Courier. Courier automatically confirms the subscription - no action needed on your part. Wait 30 seconds, then refresh the page to see the subscription status change to "Confirmed".

> **Assign configuration set to your identity**
>
> Assign the Configuration Set as the default for your verified email address or domain. This ensures all emails sent from that identity automatically use the Configuration Set for delivery tracking.
>
> **For a Verified Email Address:**
>
> * In AWS SES Console, navigate to Verified identities
> * Click on your verified email address (e.g., [noreply@yourdomain.com](mailto:noreply@yourdomain.com))
> * Go to the Configuration set tab
> * Click Edit
> * Select your Configuration Set (courier-delivery-tracking)
> * Click Save changes
>
> **For a Verified Domain:**
>
> * In AWS SES Console, navigate to Verified identities
>
> * Click on your verified domain (e.g., yourdomain.com)
>
> * Go to the Configuration set tab
>
> * Click Edit
>
> * Select your Configuration Set (courier-delivery-tracking)
>
> * Click Save changes
>
> > [!WARNING]
> >
> > **Grant the Configuration Set in your IAM policy.**\\
> >
> > A default Configuration Set on an identity makes SES authorize `ses:SendRawEmail` against it too. A policy scoped to ARNs without it fails every send.
>
> The error names the resource it couldn't reach:
>
> ```
>   User `arn:aws:sts::<account>:assumed-role/customer-ses-role/...` is not authorized to
>   perform `ses:SendRawEmail` on resource
>   `arn:aws:ses:us-east-1:<account>:configuration-set/courier-delivery-tracking`
> ```
>
> Add the Configuration Set ARN to the `Resource` list of the policy attached to the IAM user (Method 1) or the assumed role (Method 2):
>
> ```json theme={null}
> "Resource": [
>   "arn:aws:ses:region:${YOUR_AWS_ACCOUNT_ID}:identity/example.com",
>   "arn:aws:ses:region:${YOUR_AWS_ACCOUNT_ID}:configuration-set/courier-delivery-tracking"
> ]
> ```
>
> A policy using `"Resource": "*"` needs no change. Sends recover on the next retry.

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

A provider override changes what Courier sends to SES's [SendRawEmail API](https://docs.aws.amazon.com/ses/latest/APIReference/API_SendRawEmail.html). `body` takes any field that method accepts, and `config` swaps the AWS credentials and region for one send.

### Raw MIME message

`override.body.RawMessage.Data` sends a MIME 1.0 message of your own in place of the rendered template:

```javascript Node.js highlight={11-23} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    data: {
      name: "Sarah Bennett",
    },
    providers: {
      "aws-ses": {
        override: {
          body: {
            RawMessage: {
              Data: "<Mime 1.0 compatible message>",
            },
          },
          config: {
            accessKeyId: "<Access Key ID>",
            secretAccessKey: "<Secret Access Key>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={11-23} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "data": {
            "name": "Sarah Bennett",
        },
        "providers": {
            "aws-ses": {
                "override": {
                    "body": {
                        "RawMessage": {
                            "Data": "<Mime 1.0 compatible message>",
                        },
                    },
                    "config": {
                        "accessKeyId": "<Access Key ID>",
                        "secretAccessKey": "<Secret Access Key>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={14-26} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "data": {
        "name": "Sarah Bennett"
      },
      "providers": {
        "aws-ses": {
          "override": {
            "body": {
              "RawMessage": {
                "Data": "<Mime 1.0 compatible message>"
              }
            },
            "config": {
              "accessKeyId": "<Access Key ID>",
              "secretAccessKey": "<Secret Access Key>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={11-23} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    data: {
      name: "Sarah Bennett"
    },
    providers: {
      "aws-ses": {
        override: {
          body: {
            RawMessage: {
              Data: "<Mime 1.0 compatible message>"
            }
          },
          config: {
            accessKeyId: "<Access Key ID>",
            secretAccessKey: "<Secret Access Key>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={13-25} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
		Providers: shared.MessageProvidersParam{
			"aws-ses": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"RawMessage": map[string]any{
							"Data": "<Mime 1.0 compatible message>",
						},
					},
					"config": map[string]any{
						"accessKeyId": "<Access Key ID>",
						"secretAccessKey": "<Secret Access Key>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={9-19} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett"
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("aws-ses", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "RawMessage", java.util.Map.of(
                            "Data", "<Mime 1.0 compatible message>"
                        )
                    ),
                    "config", java.util.Map.of(
                        "accessKeyId", "<Access Key ID>",
                        "secretAccessKey", "<Secret Access Key>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={11-23} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'data' => [
      'name' => 'Sarah Bennett',
    ],
    'providers' => [
      'aws-ses' => [
        'override' => [
          'body' => [
            'RawMessage' => [
              'Data' => '<Mime 1.0 compatible message>',
            ],
          ],
          'config' => [
            'accessKeyId' => '<Access Key ID>',
            'secretAccessKey' => '<Secret Access Key>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={13-33} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "aws-ses",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "RawMessage": {
                              "Data": "<Mime 1.0 compatible message>"
                            }
                          },
                          "config": {
                            "accessKeyId": "<Access Key ID>",
                            "secretAccessKey": "<Secret Access Key>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}' \
  --message.providers '{"aws-ses": {"override": {"body": {"RawMessage": {"Data": "<Mime 1.0 compatible message>"}}, "config": {"accessKeyId": "<Access Key ID>", "secretAccessKey": "<Secret Access Key>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and override the SES raw message.
```

### Attachments

`override.attachments` adds files to the email. Each entry carries a `filename`, a `contentType`, and base64-encoded `data`:

```javascript Node.js highlight={11-21} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Sarah Bennett",
    },
    providers: {
      "aws-ses": {
        override: {
          attachments: [
            {
              filename: "hello.txt",
              contentType: "text/plain",
              data: "SGk=",
            },
          ],
        },
      },
    },
  },
});
```

```python Python highlight={11-21} theme={null}
response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "name": "Sarah Bennett",
        },
        "providers": {
            "aws-ses": {
                "override": {
                    "attachments": [
                        {
                            "filename": "hello.txt",
                            "contentType": "text/plain",
                            "data": "SGk=",
                        },
                    ],
                },
            },
        },
    },
)
```

```bash cURL highlight={14-24} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "name": "Sarah Bennett"
      },
      "providers": {
        "aws-ses": {
          "override": {
            "attachments": [
              {
                "filename": "hello.txt",
                "contentType": "text/plain",
                "data": "SGk="
              }
            ]
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={11-21} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Sarah Bennett"
    },
    providers: {
      "aws-ses": {
        override: {
          attachments: [
            {
              filename: "hello.txt",
              contentType: "text/plain",
              data: "SGk="
            }
          ]
        }
      }
    }
  }
)
```

```go Go highlight={13-23} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
		Providers: shared.MessageProvidersParam{
			"aws-ses": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"attachments": []any{
						map[string]any{
							"filename": "hello.txt",
							"contentType": "text/plain",
							"data": "SGk=",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={9-17} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett"
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("aws-ses", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "attachments", java.util.List.of(
                        java.util.Map.of(
                            "filename", "hello.txt",
                            "contentType", "text/plain",
                            "data", "SGk="
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={11-21} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => [
      'name' => 'Sarah Bennett',
    ],
    'providers' => [
      'aws-ses' => [
        'override' => [
          'attachments' => [
            [
              'filename' => 'hello.txt',
              'contentType' => 'text/plain',
              'data' => 'SGk=',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={13-31} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "aws-ses",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "attachments": [
                            {
                              "filename": "hello.txt",
                              "contentType": "text/plain",
                              "data": "SGk="
                            }
                          ]
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}' \
  --message.providers '{"aws-ses": {"override": {"attachments": [{"filename": "hello.txt", "contentType": "text/plain", "data": "SGk="}]}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com with an attachment through SES.
```

## Troubleshooting

> Dealing with Amazon SES requests can result in some errors. You can find them below to help you troubleshoot. You can also check the [Courier Logs
> DOC](/docs/monitor/overview) to help debug any provider errors you may encounter. For anything else, you may contact [Courier Support](mailto:support@courier.com).

> **Amazon SES 554 error**
>
> This error occurs due to numerous reasons.
>
> 1. It occurs when you haven't verified the sender email (sender identity) on Amazon SES.
>
> 2. If you're using the Amazon SES in the sandbox environment and haven't verified the recipient's email address, you may encounter this error.
>
> 3. You may encounter this error when you've provided an invalid recipient email address.
>
> ### Solution
>
> You can try the [following](https://docs.aws.amazon.com/ses/latest/dg/troubleshoot-smtp.html) steps mentioned below.
>
> * Open the Amazon SES console and verify that the sender email identity you're using has a verification status of `verified`.
>
> * If you're using the sandbox environment, ensure that you have added the recipient email address as a verified identity on the SES console. It is mandatory to add the recipient emails on Amazon SES when running in the Sandbox environment.
>
> * If both the sender and recipient email addresses are verified, ensure that you have provided the correct recipient email address for the "To" parameter.
>
> * If none of the above works for you, verify that the region specified in your AWS SDK is the same region that contains the verified identities. For example, if the verified identities are located in the Virginia region (us-east-1), you should initialize the Amazon SES instance in the same region.

> **Amazon SES email address is not verified**
>
> This error occurs if you try to send emails using an unverified identity in the region specified.
>
> Additionally, this error occurs when sending emails in the sandbox environment using unverified sender and recipient email identities.
>
> ### Solution
>
> You may try the following to [resolve](https://docs.aws.amazon.com/ses/latest/dg/troubleshoot-error-messages.html) the error.
>
> 1. **Verify the region**
>
> Verify that you're connected to SES in the region where all your verified identities are located.
>
> 1. **Confirm identity verification**
>
> Confirm that the sender's identity has been verified. If you're using the sandbox environment, confirm the verification status of the recipient identities as well.
>
> To do so, visit the SES Console and navigate to your verified identities. The status of the identities should be marked as "Verified" as shown below.
>
> ![](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/amazon-ses-verified-identities.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=f4ec4772f51bc5f438cd0184ef2b716a)
>
> Viewing the verified identities on SES
>
> If the status for your identity is `Unverified` you'll have to verify the identity before sending the email.
>
> 1. **Verify email addresses**
>
> If the identities have been verified, ensure that the email addresses you have provided are correctly spelled.

> **AWS SES timeout**
>
> This error occurs when the client (such as an EC2) can't establish a TCP connection to the public endpoint of Amazon SES.
>
> This usually means the client (EC2) has a firewall blocking outgoing connections on the SMTP ports (25, 587, or 465). It can also mean the client has no internet connection.
>
> ### Solution
>
> To resolve the error, ensure that the client has an active/stable internet connection.
>
> Hereafter, update the firewall rules on the client to allow outgoing connections on ports 25, 587, and 465 (depending on the port you use).

> **AWS SES BCC not working**
>
> This error occurs when the recipient email in the "TO" field is present in the "BCC" field. Certain email providers don't allow the email to contain duplicate recipients.
>
> Additionally, this error may occur if the email address in the "BCC" field doesn't exist.
>
> ### Solution
>
> To resolve the error, ensure that the recipient's email address isn't the same as the `BCC` email address.
>
> If the email addresses in the `BCC` are unique, verify the validity of the email addresses specified in the "BCC" list.

> **Error: is not authorized to perform ses sendemail**
>
> This error occurs when an AWS service such as a Lambda function isn't authorized to send an email using Amazon SES.
>
> ### Solution
>
> To resolve the error, you'll need to attach a policy to the IAM role to allow the AWS resource to execute the `ses:SendEmail` action.
>
> For example, to let a Lambda function send email with SES, attach an inline policy to the function's IAM role that allows the `ses:SendEmail` action. The inline policy is shown below.
>
> ```json theme={null}
> {
>   "Version": "2012-10-17",
>   "Statement" : [
>      {
>        "Sid": "Inline Policy for SES Send Email",
>        "Effect": "Allow",
>        "Resource" : "*",
>        "Actions":[
>          "ses:SendEmail"
>        ]
>      }
>   ]
> }
> ```
>
> The inline policy shown above will ensure that the AWS service is allowed to execute the `SendEmail` action on an Amazon SES resource and will resolve the permission error.

> **Amazon SES authentication credentials invalid**
>
> This error occurs when the SMTP username and password provided to connect to the SMTP endpoint of Amazon SES are incorrect.
>
> ### Solution
>
> 1. **Verify credentials:** Ensure that the username and password you enter are correct and the same one SES provided.
>
> 2. **Verify the region:** SMTP credentials in Amazon SES differ per region. Therefore, ensure that the credentials used are associated with your region.
>
> 3. **Use SMTP credentials and not console credentials:**
>
> * The SMTP endpoint credentials aren't your AWS credentials. Use the Amazon SES SMTP credentials to reach the Amazon SES SMTP interface.
>
> * You'll have to create an IAM user that can invoke the SES services and generate SMTP credentials for the newly created IAM user. It can be done using the SES console.
>
> * First, navigate to your SES account dashboard. You'll see a section titled - "SMTP Settings." Under this, you should see the output shown below.
>
> ![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/aws-ses-authentication.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=7b92f079a90d5b3799b83f86a88e1cea)
>
> Viewing SES Settings in AWS Console
>
> Click "Create SMTP Credentials." The IAM Console opens and prompts you to create an IAM User with the policies required to invoke SES.
>
> ![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/aws-ses-settings.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=b44ea3959c2533bf682c6214d0f29c42)
>
> Creating the IAM user
>
> Afterward, click "Create." This will create the IAM User, generate the credentials, and display the output below.
>
> ![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/aws-ses-create-iam-user.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=c0f4e4b6d8f41e3a8515577ed3d4b895)
>
> Viewing the SMTP credentials for IAM user
>
> To resolve the error, you can download the generated credentials and provide these values for the SMTP username/password.

> **Amazon SES 530 authentication required**
>
> This error occurs when the SMTP credentials provided to Amazon SES are invalid. This can be the username, password, port, and endpoint. Additionally, this error may occur if you haven't used TLS.
>
> ### Solution
>
> You can try the following to see which one fixes the error.
>
> 1. **Verify credentials:** Ensure that the SMTP username and password you provide are the same credentials you created for the IAM User with permissions to invoke SES.
>
> 2. **Verify the region:** Verify that you connect to SES in the region where all your verified identities are located.
>
> 3. **Verify SMTP configurations:** Visit the SES console and navigate to your account dashboard. In the account dashboard, you should see the SMTP configurations for SES.
>
> ![](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/amazon-ses-smtp-settings.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=db5e958099b26187fb1fbfb7050a9ba5)
>
> SMTP configurations for SES
>
> Cross-check the SMTP configurations shown in the SES console with the endpoint and the port you've provided to ensure that SES has been configured correctly.
>
> 1. **Use the correct port:** Ensure that the port used is port - 587. Some users have experienced issues using the TLS Wrapper port and found that using port 587 (TLS port) fixes the error.

> **AWS SES rate limit**
>
> Amazon SES gives each account a maximum send rate and a daily sending quota. In the sandbox, those are **one message per second** and **200 messages per 24 hours**. Short bursts above the per-second rate go through, but sustained sending above it doesn't.
>
> ### Solution
>
> Set a [send rate limit
> DOC](/docs/integrations/send-rate-limits) on your SES configuration to match your account's maximum send rate. Courier queues sends above it, so you can send to Courier at any rate.
>
> To raise the rate itself, [request production access](https://docs.aws.amazon.com/ses/latest/dg/manage-sending-quotas.html) from AWS. AWS reviews the request and sets a sending rate for your use case. You can ask AWS to raise it later.

> **AWS SES email not received**
>
> This error occurs if the templated email is missing a handlebar parameter. For example, if the email template requires five handlebar parameters and you've specified only four, Amazon SES will send the email and won't display any error. However, the email won't get delivered to the recipient, causing this. It may be possible to debug by viewing the [Courier logs
> DOC](/docs/monitor/overview) for any rendering errors.
>
> ### Solution
>
> To resolve the error, verify that all the required handlebar parameters have been added to the templated email parameters when sending the email.

## Provider details

```text theme={null}
aws-ses
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with Gmail through Courier
Source: https://www.courier.com/docs/integrations/email/gmail

Connect a Gmail account over OAuth, and fix the invalid_grant error when the token expires.

> [!WARNING]
>
> **Gmail is for testing and small internal sends.**\\
>
> Google caps daily sends at 500 on consumer Gmail and 2,000 on Workspace. It may suspend accounts sending bulk email through the API, and OAuth tokens expire. For production use [SendGrid
> DOC](/docs/integrations/email/sendgrid), [AWS SES
> DOC](/docs/integrations/email/aws-ses), or [Postmark
> DOC](/docs/integrations/email/postmark).

## Prerequisites

* [A Gmail or Google Workspace inbox](https://mail.google.com/)

## Setup

When you connect your Gmail account, Courier requests permission to send emails on your behalf. Courier sends nothing until you make a send request using the provider.

### OAuth authorization

Google APIs use OAuth for authentication and authorization. Once you grant permission, Courier requests an access token from the Google Authorization Server and sends the token to the Google Gmail API on your behalf.

To grant permission, sign into the Gmail inbox you want to send from and consent to Courier's requested Gmail scopes.

> [!NOTE]
>
> Gmail always sends as the authorized inbox, so a template's **From** field has no effect here. Set the display name with the integration's **From Name**, or override it per send with `override.body.fromName`. To change the address, authorize a different inbox.

### Updating authorized account

On the [Gmail Integration](https://app.courier.com/integrations/gmail) page, click "Authorize a different Gmail inbox" to send from another account. You must grant permissions again every time you change the account.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

In `override.body` you can set `subject`, `text`, `fromName`, `replyTo`, `cc`, and `bcc`. Each replaces the value Courier rendered. You can also override the request itself with `override.headers`, `override.method`, and `override.url`, and supply a token directly with `override.config.access_token`.

```javascript Node.js highlight={8-16} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      gmail: {
        override: {
          body: {
            subject: "Overridden subject",
            replyTo: "support@acme-corp.com",
            bcc: "archive@acme-corp.com",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-16} theme={null}
response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "gmail": {
                "override": {
                    "body": {
                        "subject": "Overridden subject",
                        "replyTo": "support@acme-corp.com",
                        "bcc": "archive@acme-corp.com",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-19} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "providers": {
        "gmail": {
          "override": {
            "body": {
              "subject": "Overridden subject",
              "replyTo": "support@acme-corp.com",
              "bcc": "archive@acme-corp.com"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-16} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      gmail: {
        override: {
          body: {
            subject: "Overridden subject",
            replyTo: "support@acme-corp.com",
            bcc: "archive@acme-corp.com"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-18} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"gmail": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"subject": "Overridden subject",
						"replyTo": "support@acme-corp.com",
						"bcc": "archive@acme-corp.com",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-12} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("gmail", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "subject", "Overridden subject",
                        "replyTo", "support@acme-corp.com",
                        "bcc", "archive@acme-corp.com"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-16} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'providers' => [
      'gmail' => [
        'override' => [
          'body' => [
            'subject' => 'Overridden subject',
            'replyTo' => 'support@acme-corp.com',
            'bcc' => 'archive@acme-corp.com',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-25} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "gmail",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "subject": "Overridden subject",
                            "replyTo": "support@acme-corp.com",
                            "bcc": "archive@acme-corp.com"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"gmail": {"override": {"body": {"subject": "Overridden subject", "replyTo": "support@acme-corp.com", "bcc": "archive@acme-corp.com"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and override the Gmail subject and reply-to.
```

Courier handles OAuth authorization and token refresh, so you rarely need `override.config.access_token`.

## Troubleshooting

### All Gmail sends failing with "request failed with status code 400"

This error means Courier's stored OAuth refresh token is no longer valid. Google rejected the token refresh with a `400 invalid_grant` response, so all subsequent sends fail as `UNDELIVERABLE`.

**Common causes:**

* The Gmail account password was changed
* A Google Workspace admin revoked Courier's OAuth access
* Google revoked the token due to inactivity or a security review
* The Google Cloud project's OAuth consent screen is in "Testing" mode (tokens expire after 7 days)

**How to confirm:** In Courier, check the message timeline for a Gmail-routed message. If you see `UNDELIVERABLE` with the error `"Request failed with status code 400"` and `willRetry: false`, the refresh token is dead.

**Fix:** Go to **Channels → Gmail** in Courier Studio, click **Update** next to the authorized account, and re-authorize with your Google account. This issues a fresh access token and refresh token, restoring sends immediately.

> [!NOTE]
>
> If the Gmail channel is configured with routing fallback, messages that fail on Gmail will fall through to the next configured channel (e.g., Courier Inbox). Only the Gmail delivery path is affected.

## Provider details

```text theme={null}
gmail
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with MailerSend through Courier
Source: https://www.courier.com/docs/integrations/email/mailersend

Connect MailerSend with an API token and from address, then override fields per send.

## Prerequisites

* [A MailerSend account](https://www.mailersend.com/)
* A verified sending domain in MailerSend

## Setup

**1. Verify your domain**

In MailerSend, open [Domains](https://app.mailersend.com/domains), add your domain, and complete DNS verification.

![](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/mailersend-domains.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=64779cd2f355b73e5acc196bb87669ff)

**2. Generate an API token**

Click "Manage" on your domain and [generate an API token](https://www.mailersend.com/help/managing-api-tokens).

![](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/mailersend-api-tokens.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=f4d58c3b1dd5bf2583deab92ada71d20)

**3. Configure in Courier**

In Courier, open the [MailerSend Integration](https://app.courier.com/integrations/catalog/mailersend) page. Enter your API token and From Address, then click "Save."

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

You can override any field MailerSend's [/v1/email endpoint](https://developers.mailersend.com/api/v1/email.html#send-an-email) supports. Use an override when Courier doesn't support a field yet, or to replace a value Courier generates.

This example swaps the API key and the sender in `config`:

```javascript Node.js highlight={8-15} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      mailersend: {
        override: {
          config: {
            apiKey: "<your override API key>",
            fromAddress: "alternate-sender@yourdomain.com",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-15} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "mailersend": {
                "override": {
                    "config": {
                        "apiKey": "<your override API key>",
                        "fromAddress": "alternate-sender@yourdomain.com",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-18} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "mailersend": {
          "override": {
            "config": {
              "apiKey": "<your override API key>",
              "fromAddress": "alternate-sender@yourdomain.com"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-15} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      mailersend: {
        override: {
          config: {
            apiKey: "<your override API key>",
            fromAddress: "alternate-sender@yourdomain.com"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-17} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"mailersend": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"apiKey": "<your override API key>",
						"fromAddress": "alternate-sender@yourdomain.com",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-11} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("mailersend", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "apiKey", "<your override API key>",
                        "fromAddress", "alternate-sender@yourdomain.com"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-15} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'mailersend' => [
        'override' => [
          'config' => [
            'apiKey' => '<your override API key>',
            'fromAddress' => 'alternate-sender@yourdomain.com',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-24} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "mailersend",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "apiKey": "<your override API key>",
                            "fromAddress": "alternate-sender@yourdomain.com"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"mailersend": {"override": {"config": {"apiKey": "<your override API key>", "fromAddress": "alternate-sender@yourdomain.com"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and set a MailerSend field Courier does not expose.
```

### Attachments

Add an `attachments` array in the override. File content must be base64-encoded.

```javascript Node.js highlight={8-18} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      mailersend: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
            },
          ],
        },
      },
    },
  },
});
```

```python Python highlight={8-18} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "mailersend": {
                "override": {
                    "attachments": [
                        {
                            "filename": "billing.pdf",
                            "contentType": "application/pdf",
                            "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
                        },
                    ],
                },
            },
        },
    },
)
```

```bash cURL highlight={11-21} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "mailersend": {
          "override": {
            "attachments": [
              {
                "filename": "billing.pdf",
                "contentType": "application/pdf",
                "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
              }
            ]
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-18} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      mailersend: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
            }
          ]
        }
      }
    }
  }
)
```

```go Go highlight={10-20} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"mailersend": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"attachments": []any{
						map[string]any{
							"filename": "billing.pdf",
							"contentType": "application/pdf",
							"data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-14} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("mailersend", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "attachments", java.util.List.of(
                        java.util.Map.of(
                            "filename", "billing.pdf",
                            "contentType", "application/pdf",
                            "data", "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-18} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'mailersend' => [
        'override' => [
          'attachments' => [
            [
              'filename' => 'billing.pdf',
              'contentType' => 'application/pdf',
              'data' => 'Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-27} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "mailersend",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "attachments": [
                            {
                              "filename": "billing.pdf",
                              "contentType": "application/pdf",
                              "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                            }
                          ]
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"mailersend": {"override": {"attachments": [{"filename": "billing.pdf", "contentType": "application/pdf", "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"}]}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com with an attachment through MailerSend.
```

## Troubleshooting

> **MailerSend 422 response code**
>
> A [422 error](https://www.mailersend.com/help/how-to-start-sending-emails#rest-api) from MailerSend has several possible causes:
>
> | Error | Cause |
> | - | - |
> | From email must be verified | The domain of the from email address must match the domain that the API token is from. |
> | Must provide HTML/text or template ID | The API request is missing content; provide either an HTML/text body or a template ID. |
> | File type not supported | The attachment isn't a [supported file type](https://developers.mailersend.com/api/v1/email.html#supported-file-types). |
> | Reply-to must be a valid email | The `reply_to` parameter isn't a valid email address. |
> | Email quota reached | The account's quota has been reached. Ensure your account is approved for production sending. |
>
> The most common cause is an unverified sending domain. [Verify your domain with MailerSend](https://www.mailersend.com/help/how-to-verify-and-authenticate-a-sending-domain) before using it with Courier.

## Provider details

```text theme={null}
mailersend
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with Mailgun through Courier
Source: https://www.courier.com/docs/integrations/email/mailgun

Connect Mailgun with an API key and domain, track delivery with webhooks, and override fields.

## Prerequisites

* [A Mailgun account with a verified sending domain](https://www.mailgun.com/)
* Your Mailgun API key and domain name

## Setup

**1. Create a Mailgun API key**

In Mailgun, open [API security](https://app.mailgun.com/settings/api_security) and copy a sending key. Your domain is on the Domains page.

**2. Configure in Courier**

Open the [Mailgun integration](https://app.courier.com/integrations/catalog/mailgun) in Courier, enter your API key, domain, and From Address, then save.

> [!NOTE]
>
> EU-region accounts need the host set to `api.eu.mailgun.net` in a per-send config override. The integration settings have no host field.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

Use the `override` object to change the payload Courier sends to Mailgun’s Messages API. This example adds a Mailgun tag.

```javascript Node.js highlight={8-19} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      mailgun: {
        override: {
          body: {
            "o:tag": "notifications",
          },
          config: {
            apiKey: "<your API Key>",
            domain: "<domain>",
            host: "<host>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-19} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "mailgun": {
                "override": {
                    "body": {
                        "o:tag": "notifications",
                    },
                    "config": {
                        "apiKey": "<your API Key>",
                        "domain": "<domain>",
                        "host": "<host>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-22} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "mailgun": {
          "override": {
            "body": {
              "o:tag": "notifications"
            },
            "config": {
              "apiKey": "<your API Key>",
              "domain": "<domain>",
              "host": "<host>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-19} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      mailgun: {
        override: {
          body: {
            "o:tag": "notifications"
          },
          config: {
            apiKey: "<your API Key>",
            domain: "<domain>",
            host: "<host>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-21} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"mailgun": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"o:tag": "notifications",
					},
					"config": map[string]any{
						"apiKey": "<your API Key>",
						"domain": "<domain>",
						"host": "<host>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-15} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("mailgun", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "o:tag", "notifications"
                    ),
                    "config", java.util.Map.of(
                        "apiKey", "<your API Key>",
                        "domain", "<domain>",
                        "host", "<host>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-19} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'mailgun' => [
        'override' => [
          'body' => [
            'o:tag' => 'notifications',
          ],
          'config' => [
            'apiKey' => '<your API Key>',
            'domain' => '<domain>',
            'host' => '<host>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-28} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "mailgun",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "o:tag": "notifications"
                          },
                          "config": {
                            "apiKey": "<your API Key>",
                            "domain": "<domain>",
                            "host": "<host>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"mailgun": {"override": {"body": {"o:tag": "notifications"}, "config": {"apiKey": "<your API Key>", "domain": "<domain>", "host": "<host>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and add a Mailgun tag.
```

Courier replaces the full request body with the contents of `override`.

Set `fromAddress` and other Mailgun config options under `override.config`.

Refer to the [Mailgun API docs](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/) for supported parameters.

> [!NOTE]
>
> To send through Mailgun’s EU region, set `host` to `api.eu.mailgun.net`:
>
> ```json theme={null}
> "config": {
>   "apiKey": "<your API Key>",
>   "domain": "<domain>",
>   "host": "api.eu.mailgun.net"
> }
> ```

## Attachments

Add an `attachments` array to the override. File content must be base64-encoded.

```javascript Node.js highlight={13-19} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    data: {
      hello: "world",
    },
    providers: {
      mailgun: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
            },
          ],
        },
      },
    },
  },
});
```

```python Python highlight={13-19} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "data": {
            "hello": "world",
        },
        "providers": {
            "mailgun": {
                "override": {
                    "attachments": [
                        {
                            "filename": "billing.pdf",
                            "contentType": "application/pdf",
                            "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
                        },
                    ],
                },
            },
        },
    },
)
```

```bash cURL highlight={16-22} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "data": {
        "hello": "world"
      },
      "providers": {
        "mailgun": {
          "override": {
            "attachments": [
              {
                "filename": "billing.pdf",
                "contentType": "application/pdf",
                "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
              }
            ]
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={13-19} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    data: {
      hello: "world"
    },
    providers: {
      mailgun: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
            }
          ]
        }
      }
    }
  }
)
```

```go Go highlight={15-21} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"hello": "world",
		},
		Providers: shared.MessageProvidersParam{
			"mailgun": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"attachments": []any{
						map[string]any{
							"filename": "billing.pdf",
							"contentType": "application/pdf",
							"data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={10-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "hello", "world"
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("mailgun", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "attachments", java.util.List.of(
                        java.util.Map.of(
                            "filename", "billing.pdf",
                            "contentType", "application/pdf",
                            "data", "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={13-19} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'data' => [
      'hello' => 'world',
    ],
    'providers' => [
      'mailgun' => [
        'override' => [
          'attachments' => [
            [
              'filename' => 'billing.pdf',
              'contentType' => 'application/pdf',
              'data' => 'Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={20-26} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "hello", JsonSerializer.SerializeToElement("world") },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "mailgun",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "attachments": [
                            {
                              "filename": "billing.pdf",
                              "contentType": "application/pdf",
                              "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                            }
                          ]
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"hello": "world"}' \
  --message.providers '{"mailgun": {"override": {"attachments": [{"filename": "billing.pdf", "contentType": "application/pdf", "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"}]}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com with an attachment through Mailgun.
```

## IP allowlisting

Mailgun supports IP allowlists for API access. Courier runs on AWS and doesn’t use fixed outbound IPs.

Subscribe to the [`AmazonIpSpaceChanged`](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html#subscribe-notifications) SNS topic. AWS notifies you whenever its IP ranges change, so you can update your allowlist.

## Delivery tracking

Courier doesn't poll Mailgun unless you turn on **Enable polling for status updates** in the integration settings. Without polling or a webhook, messages stay at `SENT` instead of advancing to `DELIVERED`. Webhooks are better, because Mailgun reports status to Courier in real time.

**1. Copy the Courier webhook URL**

In Courier, go to the [Mailgun configuration page](https://app.courier.com/integrations/catalog/mailgun). Copy the generated Webhook URL.

![](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/mailgun-webhook.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=f4f8f9638f1c1004e26b38ae275d0ce7)

**2. Configure webhooks in Mailgun**

In Mailgun, go to **Sending → Webhooks**.\
Add a webhook for **Delivered Messages** and paste the URL.\
Repeat for **Permanent Failure**.

![](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/mailgun-ui.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=5dbd7fe8d6adb1c1c8b0fb6092096853)

![](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/mailgun-form.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=a3a810891716c6f9b7cbf28eb78be46d)

**3. Match the domain**

In Mailgun, make sure the selected domain matches the one in Courier.

**4. Disable polling (optional)**

Wait \~1 hour so in-flight updates land. Then switch off **Enable polling for status updates** in Courier and click **Save**.

## Troubleshooting

> **550 error, missing MX record**
>
> Mailgun returns a 550 error when the sending domain has no MX record.
>
> **Fix:**\
> Add an MX record to your domain’s DNS. Wait \~2 hours for propagation.

> **Account throttling or probation**
>
> Mailgun may throttle or suspend delivery for accounts with high bounce or spam rates, or with traffic spikes.
>
> **Fix:**
>
> 1. Complete Mailgun’s Business Verification.
> 2. Remove addresses that bounce consistently. Avoid bulk sends to unverified users.

## Provider details

```text theme={null}
mailgun
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with Mailjet through Courier
Source: https://www.courier.com/docs/integrations/email/mailjet

Connect Mailjet with an API key and secret, then override attachments and API fields per send.

## Prerequisites

* [A Mailjet account](https://www.mailjet.com/)
* [Your Mailjet Public Key and Private Key](https://app.mailjet.com/account/apikeys)

## Setup

**1. Get your Mailjet API keys**

In Mailjet, open [API key management](https://app.mailjet.com/account/apikeys) and copy the API key and secret key.

**2. Configure in Courier**

Open the [Mailjet integration](https://app.courier.com/integrations/catalog/mailjet) in Courier, enter both keys and your From Address, then save.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

Use a provider override to change what Courier sends to Mailjet's Send API. This example adds an attachment.

```javascript Node.js highlight={8-20} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      mailjet: {
        override: {
          body: {
            Attachments: [
              {
                ContentType: "text/plain",
                Filename: "test.txt",
                content: "VGhpcyBpcyB5b3VyIGF0dGFjaGVkIGZpbGUhISEK",
              },
            ],
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-20} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "mailjet": {
                "override": {
                    "body": {
                        "Attachments": [
                            {
                                "ContentType": "text/plain",
                                "Filename": "test.txt",
                                "content": "VGhpcyBpcyB5b3VyIGF0dGFjaGVkIGZpbGUhISEK",
                            },
                        ],
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-23} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "mailjet": {
          "override": {
            "body": {
              "Attachments": [
                {
                  "ContentType": "text/plain",
                  "Filename": "test.txt",
                  "content": "VGhpcyBpcyB5b3VyIGF0dGFjaGVkIGZpbGUhISEK"
                }
              ]
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-20} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      mailjet: {
        override: {
          body: {
            Attachments: [
              {
                ContentType: "text/plain",
                Filename: "test.txt",
                content: "VGhpcyBpcyB5b3VyIGF0dGFjaGVkIGZpbGUhISEK"
              }
            ]
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-22} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"mailjet": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"Attachments": []any{
							map[string]any{
								"ContentType": "text/plain",
								"Filename": "test.txt",
								"content": "VGhpcyBpcyB5b3VyIGF0dGFjaGVkIGZpbGUhISEK",
							},
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("mailjet", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "Attachments", java.util.List.of(
                            java.util.Map.of(
                                "ContentType", "text/plain",
                                "Filename", "test.txt",
                                "content", "VGhpcyBpcyB5b3VyIGF0dGFjaGVkIGZpbGUhISEK"
                            )
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-20} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'mailjet' => [
        'override' => [
          'body' => [
            'Attachments' => [
              [
                'ContentType' => 'text/plain',
                'Filename' => 'test.txt',
                'content' => 'VGhpcyBpcyB5b3VyIGF0dGFjaGVkIGZpbGUhISEK',
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-29} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "mailjet",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "Attachments": [
                              {
                                "ContentType": "text/plain",
                                "Filename": "test.txt",
                                "content": "VGhpcyBpcyB5b3VyIGF0dGFjaGVkIGZpbGUhISEK"
                              }
                            ]
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"mailjet": {"override": {"body": {"Attachments": [{"ContentType": "text/plain", "Filename": "test.txt", "content": "VGhpcyBpcyB5b3VyIGF0dGFjaGVkIGZpbGUhISEK"}]}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com with an attachment through Mailjet.
```

Overrides are deep-merged into the request. Fields you set replace their counterparts, and everything you leave out is still sent. Mailjet's full field list is in the [Mailjet Send API docs](https://dev.mailjet.com/email/guides/send-api-V3/).

## Provider details

```text theme={null}
mailjet
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with Mandrill through Courier
Source: https://www.courier.com/docs/integrations/email/mandrill

Connect Mandrill with an API key, import Mandrill templates, and override fields per send.

## Prerequisites

* [A Mailchimp Transactional (Mandrill) account](https://mandrillapp.com/)
* A Mandrill API key

## Setup

**1. Create a Mandrill API key**

In Mailchimp Transactional, follow [the quick start](https://mailchimp.com/developer/transactional/guides/quick-start/) to create an API key.

**2. Configure in Courier**

Open the [Mandrill integration](https://app.courier.com/integrations/catalog/mandrill) in Courier, enter your API key, From Address, and From Name, then save.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

Use a provider override to change what Courier sends to Mandrill's Messages API. This example adds an attachment.

```javascript Node.js highlight={8-25} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      mandrill: {
        override: {
          body: {
            message: {
              from_email: "support@acme-corp.com",
              subject: "Hi there",
              from_name: "Rod",
              attachments: [
                {
                  type: "text/plain",
                  name: "myfile.txt",
                  content: "ZXhhbXBsZSBmaWxl",
                },
              ],
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-25} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "mandrill": {
                "override": {
                    "body": {
                        "message": {
                            "from_email": "support@acme-corp.com",
                            "subject": "Hi there",
                            "from_name": "Rod",
                            "attachments": [
                                {
                                    "type": "text/plain",
                                    "name": "myfile.txt",
                                    "content": "ZXhhbXBsZSBmaWxl",
                                },
                            ],
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-28} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "mandrill": {
          "override": {
            "body": {
              "message": {
                "from_email": "support@acme-corp.com",
                "subject": "Hi there",
                "from_name": "Rod",
                "attachments": [
                  {
                    "type": "text/plain",
                    "name": "myfile.txt",
                    "content": "ZXhhbXBsZSBmaWxl"
                  }
                ]
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-25} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      mandrill: {
        override: {
          body: {
            message: {
              from_email: "support@acme-corp.com",
              subject: "Hi there",
              from_name: "Rod",
              attachments: [
                {
                  type: "text/plain",
                  name: "myfile.txt",
                  content: "ZXhhbXBsZSBmaWxl"
                }
              ]
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-27} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"mandrill": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"message": map[string]any{
							"from_email": "support@acme-corp.com",
							"subject": "Hi there",
							"from_name": "Rod",
							"attachments": []any{
								map[string]any{
									"type": "text/plain",
									"name": "myfile.txt",
									"content": "ZXhhbXBsZSBmaWxl",
								},
							},
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-21} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("mandrill", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "message", java.util.Map.of(
                            "from_email", "support@acme-corp.com",
                            "subject", "Hi there",
                            "from_name", "Rod",
                            "attachments", java.util.List.of(
                                java.util.Map.of(
                                    "type", "text/plain",
                                    "name", "myfile.txt",
                                    "content", "ZXhhbXBsZSBmaWxl"
                                )
                            )
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-25} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'mandrill' => [
        'override' => [
          'body' => [
            'message' => [
              'from_email' => 'support@acme-corp.com',
              'subject' => 'Hi there',
              'from_name' => 'Rod',
              'attachments' => [
                [
                  'type' => 'text/plain',
                  'name' => 'myfile.txt',
                  'content' => 'ZXhhbXBsZSBmaWxl',
                ],
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-34} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "mandrill",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "message": {
                              "from_email": "support@acme-corp.com",
                              "subject": "Hi there",
                              "from_name": "Rod",
                              "attachments": [
                                {
                                  "type": "text/plain",
                                  "name": "myfile.txt",
                                  "content": "ZXhhbXBsZSBmaWxl"
                                }
                              ]
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"mandrill": {"override": {"body": {"message": {"from_email": "support@acme-corp.com", "subject": "Hi there", "from_name": "Rod", "attachments": [{"type": "text/plain", "name": "myfile.txt", "content": "ZXhhbXBsZSBmaWxl"}]}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com with an attachment through Mandrill.
```

Overrides are deep-merged into the request. Fields you set replace their counterparts, and everything you leave out is still sent. See the full field list in the [Mandrill Messages API docs](https://mandrillapp.com/api/docs/messages.JSON.html).

## Template import

Import your Mandrill templates from the [Mandrill configuration page](https://app.courier.com/integrations/catalog/mandrill).

> [!NOTE]
>
> Enter your Mandrill credentials on the configuration page to load your saved templates.

Templates ready for import appear as checkboxes.

![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/template-import.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=1e8c8f189a398d3ed6b692cf1c180e20)

Template import page

## Troubleshooting

> Check the [Courier Logs
> DOC](/docs/monitor/overview) to debug provider errors. For anything else, contact [Courier Support](mailto:support@courier.com).

### Mandrill click tracking not working

Three likely causes:

* Click tracking is off.
* The URL is too long, so Mandrill disabled click tracking.
* The clicks are recorded but not updated in real time.

**Solution**

Check whether click tracking is enabled:

**1. Log into Mandrill**

Log in to your Mandrill account.

**2. Open Sending defaults**

Go to Settings, then Sending defaults.

**3. Check the Track Clicks setting**

Set the "Track Clicks" dropdown to anything other than "No click tracking".

Mandrill tracks opens and clicks in real time, but status updates can lag. Delays run from a few minutes to much longer, such as when their system is under load. [Courier has its own link tracking
DOC](/docs/monitor/tracking) for clicks on your Templates.

### Mandrill BCC not working

Mandrill is ignoring the BCC headers.

**Solution**

1. Use the `to` field rather than the `bcc` field, and set `X-MC-PreserveRecipients` to `false`.
2. Or put the BCC address in the `to` field with its `type` set to `bcc`. Add `preserve_recipients: true` under the message section, as below.

```json theme={null}
{
   "to":[
      {
         "email":"sarah@acme-corp.com",
         "name":"Sarah Bennett",
         "type":"to"
      },
      {
         "email":"archive@acme-corp.com",
         "name":"Archive",
         "type":"bcc"
      },
      {
         "email":"ops@acme-corp.com",
         "name":"Ops",
         "type":"bcc"
      }
   ]
}
```

For more on X-MC-PreserveRecipients, see [Mailchimp's SMTP headers documentation](https://mailchimp.com/developer/transactional/docs/smtp-integration/#customize-messages-with-smtp-headers)

### Mandrill CC emails not present

Pass CC fields to Mandrill's API [through the designer
DOC](/docs/send/overrides) or through an API override.

As with BCC, set `preserve_recipients` to `true` in the override request. Without it, **CC emails won't be sent**.

**Solution**

```json theme={null}
{
  // ... rest of message definition
   "providers":{
      "mandrill":{
         "override":{
            "body":{
               "message":{
                  "preserve_recipients":true, //This setting must be set to true when passing CC recipients.
                  "attachments":[
                     {
                        "name":"Top Secret",
                        "content":"ZXhhbXBsZSBmaWxl",
                        "type":"application/pdf"
                     }
                  ]
               }
            }
         }
      }
   }
}
```

### Mandrill merge vars not working

Merge variables usually fail because of how they are nested.

**Solution**

Nest the variables inside the `message` struct, as below.

```javascript theme={null}
var message = {
    to: "sarah@acme-corp.com",
    mandrillOptions: {
        template_name: 'template1',
        template_content: [
        ],
        message: {
            "merge": true,
            "merge_language": "handlebars",
            "global_merge_vars": [{
                    "name": "fname",
                    "content": "Sample"
                },
                {
                    "name": "email",
                    "content": "sarah@acme-corp.com"
                }
            ]
        }
    }
};
```

## Provider details

```text theme={null}
mandrill
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with OneSignal through Courier
Source: https://www.courier.com/docs/integrations/email/onesignal-email

Connect OneSignal email with an App ID and REST API key, then override fields per send.

## Prerequisites

* [A OneSignal account](https://onesignal.com/)
* [Your OneSignal App ID and REST API Key](https://documentation.onesignal.com/docs/accounts-and-keys)

## Setup

**1. Get your OneSignal keys**

In OneSignal, open [accounts and keys](https://documentation.onesignal.com/docs/accounts-and-keys) and copy your App ID and REST API Key.

**2. Configure in Courier**

Open the [OneSignal Email integration](https://app.courier.com/integrations/catalog/onesignal-email) in Courier, enter both values, then save.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. OneSignal Email reads neither, and it doesn't support attachments.

## Provider details

```text theme={null}
onesignal-email
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Email providers
Source: https://www.courier.com/docs/integrations/email/overview

Every email provider Courier supports, what a send needs on the profile, and channel overrides.

## Available providers

> **[Amazon SES](/docs/integrations/email/aws-ses)**

> **[SendGrid](/docs/integrations/email/sendgrid)**

> **[Postmark](/docs/integrations/email/postmark)**

> **[Mailgun](/docs/integrations/email/mailgun)**

> **[Resend](/docs/integrations/email/resend)**

> **[SMTP](/docs/integrations/email/smtp)**

> **[Mandrill](/docs/integrations/email/mandrill)**

> **[SparkPost](/docs/integrations/email/sparkpost)**

> **[Mailjet](/docs/integrations/email/mailjet)**

> **[MailerSend](/docs/integrations/email/mailersend)**

> **[Amply](/docs/integrations/email/amply)**

> **[Gmail](/docs/integrations/email/gmail)**

> **[OneSignal](/docs/integrations/email/onesignal-email)**

[SMTP
DOC](/docs/integrations/email/smtp) is the generic relay for any server that speaks it.

[Gmail
DOC](/docs/integrations/email/gmail) is OAuth-based and suits testing rather than volume.

## Profile requirements

Every email provider addresses the recipient the same way, by email address, so the profile you send to needs an `email`. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    email: 'sarah@acme-corp.com',
  },
});
```

```python Python highlight={4} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "email": "sarah@acme-corp.com",
    },
)
```

```bash cURL highlight={7} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "email": "sarah@acme-corp.com"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    email: "sarah@acme-corp.com"
  }
)
```

```go Go highlight={6} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"email": "sarah@acme-corp.com",
		},
	},
)
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'email' => 'sarah@acme-corp.com',
]);
```

```csharp C# highlight={6} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
    },
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"email":"sarah@acme-corp.com"}'
```

```text MCP theme={null}
With Courier MCP, create a profile for user_123 with the email sarah@acme-corp.com.
```

A provider that also accepts an inline address still reads `email` off the profile when you send to a `user_id`, which is what lets preferences apply and lets the address change without touching your send code.

## Send to a recipient

**Send to user id**

Courier reads `email` off the saved profile, so preferences apply and the address can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to email**

A one-off to an address you aren't storing. No profile is created, so no preference applies.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com by email.
```

## Channel overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. These are the fields an email channel override accepts.

The sender is the field most often overridden. With no override and no template **From**, an email goes out as the **From Address** on the provider's integration. [Send from your own domain
GUIDE](/docs/guides/send-from-your-domain) covers all three levels. Postmark, Amply, and MailerSend also accept a sender inside a provider override at `override.config.fromAddress`. On MailerSend that value beats a channel override, and on the other two the channel override still wins.

### Available channel override fields

Every field you can set in `message.channels.email.override`. All are optional.

| Field | Type | Description |
| - | - | - |
| `subject` | string | Overrides the email subject line. |
| `from` | string | Sender address. Accepts a plain email or `"Display Name <email>"` format. |
| `reply_to` | string | Sets the Reply-To header. Same format as `from`. |
| `cc` | string | CC recipients as a comma-separated string (e.g. `"sarah@acme-corp.com,ops@acme-corp.com"`). |
| `bcc` | string | BCC recipients as a comma-separated string. Courier converts this to an array for providers that require it. |
| `html` | string | Replaces the rendered HTML body entirely. |
| `text` | string | Replaces the plain-text body. |
| `attachments` | array | File attachments. Schema varies by provider. See the provider page. |
| `brand` | object | Overrides brand settings (logo, colors). Uses the same schema as [Create a new Brand](/docs/api-reference/brands/create-a-new-brand). |
| `tracking` | object | Controls tracking behavior. Set `{ "open": false }` to disable open tracking. |

Set any of them under `channels.email.override` on the send. The table above is the full list:

```javascript Node.js highlight={7-10} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: { email: 'sarah@acme-corp.com' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    channels: {
      email: {
        override: {
          subject: 'Your order has shipped',
          reply_to: 'support@acme-corp.com',
        },
      },
    },
  },
});
```

```python Python highlight={7-10} theme={null}
response = client.send.message(
    message={
        "to": {"email": "sarah@acme-corp.com"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "channels": {
            "email": {
                "override": {
                    "subject": "Your order has shipped",
                    "reply_to": "support@acme-corp.com",
                },
            },
        },
    },
)
```

```bash cURL highlight={10-13} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "email": "sarah@acme-corp.com" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "channels": {
        "email": {
          "override": {
            "subject": "Your order has shipped",
            "reply_to": "support@acme-corp.com"
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={7-10} theme={null}
response = courier.send_.message(
  message: {
    to: { email: "sarah@acme-corp.com" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    channels: {
      email: {
        override: {
          subject: "Your order has shipped",
          reply_to: "support@acme-corp.com"
        }
      }
    }
  }
)
```

```go Go highlight={11-14} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Channels: shared.MessageChannelsParam{
			"email": shared.ChannelParam{
				Override: map[string]any{
					"subject":  "Your order has shipped",
					"reply_to": "support@acme-corp.com",
				},
			},
		},
	},
})
```

```java Java highlight={7-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .channels(MessageChannels.builder()
            .putAdditionalProperty("email", JsonValue.from(java.util.Map.of(
                "override", java.util.Map.of(
                    "subject", "Your order has shipped",
                    "reply_to", "support@acme-corp.com"))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={7-10} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['email' => 'sarah@acme-corp.com'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'channels' => [
      'email' => [
        'override' => [
          'subject' => 'Your order has shipped',
          'reply_to' => 'support@acme-corp.com',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={13-17} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Channels = new Dictionary<string, Channel>()
        {
            {
                "email",
                new()
                {
                    Override = new Dictionary<string, JsonElement>()
                    {
                        { "subject", JsonSerializer.SerializeToElement("Your order has shipped") },
                        { "reply_to", JsonSerializer.SerializeToElement("support@acme-corp.com") },
                    },
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.channels '{"email":{"override":{"subject":"Your order has shipped","reply_to":"support@acme-corp.com"}}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to sarah@acme-corp.com and override the email subject to "Your order has shipped".
```

## Brand override

The `channels.email.override.brand` property uses the same schema as the [Create a new Brand](/docs/api-reference/brands/create-a-new-brand) request payload.

You can override:

* logo
* top bar color
* brand colors

**Example:**

```json theme={null}
{
  "message": {
    // ...rest of request
    "channels": {
      "email": {
        "override": {
          "brand": {
            "settings": {
              "email": {
                "header": {
                  "logo": {
                    "image": "https://www.courier.com/logo.png",
                    "href": "https://www.courier.com"
                  },
                  "barColor": "#674ea7"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Allowlist for AWS IP addresses

Some providers, such as Mailgun, let you [allowlist the IP addresses](https://help.mailgun.com/hc/en-us/articles/360012244474-IP-Allowlist) that reach their API. Courier runs on AWS and doesn't publish an IP range to allowlist.

Instead, subscribe to the `AmazonIpSpaceChanged` topic to get notified when AWS IP ranges change. See the [AWS documentation](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html#subscribe-notifications).


# Send email with Postmark through Courier
Source: https://www.courier.com/docs/integrations/email/postmark

Connect Postmark with a server token, then override MessageStream, attachments, and templates.

## Prerequisites

* [A Postmark account with a verified sender signature](https://postmarkapp.com/)
* Your Postmark Server API Token

## Setup

**1. Get your Postmark server token**

In Postmark, open the server you send from and copy its [Server API token](https://postmarkapp.com/support/article/1008-what-are-the-account-and-server-api-tokens).

**2. Configure in Courier**

Open the [Postmark integration](https://app.courier.com/integrations/catalog/postmark) in Courier, enter your API token and From Address, then save.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Subject character limit

> [!NOTE]
>
> The Postmark API limits subject lines to \~60 characters. Emojis and special characters lower that limit because of encoding.

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

A provider override changes what Courier sends to Postmark's Email API. This example adds a [MessageStream](https://postmarkapp.com/support/article/1207-how-to-create-and-send-through-message-streams) and an attachment:

```javascript Node.js highlight={8-23} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      postmark: {
        override: {
          config: {
            MessageStream: "message_stream_id",
          },
          body: {
            Attachments: [
              {
                Name: "readme.txt",
                Content: "dGVzdCBjb250ZW50",
                ContentType: "text/plain",
              },
            ],
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-23} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "postmark": {
                "override": {
                    "config": {
                        "MessageStream": "message_stream_id",
                    },
                    "body": {
                        "Attachments": [
                            {
                                "Name": "readme.txt",
                                "Content": "dGVzdCBjb250ZW50",
                                "ContentType": "text/plain",
                            },
                        ],
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-26} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "postmark": {
          "override": {
            "config": {
              "MessageStream": "message_stream_id"
            },
            "body": {
              "Attachments": [
                {
                  "Name": "readme.txt",
                  "Content": "dGVzdCBjb250ZW50",
                  "ContentType": "text/plain"
                }
              ]
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-23} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      postmark: {
        override: {
          config: {
            MessageStream: "message_stream_id"
          },
          body: {
            Attachments: [
              {
                Name: "readme.txt",
                Content: "dGVzdCBjb250ZW50",
                ContentType: "text/plain"
              }
            ]
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-25} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"postmark": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"MessageStream": "message_stream_id",
					},
					"body": map[string]any{
						"Attachments": []any{
							map[string]any{
								"Name": "readme.txt",
								"Content": "dGVzdCBjb250ZW50",
								"ContentType": "text/plain",
							},
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-19} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("postmark", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "MessageStream", "message_stream_id"
                    ),
                    "body", java.util.Map.of(
                        "Attachments", java.util.List.of(
                            java.util.Map.of(
                                "Name", "readme.txt",
                                "Content", "dGVzdCBjb250ZW50",
                                "ContentType", "text/plain"
                            )
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-23} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'postmark' => [
        'override' => [
          'config' => [
            'MessageStream' => 'message_stream_id',
          ],
          'body' => [
            'Attachments' => [
              [
                'Name' => 'readme.txt',
                'Content' => 'dGVzdCBjb250ZW50',
                'ContentType' => 'text/plain',
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-32} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "postmark",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "MessageStream": "message_stream_id"
                          },
                          "body": {
                            "Attachments": [
                              {
                                "Name": "readme.txt",
                                "Content": "dGVzdCBjb250ZW50",
                                "ContentType": "text/plain"
                              }
                            ]
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"postmark": {"override": {"config": {"MessageStream": "message_stream_id"}, "body": {"Attachments": [{"Name": "readme.txt", "Content": "dGVzdCBjb250ZW50", "ContentType": "text/plain"}]}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com on my Postmark broadcast message stream.
```

Overrides are deep-merged into the request. Fields you set replace their counterparts, and everything you leave out is still sent. For every option, see the [Postmark API docs](https://postmarkapp.com/developer/api/email-api).

`override.config.fromAddress` swaps the sender for one message, in place of the From Address saved on the integration. A template **From** value or a `channels.email.override.from` still wins over it. [Send from your own domain
GUIDE](/docs/guides/send-from-your-domain) covers the order.

## Using Postmark templates

```javascript Node.js highlight={9-33} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      postmark: {
        override: {
          config: {
            url: "https://api.postmarkapp.com/email/withTemplate",
          },
          body: {
            TemplateId: "123456",
            TemplateModel: {
              product_url: "product_url_Value",
              product_name: "product_name_Value",
              name: "name_Value",
              action_url: "action_url_Value",
              login_url: "login_url_Value",
              username: "username_Value",
              trial_length: "trial_length_Value",
              trial_start_date: "trial_start_date_Value",
              trial_end_date: "trial_end_date_Value",
              support_email: "support_email_Value",
              live_chat_url: "live_chat_url_Value",
              sender_name: "sender_name_Value",
              help_url: "help_url_Value",
              company_name: "company_name_Value",
              company_address: "company_address_Value",
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={9-33} theme={null}
response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "postmark": {
                "override": {
                    "config": {
                        "url": "https://api.postmarkapp.com/email/withTemplate",
                    },
                    "body": {
                        "TemplateId": "123456",
                        "TemplateModel": {
                            "product_url": "product_url_Value",
                            "product_name": "product_name_Value",
                            "name": "name_Value",
                            "action_url": "action_url_Value",
                            "login_url": "login_url_Value",
                            "username": "username_Value",
                            "trial_length": "trial_length_Value",
                            "trial_start_date": "trial_start_date_Value",
                            "trial_end_date": "trial_end_date_Value",
                            "support_email": "support_email_Value",
                            "live_chat_url": "live_chat_url_Value",
                            "sender_name": "sender_name_Value",
                            "help_url": "help_url_Value",
                            "company_name": "company_name_Value",
                            "company_address": "company_address_Value",
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={12-36} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "providers": {
        "postmark": {
          "override": {
            "config": {
              "url": "https://api.postmarkapp.com/email/withTemplate"
            },
            "body": {
              "TemplateId": "123456",
              "TemplateModel": {
                "product_url": "product_url_Value",
                "product_name": "product_name_Value",
                "name": "name_Value",
                "action_url": "action_url_Value",
                "login_url": "login_url_Value",
                "username": "username_Value",
                "trial_length": "trial_length_Value",
                "trial_start_date": "trial_start_date_Value",
                "trial_end_date": "trial_end_date_Value",
                "support_email": "support_email_Value",
                "live_chat_url": "live_chat_url_Value",
                "sender_name": "sender_name_Value",
                "help_url": "help_url_Value",
                "company_name": "company_name_Value",
                "company_address": "company_address_Value"
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={9-33} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      postmark: {
        override: {
          config: {
            url: "https://api.postmarkapp.com/email/withTemplate"
          },
          body: {
            TemplateId: "123456",
            TemplateModel: {
              product_url: "product_url_Value",
              product_name: "product_name_Value",
              name: "name_Value",
              action_url: "action_url_Value",
              login_url: "login_url_Value",
              username: "username_Value",
              trial_length: "trial_length_Value",
              trial_start_date: "trial_start_date_Value",
              trial_end_date: "trial_end_date_Value",
              support_email: "support_email_Value",
              live_chat_url: "live_chat_url_Value",
              sender_name: "sender_name_Value",
              help_url: "help_url_Value",
              company_name: "company_name_Value",
              company_address: "company_address_Value"
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={11-35} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"postmark": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"url": "https://api.postmarkapp.com/email/withTemplate",
					},
					"body": map[string]any{
						"TemplateId": "123456",
						"TemplateModel": map[string]any{
							"product_url": "product_url_Value",
							"product_name": "product_name_Value",
							"name": "name_Value",
							"action_url": "action_url_Value",
							"login_url": "login_url_Value",
							"username": "username_Value",
							"trial_length": "trial_length_Value",
							"trial_start_date": "trial_start_date_Value",
							"trial_end_date": "trial_end_date_Value",
							"support_email": "support_email_Value",
							"live_chat_url": "live_chat_url_Value",
							"sender_name": "sender_name_Value",
							"help_url": "help_url_Value",
							"company_name": "company_name_Value",
							"company_address": "company_address_Value",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-30} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("postmark", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "url", "https://api.postmarkapp.com/email/withTemplate"
                    ),
                    "body", java.util.Map.of(
                        "TemplateId", "123456",
                        "TemplateModel", java.util.Map.of(
                            "product_url", "product_url_Value",
                            "product_name", "product_name_Value",
                            "name", "name_Value",
                            "action_url", "action_url_Value",
                            "login_url", "login_url_Value",
                            "username", "username_Value",
                            "trial_length", "trial_length_Value",
                            "trial_start_date", "trial_start_date_Value",
                            "trial_end_date", "trial_end_date_Value",
                            "support_email", "support_email_Value",
                            "live_chat_url", "live_chat_url_Value",
                            "sender_name", "sender_name_Value",
                            "help_url", "help_url_Value",
                            "company_name", "company_name_Value",
                            "company_address", "company_address_Value"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-33} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'providers' => [
      'postmark' => [
        'override' => [
          'config' => [
            'url' => 'https://api.postmarkapp.com/email/withTemplate',
          ],
          'body' => [
            'TemplateId' => '123456',
            'TemplateModel' => [
              'product_url' => 'product_url_Value',
              'product_name' => 'product_name_Value',
              'name' => 'name_Value',
              'action_url' => 'action_url_Value',
              'login_url' => 'login_url_Value',
              'username' => 'username_Value',
              'trial_length' => 'trial_length_Value',
              'trial_start_date' => 'trial_start_date_Value',
              'trial_end_date' => 'trial_end_date_Value',
              'support_email' => 'support_email_Value',
              'live_chat_url' => 'live_chat_url_Value',
              'sender_name' => 'sender_name_Value',
              'help_url' => 'help_url_Value',
              'company_name' => 'company_name_Value',
              'company_address' => 'company_address_Value',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={13-41} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "postmark",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "url": "https://api.postmarkapp.com/email/withTemplate"
                          },
                          "body": {
                            "TemplateId": "123456",
                            "TemplateModel": {
                              "product_url": "product_url_Value",
                              "product_name": "product_name_Value",
                              "name": "name_Value",
                              "action_url": "action_url_Value",
                              "login_url": "login_url_Value",
                              "username": "username_Value",
                              "trial_length": "trial_length_Value",
                              "trial_start_date": "trial_start_date_Value",
                              "trial_end_date": "trial_end_date_Value",
                              "support_email": "support_email_Value",
                              "live_chat_url": "live_chat_url_Value",
                              "sender_name": "sender_name_Value",
                              "help_url": "help_url_Value",
                              "company_name": "company_name_Value",
                              "company_address": "company_address_Value"
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"postmark": {"override": {"config": {"url": "https://api.postmarkapp.com/email/withTemplate"}, "body": {"TemplateId": "123456", "TemplateModel": {"product_url": "product_url_Value", "product_name": "product_name_Value", "name": "name_Value", "action_url": "action_url_Value", "login_url": "login_url_Value", "username": "username_Value", "trial_length": "trial_length_Value", "trial_start_date": "trial_start_date_Value", "trial_end_date": "trial_end_date_Value", "support_email": "support_email_Value", "live_chat_url": "live_chat_url_Value", "sender_name": "sender_name_Value", "help_url": "help_url_Value", "company_name": "company_name_Value", "company_address": "company_address_Value"}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and render it with a Postmark template.
```

The `message.providers.postmark.override.config` property replaces Courier templates with Postmark's [Templates API](https://postmarkapp.com/developer/api/templates-api).

Include the `https://api.postmarkapp.com/email/withTemplate` URL in the config object, and `TemplateId` and `TemplateModel` in the body.

> [!WARNING]
>
> With Postmark templates, your request must use a `template` parameter, not `content`. Otherwise `content` takes precedence over the Postmark override. An invalid `template_id` causes an error.

## Provider details

```text theme={null}
postmark
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with Resend through Courier
Source: https://www.courier.com/docs/integrations/email/resend

Connect Resend with an API key and from address, then override sender fields per send.

## Prerequisites

* [A Courier account](https://app.courier.com/signup)
* [A Resend account](https://resend.com/signup)

## Setup

**1. Create a Resend API Key**

In Resend, open [API Keys](https://resend.com/api-keys). Create an API key and copy it.

**2. Configure in Courier**

In Courier, open the [Resend Integration](https://app.courier.com/integrations/catalog/resend) page. Paste your API key into the "API Key" field.

**3. Set From Address**

Add a verified email address to the "From Address" field (e.g., `noreply@yourdomain.com`). Click "Add Integration" then "Save."

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

A provider override changes what Courier sends to Resend's [/emails endpoint](https://resend.com/docs/api-reference/emails/send-email). Use one to set a field Courier doesn't support yet, or to replace a value Courier generates.

For example, add Resend tags:

```javascript Node.js highlight={8-19} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      resend: {
        override: {
          body: {
            tags: [
              {
                name: "environment",
                value: "development",
              },
            ],
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-19} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "resend": {
                "override": {
                    "body": {
                        "tags": [
                            {
                                "name": "environment",
                                "value": "development",
                            },
                        ],
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-22} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "resend": {
          "override": {
            "body": {
              "tags": [
                {
                  "name": "environment",
                  "value": "development"
                }
              ]
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-19} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      resend: {
        override: {
          body: {
            tags: [
              {
                name: "environment",
                value: "development"
              }
            ]
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-21} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"resend": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"tags": []any{
							map[string]any{
								"name": "environment",
								"value": "development",
							},
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-15} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("resend", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "tags", java.util.List.of(
                            java.util.Map.of(
                                "name", "environment",
                                "value", "development"
                            )
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-19} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'resend' => [
        'override' => [
          'body' => [
            'tags' => [
              [
                'name' => 'environment',
                'value' => 'development',
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-28} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "resend",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "tags": [
                              {
                                "name": "environment",
                                "value": "development"
                              }
                            ]
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"resend": {"override": {"body": {"tags": [{"name": "environment", "value": "development"}]}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and set a Resend field Courier does not expose.
```

Courier merges everything inside `message.providers.resend.override.body` into its generated request body. You can also override config values:

```json theme={null}
{
  "message": {
    "providers": {
      "resend": {
        "override": {
          "config": {
            "apiKey": "<your override API key>",
            "fromAddress": "alternate-sender@yourdomain.com"
          }
        }
      }
    }
  }
}
```

### Attachments

To include an attachment, add an `attachments` array in the override. File content must be base64-encoded.

```javascript Node.js highlight={8-18} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      resend: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
            },
          ],
        },
      },
    },
  },
});
```

```python Python highlight={8-18} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "resend": {
                "override": {
                    "attachments": [
                        {
                            "filename": "billing.pdf",
                            "contentType": "application/pdf",
                            "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
                        },
                    ],
                },
            },
        },
    },
)
```

```bash cURL highlight={11-21} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "resend": {
          "override": {
            "attachments": [
              {
                "filename": "billing.pdf",
                "contentType": "application/pdf",
                "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
              }
            ]
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-18} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      resend: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
            }
          ]
        }
      }
    }
  }
)
```

```go Go highlight={10-20} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"resend": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"attachments": []any{
						map[string]any{
							"filename": "billing.pdf",
							"contentType": "application/pdf",
							"data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-14} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("resend", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "attachments", java.util.List.of(
                        java.util.Map.of(
                            "filename", "billing.pdf",
                            "contentType", "application/pdf",
                            "data", "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-18} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'resend' => [
        'override' => [
          'attachments' => [
            [
              'filename' => 'billing.pdf',
              'contentType' => 'application/pdf',
              'data' => 'Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-27} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "resend",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "attachments": [
                            {
                              "filename": "billing.pdf",
                              "contentType": "application/pdf",
                              "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                            }
                          ]
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"resend": {"override": {"attachments": [{"filename": "billing.pdf", "contentType": "application/pdf", "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"}]}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com with an attachment through Resend.
```

## Provider details

```text theme={null}
resend
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with SendGrid through Courier
Source: https://www.courier.com/docs/integrations/email/sendgrid

Connect SendGrid with a Mail Send API key, track delivery with the event webhook, override fields.

## Prerequisites

* [A Courier account](https://app.courier.com/signup)
* [A SendGrid account](https://signup.sendgrid.com/)

## Setup

**1. Create an API key in SendGrid**

In SendGrid, open [API Keys](https://app.sendgrid.com/settings/api_keys) and create a key with **Mail Send** permission. Copy it.

> [!NOTE]
>
> Mail Send is all Courier needs to send email, and all the [event webhook](#delivery-tracking) needs to report `delivered`. Two optional features want more: template import needs **Template Engine**, and Email Activity polling needs read access to Email Activity.

**2. Add it to Courier**

Open the [**Integrations**](https://app.courier.com/integrations) page, select the SendGrid integration, and paste the key into **API Key**.

**3. Set a From Address and save**

Add the address SendGrid sends from, such as `noreply@acme-corp.com`. Select **Add Integration**, then **Save**.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Send an email

Address the recipient by `email` and Courier routes it to SendGrid.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Sarah Bennett",
    },
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "name": "Sarah Bennett",
        },
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "name": "Sarah Bennett" }
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" }
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("name", "Sarah Bennett")))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['name' => 'Sarah Bennett'],
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to sarah@acme-corp.com by email.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

An override changes the request Courier sends to SendGrid. Use one to set a field Courier doesn't support yet, or to replace a value Courier generates.

| Key | What it replaces |
| - | - |
| `override.body` | Merged into SendGrid's [`/mail/send` request body](https://docs.sendgrid.com/api-reference/mail-send/mail-send). Any field that endpoint accepts works here. |
| `override.config.apiKey` | The API key for this one send, instead of the key saved on the integration. |

Nest either under `providers.sendgrid` on the message:

```javascript Node.js highlight={8-21} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      sendgrid: {
        override: {
          body: {
            subject: "Your appointment reminder",
            attachments: [
              {
                content: "eyJmb28iOiJiYXIifQ==",
                type: "application/json",
                filename: "appointment-details.json",
              },
            ],
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-21} theme={null}
response = client.send.message(
    message={
        "to": {
          "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "sendgrid": {
                "override": {
                  "body": {
                    "subject": "Your appointment reminder",
                    "attachments": [
                      {
                        "content": "eyJmb28iOiJiYXIifQ==",
                        "type": "application/json",
                        "filename": "appointment-details.json",
                      },
                    ],
                  },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-24} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
          "sendgrid": {
            "override": {
              "body": {
                "subject": "Your appointment reminder",
                "attachments": [
                  {
                    "content": "eyJmb28iOiJiYXIifQ==",
                    "type": "application/json",
                    "filename": "appointment-details.json"
                  }
                ]
              }
            }
          }
        }
      }
    }'
```

```ruby Ruby highlight={8-21} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "sendgrid" => {
        override: {
          body: {
            subject: "Your appointment reminder",
            attachments: [
              {
                content: "eyJmb28iOiJiYXIifQ==",
                type: "application/json",
                filename: "appointment-details.json"
              }
            ]
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-23} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"sendgrid": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"subject": "Your appointment reminder",
						"attachments": []any{
							map[string]any{
								"content": "eyJmb28iOiJiYXIifQ==",
								"type": "application/json",
								"filename": "appointment-details.json",
							},
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("sendgrid", JsonValue.from(java.util.Map.of(
                "override", java.util.Map.of("body", java.util.Map.of("subject", "Your appointment reminder", "attachments", java.util.List.of(java.util.Map.of("content", "eyJmb28iOiJiYXIifQ==", "type", "application/json", "filename", "appointment-details.json")))))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-21} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'providers' => [
      'sendgrid' => [
        'override' => [
          'body' => [
            'subject' => 'Your appointment reminder',
            'attachments' => [
              [
                'content' => 'eyJmb28iOiJiYXIifQ==',
                'type' => 'application/json',
                'filename' => 'appointment-details.json',
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-18} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "sendgrid",
                new()
                {
                    Override = new Dictionary<string, JsonElement>()
                    {
                        { "body", JsonSerializer.SerializeToElement(new { subject = "Your appointment reminder", attachments = new[] { new { content = "eyJmb28iOiJiYXIifQ==", type = "application/json", filename = "appointment-details.json" } } }) },
                    },
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"sendgrid": {"override": {"body": {"subject": "Your appointment reminder", "attachments": [{"content": "eyJmb28iOiJiYXIifQ==", "type": "application/json", "filename": "appointment-details.json"}]}}}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to sarah@acme-corp.com and override the email subject.
```

## Template import

Import your SendGrid templates from the [Courier SendGrid configuration page](https://app.courier.com/integrations/catalog/sendgrid).

> [!NOTE]
>
> Importing SendGrid Dynamic Templates needs three things:
>
> * Templates saved as [SendGrid Dynamic Templates](https://docs.sendgrid.com/ui/sending-email/how-to-send-an-email-with-dynamic-templates).
> * A SendGrid API key with [full access permissions](https://docs.sendgrid.com/ui/account-and-settings/api-keys) for `Template Engine`.
> * Your SendGrid credentials on the configuration page, so Courier can retrieve the templates.

### Import process

With those permissions, the import tool lists your templates as checkboxes. Select the ones to import.

![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/template-import.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=1e8c8f189a398d3ed6b692cf1c180e20)

Template Import Page

## Delivery tracking

Delivery tracking is **off until you set it up**. Until then a working SendGrid integration leaves every message at `SENT`, because Courier has sent the email but has heard nothing back. See [delivery statuses
DOC](/docs/send/statuses#delivery-tracking-is-per-provider).

SendGrid can report two ways, and the webhook below is the better one:

| | Event webhook | Email Activity polling |
| - | - | - |
| Speed | Real time | On a schedule |
| API key permission | Mail Send only | Read access to Email Activity |
| SendGrid add-on | None | The email-history add-on (paid) |
| Available on EU SendGrid | Yes | No, EU SendGrid has no Email Activity API |

Use the webhook. Reach for polling only if you can't add one, and not at all on EU SendGrid.

**1. Get Webhook URL**

In Courier, open the [Courier SendGrid provider configuration screen](https://app.courier.com/integrations/catalog/sendgrid) from the Channels menu. It shows a Webhook URL.

![](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/courier-ui.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=17a4e6c0a797076c7f5371e7c9310abf)

**2. Configure SendGrid Webhook**

Copy the webhook URL, then log in to SendGrid. Choose Settings, then Mail Settings, then Event Webhooks.

Click Create new webhook and fill out the form:

* **Friendly Name** - Whatever you like
* **Post URL** - Paste the URL you copied from Courier.
* **Deliverability Data** - Check all 5 boxes.
* **Security features** - Leave these disabled. The HTTPS URL you pasted carries a cryptographic token Courier uses to verify that incoming events are yours.

![](https://mintcdn.com/courier-4f1f25dc/_N31KC_ZrU1lo5hN/assets/webhook-form.webp?fit=max\&auto=format\&n=_N31KC_ZrU1lo5hN\&q=85\&s=070dc4daae5275441e084d68aad7288c)

Press Save.

**3. Turn polling off**

With the webhook live you no longer need Courier to poll. Wait about an hour first, so in-flight messages don't lose their status updates.

Then return to the [Courier SendGrid configuration screen](https://app.courier.com/integrations/catalog/sendgrid) and switch off **Enable polling for status updates** and **Enable Email Activity Tracking via Polling**. Press Save.

### Email Activity polling

Polling is the fallback when you can't add a webhook. Switch on **Enable Email Activity Tracking via Polling** in the integration settings, and Courier queries SendGrid's Email Activity API on a schedule for each message's status.

It needs two things on the SendGrid side, and both are easy to miss:

![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/sendgrid-api-key-permissions.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=331eddbb05fef3c0c180e4173788fa03)

Read access to Email Activity, on the API key.

![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/sendgrid-addons.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=d026432076b6e8f6996266059ae15c14)

The email-history add-on, on the SendGrid plan.

> [!WARNING]
>
> If either is missing, SendGrid rejects the query and **Courier turns the toggle back off**, showing a "Tracking Disabled" callout while messages stay at `SENT`. EU accounts hit this every time, since EU SendGrid has no Email Activity API. Use the webhook there.

## Troubleshooting

Check the [Courier Logs page](https://app.courier.com/logs) to debug provider errors. For anything else, contact [Courier Support](mailto:support@courier.com).

> **SendGrid API Key Access Forbidden**
>
> Your API key doesn't cover the request. Check it against [SendGrid's allowed API key actions](https://docs.sendgrid.com/api-reference/api-key-permissions/api-key-permissions).
>
> #### Solution
>
> Either stay within the actions your key allows, or create a new key that covers the ones you need.
>
> **Creating a new SendGrid API key with the permissions you want**
>
> In the SendGrid API keys console, select "Create API Key," then [select the permissions in SendGrid's API key settings](https://docs.sendgrid.com/ui/account-and-settings/api-keys).
>
> ![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/sendgrid-create-api-key.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=c1428e2b8fd09de2b6364f9b049edc44)
>
> Creating a new SendGrid API key
>
> SendGrid offers three permission scopes:
>
> * Full Access
> * Restricted Access
> * Billing Access.
>
> You can also set the access level for each one.

> **Error: sendgrid invalid email**
>
> You get this error when the address breaks internet email formatting standards, or doesn't exist on the recipient's mail server. It can come from your server or the receiver's.
>
> SendGrid checks the format before sending. If the receiving server can't find the address, it returns a 550 bounce.
>
> Addresses go invalid for several reasons:
>
> * Typos or formatting errors in the address.
>
> * The user changed addresses and left the old one empty. Inactivity and lack of engagement are the biggest cause.
>
> * The inbox provider went out of business, or its server went down for good. Every address on that dead domain is invalid.
>
> #### Solution
>
> * Scrub your email lists with an email verification tool to raise deliverability and engagement.
>
> * Sort your list by why each address signed up. Irrelevant or out-of-date email lowers open and click-through rates.
>
> * Group contacts by level of engagement. If an address looks like graymail, confirm it is still valid. If not, add it to the unsubscribe list.
>
> * Create a sunset policy, so you find disengaged contacts regularly and either remove or re-engage them.

> **Maximum Credits Exceeded SendGrid**
>
> SendGrid credits are the emails you can send. One credit per email, renewed at the start of each month. Exceeding your account's limit raises [this error in SendGrid's SMTP troubleshooting guide](https://docs.sendgrid.com/for-developers/sending-email/smtp-errors-and-troubleshooting).
>
> #### Solution
>
> Wait for your quota to renew, or upgrade your SendGrid plan for more credits.

> **SendGrid 535 Authentication Failed Bad Username Password**
>
> Three causes:
>
> * The username or password in the email client is wrong. The wrong mail server can also cause this.
>
> * The account is disabled, often for past-due payment or spam complaints.
>
> * SMTP authentication isn't enabled in your email client.
>
> #### Solution
>
> * Check your username and password, billing plan, and account status.
>
> * Check that you confirmed your email address.
>
> * Configure SMTP authentication.
>
> * Store your API keys as environment variables. You then change a key in one place instead of hunting for every use.
>
> * Set up sender authentication for your domains, which gives you SPF and DKIM on the Twilio SendGrid account.

> **Sendgrid From Field Not Working**
>
> The `from` address doesn't match a verified Sender Identity. No email sends until you fix it.
>
> #### Solution
>
> [Authenticate your sender identities in SendGrid's sender authentication guide](https://docs.sendgrid.com/glossary/sender-authentication). A sender identity is the address recipients see as the sender. Authenticate one or more with Domain Authentication or Single Sender Verification.

## Provider details

```text theme={null}
sendgrid
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with SMTP through Courier
Source: https://www.courier.com/docs/integrations/email/smtp

Connect any SMTP server with host, port, and credentials, then override transport fields per send.

## Prerequisites

* An SMTP server you can send through
* The host, username, and password for that server

## Setup

Courier's SMTP integration uses [NodeMailer](https://nodemailer.com).

Open the [SMTP integration](https://app.courier.com/integrations/catalog/smtp) in Courier, enter your SMTP host, username, password, and From Address, then save.

A provider override can change any of these for a single message.

> [!NOTE]
>
> Courier connects to your SMTP server from AWS-hosted infrastructure and doesn't use fixed outbound IPs. If your server requires IP allowlisting, see [Allowlist for AWS IP Addresses
> DOC](/docs/integrations/email/overview#allowlist-for-aws-ip-addresses) on the Email Providers page.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

Provider overrides in the Send API change the message content and the SMTP transport configuration, one message at a time.

### Message override

An override changes what Courier sends over SMTP through NodeMailer. Overrides are deep-merged into the request: fields you set replace their counterparts, and everything you leave out is still sent. For example, add an attachment:

```javascript Node.js highlight={8-21} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      smtp: {
        override: {
          body: {
            attachments: [
              {
                filename: "document.pdf",
                content: "aGVsbG8gd29ybGQh",
                encoding: "base64",
                contentType: "application/pdf",
              },
            ],
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-21} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "smtp": {
                "override": {
                    "body": {
                        "attachments": [
                            {
                                "filename": "document.pdf",
                                "content": "aGVsbG8gd29ybGQh",
                                "encoding": "base64",
                                "contentType": "application/pdf",
                            },
                        ],
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-24} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "smtp": {
          "override": {
            "body": {
              "attachments": [
                {
                  "filename": "document.pdf",
                  "content": "aGVsbG8gd29ybGQh",
                  "encoding": "base64",
                  "contentType": "application/pdf"
                }
              ]
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-21} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      smtp: {
        override: {
          body: {
            attachments: [
              {
                filename: "document.pdf",
                content: "aGVsbG8gd29ybGQh",
                encoding: "base64",
                contentType: "application/pdf"
              }
            ]
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-23} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"smtp": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"attachments": []any{
							map[string]any{
								"filename": "document.pdf",
								"content": "aGVsbG8gd29ybGQh",
								"encoding": "base64",
								"contentType": "application/pdf",
							},
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-17} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("smtp", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "attachments", java.util.List.of(
                            java.util.Map.of(
                                "filename", "document.pdf",
                                "content", "aGVsbG8gd29ybGQh",
                                "encoding", "base64",
                                "contentType", "application/pdf"
                            )
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-21} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'smtp' => [
        'override' => [
          'body' => [
            'attachments' => [
              [
                'filename' => 'document.pdf',
                'content' => 'aGVsbG8gd29ybGQh',
                'encoding' => 'base64',
                'contentType' => 'application/pdf',
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-30} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "smtp",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "attachments": [
                              {
                                "filename": "document.pdf",
                                "content": "aGVsbG8gd29ybGQh",
                                "encoding": "base64",
                                "contentType": "application/pdf"
                              }
                            ]
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"smtp": {"override": {"body": {"attachments": [{"filename": "document.pdf", "content": "aGVsbG8gd29ybGQh", "encoding": "base64", "contentType": "application/pdf"}]}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and override what goes out over SMTP.
```

Courier merges everything inside `message.providers.smtp.override.body` into its generated message and passes it to NodeMailer. For every option, see the [NodeMailer message options documentation](https://nodemailer.com/message).

### Transport override

Values in `message.providers.smtp.override.config` override the [SMTP transport configuration](https://nodemailer.com/smtp). They replace your stored provider configuration for that one message.

**Basic example:**

```javascript Node.js highlight={8-20} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      smtp: {
        override: {
          config: {
            auth: {
              user: "username",
              pass: "hunter2",
            },
            host: "smtp.example.com",
            secure: true,
            port: 465,
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-20} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "smtp": {
                "override": {
                    "config": {
                        "auth": {
                            "user": "username",
                            "pass": "hunter2",
                        },
                        "host": "smtp.example.com",
                        "secure": True,
                        "port": 465,
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-23} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "smtp": {
          "override": {
            "config": {
              "auth": {
                "user": "username",
                "pass": "hunter2"
              },
              "host": "smtp.example.com",
              "secure": true,
              "port": 465
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-20} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      smtp: {
        override: {
          config: {
            auth: {
              user: "username",
              pass: "hunter2"
            },
            host: "smtp.example.com",
            secure: true,
            port: 465
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-22} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"smtp": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"auth": map[string]any{
							"user": "username",
							"pass": "hunter2",
						},
						"host": "smtp.example.com",
						"secure": true,
						"port": 465,
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("smtp", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "auth", java.util.Map.of(
                            "user", "username",
                            "pass", "hunter2"
                        ),
                        "host", "smtp.example.com",
                        "secure", true,
                        "port", 465
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-20} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'smtp' => [
        'override' => [
          'config' => [
            'auth' => [
              'user' => 'username',
              'pass' => 'hunter2',
            ],
            'host' => 'smtp.example.com',
            'secure' => true,
            'port' => 465,
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-29} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "smtp",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "auth": {
                              "user": "username",
                              "pass": "hunter2"
                            },
                            "host": "smtp.example.com",
                            "secure": true,
                            "port": 465
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"smtp": {"override": {"config": {"auth": {"user": "username", "pass": "hunter2"}, "host": "smtp.example.com", "secure": true, "port": 465}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com through a different SMTP server.
```

**STARTTLS (port 587, recommended):**

```javascript Node.js highlight={8-21} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      smtp: {
        override: {
          config: {
            host: "smtp.yourdomain.com",
            port: 587,
            secure: false,
            requireTLS: true,
            auth: {
              user: "user@yourdomain.com",
              pass: "your-password",
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-21} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "smtp": {
                "override": {
                    "config": {
                        "host": "smtp.yourdomain.com",
                        "port": 587,
                        "secure": False,
                        "requireTLS": True,
                        "auth": {
                            "user": "user@yourdomain.com",
                            "pass": "your-password",
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-24} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "smtp": {
          "override": {
            "config": {
              "host": "smtp.yourdomain.com",
              "port": 587,
              "secure": false,
              "requireTLS": true,
              "auth": {
                "user": "user@yourdomain.com",
                "pass": "your-password"
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-21} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      smtp: {
        override: {
          config: {
            host: "smtp.yourdomain.com",
            port: 587,
            secure: false,
            requireTLS: true,
            auth: {
              user: "user@yourdomain.com",
              pass: "your-password"
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-23} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"smtp": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"host": "smtp.yourdomain.com",
						"port": 587,
						"secure": false,
						"requireTLS": true,
						"auth": map[string]any{
							"user": "user@yourdomain.com",
							"pass": "your-password",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-17} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("smtp", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "host", "smtp.yourdomain.com",
                        "port", 587,
                        "secure", false,
                        "requireTLS", true,
                        "auth", java.util.Map.of(
                            "user", "user@yourdomain.com",
                            "pass", "your-password"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-21} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'smtp' => [
        'override' => [
          'config' => [
            'host' => 'smtp.yourdomain.com',
            'port' => 587,
            'secure' => false,
            'requireTLS' => true,
            'auth' => [
              'user' => 'user@yourdomain.com',
              'pass' => 'your-password',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-30} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "smtp",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "host": "smtp.yourdomain.com",
                            "port": 587,
                            "secure": false,
                            "requireTLS": true,
                            "auth": {
                              "user": "user@yourdomain.com",
                              "pass": "your-password"
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"smtp": {"override": {"config": {"host": "smtp.yourdomain.com", "port": 587, "secure": false, "requireTLS": true, "auth": {"user": "user@yourdomain.com", "pass": "your-password"}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com over STARTTLS on port 587.
```

**Implicit TLS (port 465):**

```javascript Node.js highlight={8-20} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      smtp: {
        override: {
          config: {
            host: "smtp.yourdomain.com",
            port: 465,
            secure: true,
            auth: {
              user: "user@yourdomain.com",
              pass: "your-password",
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-20} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "smtp": {
                "override": {
                    "config": {
                        "host": "smtp.yourdomain.com",
                        "port": 465,
                        "secure": True,
                        "auth": {
                            "user": "user@yourdomain.com",
                            "pass": "your-password",
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-23} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "smtp": {
          "override": {
            "config": {
              "host": "smtp.yourdomain.com",
              "port": 465,
              "secure": true,
              "auth": {
                "user": "user@yourdomain.com",
                "pass": "your-password"
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-20} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      smtp: {
        override: {
          config: {
            host: "smtp.yourdomain.com",
            port: 465,
            secure: true,
            auth: {
              user: "user@yourdomain.com",
              pass: "your-password"
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-22} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"smtp": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"host": "smtp.yourdomain.com",
						"port": 465,
						"secure": true,
						"auth": map[string]any{
							"user": "user@yourdomain.com",
							"pass": "your-password",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("smtp", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "host", "smtp.yourdomain.com",
                        "port", 465,
                        "secure", true,
                        "auth", java.util.Map.of(
                            "user", "user@yourdomain.com",
                            "pass", "your-password"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-20} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'smtp' => [
        'override' => [
          'config' => [
            'host' => 'smtp.yourdomain.com',
            'port' => 465,
            'secure' => true,
            'auth' => [
              'user' => 'user@yourdomain.com',
              'pass' => 'your-password',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-29} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "smtp",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "host": "smtp.yourdomain.com",
                            "port": 465,
                            "secure": true,
                            "auth": {
                              "user": "user@yourdomain.com",
                              "pass": "your-password"
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"smtp": {"override": {"config": {"host": "smtp.yourdomain.com", "port": 465, "secure": true, "auth": {"user": "user@yourdomain.com", "pass": "your-password"}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com over implicit TLS on port 465.
```

**Common provider settings:**

| Provider | Host | Port | secure | requireTLS |
| - | - | - | - | - |
| Office 365 | `smtp.office365.com` | 587 | false | true |
| Gmail (app password) | `smtp.gmail.com` | 587 | false | true |
| On-prem Exchange | `mail.yourdomain.com` | 587 | false | true |
| Custom (implicit TLS) | varies | 465 | true | - |

**Transport options reference:**

| Option | Type | Description |
| - | - | - |
| `host` | string | SMTP server hostname |
| `port` | number | SMTP port (commonly 25, 465, 587) |
| `secure` | boolean | Use SSL (true for port 465) |
| `requireTLS` | boolean | Require STARTTLS (true for port 587) |
| `auth` | object | Authentication credentials `{ user, pass }` |
| `tls` | object | TLS options (see [NodeMailer TLS docs](https://nodemailer.com/smtp#tls-options)) |
| `connectionTimeout` | number | Connection timeout in milliseconds |
| `socketTimeout` | number | Socket timeout in milliseconds |

**All options:** See the [NodeMailer SMTP transport documentation](https://nodemailer.com/smtp) for every `config` override option.

## Security best practices

* Use app-specific passwords for Office 365 and Gmail, not regular account passwords.
* Send from a dedicated service account, not a personal one.
* Store credentials in Courier Studio instead of passing them in every API request.
* Always use TLS: set `requireTLS: true` for port 587, `secure: true` for port 465.
* For HIPAA or data residency requirements, use a direct connection to your on-premises SMTP server.

## Troubleshooting

Courier verifies your SMTP connection before each send. If verification fails, Courier doesn't send the message and returns an error. Courier retries connection timeouts (`ETIMEDOUT`) and temporary server unavailability.

> **Connection Timeouts**
>
> * Check that firewall rules allow outbound connections to your SMTP server
> * Check the SMTP host and port
> * Check that your SMTP server is reachable from Courier's infrastructure

> **Authentication Failures**
>
> * Check the username and password
> * For Office 365 with MFA enabled, use an app-specific password
> * Check that the account may send email over SMTP

> **TLS/SSL Errors**
>
> * Check that your SMTP server supports the encryption method you requested
> * Check certificate validity if you use custom certificates
> * Check that `secure` and `requireTLS` match your server configuration

## Provider details

```text theme={null}
smtp
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send email with SparkPost through Courier
Source: https://www.courier.com/docs/integrations/email/sparkpost

Connect SparkPost with an API key and from address, then override transmission fields per send.

## Prerequisites

* [A SparkPost account](https://www.sparkpost.com/)
* A SparkPost API key with Transmissions: Read/Write permissions

## Setup

**1. Create a SparkPost API key**

In SparkPost, open [API keys](https://app.sparkpost.com/account/api-keys) and create a key with Transmissions permission.

**2. Configure in Courier**

Open the [SparkPost integration](https://app.courier.com/integrations/catalog/sparkpost) in Courier, enter your API key and From Address, then save.

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements
DOC](/docs/integrations/email/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/email/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Email channel overrides
DOC](/docs/integrations/email/overview#channel-overrides) lists the fields every email provider takes.

A provider override changes what Courier sends to SparkPost's Transmissions API. For example, add an attachment:

```javascript Node.js highlight={8-22} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      sparkpost: {
        override: {
          body: {
            content: {
              attachments: [
                {
                  name: "billing.pdf",
                  type: "application/pdf",
                  data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
                },
              ],
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-22} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "sparkpost": {
                "override": {
                    "body": {
                        "content": {
                            "attachments": [
                                {
                                    "name": "billing.pdf",
                                    "type": "application/pdf",
                                    "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
                                },
                            ],
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-25} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "sparkpost": {
          "override": {
            "body": {
              "content": {
                "attachments": [
                  {
                    "name": "billing.pdf",
                    "type": "application/pdf",
                    "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                  }
                ]
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-22} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      sparkpost: {
        override: {
          body: {
            content: {
              attachments: [
                {
                  name: "billing.pdf",
                  type: "application/pdf",
                  data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                }
              ]
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-24} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"sparkpost": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"content": map[string]any{
							"attachments": []any{
								map[string]any{
									"name": "billing.pdf",
									"type": "application/pdf",
									"data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
								},
							},
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-18} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("sparkpost", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "content", java.util.Map.of(
                            "attachments", java.util.List.of(
                                java.util.Map.of(
                                    "name", "billing.pdf",
                                    "type", "application/pdf",
                                    "data", "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                                )
                            )
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-22} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'sparkpost' => [
        'override' => [
          'body' => [
            'content' => [
              'attachments' => [
                [
                  'name' => 'billing.pdf',
                  'type' => 'application/pdf',
                  'data' => 'Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh',
                ],
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-31} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "sparkpost",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "content": {
                              "attachments": [
                                {
                                  "name": "billing.pdf",
                                  "type": "application/pdf",
                                  "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                                }
                              ]
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"sparkpost": {"override": {"body": {"content": {"attachments": [{"name": "billing.pdf", "type": "application/pdf", "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"}]}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com with an attachment through SparkPost.
```

Overrides are deep-merged into the request: fields you set replace their counterparts, and everything you leave out is still sent. SparkPost's full field list is in the [SparkPost API docs](https://developers.sparkpost.com/api/transmissions/#header-request-body).

## Provider details

```text theme={null}
sparkpost
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# In-app channel
Source: https://www.courier.com/docs/integrations/in-app

The inbox and toasts need no provider. Push goes through APNs and FCM.

In-app is the one channel with nothing to connect! Courier hosts the Inbox itself.

![The Courier Inbox with an unread count badge in its header, listing notifications with unread dots, relative timestamps, and View all, Download, and Approve actions](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/inbox-card.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=9834fcc8c1fb404a4da412d96163c473)

The Courier Inbox: unread indicators, relative timestamps, and per-message action buttons.

> **[Set up the Inbox](/docs/in-app/overview)**
>
> Install an SDK, authenticate the user, render the component.

## Provider details

```text theme={null}
courier
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.


# Forward Courier events to Datadog
Source: https://www.courier.com/docs/integrations/observability/datadog

Forward delivery metrics and message logs to Datadog with an API key and site.

## Setup

**1. Create a Datadog account**

Create a Datadog account if you don't have one.

**2. Generate an API key**

Generate a Datadog [API key](https://app.datadoghq.com/organization-settings/api-keys).

**3. Add the API key in Courier**

Open the [Datadog integration page](https://app.courier.com/integrations/catalog/datadog) in Courier and enter the API key you generated.

**4. Verify the Datadog site parameter**

Check that the [Datadog site parameter](https://docs.datadoghq.com/getting_started/site/#access-the-datadog-site) matches the URL of your Datadog instance.

**5. Add tags (optional)**

Use the **Tags** field to tag everything Courier emits. Courier sends them as Datadog `ddtags`, so you can filter metrics and logs by environment or team.

> [!NOTE]
>
> The Datadog integration is **forward-only**. Courier starts emitting metrics when you activate it. It doesn't backfill historical data.

## Dashboard

Download the Courier Datadog dashboard to monitor Courier inside Datadog.

[Download Dashboard JSON](https://github.com/trycourier/shareable/blob/main/courier-datadog-dashboard.json)

![Datadog Dashboard](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/datadog-dashboard.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=7e92e5b0580d85b02e668502cbc97778)

Datadog Dashboard

## Available Datadog metrics

> [!TIP]
>
> Datadog's Metrics Without Limits lets you [configure a tag blocklist](https://docs.datadoghq.com/metrics/metrics-without-limits/#blocklist-of-tags) to cut cardinality and cost. You're still [billed](https://docs.datadoghq.com/account_management/billing/custom_metrics/?tab=countrate) for ingestion, at a lower rate.

### Account metrics

* `courier.account.created`
* `courier.account.deleted`
* `courier.account.updated`

### Account user relationship metrics

* `courier.account.user.added`
* `courier.account.user.removed`
* `courier.account.user.updated`

### Audience metrics

* `courier.audience.matched`
* `courier.audience.unmatched`

### Automation metrics

* `courier.automation.invoked`
* `courier.automation.throttled`
* `courier.automation.digest.triggered`
* `courier.automation.batch.triggered`
* `courier.automation.fetch-data-step.errored`
* `courier.automation.ai-step.completed`
* `courier.automation.ai-step.errored`

### Channel metrics

* `courier.email.delivered`
* `courier.email.error`
* `courier.email.sent`
* `courier.email.undeliverable`
* `courier.sms.delivered`
* `courier.sms.error`
* `courier.sms.sent`
* `courier.sms.undeliverable`
* `courier.push.delivered`
* `courier.push.error`
* `courier.push.sent`
* `courier.push.undeliverable`
* `courier.direct_message.delivered`
* `courier.direct_message.error`
* `courier.direct_message.sent`
* `courier.direct_message.undeliverable`
* `courier.inbox.delivered`
* `courier.inbox.error`
* `courier.inbox.sent`
* `courier.inbox.undeliverable`
* `courier.webhook.delivered`
* `courier.webhook.error`
* `courier.webhook.sent`
* `courier.webhook.undeliverable`
* `courier.banner.delivered`
* `courier.banner.error`
* `courier.banner.sent`
* `courier.banner.undeliverable`

### Debug metric

* `courier.debug`

### Inbox metrics

* `courier.inbox.connection_attempt`
* `courier.inbox.connection_error`
* `courier.inbox.reconnection_attempt`
* `courier.inbox.notification_attempt`

### List metrics

* `courier.list.subscribed`
* `courier.list.unsubscribed`
* `courier.list.subscribe.failed`

### Message metrics

* `courier.message.canceled`
* `courier.message.clicked.details`
* `courier.message.delivered`
* `courier.message.digested`
* `courier.message.filtered`
* `courier.message.received`
* `courier.message.sent`
* `courier.message.throttled`
* `courier.message.total.clicked`
* `courier.message.total.opened`
* `courier.message.undeliverable`
* `courier.message.unique.clicked`
* `courier.message.unique.opened`
* `courier.message.unique.sent`
* `courier.message.unmapped`
* `courier.message.unroutable`

### User metrics

* `courier.user.created`
* `courier.user.deleted`
* `courier.user.unsubscribed`
* `courier.user.updated`
* `courier.user.update.failed`

## Logs

Courier also forwards delivery logs to Datadog's log intake for your site (`https://http-intake.logs.<your-datadog-site>/api/v2/logs`). Each entry carries the message, its level, and any tags from the **Tags** field, so you can match a log line to the metric that reported it. No extra setup is needed. The same API key and site parameter cover both.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| No metrics appearing in Datadog | API key incorrect, or Datadog site parameter mismatch | Verify the API key and [site parameter](https://docs.datadoghq.com/getting_started/site/#access-the-datadog-site) match your Datadog instance |
| Metrics start from integration date, not historical | The integration is forward-only | Expected behavior. Courier doesn't backfill. Enable the integration before you need the data |
| Metrics appear in test but not production (or vice versa) | The integration is configured per environment | Install the Datadog integration in each Courier environment (test and production) separately |
| `courier.message.*` counts don't match message logs | Metrics are emitted per status transition, not per message | A single message may trigger multiple `message.updated` metrics as it progresses through statuses |


# Forward Courier events to New Relic
Source: https://www.courier.com/docs/integrations/observability/new-relic

Forward delivery metrics and message logs to New Relic with your license key.

## Prerequisites

* [A New Relic account](https://newrelic.com/)
* [Your New Relic License key](https://one.newrelic.com/api-keys)

## Setup

**1. Get your New Relic license key**

In New Relic, open [API keys](https://one.newrelic.com/api-keys) and copy your license key.

**2. Configure in Courier**

In Courier, open the New Relic channel on the Channels page and enter your License key in the API Key field.

## New Relic metrics endpoint

Optionally set a [Metrics Endpoint](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/report-metrics-metric-api/#api-endpoint) for the integration. Courier defaults to the United States (US) endpoint.

## New Relic logs endpoint

Optionally set a [Logs Endpoint](https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/#endpoint) for the integration. Courier defaults to the United States (US) endpoint.

## Metrics

New Relic receives the same `courier.*` metrics as every other observability integration: messages, channels, automations, lists, users, audiences, and inbox connections. The names are identical. See the full list on the [Datadog page
DOC](/docs/integrations/observability/datadog#available-datadog-metrics).

## Dashboard

Download the Courier New Relic dashboard to monitor Courier inside New Relic.

[Download Dashboard JSON](https://github.com/trycourier/shareable/blob/main/courier-new-relic-dashboard.json)

## Dashboard preview

![New Relic Dashboard](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/new-relic-dashboard.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=22a46b12eb2997203ee2e2c04f82473e)

New Relic Dashboard


# Forward Courier events to OpenTelemetry
Source: https://www.courier.com/docs/integrations/observability/open-telemetry

Export delivery metrics and logs to any OpenTelemetry endpoint.

Export Courier logs and metrics to any OpenTelemetry-compatible (OTel) platform from the Courier dashboard.

Courier supports **Basic auth** and **Bearer Token** authorization, so you connect directly to most providers without an OTel Collector or proxy.

## Setup

**1. Open the OpenTelemetry integration**

In Courier, go to **Channels** (or **Integrations**) and open the **OpenTelemetry** integration.

**2. Enable the integration**

Turn the **Enabled** toggle on.

**3. Choose authorization**

Set **Authorization type** to match your provider:

* **Basic**: enter your username and password. Used by Grafana Cloud and others.
* **Bearer Token**: enter your API key or token.

**4. Set your OTLP endpoint**

Enter your provider's OTLP endpoint URL in **OTLP endpoint**. For example:

* Grafana Cloud: `https://otlp-gateway-<region>.grafana.net/otlp`
* Self-hosted collector: `https://otel-collector.example.com:4318`

**5. Optional: set metrics and logs paths**

If your endpoint uses custom paths, fill in **Metrics path** and **Logs path**. Common defaults are `/v1/metrics` and `/v1/logs`. Leave both blank to use the endpoint defaults.

**6. Save**

Click **Complete**. Courier starts exporting logs and metrics to your platform.

## Configuration reference

| Field | Required | Description |
| - | - | - |
| **Enabled** | No | Toggle the integration on or off. |
| **Authorization type** | Yes | **Basic** or **Bearer Token**. |
| **Username** | When using Basic | Username for Basic auth (e.g. Grafana Cloud Instance ID). |
| **Password** | When using Basic | Password for Basic auth (e.g. Grafana Cloud API token). |
| **Bearer token** | When using Bearer | API key or token for Bearer auth. |
| **OTLP endpoint** | Yes | Your provider's OTLP endpoint URL. |
| **Metrics path** | No | Custom path for metrics (e.g. `/v1/metrics`). |
| **Logs path** | No | Custom path for logs (e.g. `/v1/logs`). |

> [!TIP]
>
> Use HTTPS and dedicated credentials, so you can rotate or revoke them without affecting other services.

## What gets exported

Courier sends **logs** and **metrics** over the [OTLP](https://opentelemetry.io/docs/specs/otlp/) protocol. For the full list of metrics, see [Observability
DOC](/docs/monitor/observability#metrics).

***

## Grafana Cloud OTel setup guide

Courier connects directly to Grafana Cloud using Basic auth. No OTel Collector or proxy required.

### Step 1: get your credentials

1. Sign in to the [Grafana Cloud Portal](https://grafana.com/auth/sign-in/).
2. Select your stack and click **Configure** on the **OpenTelemetry** tile.
3. Note your **Instance ID** (numeric) and your **OTLP endpoint URL** (e.g. `https://otlp-gateway-prod-us-east-0.grafana.net/otlp`).
4. Generate a **Cloud API token** with `metrics:write` and `logs:write` scopes.

### Step 2: configure Courier

Open the OpenTelemetry integration in Courier and enter:

| Field | Value |
| - | - |
| **Enabled** | On |
| **Authorization type** | Basic |
| **Username** | Your Instance ID |
| **Password** | Your Cloud API token |
| **OTLP endpoint** | `https://otlp-gateway-<region>.grafana.net/otlp` |
| **Metrics path** | *(leave blank)* |
| **Logs path** | *(leave blank)* |

Click **Complete** to save.

### Step 3: verify

1. In Grafana Cloud, go to **Explore**.
2. Select your **Mimir** data source and filter for `{service_name="courier"}`.
3. Switch to **Loki** to confirm logs are arriving.

Data appears within a few minutes of enabling the integration.


# Observability integrations
Source: https://www.courier.com/docs/integrations/observability/overview

Send Courier delivery metrics and logs to Datadog, New Relic, or any OpenTelemetry endpoint.

> [!NOTE]
>
> Observability integrations require the **Enterprise** plan. See [Courier pricing](https://www.courier.com/pricing).

Pick the monitoring tool you send Courier's metrics and logs to. [Observability
DOC](/docs/monitor/observability) lists every metric Courier exports and when to use this instead of webhooks.

> **[Datadog](/docs/integrations/observability/datadog)**

> **[New Relic](/docs/integrations/observability/new-relic)**

> **[OpenTelemetry](/docs/integrations/observability/open-telemetry)**


# Build a custom provider for Courier
Source: https://www.courier.com/docs/integrations/other/custom-provider

Route messages to your own webhook so an in-house channel works like any provider.

## Prerequisites

* An HTTPS endpoint you control, ready to receive Courier's webhook
* The authentication your endpoint expects, if any

## Setup

Open the [Custom Provider integration](https://app.courier.com/integrations/catalog/custom). Enter your webhook HTTP address and choose an authentication model.

![Custom Provider](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/custom-provider.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=fda6a402412de38293abe5fb9c39939a)

You can now add the Custom Provider to any Push channel. Add a Push channel, then open the Channel Settings modal.

![Custom Provider Settings](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/custom-provider-settings.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=67496b358769a77e5b15506c3a8e0ae9)

"Custom" appears in the list of installed providers.

![Installed Custom Provider](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/custom-installed-provider.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=f96895090a1fee950bf63c2bda17c195)

Add a title and blocks in the designer. Courier sends them to your webhook as plain text and as an array of blocks.

![Custom Provider Designer](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/custom-provider-designer.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=46cd8db590f00cd0317d3af0ec46bb59)

When the message sends, your webhook receives a payload like this:

```ts theme={null}
interface TextBlock {
  type: "text";
  text: string;
}

interface ActionBlock {
  type: "action";
  url: string;
  text: string;
}

interface PushMessage {
  type: "push";
  data: {
  	messageId: string;
    content: {
      title: string;
      body: string;
      blocks: Array<ActionBlock | TextBlock>
    }
  }
}
```

```json theme={null}
{
  "type": "push",
  "data": {
    "messageId": "1-6140e057-2749378a31c6026f3dab823f",
    "content": {
      "blocks": [
        {
          "text": "My Body",
          "type": "text"
        },
        {
          "text": "Click Here",
          "url": "https://example.execute-api.us-east-1.amazonaws.com/dev/r/TRACKING_ID",
          "type": "action"
        }
      ],
      "body": "My Body\nClick Here: https://example.execute-api.us-east-1.amazonaws.com/dev/r/TRACKING_ID",
      "title": "My Title"
    }
  }
}
```

## Profile requirements

No profile data is required. Courier posts the rendered message to your endpoint, and your endpoint decides how to address the recipient.

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

An override changes what Courier sends to your custom provider. You can override the `body`, `headers`, `method`, and `url` fields. `body` is deep-merged into the request, so fields you leave out are still sent.

```javascript Node.js highlight={8-15} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      custom: {
        override: {
          body: {},
          headers: {},
          method: "POST",
          url: "https://your-endpoint.example.com/webhook",
        },
      },
    },
  },
});
```

```python Python highlight={8-15} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "custom": {
                "override": {
                    "body": {},
                    "headers": {},
                    "method": "POST",
                    "url": "https://your-endpoint.example.com/webhook",
                },
            },
        },
    },
)
```

```bash cURL highlight={11-18} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "custom": {
          "override": {
            "body": {},
            "headers": {},
            "method": "POST",
            "url": "https://your-endpoint.example.com/webhook"
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-15} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      custom: {
        override: {
          body: {},
          headers: {},
          method: "POST",
          url: "https://your-endpoint.example.com/webhook"
        }
      }
    }
  }
)
```

```go Go highlight={10-17} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"custom": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{},
					"headers": map[string]any{},
					"method": "POST",
					"url": "https://your-endpoint.example.com/webhook",
				},
			},
		},
	},
})
```

```java Java highlight={6-11} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("custom", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(),
                    "headers", java.util.Map.of(),
                    "method", "POST",
                    "url", "https://your-endpoint.example.com/webhook"
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-15} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'custom' => [
        'override' => [
          'body' => [],
          'headers' => [],
          'method' => 'POST',
          'url' => 'https://your-endpoint.example.com/webhook',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-24} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "custom",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {},
                          "headers": {},
                          "method": "POST",
                          "url": "https://your-endpoint.example.com/webhook"
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"custom": {"override": {"body": {}, "headers": {}, "method": "POST", "url": "https://your-endpoint.example.com/webhook"}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and override my custom provider's URL and body.
```

## Provider details

```text theme={null}
custom
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send Drift messages through Courier
Source: https://www.courier.com/docs/integrations/other/drift

Connect Drift with an OAuth token and start a conversation by the recipient's email.

## Prerequisites

* Your Drift access token

## Setup

Install the [Drift integration](https://app.courier.com/integrations/catalog/drift) in Courier and enter your access token.

> [!NOTE]
>
> Salesloft acquired Drift. The legacy Drift API docs at `devdocs.drift.com` may no longer be available. See [Salesloft's developer documentation](https://developers.salesloft.com/) for current APIs.

## Profile requirements

Drift addresses the recipient by email, so the profile you send to needs a `email`. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    email: 'sarah@acme-corp.com',
  },
});
```

```python Python highlight={4} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "email": "sarah@acme-corp.com",
    },
)
```

```bash cURL highlight={7} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "email": "sarah@acme-corp.com"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    email: "sarah@acme-corp.com"
  }
)
```

```go Go highlight={6} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"email": "sarah@acme-corp.com",
		},
	},
)
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'email' => 'sarah@acme-corp.com',
]);
```

```csharp C# highlight={6} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
    },
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"email":"sarah@acme-corp.com"}'
```

```text MCP theme={null}
With Courier MCP, create a profile for user_123 with the email sarah@acme-corp.com.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "email": "sarah@acme-corp.com" }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `email` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to an email**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com by email.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

You can override the request body, access token, URL, and headers. This example overrides the body and access token.

```javascript Node.js highlight={8-19} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      drift: {
        override: {
          body: {
            message: {
              body: "Custom message body",
            },
          },
          config: {
            accessToken: "RUNTIME_ACCESS_TOKEN",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-19} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "drift": {
                "override": {
                    "body": {
                        "message": {
                            "body": "Custom message body",
                        },
                    },
                    "config": {
                        "accessToken": "RUNTIME_ACCESS_TOKEN",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-22} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "drift": {
          "override": {
            "body": {
              "message": {
                "body": "Custom message body"
              }
            },
            "config": {
              "accessToken": "RUNTIME_ACCESS_TOKEN"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-19} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      drift: {
        override: {
          body: {
            message: {
              body: "Custom message body"
            }
          },
          config: {
            accessToken: "RUNTIME_ACCESS_TOKEN"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-21} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"drift": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"message": map[string]any{
							"body": "Custom message body",
						},
					},
					"config": map[string]any{
						"accessToken": "RUNTIME_ACCESS_TOKEN",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-15} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("drift", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "message", java.util.Map.of(
                            "body", "Custom message body"
                        )
                    ),
                    "config", java.util.Map.of(
                        "accessToken", "RUNTIME_ACCESS_TOKEN"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-19} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'drift' => [
        'override' => [
          'body' => [
            'message' => [
              'body' => 'Custom message body',
            ],
          ],
          'config' => [
            'accessToken' => 'RUNTIME_ACCESS_TOKEN',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-28} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "drift",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "message": {
                              "body": "Custom message body"
                            }
                          },
                          "config": {
                            "accessToken": "RUNTIME_ACCESS_TOKEN"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"drift": {"override": {"body": {"message": {"body": "Custom message body"}}, "config": {"accessToken": "RUNTIME_ACCESS_TOKEN"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and override Drift's body and access token.
```

## Provider details

```text theme={null}
drift
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send Intercom messages through Courier
Source: https://www.courier.com/docs/integrations/other/intercom

Connect Intercom with an access token and send in-app messages by Intercom user ID.

## Prerequisites

* Your Intercom access token
* An Intercom admin or bot user ID

## Setup

**1. Get your Intercom access token**

In Intercom, follow [the authentication guide](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication) to create an access token.

**2. Configure in Courier**

Install the [Intercom integration](https://app.courier.com/integrations/catalog/intercom) in Courier and enter your access token and user ID.

## Profile requirements

Intercom addresses the recipient by user ID, nested under `intercom.to.id` on the profile. Courier assumes the user is of type `user`. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3-7} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    intercom: {
      to: {
        id: 'INTERCOM_USER_ID',
      },
    },
  },
});
```

```python Python highlight={4-8} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "intercom": {
            "to": {
                "id": "INTERCOM_USER_ID",
            },
        },
    },
)
```

```bash cURL highlight={7-11} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "intercom": {
        "to": {
          "id": "INTERCOM_USER_ID"
        }
      }
    }
  }'
```

```ruby Ruby highlight={4-8} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    intercom: {
      to: {
        id: "INTERCOM_USER_ID"
      }
    }
  }
)
```

```go Go highlight={6-10} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"intercom": map[string]any{
				"to": map[string]any{
					"id": "INTERCOM_USER_ID",
				},
			},
		},
	},
)
```

```java Java highlight={4-6} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("intercom", JsonValue.from(java.util.Map.of(
            "to", java.util.Map.of(
                "id", "INTERCOM_USER_ID"))))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-6} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'intercom' => [
    'to' => [
      'id' => 'INTERCOM_USER_ID',
    ],
  ],
]);
```

```csharp C# highlight={7-11} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "intercom": {
            "to": {
              "id": "INTERCOM_USER_ID"
            }
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"intercom":{"to":{"id":"INTERCOM_USER_ID"}}}'
```

```text MCP theme={null}
With Courier MCP, save the Intercom user id INTERCOM_USER_ID on user_123.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "intercom": { "to": { "id": "INTERCOM_USER_ID" } } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `intercom` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `intercom`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-9} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      intercom: {
        to: {
          id: "INTERCOM_USER_ID",
        },
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-8} theme={null}
response = client.send.message(
    message={
        "to": {
            "intercom": {
                "to": {
                    "id": "INTERCOM_USER_ID",
                },
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-11} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "intercom": {
          "to": {
            "id": "INTERCOM_USER_ID"
          }
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-8} theme={null}
response = courier.send_.message(
  message: {
    to: {
      intercom: {
        to: {
          id: "INTERCOM_USER_ID"
        }
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"intercom": {"to": {"id": "INTERCOM_USER_ID"}}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("intercom", JsonValue.from(Map.of(
            "to", Map.of(
                "id", "INTERCOM_USER_ID"))))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-8} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'intercom' => [
        'to' => [
          'id' => 'INTERCOM_USER_ID',
        ],
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"intercom": {"to": {"id": "INTERCOM_USER_ID"}}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"intercom": {"to": {"id": "INTERCOM_USER_ID"}}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the Intercom user INTERCOM_USER_ID.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A provider override changes what Courier sends as an Intercom Message. Overrides are deep-merged into the request: fields you set replace their counterparts, and everything you leave out is still sent. You can override the message body and the From User ID. This example overrides both:

```javascript Node.js highlight={5-9,12-21} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      intercom: {
        to: {
          id: "INTERCOM_USER_ID",
        },
      },
    },
    providers: {
      intercom: {
        override: {
          body: {
            body: "I overrode this message",
            from: {
              id: "012345",
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={5-9,12-21} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "intercom": {
                "to": {
                    "id": "INTERCOM_USER_ID",
                },
            },
        },
        "providers": {
            "intercom": {
                "override": {
                    "body": {
                        "body": "I overrode this message",
                        "from": {
                            "id": "012345",
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={8-12,15-24} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "intercom": {
          "to": {
            "id": "INTERCOM_USER_ID"
          }
        }
      },
      "providers": {
        "intercom": {
          "override": {
            "body": {
              "body": "I overrode this message",
              "from": {
                "id": "012345"
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={5-9,12-21} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      intercom: {
        to: {
          id: "INTERCOM_USER_ID"
        }
      }
    },
    providers: {
      intercom: {
        override: {
          body: {
            body: "I overrode this message",
            from: {
              id: "012345"
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={4-8,16-25} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "intercom": {
    "to": {
      "id": "INTERCOM_USER_ID"
    }
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"intercom": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"body": "I overrode this message",
						"from": map[string]any{
							"id": "012345",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-10,14-21} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("intercom", JsonValue.from(java.util.Map.of(
                "to", java.util.Map.of(
                    "id", "INTERCOM_USER_ID"
                )
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("intercom", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "body", "I overrode this message",
                        "from", java.util.Map.of(
                            "id", "012345"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={5-9,12-21} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'intercom' => [
        'to' => [
          'id' => 'INTERCOM_USER_ID',
        ],
      ],
    ],
    'providers' => [
      'intercom' => [
        'override' => [
          'body' => [
            'body' => 'I overrode this message',
            'from' => [
              'id' => '012345',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={11-15,23-40} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "intercom": {
                    "to": {
                      "id": "INTERCOM_USER_ID"
                    }
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "intercom",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "body": "I overrode this message",
                            "from": {
                              "id": "012345"
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3,5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"intercom": {"to": {"id": "INTERCOM_USER_ID"}}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"intercom": {"override": {"body": {"body": "I overrode this message", "from": {"id": "012345"}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this Intercom contact with a body override.
```

Other supported overrides are documented in the [Intercom API reference](https://developers.intercom.com/intercom-api-reference/reference#admin-initiated-conversation).

## Provider details

```text theme={null}
intercom
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Trigger Opsgenie alerts from Courier
Source: https://www.courier.com/docs/integrations/other/ops-genie

Connect Opsgenie with an API key and create alerts from a template. No profile data needed.

## Prerequisites

* [An Opsgenie account](https://www.atlassian.com/software/opsgenie)
* Your Opsgenie API key

## Setup

**1. Create an Opsgenie API integration**

In Opsgenie, [create an API integration](https://support.atlassian.com/opsgenie/docs/create-a-default-api-integration/) and copy its API key.

**2. Configure in Courier**

Install the [Opsgenie integration](https://app.courier.com/integrations/catalog/opsgenie) in Courier and enter your API key.

> [!NOTE]
>
> Set a value in the `Message` field in the channel configuration. Use a static message, or add the `data` property to the API call payload.

![OpsGenie Channel Configuration](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/opsgenie-channel-configuration.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=708f37e5b31f89d72cc11105bb772348)

## Profile requirements

Opsgenie needs no profile data. Include the Opsgenie channel in your template, and Courier routes the notification to Opsgenie.

```javascript Node.js theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {},
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {},
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: {},
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => [],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient {  },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my Opsgenie template with no recipient profile data.
```

For dynamic content, include the `data` property in the API call payload:

```javascript Node.js highlight={3-4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    data: {
      metadata: {
        greeting: "Hey... DO NOT PANIC...",
      },
    },
    providers: {
      opsgenie: {
        override: {
          config: {
            apiKey: "YOUR_OPSGENIE_API_KEY",
          },
        },
      },
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
  },
});
```

```python Python highlight={3-4} theme={null}
response = client.send.message(
    message={
        "data": {
            "metadata": {
                "greeting": "Hey... DO NOT PANIC...",
            },
        },
        "providers": {
            "opsgenie": {
                "override": {
                    "config": {
                        "apiKey": "YOUR_OPSGENIE_API_KEY",
                    },
                },
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {},
    },
)
```

```bash cURL highlight={6-7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "data": {
        "metadata": {
          "greeting": "Hey... DO NOT PANIC..."
        }
      },
      "providers": {
        "opsgenie": {
          "override": {
            "config": {
              "apiKey": "YOUR_OPSGENIE_API_KEY"
            }
          }
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {}
    }
  }'
```

```ruby Ruby highlight={3-4} theme={null}
response = courier.send_.message(
  message: {
    data: {
      metadata: {
        greeting: "Hey... DO NOT PANIC..."
      }
    },
    providers: {
      opsgenie: {
        override: {
          config: {
            apiKey: "YOUR_OPSGENIE_API_KEY"
          }
        }
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {}
  }
)
```

```go Go highlight={9} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"metadata": map[string]any{
				"greeting": "Hey... DO NOT PANIC...",
			},
		},
		Providers: shared.MessageProvidersParam{
			"opsgenie": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"apiKey": "YOUR_OPSGENIE_API_KEY",
					},
				},
			},
		},
	},
})
```

```java Java highlight={5-6} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "metadata", java.util.Map.of(
                "greeting", "Hey... DO NOT PANIC..."
            )
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("opsgenie", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "apiKey", "YOUR_OPSGENIE_API_KEY"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={3-4} theme={null}
$response = $client->send->message(
  message: [
    'data' => [
      'metadata' => [
        'greeting' => 'Hey... DO NOT PANIC...',
      ],
    ],
    'providers' => [
      'opsgenie' => [
        'override' => [
          'config' => [
            'apiKey' => 'YOUR_OPSGENIE_API_KEY',
          ],
        ],
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [],
  ],
);
```

```csharp C# highlight={9} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient {  },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "metadata", JsonSerializer.Deserialize<JsonElement>(
                """
                {
                  "greeting": "Hey... DO NOT PANIC..."
                }
                """
            ) },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "opsgenie",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "apiKey": "YOUR_OPSGENIE_API_KEY"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"metadata": {"greeting": "Hey... DO NOT PANIC..."}}' \
  --message.providers '{"opsgenie": {"override": {"config": {"apiKey": "YOUR_OPSGENIE_API_KEY"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my Opsgenie template with a custom greeting in the data.
```

The delivered notification includes the value from the `data` property.

![OpsGenie Resulting Notification](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/opsgenie-resulting-notification.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=777dee0776a07b5a0deb7286f41e2506)

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

Overrides change the configuration or request body Courier sends to Opsgenie, such as the API key or the message body.

> [!NOTE]
>
> If you're using Opsgenie in the Europe region, use the URL `https://api.eu.opsgenie.com/v2` and the API key associated with your EU instance.

```javascript Node.js highlight={6-17} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      opsgenie: {
        override: {
          config: {
            apiKey: "YOUR_OPSGENIE_API_KEY",
            url: "https://api.eu.opsgenie.com/v2",
          },
          headers: {},
          body: {
            message: "YOUR MESSAGE",
          },
        },
      },
    },
  },
});
```

```python Python highlight={6-17} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {},
        "providers": {
            "opsgenie": {
                "override": {
                    "config": {
                        "apiKey": "YOUR_OPSGENIE_API_KEY",
                        "url": "https://api.eu.opsgenie.com/v2",
                    },
                    "headers": {},
                    "body": {
                        "message": "YOUR MESSAGE",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={9-20} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {},
      "providers": {
        "opsgenie": {
          "override": {
            "config": {
              "apiKey": "YOUR_OPSGENIE_API_KEY",
              "url": "https://api.eu.opsgenie.com/v2"
            },
            "headers": {},
            "body": {
              "message": "YOUR MESSAGE"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={6-17} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      opsgenie: {
        override: {
          config: {
            apiKey: "YOUR_OPSGENIE_API_KEY",
            url: "https://api.eu.opsgenie.com/v2"
          },
          headers: {},
          body: {
            message: "YOUR MESSAGE"
          }
        }
      }
    }
  }
)
```

```go Go highlight={9-20} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"opsgenie": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"apiKey": "YOUR_OPSGENIE_API_KEY",
						"url": "https://api.eu.opsgenie.com/v2",
					},
					"headers": map[string]any{},
					"body": map[string]any{
						"message": "YOUR MESSAGE",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-15} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("opsgenie", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "apiKey", "YOUR_OPSGENIE_API_KEY",
                        "url", "https://api.eu.opsgenie.com/v2"
                    ),
                    "headers", java.util.Map.of(),
                    "body", java.util.Map.of(
                        "message", "YOUR MESSAGE"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={6-17} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [],
    'providers' => [
      'opsgenie' => [
        'override' => [
          'config' => [
            'apiKey' => 'YOUR_OPSGENIE_API_KEY',
            'url' => 'https://api.eu.opsgenie.com/v2',
          ],
          'headers' => [],
          'body' => [
            'message' => 'YOUR MESSAGE',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-28} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient {  },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "opsgenie",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "apiKey": "YOUR_OPSGENIE_API_KEY",
                            "url": "https://api.eu.opsgenie.com/v2"
                          },
                          "headers": {},
                          "body": {
                            "message": "YOUR MESSAGE"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"opsgenie": {"override": {"config": {"apiKey": "YOUR_OPSGENIE_API_KEY", "url": "https://api.eu.opsgenie.com/v2"}, "headers": {}, "body": {"message": "YOUR MESSAGE"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my Opsgenie template through the EU API URL and key.
```

## Provider details

```text theme={null}
opsgenie
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Other providers
Source: https://www.courier.com/docs/integrations/other/overview

Alerting, support, and webhook destinations: PagerDuty, Opsgenie, Splunk On-Call, Drift, Intercom.

## Available providers

> **[PagerDuty](/docs/integrations/other/pagerduty)**

> **[Opsgenie](/docs/integrations/other/ops-genie)**

> **[Splunk On-Call](/docs/integrations/other/splunk-on-call)**

> **[Intercom](/docs/integrations/other/intercom)**

> **[Drift](/docs/integrations/other/drift)**

> **[Webhook](/docs/integrations/other/webhook-integration)**

> **[Custom Provider](/docs/integrations/other/custom-provider)**

## Choosing between them

Every one of these uses the same templates and the same send call as email or SMS.

**On-call alerting.** PagerDuty, Opsgenie, and Splunk On-Call turn a notification into an incident in the tool your team already pages from. PagerDuty and Opsgenie need no recipient profile data, so adding the channel to a template is enough. Splunk On-Call needs a target type and slug in the profile.

**Support and in-app messaging.** Intercom and Drift reach users inside a support widget rather than a notification channel. Both identify the recipient from profile data: an Intercom user ID or an email address.

**Anywhere else.** The [Webhook
DOC](/docs/integrations/other/webhook-integration) provider delivers a plain HTTP request. Use it to reach an internal service, or a provider Courier doesn't integrate with directly. The [Custom Provider
DOC](/docs/integrations/other/custom-provider) is its push-channel equivalent, so a webhook destination can sit alongside APNs and FCM in a push channel's provider order.

> [!TIP]
>
> Can't find a provider? Start a chat or email [support@courier.com](mailto:support@courier.com)


# Trigger PagerDuty incidents from Courier
Source: https://www.courier.com/docs/integrations/other/pagerduty

Connect PagerDuty with an Events API v2 key and trigger incidents from a template.

## Prerequisites

* [A PagerDuty account with elevated privileges](https://www.pagerduty.com/sign-up/)
* A PagerDuty Service with an Events API v2 integration

## Setup

### Configure PagerDuty integration

**1. Open your Service integrations**

In your PagerDuty account, open the Service and its "Integrations" settings.

**2. Add an Events API v2 integration**

Add a new ["Events API v2" integration](https://support.pagerduty.com/main/docs/services-and-integrations) and configure it.

**3. Copy the Integration Key**

Copy the Integration Key PagerDuty shows for the new integration.

**4. Configure the integration in Courier**

Open the [PagerDuty integration setup page](https://app.courier.com/integrations/catalog/pagerduty) in Courier and fill in the fields below, including the Integration Key.

| | |
| - | - |
| **Routing Key** | Paste the Integration Key obtained from PagerDuty. |
| **Event Action** | The event action, such as trigger. |
| **Source** | The host name or fully qualified domain name (FQDN) of the sender. |
| **Severity** | The severity level: info, warning, error, or critical. |

## Profile requirements

PagerDuty needs no recipient profile fields. Courier triggers the incident against the Service behind the integration's Events API v2 routing key.

To route one recipient elsewhere, set `pagerduty.routing_key` on their profile. It takes precedence over the key on the integration.

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    pagerduty: {
      routing_key: 'PROFILE_SPECIFIC_ROUTING_KEY',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "pagerduty": {
            "routing_key": "PROFILE_SPECIFIC_ROUTING_KEY",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "pagerduty": {
        "routing_key": "PROFILE_SPECIFIC_ROUTING_KEY"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    pagerduty: {
      routing_key: "PROFILE_SPECIFIC_ROUTING_KEY"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"pagerduty": map[string]any{
				"routing_key": "PROFILE_SPECIFIC_ROUTING_KEY",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("pagerduty", JsonValue.from(java.util.Map.of(
            "routing_key", "PROFILE_SPECIFIC_ROUTING_KEY")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'pagerduty' => [
    'routing_key' => 'PROFILE_SPECIFIC_ROUTING_KEY',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "pagerduty": {
            "routing_key": "PROFILE_SPECIFIC_ROUTING_KEY"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"pagerduty":{"routing_key":"PROFILE_SPECIFIC_ROUTING_KEY"}}'
```

```text MCP theme={null}
With Courier MCP, save the PagerDuty routing key PROFILE_SPECIFIC_ROUTING_KEY on user_123.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A provider override changes the payload Courier sends to PagerDuty's Events API, such as the severity and the source.

```javascript Node.js highlight={8-17} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      user_id: "1234567890",
    },
    providers: {
      pagerduty: {
        override: {
          body: {
            payload: {
              severity: "error",
              source: "a different source",
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-17} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "user_id": "1234567890",
        },
        "providers": {
            "pagerduty": {
                "override": {
                    "body": {
                        "payload": {
                            "severity": "error",
                            "source": "a different source",
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-20} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "user_id": "1234567890"
      },
      "providers": {
        "pagerduty": {
          "override": {
            "body": {
              "payload": {
                "severity": "error",
                "source": "a different source"
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-17} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      user_id: "1234567890"
    },
    providers: {
      pagerduty: {
        override: {
          body: {
            payload: {
              severity: "error",
              source: "a different source"
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-19} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("1234567890"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"pagerduty": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"payload": map[string]any{
							"severity": "error",
							"source": "a different source",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-13} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("1234567890").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("pagerduty", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "payload", java.util.Map.of(
                            "severity", "error",
                            "source", "a different source"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-17} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'user_id' => '1234567890',
    ],
    'providers' => [
      'pagerduty' => [
        'override' => [
          'body' => [
            'payload' => [
              'severity' => 'error',
              'source' => 'a different source',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-26} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "1234567890" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "pagerduty",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "payload": {
                              "severity": "error",
                              "source": "a different source"
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "1234567890"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"pagerduty": {"override": {"body": {"payload": {"severity": "error", "source": "a different source"}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to PagerDuty with the severity and source overridden.
```

For all supported payload overrides, see the [PagerDuty Events API v2 documentation](https://v2.developer.pagerduty.com/docs/send-an-event-events-api-v2).

## Provider details

```text theme={null}
pagerduty
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Trigger Splunk On-Call alerts from Courier
Source: https://www.courier.com/docs/integrations/other/splunk-on-call

Connect Splunk On-Call with a REST endpoint key and route alerts by target type and slug.

## Prerequisites

* Your Splunk On-Call API key and API ID

## Setup

Install the [Splunk On-Call integration](https://app.courier.com/integrations/catalog/splunk-on-call) in Courier and enter your API key and API ID.

> [!NOTE]
>
> Splunk On-Call was formerly known as VictorOps. The API documentation at `portal.victorops.com` may redirect to Splunk's current documentation.

## Profile requirements

Splunk On-Call addresses the recipient by target type and slug, under `splunk_on_call` on the profile. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3-8} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    splunk_on_call: {
      target: {
        type: 'User',
        slug: 'userSlug',
      },
    },
  },
});
```

```python Python highlight={4-9} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "splunk_on_call": {
            "target": {
                "type": "User",
                "slug": "userSlug",
            },
        },
    },
)
```

```bash cURL highlight={7-12} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "splunk_on_call": {
        "target": {
          "type": "User",
          "slug": "userSlug"
        }
      }
    }
  }'
```

```ruby Ruby highlight={4-9} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    splunk_on_call: {
      target: {
        type: "User",
        slug: "userSlug"
      }
    }
  }
)
```

```go Go highlight={6-11} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"splunk_on_call": map[string]any{
				"target": map[string]any{
					"type": "User",
					"slug": "userSlug",
				},
			},
		},
	},
)
```

```java Java highlight={4-7} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("splunk_on_call", JsonValue.from(java.util.Map.of(
            "target", java.util.Map.of(
                "type", "User",
                "slug", "userSlug"))))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-7} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'splunk_on_call' => [
    'target' => [
      'type' => 'User',
      'slug' => 'userSlug',
    ],
  ],
]);
```

```csharp C# highlight={7-12} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "splunk_on_call": {
            "target": {
              "type": "User",
              "slug": "userSlug"
            }
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"splunk_on_call":{"target":{"type":"User","slug":"userSlug"}}}'
```

```text MCP theme={null}
With Courier MCP, save the Splunk On-Call user target userSlug on user_123.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "splunk_on_call": { "target": { "type": "User", "slug": "userSlug" } } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `splunk_on_call` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `splunk_on_call`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-10} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      splunk_on_call: {
        target: {
          type: "User",
          slug: "userSlug",
        },
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-9} theme={null}
response = client.send.message(
    message={
        "to": {
            "splunk_on_call": {
                "target": {
                    "type": "User",
                    "slug": "userSlug",
                },
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-12} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "splunk_on_call": {
          "target": {
            "type": "User",
            "slug": "userSlug"
          }
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-9} theme={null}
response = courier.send_.message(
  message: {
    to: {
      splunk_on_call: {
        target: {
          type: "User",
          slug: "userSlug"
        }
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"splunk_on_call": {"target": {"type": "User", "slug": "userSlug"}}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-6} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("splunk_on_call", JsonValue.from(Map.of(
            "target", Map.of(
                "type", "User",
                "slug", "userSlug"))))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-9} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'splunk_on_call' => [
        'target' => [
          'type' => 'User',
          'slug' => 'userSlug',
        ],
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"splunk_on_call": {"target": {"type": "User", "slug": "userSlug"}}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"splunk_on_call": {"target": {"type": "User", "slug": "userSlug"}}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the Splunk On-Call user userSlug.
```

## Template requirements

Provide a summary in the notification's integration settings.

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

You can override the API key, API ID, username, URL, and request body. This example overrides the API key and username through `config`:

```javascript Node.js highlight={13-20} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      splunk_on_call: {
        target: {
          type: "User",
          slug: "sbennett",
        },
      },
    },
    providers: {
      "splunk-on-call": {
        override: {
          config: {
            apiKey: "RUNTIME_API_KEY",
            userName: "RUNTIME_USERNAME",
          },
        },
      },
    },
  },
});
```

```python Python highlight={13-20} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "splunk_on_call": {
                "target": {
                    "type": "User",
                    "slug": "sbennett",
                },
            },
        },
        "providers": {
            "splunk-on-call": {
                "override": {
                    "config": {
                        "apiKey": "RUNTIME_API_KEY",
                        "userName": "RUNTIME_USERNAME",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={16-23} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "splunk_on_call": {
          "target": {
            "type": "User",
            "slug": "sbennett"
          }
        }
      },
      "providers": {
        "splunk-on-call": {
          "override": {
            "config": {
              "apiKey": "RUNTIME_API_KEY",
              "userName": "RUNTIME_USERNAME"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={13-20} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      splunk_on_call: {
        target: {
          type: "User",
          slug: "sbennett"
        }
      }
    },
    providers: {
      "splunk-on-call": {
        override: {
          config: {
            apiKey: "RUNTIME_API_KEY",
            userName: "RUNTIME_USERNAME"
          }
        }
      }
    }
  }
)
```

```go Go highlight={17-24} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "splunk_on_call": {
    "target": {
      "type": "User",
      "slug": "sbennett"
    }
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"splunk-on-call": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"apiKey": "RUNTIME_API_KEY",
						"userName": "RUNTIME_USERNAME",
					},
				},
			},
		},
	},
})
```

```java Java highlight={15-20} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("splunk_on_call", JsonValue.from(java.util.Map.of(
                "target", java.util.Map.of(
                    "type", "User",
                    "slug", "sbennett"
                )
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("splunk-on-call", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "apiKey", "RUNTIME_API_KEY",
                        "userName", "RUNTIME_USERNAME"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={13-20} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'splunk_on_call' => [
        'target' => [
          'type' => 'User',
          'slug' => 'sbennett',
        ],
      ],
    ],
    'providers' => [
      'splunk-on-call' => [
        'override' => [
          'config' => [
            'apiKey' => 'RUNTIME_API_KEY',
            'userName' => 'RUNTIME_USERNAME',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={24-39} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "splunk_on_call": {
                    "target": {
                      "type": "User",
                      "slug": "sbennett"
                    }
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "splunk-on-call",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "apiKey": "RUNTIME_API_KEY",
                            "userName": "RUNTIME_USERNAME"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"splunk_on_call": {"target": {"type": "User", "slug": "sbennett"}}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"splunk-on-call": {"override": {"config": {"apiKey": "RUNTIME_API_KEY", "userName": "RUNTIME_USERNAME"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to Splunk On-Call with a different API key and username.
```

## Provider details

```text theme={null}
splunk-on-call
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Deliver Courier messages to your own webhook
Source: https://www.courier.com/docs/integrations/other/webhook-integration

Deliver messages as HTTP requests to a static URL or one from the profile.

## Prerequisites

* A destination URL that accepts HTTP requests

## Setup

For a static destination, set the Webhook URL and Authorization type on the [webhook integration setup page](https://app.courier.com/integrations/webhook).

## Profile requirements

Every HTTP request needs a destination.

### Dynamic destination

To set the destination per recipient, choose "Dynamic Destination" and store a `webhook` object on the profile. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3-13} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    webhook: {
      url: 'https://www.example.com',
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      authentication: {
        mode: 'bearer',
        token: 'ABCDEFG123456',
      },
    },
  },
});
```

```python Python highlight={4-14} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "webhook": {
            "url": "https://www.example.com",
            "method": "POST",
            "headers": {
                "Content-Type": "application/json",
            },
            "authentication": {
                "mode": "bearer",
                "token": "ABCDEFG123456",
            },
        },
    },
)
```

```bash cURL highlight={7-17} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "webhook": {
        "url": "https://www.example.com",
        "method": "POST",
        "headers": {
          "Content-Type": "application/json"
        },
        "authentication": {
          "mode": "bearer",
          "token": "ABCDEFG123456"
        }
      }
    }
  }'
```

```ruby Ruby highlight={4-14} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    webhook: {
      url: "https://www.example.com",
      method: "POST",
      headers: {
        "Content-Type" => "application/json"
      },
      authentication: {
        mode: "bearer",
        token: "ABCDEFG123456"
      }
    }
  }
)
```

```go Go highlight={6-16} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"webhook": map[string]any{
				"url": "https://www.example.com",
				"method": "POST",
				"headers": map[string]any{
					"Content-Type": "application/json",
				},
				"authentication": map[string]any{
					"mode": "bearer",
					"token": "ABCDEFG123456",
				},
			},
		},
	},
)
```

```java Java highlight={4-11} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("webhook", JsonValue.from(java.util.Map.of(
            "url", "https://www.example.com",
            "method", "POST",
            "headers", java.util.Map.of(
                "Content-Type", "application/json"),
            "authentication", java.util.Map.of(
                "mode", "bearer",
                "token", "ABCDEFG123456"))))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-12} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'webhook' => [
    'url' => 'https://www.example.com',
    'method' => 'POST',
    'headers' => [
      'Content-Type' => 'application/json',
    ],
    'authentication' => [
      'mode' => 'bearer',
      'token' => 'ABCDEFG123456',
    ],
  ],
]);
```

```csharp C# highlight={7-17} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "webhook": {
            "url": "https://www.example.com",
            "method": "POST",
            "headers": {
              "Content-Type": "application/json"
            },
            "authentication": {
              "mode": "bearer",
              "token": "ABCDEFG123456"
            }
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"webhook":{"url":"https://www.example.com","method":"POST","headers":{"Content-Type":"application/json"},"authentication":{"mode":"bearer","token":"ABCDEFG123456"}}}'
```

```text MCP theme={null}
With Courier MCP, save the webhook destination https://www.example.com on user_123.
```

#### Authentication

The webhook provider supports basic and bearer authentication. Set `authentication.mode` to `basic` or `bearer` and provide the credentials. The mode defaults to `none`.

```json theme={null}
{
  "mode": "basic",
  "username": "AzureDiamond",
  "password": "hunter2"
}
```

```json theme={null}
{
  "mode": "bearer",
  "token": "ABCDEFG123456"
}
```

Then send to `user_id` and Courier resolves the address.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `webhook` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `webhook`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={4-6} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      webhook: {
        url: "https://www.example.com",
      },
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-6} theme={null}
response = client.send.message(
    message={
        "to": {
            "webhook": {
                "url": "https://www.example.com",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-9} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "webhook": {
          "url": "https://www.example.com"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
response = courier.send_.message(
  message: {
    to: {
      webhook: {
        url: "https://www.example.com"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={4-6} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfWebhookRecipient: &shared.WebhookRecipientParam{
				Webhook: shared.WebhookProfileParam{URL: "https://www.example.com"},
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={4-6} theme={null}
client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(WebhookRecipient.builder()
            .webhook(WebhookProfile.builder()
                .url("https://www.example.com")
                .build())
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-6} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'webhook' => [
        'url' => 'https://www.example.com',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={6-8} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new WebhookRecipient
        {
            Webhook = new () { Url = "https://www.example.com" },
        },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"webhook": {"url": "https://www.example.com"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the webhook at https://www.example.com.
```

## Request payload

The webhook provider posts the data from your send request to the destination.

```javascript Node.js theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
      phone_number: "+12025550165",
    },
    data: {
      name: "Sarah Bennett",
      location: "Gravity Falls, OR",
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
            "phone_number": "+12025550165",
        },
        "data": {
            "name": "Sarah Bennett",
            "location": "Gravity Falls, OR",
        },
    },
)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com",
        "phone_number": "+12025550165"
      },
      "data": {
        "name": "Sarah Bennett",
        "location": "Gravity Falls, OR"
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
      phone_number: "+12025550165"
    },
    data: {
      name: "Sarah Bennett",
      location: "Gravity Falls, OR"
    }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
				PhoneNumber: courier.String("+12025550165"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
			"location": "Gravity Falls, OR",
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").phoneNumber("+12025550165").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett",
            "location", "Gravity Falls, OR"
        )))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
      'phone_number' => '+12025550165',
    ],
    'data' => [
      'name' => 'Sarah Bennett',
      'location' => 'Gravity Falls, OR',
    ],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com", PhoneNumber = "+12025550165" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
            { "location", JsonSerializer.SerializeToElement("Gravity Falls, OR") },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com", "phone_number": "+12025550165"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett", "location": "Gravity Falls, OR"}'
```

```text MCP theme={null}
With Courier MCP, send my template through the webhook provider with this recipient's details.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A provider override changes what Courier sends to the destination. You can override `url`, `method`, `headers`, and `body`. `body` and `headers` are deep-merged, so fields you leave out are still sent. `url` and `method` are replaced outright.

```javascript Node.js highlight={8-19} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      webhook: {
        override: {
          url: "https://www.example.com",
          method: "PUT",
          headers: {
            "X-Custom-Header": "Hello from Courier",
          },
          body: {
            key: "value",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-19} theme={null}
response = client.send.message(
    message={
        "to": {
          "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "webhook": {
                "override": {
                  "url": "https://www.example.com",
                  "method": "PUT",
                  "headers": {
                    "X-Custom-Header": "Hello from Courier",
                  },
                  "body": {
                    "key": "value",
                  },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-22} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "user_id": "user_123"
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
          "webhook": {
            "override": {
              "url": "https://www.example.com",
              "method": "PUT",
              "headers": {
                "X-Custom-Header": "Hello from Courier"
              },
              "body": {
                "key": "value"
              }
            }
          }
        }
      }
    }'
```

```ruby Ruby highlight={8-19} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "webhook" => {
        override: {
          url: "https://www.example.com",
          method: "PUT",
          headers: {
            "X-Custom-Header" => "Hello from Courier"
          },
          body: {
            key: "value"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-21} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"webhook": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"url": "https://www.example.com",
					"method": "PUT",
					"headers": map[string]any{
						"X-Custom-Header": "Hello from Courier",
					},
					"body": map[string]any{
						"key": "value",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("webhook", JsonValue.from(java.util.Map.of(
                "override", java.util.Map.of("url", "https://www.example.com", "method", "PUT", "headers", java.util.Map.of("X-Custom-Header", "Hello from Courier"), "body", java.util.Map.of("key", "value")))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-19} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'providers' => [
      'webhook' => [
        'override' => [
          'url' => 'https://www.example.com',
          'method' => 'PUT',
          'headers' => [
            'X-Custom-Header' => 'Hello from Courier',
          ],
          'body' => [
            'key' => 'value',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-21} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "webhook",
                new()
                {
                    Override = new Dictionary<string, JsonElement>()
                    {
                        { "url", JsonSerializer.SerializeToElement("https://www.example.com") },
                        { "method", JsonSerializer.SerializeToElement("PUT") },
                        { "headers", JsonSerializer.SerializeToElement(new { X-Custom-Header = "Hello from Courier" }) },
                        { "body", JsonSerializer.SerializeToElement(new { key = "value" }) },
                    },
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"webhook": {"override": {"url": "https://www.example.com", "method": "PUT", "headers": {"X-Custom-Header": "Hello from Courier"}, "body": {"key": "value"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 over the webhook provider and override the destination URL.
```

## Provider details

```text theme={null}
webhook
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Integrations
Source: https://www.courier.com/docs/integrations/overview

Connect your email, SMS, push, chat, CDP, and observability providers to Courier.

Courier integrates with providers across email, SMS, push, chat, and in-app. Send through any of them with one API call.

Connect the providers your system already uses. Courier handles routing, failover, retries, and rate limits.

## Which type of notification are you sending?

Start with the channel you need. Each introduction page lists that category's providers, the profile fields that address a recipient, and the send-time overrides.

> **[Email](/docs/integrations/email/overview)**
>
> From Amazon SES and SendGrid to a generic SMTP relay.

> **[SMS](/docs/integrations/sms/overview)**
>
> Twilio, Vonage, Sinch, and regional carriers.

> **[Push](/docs/integrations/push/overview)**
>
> For iOS, Android, web, and React Native.

> **[Chat & direct message](/docs/integrations/direct-message/overview)**
>
> Slack, Teams, WhatsApp, and Discord.

> **[In-app](/docs/in-app/overview)**
>
> Courier Inbox, on the In-App tab. Nothing to connect.

> **[Other Providers](/docs/integrations/other/overview)**
>
> On-call alerting, support tools, and webhooks to anywhere else.

Two categories carry data rather than messages:

> **[Customer data platforms](/docs/integrations/cdp/overview)**
>
> Sync profiles and trigger sends from Segment or RudderStack events.

> **[Observability](/docs/integrations/observability/overview)**
>
> Export delivery metrics to Datadog, New Relic, or OpenTelemetry.

### Most-used providers

Each channel's full list lives on its introduction page. Here are the most popular, in order:

#### Email

> **[SendGrid](/docs/integrations/email/sendgrid)**

> **[Amazon SES](/docs/integrations/email/aws-ses)**

> **[Mailgun](/docs/integrations/email/mailgun)**

> **[Postmark](/docs/integrations/email/postmark)**

> **[Resend](/docs/integrations/email/resend)**

> **[SMTP](/docs/integrations/email/smtp)**

#### SMS

> **[Twilio](/docs/integrations/sms/twilio)**

> **[Vonage](/docs/integrations/sms/vonage)**

> **[Bird](/docs/integrations/sms/bird)**

> **[Plivo](/docs/integrations/sms/plivo)**

> **[Sinch](/docs/integrations/sms/sinch)**

#### Push

> **[Firebase FCM](/docs/integrations/push/firebase-fcm)**

> **[Apple APNs](/docs/integrations/push/apple-push-notification)**

> **[Expo](/docs/integrations/push/expo)**

> **[OneSignal](/docs/integrations/push/onesignal-push)**

#### Chat

> **[Slack](/docs/integrations/direct-message/slack)**

> **[Microsoft Teams](/docs/integrations/direct-message/microsoft-teams)**

> **[WhatsApp](/docs/integrations/direct-message/whatsapp)**

> **[Discord](/docs/integrations/direct-message/discord)**

#### Alerting

> **[PagerDuty](/docs/integrations/other/pagerduty)**

> **[Opsgenie](/docs/integrations/other/ops-genie)**

***

## Connecting a provider

**1. Get credentials from the provider**

Get the API key or authentication token from the provider. Your channel's introduction page links to each provider's page, which names the credentials that provider needs.

**2. Add the provider in Courier**

Open the [Integrations Catalog](https://app.courier.com/integrations/catalog) and add the provider.

**3. Test the connection**

Verify your credentials and confirm Courier can send through the provider.

**4. Add the channel to a template**

To send through the provider from a template, activate its channel's tab in Design Studio and include that channel in the template's [routing strategy
DOC](/docs/send/routing-strategies). The strategy also sets the fallback order and provider priority.

> [!NOTE]
>
> Provider API keys are configured **per environment**. SendGrid set up in Production also needs its API key added in Test to send test messages. A missing provider configuration gives a `MISSING_CONFIGURATION` error in your message logs.

***

## What Courier handles for you

Once a provider is connected, delivery behavior comes from Courier, not your code:

* **Routing and failover.** Courier picks the channel and provider per send. It moves to the next one when a provider fails. See [how routing & failover work
  DOC](/docs/send/routing).
* **Provider metrics.** Delivery rates, latency, and error rates per provider appear in the Analytics dashboard. See [analytics
  DOC](/docs/monitor/analytics).
* **Rate limit backoff.** Provider 429s are queued and retried on the schedule below.

### Rate limit management

To keep sends under a provider's limits, set a [send rate limit
DOC](/docs/integrations/send-rate-limits) on its configuration. When a provider returns a rate limit error (HTTP 429), Courier queues the message and retries with exponential backoff:

| Attempt | Delay |
| - | - |
| 1 | 5 seconds |
| 2 | 10 seconds |
| 3 | 20 seconds |
| 4 | 40 seconds |
| 5 | 60 seconds |
| 6 | 2 minutes |
| 7 | 4 minutes |
| 8 | 8 minutes |
| 9 | 12 minutes |
| 10+ | 15 minutes |

Retries continue for up to **24 hours** (approximately 104 total attempts). A provider `Retry-After` header overrides the default backoff schedule.

After retries are exhausted, Courier attempts [failover
DOC](/docs/send/routing#failover) to another configured provider or channel. With no alternative, the message is marked `UNDELIVERABLE`.


# Send push with Airship through Courier
Source: https://www.courier.com/docs/integrations/push/airship

Connect Airship with an app key and secret, and target audience and device_types from the profile.

## Prerequisites

* [An Airship account with a project](https://www.airship.com/)
* Your Airship auth token and base URL

## Setup

**1. Create an Airship auth token**

In Airship, open your project at [go.airship.com](https://go.airship.com/) and create a bearer token. The base URL is your project's region endpoint.

**2. Configure in Courier**

Open the [Airship Integration](https://app.courier.com/integrations/catalog/airship) in Courier, enter your auth token and base URL, then click "Save."

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

Airship addresses the recipient by audience and device types, both under `airship` on the profile. Store them once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3-10} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    airship: {
      audience: {
        named_user: 'user_123',
      },
      device_types: [
        'ios',
      ],
    },
  },
});
```

```python Python highlight={4-11} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "airship": {
            "audience": {
                "named_user": "user_123",
            },
            "device_types": [
                "ios",
            ],
        },
    },
)
```

```bash cURL highlight={7-14} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "airship": {
        "audience": {
          "named_user": "user_123"
        },
        "device_types": [
          "ios"
        ]
      }
    }
  }'
```

```ruby Ruby highlight={4-9} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    airship: {
      audience: {
        named_user: "user_123"
      },
      device_types: ["ios"]
    }
  }
)
```

```go Go highlight={6-11} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"airship": map[string]any{
				"audience": map[string]any{
					"named_user": "user_123",
				},
				"device_types": []any{"ios"},
			},
		},
	},
)
```

```java Java highlight={4-7} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("airship", JsonValue.from(java.util.Map.of(
            "audience", java.util.Map.of(
                "named_user", "user_123"),
            "device_types", java.util.List.of("ios"))))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-7} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'airship' => [
    'audience' => [
      'named_user' => 'user_123',
    ],
    'device_types' => ['ios'],
  ],
]);
```

```csharp C# highlight={7-14} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "airship": {
            "audience": {
              "named_user": "user_123"
            },
            "device_types": [
              "ios"
            ]
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"airship":{"audience":{"named_user":"user_123"},"device_types":["ios"]}}'
```

```text MCP theme={null}
With Courier MCP, save the Airship named user user_123 on user_123, for iOS.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "airship": { "audience": { "named_user": "user_123" }, "device_types": ["ios"] } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `airship` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `airship`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-10} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      airship: {
        audience: {
          named_user: "user_123",
        },
        device_types: ["ios"],
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-9} theme={null}
response = client.send.message(
    message={
        "to": {
            "airship": {
                "audience": {
                    "named_user": "user_123",
                },
                "device_types": ["ios"],
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-14} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "airship": {
          "audience": {
            "named_user": "user_123"
          },
          "device_types": [
            "ios"
          ]
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-9} theme={null}
response = courier.send_.message(
  message: {
    to: {
      airship: {
        audience: {
          named_user: "user_123"
        },
        device_types: ["ios"]
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"airship": {"audience": {"named_user": "user_123"}, "device_types": ["ios"]}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-6} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("airship", JsonValue.from(Map.of(
            "audience", Map.of(
                "named_user", "user_123"),
            "device_types", List.of("ios"))))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-9} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'airship' => [
        'audience' => [
          'named_user' => 'user_123',
        ],
        'device_types' => ['ios'],
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"airship": {"audience": {"named_user": "user_123"}, "device_types": ["ios"]}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"airship": {"audience": {"named_user": "user_123"}, "device_types": ["ios"]}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the Airship named user user_123.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

A provider override changes what Courier sends to Airship's API. For example, use basic auth on one send request:

```javascript Node.js highlight={5-12,18-25} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      airship: {
        audience: {
          named_user: "user_123",
        },
        device_types: [
          "ios",
        ],
      },
    },
    data: {
      dataForPushMessage: true,
    },
    providers: {
      airship: {
        override: {
          body: {},
          headers: {
            Authorization: "Basic <EncodedAppKey:AppSecret>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={5-12,18-25} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "airship": {
                "audience": {
                    "named_user": "user_123",
                },
                "device_types": [
                    "ios",
                ],
            },
        },
        "data": {
            "dataForPushMessage": True,
        },
        "providers": {
            "airship": {
                "override": {
                    "body": {},
                    "headers": {
                        "Authorization": "Basic <EncodedAppKey:AppSecret>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={8-15,21-28} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "airship": {
          "audience": {
            "named_user": "user_123"
          },
          "device_types": [
            "ios"
          ]
        }
      },
      "data": {
        "dataForPushMessage": true
      },
      "providers": {
        "airship": {
          "override": {
            "body": {},
            "headers": {
              "Authorization": "Basic <EncodedAppKey:AppSecret>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={5-12,18-25} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      airship: {
        audience: {
          named_user: "user_123"
        },
        device_types: [
          "ios"
        ]
      }
    },
    data: {
      dataForPushMessage: true
    },
    providers: {
      airship: {
        override: {
          body: {},
          headers: {
            Authorization: "Basic <EncodedAppKey:AppSecret>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={4-11,22-29} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "airship": {
    "audience": {
      "named_user": "user_123"
    },
    "device_types": [
      "ios"
    ]
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"dataForPushMessage": true,
		},
		Providers: shared.MessageProvidersParam{
			"airship": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{},
					"headers": map[string]any{
						"Authorization": "Basic <EncodedAppKey:AppSecret>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-13,20-25} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("airship", JsonValue.from(java.util.Map.of(
                "audience", java.util.Map.of(
                    "named_user", "user_123"
                ),
                "device_types", java.util.List.of(
                    "ios"
                )
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "dataForPushMessage", true
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("airship", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(),
                    "headers", java.util.Map.of(
                        "Authorization", "Basic <EncodedAppKey:AppSecret>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={5-12,18-25} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'airship' => [
        'audience' => [
          'named_user' => 'user_123',
        ],
        'device_types' => [
          'ios',
        ],
      ],
    ],
    'data' => [
      'dataForPushMessage' => true,
    ],
    'providers' => [
      'airship' => [
        'override' => [
          'body' => [],
          'headers' => [
            'Authorization' => 'Basic <EncodedAppKey:AppSecret>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={11-18,30-45} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "airship": {
                    "audience": {
                      "named_user": "user_123"
                    },
                    "device_types": [
                      "ios"
                    ]
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "dataForPushMessage", JsonSerializer.SerializeToElement(true) },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "airship",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {},
                          "headers": {
                            "Authorization": "Basic <EncodedAppKey:AppSecret>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3,6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"airship": {"audience": {"named_user": "user_123"}, "device_types": ["ios"]}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"dataForPushMessage": true}' \
  --message.providers '{"airship": {"override": {"body": {}, "headers": {"Authorization": "Basic <EncodedAppKey:AppSecret>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template through Airship using basic auth on this one send.
```

Overrides are deep-merged into the request. Fields you set replace their counterparts, and everything you leave out is still sent. The full field list is in [Airship's API docs](https://docs.airship.com/api/ua/).

## Tracking events

Courier puts the tracking URL in the `global_attributes` data bag. See [push notification tracking
DOC](/docs/integrations/push/overview#tracking) for details.

## Provider details

```text theme={null}
airship
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send iOS push with APNs through Courier
Source: https://www.courier.com/docs/integrations/push/apple-push-notification

Connect APNs with a .p8 key, team ID, and bundle ID, and sync device tokens with the iOS SDK.

## Prerequisites

* [An Apple Developer account](https://developer.apple.com/account)
* An APNs authentication key, downloaded as a `.p8` file
* Your team identifier and the app bundle ID you send to
* A physical iOS device, since simulators don't receive push

## Setup

**1. Create an APNs key**

In your [Apple Developer Account](https://developer.apple.com/account), open **Certificates → Keys** and add a key. Enable **Apple Push Notifications service (APNs)**, register it, and download the `.p8` file.

**2. Enter your credentials**

Open the [APNs provider configuration](https://app.courier.com/integrations/catalog/apn) and fill in four fields:

* **Key Id**, the identifier of the APNs key.
* **Key**, the full contents of the downloaded `.p8` file.
* **Team Id**, your Apple Developer team identifier.
* **Topic (App Bundle Id)**, the bundle ID of the app you're sending to.

Then set the two toggles:

* **Send to Production**, off by default. Off targets Apple's sandbox, which a local development build needs. On targets production, for your App Store app. Getting this wrong is the usual cause of [`BadEnvironmentKeyInToken`](#badenvironmentkeyintoken).
* **Attach Mutable Content**, on by default. It adds `"mutable-content": 1`, which is what lets Courier's [Notification Service Extension
  DOC](/docs/sdk-libraries/ios#notification-service-extension) run before the alert appears. The extension is what reports a delivery while your app is closed. Turn this off and delivery only registers in the foreground. See [Delivery and click tracking
  GUIDE](/docs/guides/set-up-mobile-push#delivery-and-click-tracking).

![APNs provider configuration showing the Send to Production and Attach Mutable Content toggles](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/apns-auto-override.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=19359965ffd78512f7e4a0c3eb59fc38)

The APNs provider configuration with the Send to Production and Attach Mutable Content toggles.

**3. Install the provider**

Click "Install Provider" or "Save".

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

APNs addresses the device by token, so the profile you send to needs an `apn` object. Store the token once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

**One device**

`apn.token` holds a single device token.

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    apn: {
      token: 'YOUR_APNS_TOKEN',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "apn": {
            "token": "YOUR_APNS_TOKEN",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "apn": {
        "token": "YOUR_APNS_TOKEN"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    apn: {
      token: "YOUR_APNS_TOKEN"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"apn": map[string]any{
				"token": "YOUR_APNS_TOKEN",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("apn", JsonValue.from(java.util.Map.of(
            "token", "YOUR_APNS_TOKEN")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'apn' => [
    'token' => 'YOUR_APNS_TOKEN',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "apn": {
            "token": "YOUR_APNS_TOKEN"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"apn":{"token":"YOUR_APNS_TOKEN"}}'
```

```text MCP theme={null}
With Courier MCP, save the APNs token YOUR_APNS_TOKEN on user_123.
```

**Several devices**

`apn.tokens` holds every device that user signs in on. Courier delivers to all of them.

```javascript Node.js highlight={3-8} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    apn: {
      tokens: [
        'APNS_TOKEN_ONE',
        'APNS_TOKEN_TWO',
      ],
    },
  },
});
```

```python Python highlight={4-9} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "apn": {
            "tokens": [
                "APNS_TOKEN_ONE",
                "APNS_TOKEN_TWO",
            ],
        },
    },
)
```

```bash cURL highlight={7-12} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "apn": {
        "tokens": [
          "APNS_TOKEN_ONE",
          "APNS_TOKEN_TWO"
        ]
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    apn: {
      tokens: ["APNS_TOKEN_ONE", "APNS_TOKEN_TWO"]
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"apn": map[string]any{
				"tokens": []any{"APNS_TOKEN_ONE", "APNS_TOKEN_TWO"},
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("apn", JsonValue.from(java.util.Map.of(
            "tokens", java.util.List.of("APNS_TOKEN_ONE", "APNS_TOKEN_TWO"))))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'apn' => [
    'tokens' => ['APNS_TOKEN_ONE', 'APNS_TOKEN_TWO'],
  ],
]);
```

```csharp C# highlight={7-12} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "apn": {
            "tokens": [
              "APNS_TOKEN_ONE",
              "APNS_TOKEN_TWO"
            ]
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"apn":{"tokens":["APNS_TOKEN_ONE","APNS_TOKEN_TWO"]}}'
```

```text MCP theme={null}
With Courier MCP, save the APNs tokens APNS_TOKEN_ONE and APNS_TOKEN_TWO on user_123.
```

A Courier mobile SDK writes that object for you once you extend `CourierDelegate`, so you send to a `user_id` and never handle a token. APNs is Apple-only, so that means the [iOS
DOC](/docs/sdk-libraries/ios), [React Native
DOC](/docs/sdk-libraries/react-native), and [Flutter
DOC](/docs/sdk-libraries/flutter) SDKs. The Android SDK uses [FCM
DOC](/docs/integrations/push/firebase-fcm) instead.

For a one-off with no stored profile, pass it inline instead: `"to": { "apn": { "token": "YOUR_APNS_TOKEN" } }`.

> **[Set up push notifications](/docs/guides/set-up-mobile-push)**
>
> Wire up the SDK, sync tokens, and send your first push.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `apn` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to a token**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

| To address | Use |
| - | - |
| One device | `"to": { "apn": { "token": "YOUR_APNS_TOKEN" } }` |
| Several devices | `"to": { "apn": { "tokens": ["APNS_TOKEN_ONE", "APNS_TOKEN_TWO"] } }` |
| A user, and a specific device | `"to": { "user_id": "user_123", "apn": { "token": "YOUR_APNS_TOKEN" } }` |

> [!NOTE]
>
> Include a `user_id` alongside the token to keep the send tied to that person. Courier then keeps their stored preferences and profile, managed token lookup, expiry, sign-out cleanup, and `bundleId` filtering, and delivery and click events on their history. Without a `user_id`, Courier logs the message under a synthetic `anon_<hash>` recipient instead.

To pick among several tokens on one user, see [Targeting specific devices
DOC](/docs/integrations/push/overview#targeting-specific-devices).

```javascript Node.js highlight={5-7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      apn: {
        token: "YOUR_APNS_TOKEN",
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-6} theme={null}
response = client.send.message(
    message={
        "to": {
            "apn": {
                "token": "YOUR_APNS_TOKEN",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-9} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "apn": {
          "token": "YOUR_APNS_TOKEN"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
response = courier.send_.message(
  message: {
    to: {
      apn: {
        token: "YOUR_APNS_TOKEN"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"apn": {"token": "YOUR_APNS_TOKEN"}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("apn", JsonValue.from(Map.of(
            "token", "YOUR_APNS_TOKEN")))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-6} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'apn' => [
        'token' => 'YOUR_APNS_TOKEN',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"apn": {"token": "YOUR_APNS_TOKEN"}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"apn": {"token": "YOUR_APNS_TOKEN"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the APNs token YOUR_APNS_TOKEN.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

An APNs override sits at `providers.apn.override`. `body` changes the notification, and `config` swaps the credentials the send authenticates with.

### Body overrides

Courier compiles the reserved `aps` dictionary from the message content and these fields.

| Field | Sets |
| - | - |
| `payload` | Custom data at the payload root, beside `aps`. Your app reads these keys on tap. Unlike FCM, APNs preserves nested objects and non-string types. |
| `alert` | The title, subtitle, and body Courier rendered from the message. |
| `sound` | The tone played. Defaults to `ping.aiff`, so every push plays the default tone. |
| `badge` | The app icon badge, as a number. Courier ignores `0`, so a send can't clear the badge. |
| `expiry` | A Unix timestamp for how long APNs keeps retrying. Defaults to one hour after the send. |
| `topic` | The bundle id the push targets. |
| `category` | The notification category, for actionable notifications. |
| `threadId` | The thread the notification groups into. |
| `content-available` | Background delivery. A value above `0` marks the push content-available. |
| `apns-priority` | The delivery priority APNs sends at. |
| `apns-collapse-id` | The id APNs coalesces notifications on. |

For a push that carries data but shows no alert, see [silent push
DOC](/docs/send/push/custom-data#send-data-with-no-visible-alert).

### Config overrides

Each of these replaces the integration's own credentials and settings, for one send.

| Field | Replaces |
| - | - |
| `isProduction` | Which APNs environment the send targets. Defaults to `true`. |
| `mutableContent` | Whether the push is marked mutable, for a notification service extension. |
| `teamId` | The Apple team the send authenticates as. |
| `key` and `keyId` | The `.p8` key and its id, on p8 auth. |
| `pfx` and `passphrase` | The `.p12` certificate and its password, on p12 auth. `passphrase` replaces the integration's `pfxPassword`. |

**`override.body.aps` replaces the `aps` dictionary, it doesn't merge.** The rendered `alert`, `sound`, `badge`, `category`, `thread-id`, and `content-available` are all discarded unless you restate them. Use the individual fields above to change one and keep the rest.

An `aps` override leaves the rest of the request alone. `expiry`, `topic`, `apns-priority`, `apns-collapse-id`, and your own `payload` keys are headers or sit outside `aps`, and mutable content is applied afterward.

### Override the payload

The `apn` override applies whenever APNs is the provider that runs.

```javascript Node.js highlight={15-23} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push",
      ],
    },
    providers: {
      apn: {
        override: {
          body: {
            sound: "ping.aiff",
            badge: 99,
            payload: {
              YOUR_CUSTOM_KEY: "YOUR_CUSTOM_VALUE",
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={15-23} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": [
                "push",
            ],
        },
        "providers": {
            "apn": {
                "override": {
                    "body": {
                        "sound": "ping.aiff",
                        "badge": 99,
                        "payload": {
                            "YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE",
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={18-26} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": [
          "push"
        ]
      },
      "providers": {
        "apn": {
          "override": {
            "body": {
              "sound": "ping.aiff",
              "badge": 99,
              "payload": {
                "YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={15-23} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push"
      ]
    },
    providers: {
      apn: {
        override: {
          body: {
            sound: "ping.aiff",
            badge: 99,
            payload: {
              YOUR_CUSTOM_KEY: "YOUR_CUSTOM_VALUE"
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={17-25} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
			},
			Method: "single",
		},
		Providers: shared.MessageProvidersParam{
			"apn": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"sound": "ping.aiff",
						"badge": 99,
						"payload": map[string]any{
							"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={10-18} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("push")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .providers(MessageProviders.builder()
            .putAdditionalProperty("apn", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "sound", "ping.aiff",
                        "badge", 99,
                        "payload", java.util.Map.of(
                            "YOUR_CUSTOM_KEY", "YOUR_CUSTOM_VALUE"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={15-23} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => [
        'push',
      ],
    ],
    'providers' => [
      'apn' => [
        'override' => [
          'body' => [
            'sound' => 'ping.aiff',
            'badge' => 99,
            'payload' => [
              'YOUR_CUSTOM_KEY' => 'YOUR_CUSTOM_VALUE',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={14-26} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["push"], Method = Send::Method.Single },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "apn",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "sound": "ping.aiff",
                            "badge": 99,
                            "payload": {
                              "YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push"]}' \
  --message.providers '{"apn": {"override": {"body": {"sound": "ping.aiff", "badge": 99, "payload": {"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 on push, with an APNs sound and badge.
```

Custom data, deep links on tap, and silent pushes are the same call with a different payload. [Set up push notifications
GUIDE](/docs/guides/set-up-mobile-push) covers each, including where APNs and FCM differ.

Custom data not reaching the device? [Data mapping
DOC](/docs/design/templates/data-mapping) covers the one template setting that stops it.

## Troubleshooting

### `BadDeviceToken`

APNs returns `BadDeviceToken` when the token doesn't match any registered device for the environment you target (production vs. sandbox). Common causes:

* **Wrong environment**: a token registered against the sandbox environment fails in production, and vice versa. Check the **Send to Production** toggle in the [APNs provider configuration](https://app.courier.com/integrations/catalog/apn).
* **Stale token**: the user uninstalled and reinstalled the app, generating a new token. Update the stored token via the [Device Tokens API](/docs/api-reference/device-tokens/add-a-token-to-a-user) when your app receives a new registration token.
* **Token never registered**: the token was never added to a Courier user profile. Your app must call the registration step on every launch.

### `BadEnvironmentKeyInToken`

The key that signed the APNs JWT belongs to a different team or bundle ID than the token. Check that the **Team ID** and **Key ID** in your Courier APNs configuration match the app whose tokens you send.

### Invalid device tokens

Courier records rejected tokens so later sends skip them. This applies only to **managed tokens**, the ones a Courier Mobile SDK syncs. Tokens you pass in `apn.token` or `apn.tokens` are used as sent.

* `BadDeviceToken`, `Unregistered`, `DeviceTokenNotForTopic`, and `MissingDeviceToken` mark that token failed until the device registers a fresh one.
* The status is scoped **to one token and user**. Other users, tokens, and channels are unaffected.
* Managed tokens not refreshed in **60 days** go stale and are skipped. The SDKs refresh on app launch.

> [!TIP]
>
> If a user stops receiving push notifications, confirm their device has registered a current token. Reinstalling the app generates a new one. Confirm your app calls the Courier SDK's token registration on every launch.

## Provider details

```text theme={null}
apn
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send push with Amazon SNS for push through Courier
Source: https://www.courier.com/docs/integrations/push/aws-sns

Connect Amazon SNS for push with IAM credentials and target a topic or endpoint ARN.

Amazon Simple Notification Service, also written as Amazon SNS or AWS SNS, pushes to devices subscribed to an SNS topic or target ARN.

Its Courier provider key is `aws-sns`.

> [!NOTE]
>
> Amazon SNS also works as an SMS provider. See [Amazon SNS for SMS
> DOC](/docs/integrations/sms/aws-sns).

## Prerequisites

* [An AWS account with an IAM user for SNS](https://aws.amazon.com/)
* [Your Access Key ID and Secret Access Key](https://console.aws.amazon.com/iam/)
* The AWS region for your SNS topics

## Setup

**1. Create an AWS access key**

In AWS, create an IAM user with SNS publish permission and copy its [access key ID and secret access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).

**2. Configure in Courier**

Open the [Amazon SNS integration](https://app.courier.com/integrations/catalog/aws-sns) in Courier, enter your Access Key ID and Secret Access Key, choose your region, then click "Complete."

You only add the integration once. It is then available as a provider on both the push and SMS channels.

> [!WARNING]
>
> Leave Topic ARN empty to push to individual devices. A saved Topic ARN outranks the Target ARN on a recipient's profile, so every push goes to the topic instead. See [Destination precedence](#destination-precedence).

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

SNS addresses the device by the Target ARN it is subscribed to, nested under `aws_sns` on the profile. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    aws_sns: {
      target_arn: 'your:target:arn',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "aws_sns": {
            "target_arn": "your:target:arn",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "aws_sns": {
        "target_arn": "your:target:arn"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    aws_sns: {
      target_arn: "your:target:arn"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"aws_sns": map[string]any{
				"target_arn": "your:target:arn",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("aws_sns", JsonValue.from(java.util.Map.of(
            "target_arn", "your:target:arn")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'aws_sns' => [
    'target_arn' => 'your:target:arn',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "aws_sns": {
            "target_arn": "your:target:arn"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"aws_sns":{"target_arn":"your:target:arn"}}'
```

```text MCP theme={null}
With Courier MCP, save the SNS target ARN your:target:arn on user_123.
```

To use a Topic ARN instead, set it on the integration or pass it as a [`config` override](#overrides). It isn't read from the recipient profile.

### Destination precedence

Courier picks exactly one SNS destination per message, in this order:

1. `phone_number` on the profile, which sends an SMS rather than a push
2. Topic ARN, from the integration config or a `config` override
3. `aws_sns.target_arn` on the profile

The first one present wins and the rest are discarded. Nothing is sent if none of the three is set.

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "aws_sns": { "target_arn": "your:target:arn" } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `aws_sns` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `aws_sns`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      aws_sns: {
        target_arn: "your:target:arn",
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-6} theme={null}
response = client.send.message(
    message={
        "to": {
            "aws_sns": {
                "target_arn": "your:target:arn",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-9} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "aws_sns": {
          "target_arn": "your:target:arn"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
response = courier.send_.message(
  message: {
    to: {
      aws_sns: {
        target_arn: "your:target:arn"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"aws_sns": {"target_arn": "your:target:arn"}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("aws_sns", JsonValue.from(Map.of(
            "target_arn", "your:target:arn")))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-6} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'aws_sns' => [
        'target_arn' => 'your:target:arn',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"aws_sns": {"target_arn": "your:target:arn"}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"aws_sns": {"target_arn": "your:target:arn"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the SNS target arn your:target:arn.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

The `config` override swaps credentials, region, or the Topic ARN at send time:

| Field | Effect |
| - | - |
| `accessKeyId` | Replaces the saved Access Key ID |
| `secretAccessKey` | Replaces the saved Secret Access Key |
| `region` | Replaces the saved region. Defaults to `us-east-1` if neither is set |
| `topicArn` | Replaces the saved Topic ARN, and still outranks a profile's `target_arn` |

```javascript Node.js highlight={10-18} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      aws_sns: {
        target_arn: "your:target:arn",
      },
    },
    providers: {
      "aws-sns": {
        override: {
          config: {
            accessKeyId: "RUNTIME_ACCESS_KEY_ID",
            secretAccessKey: "RUNTIME_SECRET_ACCESS_KEY",
            region: "eu-west-1",
          },
        },
      },
    },
  },
});
```

```python Python highlight={10-18} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "aws_sns": {
                "target_arn": "your:target:arn",
            },
        },
        "providers": {
            "aws-sns": {
                "override": {
                    "config": {
                        "accessKeyId": "RUNTIME_ACCESS_KEY_ID",
                        "secretAccessKey": "RUNTIME_SECRET_ACCESS_KEY",
                        "region": "eu-west-1",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={13-21} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "aws_sns": {
          "target_arn": "your:target:arn"
        }
      },
      "providers": {
        "aws-sns": {
          "override": {
            "config": {
              "accessKeyId": "RUNTIME_ACCESS_KEY_ID",
              "secretAccessKey": "RUNTIME_SECRET_ACCESS_KEY",
              "region": "eu-west-1"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={10-18} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      aws_sns: {
        target_arn: "your:target:arn"
      }
    },
    providers: {
      "aws-sns": {
        override: {
          config: {
            accessKeyId: "RUNTIME_ACCESS_KEY_ID",
            secretAccessKey: "RUNTIME_SECRET_ACCESS_KEY",
            region: "eu-west-1"
          }
        }
      }
    }
  }
)
```

```go Go highlight={14-22} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "aws_sns": {
    "target_arn": "your:target:arn"
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"aws-sns": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"accessKeyId": "RUNTIME_ACCESS_KEY_ID",
						"secretAccessKey": "RUNTIME_SECRET_ACCESS_KEY",
						"region": "eu-west-1",
					},
				},
			},
		},
	},
})
```

```java Java highlight={12-18} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("aws_sns", JsonValue.from(java.util.Map.of(
                "target_arn", "your:target:arn"
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("aws-sns", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "accessKeyId", "RUNTIME_ACCESS_KEY_ID",
                        "secretAccessKey", "RUNTIME_SECRET_ACCESS_KEY",
                        "region", "eu-west-1"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={10-18} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'aws_sns' => [
        'target_arn' => 'your:target:arn',
      ],
    ],
    'providers' => [
      'aws-sns' => [
        'override' => [
          'config' => [
            'accessKeyId' => 'RUNTIME_ACCESS_KEY_ID',
            'secretAccessKey' => 'RUNTIME_SECRET_ACCESS_KEY',
            'region' => 'eu-west-1',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={21-37} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "aws_sns": {
                    "target_arn": "your:target:arn"
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "aws-sns",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "accessKeyId": "RUNTIME_ACCESS_KEY_ID",
                            "secretAccessKey": "RUNTIME_SECRET_ACCESS_KEY",
                            "region": "eu-west-1"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"aws_sns": {"target_arn": "your:target:arn"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"aws-sns": {"override": {"config": {"accessKeyId": "RUNTIME_ACCESS_KEY_ID", "secretAccessKey": "RUNTIME_SECRET_ACCESS_KEY", "region": "eu-west-1"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this SNS target ARN in a different region.
```

The `body` override merges into the SNS `Publish` request itself, so its fields use the AWS parameter names rather than Courier's. See the [SNS publish properties](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SNS.html#publish-property).

```javascript Node.js highlight={10-17} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      aws_sns: {
        target_arn: "your:target:arn",
      },
    },
    providers: {
      "aws-sns": {
        override: {
          body: {
            Subject: "Order update",
            MessageStructure: "json",
          },
        },
      },
    },
  },
});
```

```python Python highlight={10-17} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "aws_sns": {
                "target_arn": "your:target:arn",
            },
        },
        "providers": {
            "aws-sns": {
                "override": {
                    "body": {
                        "Subject": "Order update",
                        "MessageStructure": "json",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={13-20} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "aws_sns": {
          "target_arn": "your:target:arn"
        }
      },
      "providers": {
        "aws-sns": {
          "override": {
            "body": {
              "Subject": "Order update",
              "MessageStructure": "json"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={10-17} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      aws_sns: {
        target_arn: "your:target:arn"
      }
    },
    providers: {
      "aws-sns": {
        override: {
          body: {
            Subject: "Order update",
            MessageStructure: "json"
          }
        }
      }
    }
  }
)
```

```go Go highlight={14-21} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "aws_sns": {
    "target_arn": "your:target:arn"
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"aws-sns": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"Subject": "Order update",
						"MessageStructure": "json",
					},
				},
			},
		},
	},
})
```

```java Java highlight={12-17} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("aws_sns", JsonValue.from(java.util.Map.of(
                "target_arn", "your:target:arn"
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("aws-sns", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "Subject", "Order update",
                        "MessageStructure", "json"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={10-17} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'aws_sns' => [
        'target_arn' => 'your:target:arn',
      ],
    ],
    'providers' => [
      'aws-sns' => [
        'override' => [
          'body' => [
            'Subject' => 'Order update',
            'MessageStructure' => 'json',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={21-36} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "aws_sns": {
                    "target_arn": "your:target:arn"
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "aws-sns",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "Subject": "Order update",
                            "MessageStructure": "json"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"aws_sns": {"target_arn": "your:target:arn"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"aws-sns": {"override": {"body": {"Subject": "Order update", "MessageStructure": "json"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this SNS target ARN with the publish parameters overridden.
```

## Provider details

```text theme={null}
aws-sns
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send push with Beamer through Courier
Source: https://www.courier.com/docs/integrations/push/beamer

Connect Beamer with an API key, set its profile field, and override fields per send.

## Prerequisites

* [A Beamer account](https://www.getbeamer.com/)
* Your Beamer API key
* [A template with a Beamer channel
  DOC](/docs/design/templates/overview)
* A category in that template's Beamer channel settings

## Setup

**1. Get your Beamer API key**

In Beamer, open [settings](https://app.getbeamer.com/settings) and copy your API key.

**2. Configure in Courier**

Open the [Beamer Integration](https://app.courier.com/integrations/catalog/beamer) in Courier, enter your API key, then click "Save."

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

No profile data is required for Beamer.

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

Overrides change the request body Courier uses to send a push message. You can override these fields from Beamer's `postcreation` object ([documented in Beamer's API docs](https://www.getbeamer.com/api#definition-PostCreation)).

```json theme={null}
{
  "filter": "",
  "filterUserId": "",
  "filterUrl": "",
  "sendPushNotification": "",
  "publish": ""
}
```

This override delivers a post to a specific known user id.

```javascript Node.js highlight={6-14} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      beamer: {
        override: {
          body: {
            filterUserId: "user_123",
            sendPushNotification: "false",
            publish: "true",
          },
        },
      },
    },
  },
});
```

```python Python highlight={6-14} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {},
        "providers": {
            "beamer": {
                "override": {
                    "body": {
                        "filterUserId": "user_123",
                        "sendPushNotification": "false",
                        "publish": "true",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={9-17} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {},
      "providers": {
        "beamer": {
          "override": {
            "body": {
              "filterUserId": "user_123",
              "sendPushNotification": "false",
              "publish": "true"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={6-14} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      beamer: {
        override: {
          body: {
            filterUserId: "user_123",
            sendPushNotification: "false",
            publish: "true"
          }
        }
      }
    }
  }
)
```

```go Go highlight={9-17} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"beamer": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"filterUserId": "user_123",
						"sendPushNotification": "false",
						"publish": "true",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-12} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("beamer", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "filterUserId", "user_123",
                        "sendPushNotification", "false",
                        "publish", "true"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={6-14} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [],
    'providers' => [
      'beamer' => [
        'override' => [
          'body' => [
            'filterUserId' => 'user_123',
            'sendPushNotification' => 'false',
            'publish' => 'true',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-25} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient {  },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "beamer",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "filterUserId": "user_123",
                            "sendPushNotification": "false",
                            "publish": "true"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"beamer": {"override": {"body": {"filterUserId": "user_123", "sendPushNotification": "false", "publish": "true"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to a known Beamer user id.
```

## Provider details

```text theme={null}
beamer
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send push with Expo through Courier
Source: https://www.courier.com/docs/integrations/push/expo

Connect Expo and store each recipient's Expo push tokens on the profile.

## Prerequisites

* [An Expo account](https://expo.dev/)
* [An Expo project with push notifications configured](https://docs.expo.dev/push-notifications/overview/)

## Setup

Open the [Expo Integration](https://app.courier.com/integrations/catalog/expo) in Courier and enable it. The integration needs no credentials, because Courier delivers using the Expo push tokens on each recipient's profile.

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

Expo addresses the device by Exponent push token, so the profile you send to needs an `expo` object. Store the token once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

**One device**

Pass one device's token as a string to `expo.token`.

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    expo: {
      token: 'ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "expo": {
            "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "expo": {
        "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    expo: {
      token: "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"expo": map[string]any{
				"token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("expo", JsonValue.from(java.util.Map.of(
            "token", "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'expo' => [
    'token' => 'ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "expo": {
            "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"expo":{"token":"ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"}}'
```

```text MCP theme={null}
With Courier MCP, save the Expo push token ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx] on user_123.
```

**Several devices**

To reach every device on a profile, pass the tokens as an array to `expo.tokens`.

```javascript Node.js highlight={3-8} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    expo: {
      tokens: [
        'ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]',
        'ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]',
      ],
    },
  },
});
```

```python Python highlight={4-9} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "expo": {
            "tokens": [
                "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
                "ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]",
            ],
        },
    },
)
```

```bash cURL highlight={7-12} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "expo": {
        "tokens": [
          "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
          "ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]"
        ]
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    expo: {
      tokens: ["ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]", "ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]"]
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"expo": map[string]any{
				"tokens": []any{"ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]", "ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]"},
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("expo", JsonValue.from(java.util.Map.of(
            "tokens", java.util.List.of("ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]", "ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]"))))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'expo' => [
    'tokens' => ['ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]', 'ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]'],
  ],
]);
```

```csharp C# highlight={7-12} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "expo": {
            "tokens": [
              "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
              "ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]"
            ]
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"expo":{"tokens":["ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]","ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]"]}}'
```

```text MCP theme={null}
With Courier MCP, save both of my Expo push tokens on user_123.
```

> [!NOTE]
>
> If you pass both `token` and `tokens`, Courier merges `token` into the `tokens` array and dedupes it.

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "expo": { "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]" } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `expo` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to a token**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      expo: {
        token: "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-6} theme={null}
response = client.send.message(
    message={
        "to": {
            "expo": {
                "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-9} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "expo": {
          "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
response = courier.send_.message(
  message: {
    to: {
      expo: {
        token: "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"expo": {"token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("expo", JsonValue.from(Map.of(
            "token", "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]")))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-6} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'expo' => [
        'token' => 'ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"expo": {"token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"expo": {"token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to that Expo push token.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

A provider override changes what Courier sends to Expo's API. Override keys apply at the top level of the Expo message, **not** nested under `body`. This request adds a ttl and turns off the sound:

```javascript Node.js highlight={5-7,13-18} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      expo: {
        token: "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
      },
    },
    data: {
      dataForPushMessage: true,
    },
    providers: {
      expo: {
        override: {
          ttl: 10,
          sound: null,
        },
      },
    },
  },
});
```

```python Python highlight={5-7,13-18} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "expo": {
                "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
            },
        },
        "data": {
            "dataForPushMessage": True,
        },
        "providers": {
            "expo": {
                "override": {
                    "ttl": 10,
                    "sound": None,
                },
            },
        },
    },
)
```

```bash cURL highlight={8-10,16-21} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "expo": {
          "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
        }
      },
      "data": {
        "dataForPushMessage": true
      },
      "providers": {
        "expo": {
          "override": {
            "ttl": 10,
            "sound": null
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={5-7,13-18} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      expo: {
        token: "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
      }
    },
    data: {
      dataForPushMessage: true
    },
    providers: {
      expo: {
        override: {
          ttl: 10,
          sound: nil
        }
      }
    }
  }
)
```

```go Go highlight={4-6,17-22} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "expo": {
    "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"dataForPushMessage": true,
		},
		Providers: shared.MessageProvidersParam{
			"expo": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"ttl": 10,
					"sound": nil,
				},
			},
		},
	},
})
```

```java Java highlight={6-8,15-18} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("expo", JsonValue.from(java.util.Map.of(
                "token", "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "dataForPushMessage", true
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("expo", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "ttl", 10,
                    "sound", null
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={5-7,13-18} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'expo' => [
        'token' => 'ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]',
      ],
    ],
    'data' => [
      'dataForPushMessage' => true,
    ],
    'providers' => [
      'expo' => [
        'override' => [
          'ttl' => 10,
          'sound' => null,
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={11-13,25-38} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "expo": {
                    "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "dataForPushMessage", JsonSerializer.SerializeToElement(true) },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "expo",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "ttl": 10,
                          "sound": null
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3,6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"expo": {"token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"dataForPushMessage": true}' \
  --message.providers '{"expo": {"override": {"ttl": 10, "sound": null}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this Expo push token with a 10 second TTL and no sound.
```

Each key you set replaces that key outright. Keys you leave out are still generated and sent (title, subtitle, body, and data above). For every option, see [Expo's push notifications docs](https://docs.expo.dev/push-notifications/overview/).

To send to specific devices when a user has multiple Expo tokens, see [Targeting Specific Devices
DOC](/docs/integrations/push/overview#targeting-specific-devices).

## Tracking events

Courier includes tracking URL information in the `data` attribute of the incoming message payload.

See [Courier push notification tracking
DOC](/docs/integrations/push/overview#tracking)

## Troubleshooting

### Could not find APNs credentials

Expo's [help forum](https://forums.expo.dev/t/push-notification-error-could-not-find-apns-credentials-for-standalone-app/6955) explains how Expo handles APN tokens:

> Expo push tokens work quite similarly to how Apple's tokens work with APN's, since Expo's server is a relatively thin service that relays notifications to Apple. Expo needs valid APN credentials to send push notifications. And as with APNs in general (not specific to Expo), it doesn't matter what APNs credentials you had at the time an iOS device provided a device token - the APN credentials just need to be valid at the time of sending the notification.

> So, if you revoke your APNs credentials or clear them from Expo, or if your APNs credentials expire (APN p12 certificates expire after one year), Apple will reject all of your push notifications until you provide Expo with valid APN credentials. To be clear, **your Expo push tokens and the underlying iOS device tokens are still valid** and will still work once you provide new, valid APN credentials.

> In this case, the error `Could not find APNs credentials for…` means that Expo does not have any copy of your APNs credentials (currently a p12 certificate). You will need to let Expo recreate the credentials for you (**recommended in most cases:** run `exp build:ios -c` to clear all of them and then run `exp build:ios` to let Expo re-provision them) or upload your own credentials from Apple's developer center (be sure to follow the instructions carefully.

* Your push key should be correctly configured at `https://expo.dev/accounts/[account]/projects/[project]/credentials?platform=ios`
* You've correctly set your bundle identifier in your configuration
* If you're explicitly passing in the `experienceId` in `Notifications.getExpoPushTokenAsync({ experienceId: 'xxxx' })`, make sure it is in the format of `@expo_account/expo_projectname`

## Provider details

```text theme={null}
expo
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send push with Firebase Cloud Messaging through Courier
Source: https://www.courier.com/docs/integrations/push/firebase-fcm

Connect FCM with a service account and sync device tokens with the Android, iOS, or Flutter SDK.

## Prerequisites

* [A Firebase project](https://firebase.google.com/)
* A service account private key from that project
* For iOS, an APNs key uploaded to Firebase

## Setup

### Configure FCM provider

**1. Generate a private key**

In your [Firebase Project](https://console.firebase.google.com/), go to "Project Settings" > "Service Accounts" and generate a new private key.

**2. Add the key to Courier**

Copy the contents of the downloaded private key JSON file and paste it into **Service Account JSON** in the [Courier FCM provider configuration](https://app.courier.com/integrations/catalog/firebase-fcm).

**3. Review the remaining settings**

* **Apply Recommended Courier Mobile SDK Formatting**, on by default. It ships the message as a `data` payload rather than `notification`, so Android wakes in the background and your own notification style applies. That background wake is also what reports the delivery back to Courier. It attaches an APNs override for Courier's [iOS Notification Service Extension
  DOC](/docs/sdk-libraries/ios#notification-service-extension) too, so an iOS device receiving through FCM still tracks delivery. See [Delivery and click tracking
  GUIDE](/docs/guides/set-up-mobile-push#delivery-and-click-tracking).

![FCM provider configuration showing the Apply Recommended Courier Mobile SDK Formatting toggle](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/fcm-auto-override.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=bb8ddd0ff4b4835b9e11ab6331075a23)

The Courier FCM provider configuration with the Apply Recommended Courier Mobile SDK Formatting toggle enabled.

* **Bundle ID** and **Filter By Bundle ID**, off by default. Together they restrict a send to tokens whose `device.app_id` matches, so a user with two app installs only gets it on the right one.

**4. Install the provider**

Click "Install Provider" or "Save" to complete the configuration.

### Enable iOS support (if required)

**1. Integrate Firebase into your iOS project**

Integrate Firebase into your [iOS project](https://firebase.google.com/docs/ios/setup).

**2. Select your iOS project in Cloud Messaging**

In your Firebase project settings, go to "Cloud Messaging" and select your iOS project under "Apple app configuration".

**3. Create an APNs key**

Create a new key in your [Apple Developer Account](https://developer.apple.com/account) with "Apple Push Notifications Service (APNs)" enabled.

**4. Upload the .p8 file to Firebase**

Download the generated `.p8` file and upload it to your Firebase project settings under "Apple apps" > your app > "APNs Authentication Key".

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

FCM addresses the device by registration token, so the profile you send to needs a `firebaseToken`. Store the token once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

**One device**

A single registration token, as a string.

```javascript Node.js highlight={3} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    firebaseToken: 'YOUR_FCM_TOKEN',
  },
});
```

```python Python highlight={4} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "firebaseToken": "YOUR_FCM_TOKEN",
    },
)
```

```bash cURL highlight={7} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "firebaseToken": "YOUR_FCM_TOKEN"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    firebaseToken: "YOUR_FCM_TOKEN"
  }
)
```

```go Go highlight={6} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"firebaseToken": "YOUR_FCM_TOKEN",
		},
	},
)
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("firebaseToken", JsonValue.from("YOUR_FCM_TOKEN"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'firebaseToken' => 'YOUR_FCM_TOKEN',
]);
```

```csharp C# highlight={6} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "firebaseToken", JsonSerializer.SerializeToElement("YOUR_FCM_TOKEN") },
    },
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"firebaseToken":"YOUR_FCM_TOKEN"}'
```

```text MCP theme={null}
With Courier MCP, save the FCM token YOUR_FCM_TOKEN on user_123.
```

**Several devices**

An array reaches every device that user signs in on.

```javascript Node.js highlight={3-6} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    firebaseToken: [
      'FCM_TOKEN_ONE',
      'FCM_TOKEN_TWO',
    ],
  },
});
```

```python Python highlight={4-7} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "firebaseToken": [
            "FCM_TOKEN_ONE",
            "FCM_TOKEN_TWO",
        ],
    },
)
```

```bash cURL highlight={7-10} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "firebaseToken": [
        "FCM_TOKEN_ONE",
        "FCM_TOKEN_TWO"
      ]
    }
  }'
```

```ruby Ruby highlight={3-5} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    firebaseToken: ["FCM_TOKEN_ONE", "FCM_TOKEN_TWO"]
  }
)
```

```go Go highlight={5-7} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"firebaseToken": []any{"FCM_TOKEN_ONE", "FCM_TOKEN_TWO"},
		},
	},
)
```

```java Java highlight={3-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("firebaseToken", JsonValue.from(java.util.List.of("FCM_TOKEN_ONE", "FCM_TOKEN_TWO")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'firebaseToken' => ['FCM_TOKEN_ONE', 'FCM_TOKEN_TWO'],
]);
```

```csharp C# highlight={7-10} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "firebaseToken": [
            "FCM_TOKEN_ONE",
            "FCM_TOKEN_TWO"
          ]
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"firebaseToken":["FCM_TOKEN_ONE","FCM_TOKEN_TWO"]}'
```

```text MCP theme={null}
With Courier MCP, save the FCM tokens FCM_TOKEN_ONE and FCM_TOKEN_TWO on user_123.
```

On Android the Courier SDK keeps that token current once you forward `onNewToken` to it. You send to a `user_id` and never put a token on a profile yourself.

On iOS, FCM is a token you register and refresh, because the SDK's own hook there is APNs.

For a one-off with no stored profile, pass it inline instead: `"to": { "firebaseToken": "YOUR_FCM_TOKEN" }`.

> **[Set up push notifications](/docs/guides/set-up-mobile-push)**
>
> Wire up the SDK, sync tokens, and send your first push.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `firebaseToken` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to a token**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

| To address | Use |
| - | - |
| One device | `"to": { "firebaseToken": "YOUR_FCM_TOKEN" }` |
| Several devices | `"to": { "firebaseToken": ["FCM_TOKEN_ONE", "FCM_TOKEN_TWO"] }` |
| A user, and a specific device | `"to": { "user_id": "user_123", "firebaseToken": "YOUR_FCM_TOKEN" }` |

> [!NOTE]
>
> Include a `user_id` alongside the token to keep the send tied to that person. Courier then keeps their stored preferences and profile, managed token lookup, expiry, sign-out cleanup, and `bundleId` filtering, and delivery and click events on their history. Without a `user_id`, Courier logs the message under a synthetic `anon_<hash>` recipient instead.

To pick among several tokens on one user, see [Targeting specific devices
DOC](/docs/integrations/push/overview#targeting-specific-devices).

```javascript Node.js highlight={5} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      firebaseToken: "YOUR_FCM_TOKEN",
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "firebaseToken": "YOUR_FCM_TOKEN",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "firebaseToken": "YOUR_FCM_TOKEN"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      firebaseToken: "YOUR_FCM_TOKEN"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={3} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"firebaseToken": "YOUR_FCM_TOKEN"}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("firebaseToken", JsonValue.from("YOUR_FCM_TOKEN"))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'firebaseToken' => 'YOUR_FCM_TOKEN',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"firebaseToken": "YOUR_FCM_TOKEN"}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"firebaseToken": "YOUR_FCM_TOKEN"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the FCM token YOUR_FCM_TOKEN.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

An override changes the request Courier sends to FCM. Two paths cover most cases:

* `providers.firebase-fcm.override.body.data.YOUR_CUSTOM_KEY` adds custom data, usually to open a screen on tap. Firebase requires `data` to be flat, and override values merge in raw, so every value must already be a string. See [Firebase's data field reference](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#Message.FIELDS.data).
* `providers.firebase-fcm.override.body.apns` applies iOS-specific values. See [Apple's remote notification guide](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification).

`providers.firebase-fcm.override.config` replaces the integration's own settings for a single send:

| Key | What it replaces |
| - | - |
| `serviceAccountJSON` | The service account this send authenticates as. |
| `remapData` | Whether Courier remaps `data` for this send. |

**Put personalization variables in `message.data`, not in `to`.** Courier reads anything nested in `to` as profile data, so it fills no template variables and triggers no data mapping.

Custom data not reaching the device? [Data mapping
DOC](/docs/design/templates/data-mapping)
covers the one template setting that stops it.

### Override the payload

```javascript Node.js highlight={15-29} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push",
      ],
    },
    providers: {
      "firebase-fcm": {
        override: {
          body: {
            data: {
              YOUR_CUSTOM_KEY: "YOUR_CUSTOM_VALUE",
            },
            apns: {
              payload: {
                aps: {
                  sound: "ping.aiff",
                  badge: 99,
                },
              },
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={15-29} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": [
                "push",
            ],
        },
        "providers": {
            "firebase-fcm": {
                "override": {
                    "body": {
                        "data": {
                            "YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE",
                        },
                        "apns": {
                            "payload": {
                                "aps": {
                                    "sound": "ping.aiff",
                                    "badge": 99,
                                },
                            },
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={18-32} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": [
          "push"
        ]
      },
      "providers": {
        "firebase-fcm": {
          "override": {
            "body": {
              "data": {
                "YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
              },
              "apns": {
                "payload": {
                  "aps": {
                    "sound": "ping.aiff",
                    "badge": 99
                  }
                }
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={15-29} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push"
      ]
    },
    providers: {
      "firebase-fcm": {
        override: {
          body: {
            data: {
              YOUR_CUSTOM_KEY: "YOUR_CUSTOM_VALUE"
            },
            apns: {
              payload: {
                aps: {
                  sound: "ping.aiff",
                  badge: 99
                }
              }
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={17-31} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
			},
			Method: "single",
		},
		Providers: shared.MessageProvidersParam{
			"firebase-fcm": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"data": map[string]any{
							"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE",
						},
						"apns": map[string]any{
							"payload": map[string]any{
								"aps": map[string]any{
									"sound": "ping.aiff",
									"badge": 99,
								},
							},
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={10-24} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("push")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .providers(MessageProviders.builder()
            .putAdditionalProperty("firebase-fcm", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "data", java.util.Map.of(
                            "YOUR_CUSTOM_KEY", "YOUR_CUSTOM_VALUE"
                        ),
                        "apns", java.util.Map.of(
                            "payload", java.util.Map.of(
                                "aps", java.util.Map.of(
                                    "sound", "ping.aiff",
                                    "badge", 99
                                )
                            )
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={15-29} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => [
        'push',
      ],
    ],
    'providers' => [
      'firebase-fcm' => [
        'override' => [
          'body' => [
            'data' => [
              'YOUR_CUSTOM_KEY' => 'YOUR_CUSTOM_VALUE',
            ],
            'apns' => [
              'payload' => [
                'aps' => [
                  'sound' => 'ping.aiff',
                  'badge' => 99,
                ],
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={14-32} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["push"], Method = Send::Method.Single },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "firebase-fcm",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "data": {
                              "YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"
                            },
                            "apns": {
                              "payload": {
                                "aps": {
                                  "sound": "ping.aiff",
                                  "badge": 99
                                }
                              }
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push"]}' \
  --message.providers '{"firebase-fcm": {"override": {"body": {"data": {"YOUR_CUSTOM_KEY": "YOUR_CUSTOM_VALUE"}, "apns": {"payload": {"aps": {"sound": "ping.aiff", "badge": 99}}}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 on push, with an FCM sound and badge.
```

## Provider details

```text theme={null}
firebase-fcm
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send push with MagicBell through Courier
Source: https://www.courier.com/docs/integrations/push/magicbell

Connect MagicBell with an API key and secret, and target a recipient by email or external ID.

## Prerequisites

* [A MagicBell account with a project](https://www.magicbell.com/)
* Your MagicBell API key and API secret

## Setup

**1. Get your MagicBell credentials**

In MagicBell, open your project at [app.magicbell.com](https://app.magicbell.com/) and copy the API key and API secret.

**2. Configure in Courier**

Open the [MagicBell Integration](https://app.courier.com/integrations/catalog/magicbell) in Courier, enter your API key and API secret, then click "Save."

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

MagicBell addresses the recipient by email address or by external ID. Store either one once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

**Email**

MagicBell matches the address against the user it holds.

```javascript Node.js highlight={3} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    email: 'sarah@acme-corp.com',
  },
});
```

```python Python highlight={4} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "email": "sarah@acme-corp.com",
    },
)
```

```bash cURL highlight={7} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "email": "sarah@acme-corp.com"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    email: "sarah@acme-corp.com"
  }
)
```

```go Go highlight={6} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"email": "sarah@acme-corp.com",
		},
	},
)
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'email' => 'sarah@acme-corp.com',
]);
```

```csharp C# highlight={6} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
    },
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"email":"sarah@acme-corp.com"}'
```

```text MCP theme={null}
With Courier MCP, save the email sarah@acme-corp.com on user_123.
```

**External ID**

The id your own system uses for that person.

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    magicbell: {
      external_id: 'user123',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "magicbell": {
            "external_id": "user123",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "magicbell": {
        "external_id": "user123"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    magicbell: {
      external_id: "user123"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"magicbell": map[string]any{
				"external_id": "user123",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("magicbell", JsonValue.from(java.util.Map.of(
            "external_id", "user123")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'magicbell' => [
    'external_id' => 'user123',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "magicbell": {
            "external_id": "user123"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"magicbell":{"external_id":"user123"}}'
```

```text MCP theme={null}
With Courier MCP, save the MagicBell external id user123 on user_123.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "magicbell": { "external_id": "user123" } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `email` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to an email**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com by email.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

Overrides change the request body Courier sends to MagicBell.

This example overrides the MagicBell category and action URL:

```javascript Node.js highlight={9-18} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    data: {},
    providers: {
      magicbell: {
        override: {
          body: {
            notification: {
              category: "new_message",
              action_url: "https://example.com/example_link",
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={9-18} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "data": {},
        "providers": {
            "magicbell": {
                "override": {
                    "body": {
                        "notification": {
                            "category": "new_message",
                            "action_url": "https://example.com/example_link",
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={12-21} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "data": {},
      "providers": {
        "magicbell": {
          "override": {
            "body": {
              "notification": {
                "category": "new_message",
                "action_url": "https://example.com/example_link"
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={9-18} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    data: {},
    providers: {
      magicbell: {
        override: {
          body: {
            notification: {
              category: "new_message",
              action_url: "https://example.com/example_link"
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-19} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"magicbell": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"notification": map[string]any{
							"category": "new_message",
							"action_url": "https://example.com/example_link",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-13} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("magicbell", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "notification", java.util.Map.of(
                            "category", "new_message",
                            "action_url", "https://example.com/example_link"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-18} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'data' => [],
    'providers' => [
      'magicbell' => [
        'override' => [
          'body' => [
            'notification' => [
              'category' => 'new_message',
              'action_url' => 'https://example.com/example_link',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-26} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "magicbell",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "notification": {
                              "category": "new_message",
                              "action_url": "https://example.com/example_link"
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"magicbell": {"override": {"body": {"notification": {"category": "new_message", "action_url": "https://example.com/example_link"}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com with a MagicBell category and action URL.
```

## Provider details

```text theme={null}
magicbell
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send push with NowPush through Courier
Source: https://www.courier.com/docs/integrations/push/nowpush

Connect NowPush with an API key. A send addresses the account, so no profile field is needed.

## Prerequisites

* [A NowPush account](https://nowpush.io/)
* Your NowPush API key

## Setup

Open the [NowPush Integration](https://app.courier.com/integrations/catalog/nowpush) in Courier, enter your API key, then click "Save."

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

NowPush needs no profile data. If your notification template includes `device_type`, `message_type`, `url` or `apiKey`, those values replace the configuration.

```json theme={null}
{
  "message": {
    "to": {
      "nowpush": {
        "device_type": "browser",
        "message_type": "link",
        "url": "www.nowpush.com",
        "apiKey": ""
      }
    }
  }
}
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

A provider override changes the request body Courier sends to NowPush, or swaps the API key and URL.

### Body overrides

This example sets the device type and the message type:

```javascript Node.js highlight={6-13} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      nowpush: {
        override: {
          body: {
            device_type: "browser",
            message_type: "nowpush_msg",
          },
        },
      },
    },
  },
});
```

```python Python highlight={6-13} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {},
        "providers": {
            "nowpush": {
                "override": {
                    "body": {
                        "device_type": "browser",
                        "message_type": "nowpush_msg",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={9-16} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {},
      "providers": {
        "nowpush": {
          "override": {
            "body": {
              "device_type": "browser",
              "message_type": "nowpush_msg"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={6-13} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      nowpush: {
        override: {
          body: {
            device_type: "browser",
            message_type: "nowpush_msg"
          }
        }
      }
    }
  }
)
```

```go Go highlight={9-16} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"nowpush": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"device_type": "browser",
						"message_type": "nowpush_msg",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-11} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("nowpush", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "device_type", "browser",
                        "message_type", "nowpush_msg"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={6-13} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [],
    'providers' => [
      'nowpush' => [
        'override' => [
          'body' => [
            'device_type' => 'browser',
            'message_type' => 'nowpush_msg',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-24} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient {  },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "nowpush",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "device_type": "browser",
                            "message_type": "nowpush_msg"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"nowpush": {"override": {"body": {"device_type": "browser", "message_type": "nowpush_msg"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template through NowPush with the body overridden.
```

### Config overrides

Swap the API key or URL at send time with a config override:

```javascript Node.js highlight={6-12} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      nowpush: {
        override: {
          config: {
            apiKey: "RUNTIME_API_KEY",
          },
        },
      },
    },
  },
});
```

```python Python highlight={6-12} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {},
        "providers": {
            "nowpush": {
                "override": {
                    "config": {
                        "apiKey": "RUNTIME_API_KEY",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={9-15} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {},
      "providers": {
        "nowpush": {
          "override": {
            "config": {
              "apiKey": "RUNTIME_API_KEY"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={6-12} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      nowpush: {
        override: {
          config: {
            apiKey: "RUNTIME_API_KEY"
          }
        }
      }
    }
  }
)
```

```go Go highlight={9-15} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"nowpush": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"apiKey": "RUNTIME_API_KEY",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-10} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("nowpush", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "apiKey", "RUNTIME_API_KEY"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={6-12} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [],
    'providers' => [
      'nowpush' => [
        'override' => [
          'config' => [
            'apiKey' => 'RUNTIME_API_KEY',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-23} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient {  },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "nowpush",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "apiKey": "RUNTIME_API_KEY"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"nowpush": {"override": {"config": {"apiKey": "RUNTIME_API_KEY"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template through NowPush with a different API key.
```

## Provider details

```text theme={null}
nowpush
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send push with OneSignal through Courier
Source: https://www.courier.com/docs/integrations/push/onesignal-push

Connect OneSignal with an App ID and REST API key, and target a Player ID or External User ID.

## Prerequisites

* [A OneSignal account with an app](https://onesignal.com/)
* [Your OneSignal `App ID` and `REST API Key`](https://documentation.onesignal.com/docs/accounts-and-keys)

## Setup

**1. Get your OneSignal keys**

In OneSignal, open [accounts and keys](https://documentation.onesignal.com/docs/accounts-and-keys) and copy your App ID and REST API Key.

**2. Configure in Courier**

Open the [OneSignal Integration](https://app.courier.com/integrations/catalog/onesignal) in Courier, enter your `App ID` and `REST API Key`, then click "Save."

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

OneSignal addresses the recipient by [PlayerId](https://documentation.onesignal.com/docs/users#section-player-id) or [ExternalId](https://documentation.onesignal.com/docs/user-model-migration-guide#user-model). Store either one once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

**Player ID**

The id OneSignal assigned the device.

```javascript Node.js highlight={3} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    oneSignalPlayerID: 'YOUR_ONESIGNAL_PLAYER_ID',
  },
});
```

```python Python highlight={4} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "oneSignalPlayerID": "YOUR_ONESIGNAL_PLAYER_ID",
    },
)
```

```bash cURL highlight={7} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "oneSignalPlayerID": "YOUR_ONESIGNAL_PLAYER_ID"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    oneSignalPlayerID: "YOUR_ONESIGNAL_PLAYER_ID"
  }
)
```

```go Go highlight={6} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"oneSignalPlayerID": "YOUR_ONESIGNAL_PLAYER_ID",
		},
	},
)
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("oneSignalPlayerID", JsonValue.from("YOUR_ONESIGNAL_PLAYER_ID"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'oneSignalPlayerID' => 'YOUR_ONESIGNAL_PLAYER_ID',
]);
```

```csharp C# highlight={6} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "oneSignalPlayerID", JsonSerializer.SerializeToElement("YOUR_ONESIGNAL_PLAYER_ID") },
    },
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"oneSignalPlayerID":"YOUR_ONESIGNAL_PLAYER_ID"}'
```

```text MCP theme={null}
With Courier MCP, save the OneSignal player id YOUR_ONESIGNAL_PLAYER_ID on user_123.
```

**External ID**

The id your own system uses, once you have set it in OneSignal.

```javascript Node.js highlight={3} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    oneSignalExternalUserId: 'user_123',
  },
});
```

```python Python highlight={4} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "oneSignalExternalUserId": "user_123",
    },
)
```

```bash cURL highlight={7} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "oneSignalExternalUserId": "user_123"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    oneSignalExternalUserId: "user_123"
  }
)
```

```go Go highlight={6} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"oneSignalExternalUserId": "user_123",
		},
	},
)
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("oneSignalExternalUserId", JsonValue.from("user_123"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'oneSignalExternalUserId' => 'user_123',
]);
```

```csharp C# highlight={6} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "oneSignalExternalUserId", JsonSerializer.SerializeToElement("user_123") },
    },
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"oneSignalExternalUserId":"user_123"}'
```

```text MCP theme={null}
With Courier MCP, save the OneSignal external user id user_123 on user_123.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "oneSignalPlayerID": "YOUR_ONESIGNAL_PLAYER_ID" }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `oneSignalPlayerID` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `oneSignalPlayerID`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      oneSignalPlayerID: "...",
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "oneSignalPlayerID": "...",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "oneSignalPlayerID": "..."
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      oneSignalPlayerID: "..."
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={3} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"oneSignalPlayerID": "..."}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("oneSignalPlayerID", JsonValue.from("..."))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'oneSignalPlayerID' => '...',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"oneSignalPlayerID": "..."}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"oneSignalPlayerID": "..."}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to that OneSignal player id.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

A provider override changes the request body Courier sends to OneSignal's API, and takes any field supported by OneSignal's [Create notification](https://documentation.onesignal.com/reference/create-notification) endpoint.

```javascript Node.js highlight={8-16} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      oneSignalPlayerID: "player-id-123",
    },
    providers: {
      onesignal: {
        override: {
          body: {
            priority: 10,
            ttl: 3600,
            small_icon: "ic_notification",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-16} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "oneSignalPlayerID": "player-id-123",
        },
        "providers": {
            "onesignal": {
                "override": {
                    "body": {
                        "priority": 10,
                        "ttl": 3600,
                        "small_icon": "ic_notification",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-19} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "oneSignalPlayerID": "player-id-123"
      },
      "providers": {
        "onesignal": {
          "override": {
            "body": {
              "priority": 10,
              "ttl": 3600,
              "small_icon": "ic_notification"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-16} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      oneSignalPlayerID: "player-id-123"
    },
    providers: {
      onesignal: {
        override: {
          body: {
            priority: 10,
            ttl: 3600,
            small_icon: "ic_notification"
          }
        }
      }
    }
  }
)
```

```go Go highlight={12-20} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "oneSignalPlayerID": "player-id-123"
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"onesignal": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"priority": 10,
						"ttl": 3600,
						"small_icon": "ic_notification",
					},
				},
			},
		},
	},
})
```

```java Java highlight={10-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("oneSignalPlayerID", JsonValue.from("player-id-123"))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("onesignal", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "priority", 10,
                        "ttl", 3600,
                        "small_icon", "ic_notification"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-16} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'oneSignalPlayerID' => 'player-id-123',
    ],
    'providers' => [
      'onesignal' => [
        'override' => [
          'body' => [
            'priority' => 10,
            'ttl' => 3600,
            'small_icon' => 'ic_notification',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={19-35} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "oneSignalPlayerID": "player-id-123"
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "onesignal",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "priority": 10,
                            "ttl": 3600,
                            "small_icon": "ic_notification"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"oneSignalPlayerID": "player-id-123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"onesignal": {"override": {"body": {"priority": 10, "ttl": 3600, "small_icon": "ic_notification"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to this OneSignal player id with a body override.
```

## Data mapping

OneSignal caps the size of a push payload. In automated workflows that batch sends, a data payload can exceed that cap and the send fails.

Enable data mapping on the push channel to choose which fields reach the provider. [Data mapping
DOC](/docs/design/templates/data-mapping) covers the template setting.

![](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/onesignal-data-map.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=cc318546a0407b6a72cf3622b169aa23)

OneSignal Data Mapping

## Provider details

```text theme={null}
onesignal
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Push providers
Source: https://www.courier.com/docs/integrations/push/overview

Every push provider Courier supports, how device tokens are stored, and payload overrides.

## Available providers

> **[Apple APNs](/docs/integrations/push/apple-push-notification)**

> **[Firebase FCM](/docs/integrations/push/firebase-fcm)**

> **[Expo](/docs/integrations/push/expo)**

> **[OneSignal](/docs/integrations/push/onesignal-push)**

> **[Airship](/docs/integrations/push/airship)**

> **[Amazon SNS](/docs/integrations/push/aws-sns)**

> **[Pusher Beams](/docs/integrations/push/pusher-beams)**

> **[Pusher](/docs/integrations/push/pusher)**

> **[MagicBell](/docs/integrations/push/magicbell)**

> **[Pushbullet](/docs/integrations/push/pushbullet)**

> **[Beamer](/docs/integrations/push/beamer)**

> **[NowPush](/docs/integrations/push/nowpush)**

Amazon SNS also sends [SMS
DOC](/docs/integrations/sms/aws-sns). Apple APNs and Firebase FCM are the two the [Courier Mobile SDKs
DOC](/docs/sdk-libraries/sdks-overview) register device tokens for.

> [!TIP]
>
> Can't find a provider? Start a chat on the Courier site, or email [support@courier.com](mailto:support@courier.com)

## Channel overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. These are the fields a push channel override accepts, whichever provider sends.

| Field | Sets |
| :- | :- |
| `title` | The notification title |
| `body` | The notification body |
| `data` | Custom key-value data delivered alongside the notification |
| `icon` | The notification icon |

```javascript Node.js highlight={7-10} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    channels: {
      push: {
        override: {
          title: 'Order shipped',
          body: 'Your order is on its way.',
        },
      },
    },
  },
});
```

```python Python highlight={7-10} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "channels": {
            "push": {
                "override": {
                    "title": "Order shipped",
                    "body": "Your order is on its way.",
                },
            },
        },
    },
)
```

```bash cURL highlight={10-13} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "channels": {
        "push": {
          "override": {
            "title": "Order shipped",
            "body": "Your order is on its way."
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={7-10} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    channels: {
      push: {
        override: {
          title: "Order shipped",
          body: "Your order is on its way."
        }
      }
    }
  }
)
```

```go Go highlight={11-14} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Channels: shared.MessageChannelsParam{
			"push": shared.ChannelParam{
				Override: map[string]any{
					"title":       "Order shipped",
					"body":        "Your order is on its way.",
				},
			},
		},
	},
})
```

```java Java highlight={7-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .channels(MessageChannels.builder()
            .putAdditionalProperty("push", JsonValue.from(java.util.Map.of(
                "override", java.util.Map.of(
                    "title", "Order shipped",
                    "body", "Your order is on its way."))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={7-10} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'channels' => [
      'push' => [
        'override' => [
          'title' => 'Order shipped',
          'body' => 'Your order is on its way.',
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={13-17} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Channels = new Dictionary<string, Channel>()
        {
            {
                "push",
                new()
                {
                    Override = new Dictionary<string, JsonElement>()
                    {
                        { "title", JsonSerializer.SerializeToElement("Order shipped") },
                        { "body", JsonSerializer.SerializeToElement("Your order is on its way.") },
                    },
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.channels '{"push":{"override":{"title":"Order shipped","body":"Your order is on its way."}}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 and override the push title to "Order shipped".
```

## Tracking

Courier attaches a `trackingUrl` to every push request. Posting to it updates the notification's state. The [Courier Mobile SDKs
DOC](/docs/sdk-libraries/sdks-overview) do this for you. To do it manually:

### Example message

```json theme={null}
{
  "message": {
    "data": {
      "trackingUrl": "https://api.courier.com/e/123_channelTrackingId"
      // other data attributes
    }
    // other messages attributes
  }
}
```

### Example request

```javascript Node.js theme={null}
await fetch("https://api.courier.com/e/123_channelTrackingId", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ event: "DELIVERED" }),
});
```

```python Python theme={null}
import requests

requests.post(
    "https://api.courier.com/e/123_channelTrackingId",
    json={"event": "DELIVERED"},
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/e/123_channelTrackingId \
  -H "Content-Type: application/json" \
  -d '{"event":"DELIVERED"}'
```

`event` is `DELIVERED` or `CLICKED`.

### Provider-specific tracking

Each provider puts the `trackingUrl` somewhere different in the payload your app receives:

| Provider | Where to read it |
| - | - |
| [Apple APNs&#xA;DOC](/docs/integrations/push/apple-push-notification) | `data` on the incoming [`payload`](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns/) |
| [Firebase FCM&#xA;DOC](/docs/integrations/push/firebase-fcm) | `data` on the incoming `message` payload |
| [Expo&#xA;DOC](/docs/integrations/push/expo) | `data` on the incoming payload |
| [Pusher&#xA;DOC](/docs/integrations/push/pusher) | `data` on the incoming payload |
| [Airship&#xA;DOC](/docs/integrations/push/airship) | `global_attributes` [data bag](https://docs.airship.com/whats-new/2021-08-02-push-api-personalization/) |

## Targeting specific devices

If a user has tokens from more than one app, target a subset at send time. Use it for per-platform notifications, or when several apps share one provider project.

The [Courier mobile SDKs
DOC](/docs/sdk-libraries/sdks-overview) already tag every token they register with the app's own identifier, the bundle id on iOS and the package name on Android. Nothing to set up, so the only thing you write is the filter.

### Filter tokens at send time

Pass `filterByBundleId` and `bundleId` in the provider override to send only to tokens whose `device.app_id` matches:

```javascript Node.js highlight={17-18} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      user_id: "user_123",
    },
    routing: {
      method: "single",
      channels: [
        "push",
      ],
    },
    providers: {
      "firebase-fcm": {
        override: {
          config: {
            filterByBundleId: true,
            bundleId: "com.acme-corp.app",
          },
        },
      },
    },
  },
});
```

```python Python highlight={17-18} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "user_id": "user_123",
        },
        "routing": {
            "method": "single",
            "channels": [
                "push",
            ],
        },
        "providers": {
            "firebase-fcm": {
                "override": {
                    "config": {
                        "filterByBundleId": True,
                        "bundleId": "com.acme-corp.app",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={20-21} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "user_id": "user_123"
      },
      "routing": {
        "method": "single",
        "channels": [
          "push"
        ]
      },
      "providers": {
        "firebase-fcm": {
          "override": {
            "config": {
              "filterByBundleId": true,
              "bundleId": "com.acme-corp.app"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={17-18} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      user_id: "user_123"
    },
    routing: {
      method: "single",
      channels: [
        "push"
      ]
    },
    providers: {
      "firebase-fcm": {
        override: {
          config: {
            filterByBundleId: true,
            bundleId: "com.acme-corp.app"
          }
        }
      }
    }
  }
)
```

```go Go highlight={19-20} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
			},
			Method: "single",
		},
		Providers: shared.MessageProvidersParam{
			"firebase-fcm": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"filterByBundleId": true,
						"bundleId": "com.acme-corp.app",
					},
				},
			},
		},
	},
})
```

```java Java highlight={12-13} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("push")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .providers(MessageProviders.builder()
            .putAdditionalProperty("firebase-fcm", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "filterByBundleId", true,
                        "bundleId", "com.acme-corp.app"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={17-18} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'user_id' => 'user_123',
    ],
    'routing' => [
      'method' => 'single',
      'channels' => [
        'push',
      ],
    ],
    'providers' => [
      'firebase-fcm' => [
        'override' => [
          'config' => [
            'filterByBundleId' => true,
            'bundleId' => 'com.acme-corp.app',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={18-19} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["push"], Method = Send::Method.Single },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "firebase-fcm",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "filterByBundleId": true,
                            "bundleId": "com.acme-corp.app"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push"]}' \
  --message.providers '{"firebase-fcm": {"override": {"config": {"filterByBundleId": true, "bundleId": "com.acme-corp.app"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to user_123, only to tokens from my desktop app bundle.
```

Use the bundle id of the app whose devices you want, `com.acme-corp.app` above. If `bundleId` matches none of the user's tokens, the message isn't delivered to that provider.

The same override structure works for any push provider:

| Provider | Override path |
| - | - |
| Firebase Cloud Messaging | `providers.firebase-fcm.override.config` |
| Apple Push Notification service | `providers.apn.override.config` |
| Expo | `providers.expo.override.config` |
| OneSignal | `providers.onesignal.override.config` |

> [!NOTE]
>
> Filtering reads the tokens Courier manages, whether an SDK registered them or your backend did. A token passed inline in `to`, such as `firebaseToken` or `apn.token`, carries no device record and bypasses the filter.

Registering tokens from your backend rather than through an SDK? Set `device.app_id` yourself on the write. [Manage tokens yourself
DOC](/docs/send/push/overview#manage-tokens-yourself) has that call.

> [!NOTE]
>
> **Custom data not reaching the device?** `data` maps into the push payload by default. [Data mapping
> DOC](/docs/design/templates/data-mapping) covers the v1 template setting that can stop it.


# Send push with Pushbullet through Courier
Source: https://www.courier.com/docs/integrations/push/pushbullet

Connect Pushbullet with an access token. No profile field is needed.

## Prerequisites

* [A Pushbullet account](https://www.pushbullet.com/)
* Your Pushbullet Access Token

## Setup

**1. Create a Pushbullet access token**

In Pushbullet, open [account settings](https://www.pushbullet.com/#settings/account) and create an access token.

**2. Configure in Courier**

Open the [Pushbullet Integration](https://app.courier.com/integrations/catalog/pushbullet) in Courier, enter your access token, then click "Save."

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

Pushbullet needs no profile data.

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

Overrides change the request body Courier sends. You can override any field supported by Pushbullet's `/pushes` endpoint ([Pushbullet's create push reference](https://docs.pushbullet.com/#create-push)).

### Body overrides

This example sends a `url` by overriding the push `type`:

```javascript Node.js highlight={9-10} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      pushbullet: {
        override: {
          body: {
            type: "link",
            url: "https://www.courier.com",
          },
        },
      },
    },
  },
});
```

```python Python highlight={9-10} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {},
        "providers": {
            "pushbullet": {
                "override": {
                    "body": {
                        "type": "link",
                        "url": "https://www.courier.com",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={1,12-13} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {},
      "providers": {
        "pushbullet": {
          "override": {
            "body": {
              "type": "link",
              "url": "https://www.courier.com"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={9-10} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      pushbullet: {
        override: {
          body: {
            type: "link",
            url: "https://www.courier.com"
          }
        }
      }
    }
  }
)
```

```go Go highlight={12-13} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"pushbullet": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"type": "link",
						"url": "https://www.courier.com",
					},
				},
			},
		},
	},
})
```

```java Java highlight={8-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("pushbullet", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "type", "link",
                        "url", "https://www.courier.com"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9-10} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [],
    'providers' => [
      'pushbullet' => [
        'override' => [
          'body' => [
            'type' => 'link',
            'url' => 'https://www.courier.com',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={17-18} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient {  },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "pushbullet",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "type": "link",
                            "url": "https://www.courier.com"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"pushbullet": {"override": {"body": {"type": "link", "url": "https://www.courier.com"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template through Pushbullet as a link push.
```

### Config overrides

Swap the access token at send time with a config override:

```javascript Node.js highlight={6-12} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      pushbullet: {
        override: {
          config: {
            accessToken: "RUNTIME_ACCESS_TOKEN",
          },
        },
      },
    },
  },
});
```

```python Python highlight={6-12} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {},
        "providers": {
            "pushbullet": {
                "override": {
                    "config": {
                        "accessToken": "RUNTIME_ACCESS_TOKEN",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={9-15} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {},
      "providers": {
        "pushbullet": {
          "override": {
            "config": {
              "accessToken": "RUNTIME_ACCESS_TOKEN"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={6-12} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {},
    providers: {
      pushbullet: {
        override: {
          config: {
            accessToken: "RUNTIME_ACCESS_TOKEN"
          }
        }
      }
    }
  }
)
```

```go Go highlight={9-15} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"pushbullet": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"accessToken": "RUNTIME_ACCESS_TOKEN",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-10} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("pushbullet", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "accessToken", "RUNTIME_ACCESS_TOKEN"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={6-12} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [],
    'providers' => [
      'pushbullet' => [
        'override' => [
          'config' => [
            'accessToken' => 'RUNTIME_ACCESS_TOKEN',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-23} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient {  },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "pushbullet",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "accessToken": "RUNTIME_ACCESS_TOKEN"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"pushbullet": {"override": {"config": {"accessToken": "RUNTIME_ACCESS_TOKEN"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template through Pushbullet with a different access token.
```

## Provider details

```text theme={null}
pushbullet
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send push with Pusher through Courier
Source: https://www.courier.com/docs/integrations/push/pusher

Connect Pusher Channels with an app ID, key, secret, and cluster, and publish to a channel.

## Prerequisites

* [A Pusher Channels app](https://pusher.com/)
* Your Pusher App ID, Key, Secret, and Cluster

## Setup

**1. Get your Pusher Channels credentials**

In Pusher, open the [dashboard](https://dashboard.pusher.com/), select your app, and copy the app ID, key, secret, and cluster.

**2. Configure in Courier**

Open the [Pusher Integration](https://app.courier.com/integrations/catalog/pusher) in Courier, enter your app ID, key, secret, and cluster, then click "Save."

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

Pusher addresses the recipient by channel, so the profile you send to needs a `pusher` object. Store the channel once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3-5} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    pusher: {
      channel: 'my-channel',
    },
  },
});
```

```python Python highlight={4-6} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "pusher": {
            "channel": "my-channel",
        },
    },
)
```

```bash cURL highlight={7-9} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "pusher": {
        "channel": "my-channel"
      }
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    pusher: {
      channel: "my-channel"
    }
  }
)
```

```go Go highlight={6-8} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"pusher": map[string]any{
				"channel": "my-channel",
			},
		},
	},
)
```

```java Java highlight={4-5} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("pusher", JsonValue.from(java.util.Map.of(
            "channel", "my-channel")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-4} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'pusher' => [
    'channel' => 'my-channel',
  ],
]);
```

```csharp C# highlight={7-9} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "pusher": {
            "channel": "my-channel"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"pusher":{"channel":"my-channel"}}'
```

```text MCP theme={null}
With Courier MCP, save the Pusher channel my-channel on user_123.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "pusher": { "channel": "my-channel" } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `pusher` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `pusher`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      pusher: {
        channel: "my-channel",
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-6} theme={null}
response = client.send.message(
    message={
        "to": {
            "pusher": {
                "channel": "my-channel",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-9} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "pusher": {
          "channel": "my-channel"
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-6} theme={null}
response = courier.send_.message(
  message: {
    to: {
      pusher: {
        channel: "my-channel"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"pusher": {"channel": "my-channel"}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("pusher", JsonValue.from(Map.of(
            "channel", "my-channel")))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-6} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'pusher' => [
        'channel' => 'my-channel',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"pusher": {"channel": "my-channel"}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"pusher": {"channel": "my-channel"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the Pusher channel my-channel.
```

## Template requirements

You can use Pusher two ways in Courier:

* **The Push channel.** You get the rich editor.
* **A direct Pusher channel.** You get a jsonnet editor to customize your payload.

## Example event

```javascript Node.js theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      pusher: {
        channel: "my-channel",
      },
    },
    data: {
      name: "Sarah Bennett",
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "pusher": {
                "channel": "my-channel",
            },
        },
        "data": {
            "name": "Sarah Bennett",
        },
    },
)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "pusher": {
          "channel": "my-channel"
        }
      },
      "data": {
        "name": "Sarah Bennett"
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      pusher: {
        channel: "my-channel"
      }
    },
    data: {
      name: "Sarah Bennett"
    }
  }
)
```

```go Go theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "pusher": {
    "channel": "my-channel"
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("pusher", JsonValue.from(java.util.Map.of(
                "channel", "my-channel"
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett"
        )))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'pusher' => [
        'channel' => 'my-channel',
      ],
    ],
    'data' => [
      'name' => 'Sarah Bennett',
    ],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "pusher": {
                    "channel": "my-channel"
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"pusher": {"channel": "my-channel"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}'
```

```text MCP theme={null}
With Courier MCP, send my template to the my-channel Pusher channel.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

Pusher uses the Pusher SDK directly, so it takes no `providers.pusher.override`. Courier sends the rendered event to the channel on the recipient profile, and a push channel override's `data` replaces the data that goes with it.

## Tracking events

Courier includes tracking URL information in the `data` attribute on the incoming message payload. See [Courier push notification tracking
DOC](/docs/integrations/push/overview#tracking).

## Provider details

```text theme={null}
pusher
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send push with Pusher Beams through Courier
Source: https://www.courier.com/docs/integrations/push/pusher-beams

Connect Pusher Beams with an instance ID and secret key, and target users or interests.

## Prerequisites

* [A Pusher Beams instance](https://pusher.com/beams)
* Your Pusher Beams Instance ID and Secret Key

## Setup

**1. Get your Pusher Beams credentials**

In Pusher, open the [dashboard](https://dashboard.pusher.com/) and copy your Beams instance ID and secret key.

**2. Configure in Courier**

Open the [Pusher Beams Integration](https://app.courier.com/integrations/catalog/pusher-beams) in Courier, enter your instance ID and secret key, then click "Save."

## Profile requirements

Device tokens live on the user profile rather than on the send, so one profile can hold tokens for several devices and every push provider reads them from the same place. [Send push
DOC](/docs/send/push/overview) covers the model.

Pusher Beams sends to interests or to users, so the profile you send to needs a `pusherBeams` object with at least one `mode`: `web`, `apns`, or `fcm`. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

**Interests**

Everyone subscribed to the interest gets the notification.

```javascript Node.js highlight={3-12} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    pusherBeams: {
      interests: [
        'interest-1',
        'interest-2',
      ],
      mode: [
        'apns',
        'fcm',
      ],
    },
  },
});
```

```python Python highlight={4-13} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "pusherBeams": {
            "interests": [
                "interest-1",
                "interest-2",
            ],
            "mode": [
                "apns",
                "fcm",
            ],
        },
    },
)
```

```bash cURL highlight={7-16} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "pusherBeams": {
        "interests": [
          "interest-1",
          "interest-2"
        ],
        "mode": [
          "apns",
          "fcm"
        ]
      }
    }
  }'
```

```ruby Ruby highlight={4-7} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    pusherBeams: {
      interests: ["interest-1", "interest-2"],
      mode: ["apns", "fcm"]
    }
  }
)
```

```go Go highlight={6-9} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"pusherBeams": map[string]any{
				"interests": []any{"interest-1", "interest-2"},
				"mode": []any{"apns", "fcm"},
			},
		},
	},
)
```

```java Java highlight={4-6} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("pusherBeams", JsonValue.from(java.util.Map.of(
            "interests", java.util.List.of("interest-1", "interest-2"),
            "mode", java.util.List.of("apns", "fcm"))))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-5} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'pusherBeams' => [
    'interests' => ['interest-1', 'interest-2'],
    'mode' => ['apns', 'fcm'],
  ],
]);
```

```csharp C# highlight={7-16} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "pusherBeams": {
            "interests": [
              "interest-1",
              "interest-2"
            ],
            "mode": [
              "apns",
              "fcm"
            ]
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"pusherBeams":{"interests":["interest-1","interest-2"],"mode":["apns","fcm"]}}'
```

```text MCP theme={null}
With Courier MCP, save the Pusher Beams interests interest-1 and interest-2 on user_123.
```

**Users**

Beams resolves each id against the users it has registered.

```javascript Node.js highlight={3-12} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    pusherBeams: {
      userIds: [
        'user-id-1',
        'user-id-2',
      ],
      mode: [
        'apns',
        'fcm',
      ],
    },
  },
});
```

```python Python highlight={4-13} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "pusherBeams": {
            "userIds": [
                "user-id-1",
                "user-id-2",
            ],
            "mode": [
                "apns",
                "fcm",
            ],
        },
    },
)
```

```bash cURL highlight={7-16} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "pusherBeams": {
        "userIds": [
          "user-id-1",
          "user-id-2"
        ],
        "mode": [
          "apns",
          "fcm"
        ]
      }
    }
  }'
```

```ruby Ruby highlight={4-7} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    pusherBeams: {
      userIds: ["user-id-1", "user-id-2"],
      mode: ["apns", "fcm"]
    }
  }
)
```

```go Go highlight={6-9} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"pusherBeams": map[string]any{
				"userIds": []any{"user-id-1", "user-id-2"},
				"mode": []any{"apns", "fcm"},
			},
		},
	},
)
```

```java Java highlight={4-6} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("pusherBeams", JsonValue.from(java.util.Map.of(
            "userIds", java.util.List.of("user-id-1", "user-id-2"),
            "mode", java.util.List.of("apns", "fcm"))))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2-5} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'pusherBeams' => [
    'userIds' => ['user-id-1', 'user-id-2'],
    'mode' => ['apns', 'fcm'],
  ],
]);
```

```csharp C# highlight={7-16} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "pusherBeams": {
            "userIds": [
              "user-id-1",
              "user-id-2"
            ],
            "mode": [
              "apns",
              "fcm"
            ]
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} wrap theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"pusherBeams":{"userIds":["user-id-1","user-id-2"],"mode":["apns","fcm"]}}'
```

```text MCP theme={null}
With Courier MCP, save the Pusher Beams user ids user-id-1 and user-id-2 on user_123.
```

Then send to `user_id` and Courier resolves the address.

For a one-off with no stored profile, pass it inline instead: `"to": { "pusherBeams": { "interests": ["interest-1"], "mode": ["apns"] } }`.

> **[Send by user id](/docs/recipients/overview#send-by-user-id)**
>
> The call in every language, and the rest of the profile object.

## Send to a recipient

**Send to user id**

Courier reads `pusherBeams` off the saved profile, so preferences apply and the value can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by email.
```

**Send to `pusherBeams`**

Pass it inline instead and nothing is stored. Swap this `to` object into the call on the other tab.

```javascript Node.js highlight={5-8} theme={null}
const { requestId } = await courier.send.message({
  message: {
    // A provider recipient is a profile field, so it sits outside the typed union.
    to: {
      pusherBeams: {
        interests: ["interest-1", "interest-2"],
        mode: ["apns", "fcm"],
      },
    } as any,
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4-7} theme={null}
response = client.send.message(
    message={
        "to": {
            "pusherBeams": {
                "interests": ["interest-1", "interest-2"],
                "mode": ["apns", "fcm"],
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7-16} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "pusherBeams": {
          "interests": [
            "interest-1",
            "interest-2"
          ],
          "mode": [
            "apns",
            "fcm"
          ]
        }
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4-7} theme={null}
response = courier.send_.message(
  message: {
    to: {
      pusherBeams: {
        interests: ["interest-1", "interest-2"],
        mode: ["apns", "fcm"]
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={2-4} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
to := param.Override[shared.UserRecipientParam](
	json.RawMessage(`{"pusherBeams": {"interests": ["interest-1", "interest-2"], "mode": ["apns", "fcm"]}}`),
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.builder()
    .putAdditionalProperty("pusherBeams", JsonValue.from(Map.of(
            "interests", List.of("interest-1", "interest-2"),
            "mode", List.of("apns", "fcm"))))
    .build();

client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(to)
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build());
```

```php PHP highlight={4-7} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'pusherBeams' => [
        'interests' => ['interest-1', 'interest-2'],
        'mode' => ['apns', 'fcm'],
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={3-5} theme={null}
// A provider recipient is a profile field, so it sits outside the typed union.
UserRecipient to = UserRecipient.FromRawUnchecked(
    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"pusherBeams": {"interests": ["interest-1", "interest-2"], "mode": ["apns", "fcm"]}}"""
    )
);

var response = await client.Send.Message(new() { Message = new() { To = to, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" } });
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"pusherBeams": {"interests": ["interest-1", "interest-2"], "mode": ["apns", "fcm"]}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to the Pusher Beams interests interest-1 and interest-2.
```

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. [Push channel overrides
DOC](/docs/integrations/push/overview#channel-overrides) lists the fields every push provider takes.

A provider override changes the request body Courier sends to Pusher Beams, or swaps the instance ID and secret key.

### Body overrides

This example replaces the title and body:

```javascript Node.js highlight={15-22} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      pusherBeams: {
        interests: [
          "interest-1",
        ],
        mode: [
          "fcm",
        ],
      },
    },
    providers: {
      "pusher-beams": {
        override: {
          body: {
            title: "Custom Title",
            body: "Custom body text",
          },
        },
      },
    },
  },
});
```

```python Python highlight={15-22} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "pusherBeams": {
                "interests": [
                    "interest-1",
                ],
                "mode": [
                    "fcm",
                ],
            },
        },
        "providers": {
            "pusher-beams": {
                "override": {
                    "body": {
                        "title": "Custom Title",
                        "body": "Custom body text",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={18-25} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "pusherBeams": {
          "interests": [
            "interest-1"
          ],
          "mode": [
            "fcm"
          ]
        }
      },
      "providers": {
        "pusher-beams": {
          "override": {
            "body": {
              "title": "Custom Title",
              "body": "Custom body text"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={15-22} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      pusherBeams: {
        interests: [
          "interest-1"
        ],
        mode: [
          "fcm"
        ]
      }
    },
    providers: {
      "pusher-beams": {
        override: {
          body: {
            title: "Custom Title",
            body: "Custom body text"
          }
        }
      }
    }
  }
)
```

```go Go highlight={19-26} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "pusherBeams": {
    "interests": [
      "interest-1"
    ],
    "mode": [
      "fcm"
    ]
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"pusher-beams": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"title": "Custom Title",
						"body": "Custom body text",
					},
				},
			},
		},
	},
})
```

```java Java highlight={17-22} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("pusherBeams", JsonValue.from(java.util.Map.of(
                "interests", java.util.List.of(
                    "interest-1"
                ),
                "mode", java.util.List.of(
                    "fcm"
                )
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("pusher-beams", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "title", "Custom Title",
                        "body", "Custom body text"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={15-22} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'pusherBeams' => [
        'interests' => [
          'interest-1',
        ],
        'mode' => [
          'fcm',
        ],
      ],
    ],
    'providers' => [
      'pusher-beams' => [
        'override' => [
          'body' => [
            'title' => 'Custom Title',
            'body' => 'Custom body text',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={26-41} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "pusherBeams": {
                    "interests": [
                      "interest-1"
                    ],
                    "mode": [
                      "fcm"
                    ]
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "pusher-beams",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "title": "Custom Title",
                            "body": "Custom body text"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"pusherBeams": {"interests": ["interest-1"], "mode": ["fcm"]}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"pusher-beams": {"override": {"body": {"title": "Custom Title", "body": "Custom body text"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to these Pusher Beams interests with the body overridden.
```

> [!NOTE]
>
> Courier sets only `title` and `body`. Overrides merge into that alert object and go out in every mode you select, so mode-specific shapes like `fcm.notification` are ignored.

### Config overrides

Swap the instance ID or secret key at send time:

```javascript Node.js highlight={15-22} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      pusherBeams: {
        interests: [
          "interest-1",
        ],
        mode: [
          "fcm",
        ],
      },
    },
    providers: {
      "pusher-beams": {
        override: {
          config: {
            instanceId: "RUNTIME_INSTANCE_ID",
            secretKey: "RUNTIME_SECRET_KEY",
          },
        },
      },
    },
  },
});
```

```python Python highlight={15-22} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "pusherBeams": {
                "interests": [
                    "interest-1",
                ],
                "mode": [
                    "fcm",
                ],
            },
        },
        "providers": {
            "pusher-beams": {
                "override": {
                    "config": {
                        "instanceId": "RUNTIME_INSTANCE_ID",
                        "secretKey": "RUNTIME_SECRET_KEY",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={18-25} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "pusherBeams": {
          "interests": [
            "interest-1"
          ],
          "mode": [
            "fcm"
          ]
        }
      },
      "providers": {
        "pusher-beams": {
          "override": {
            "config": {
              "instanceId": "RUNTIME_INSTANCE_ID",
              "secretKey": "RUNTIME_SECRET_KEY"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={15-22} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      pusherBeams: {
        interests: [
          "interest-1"
        ],
        mode: [
          "fcm"
        ]
      }
    },
    providers: {
      "pusher-beams": {
        override: {
          config: {
            instanceId: "RUNTIME_INSTANCE_ID",
            secretKey: "RUNTIME_SECRET_KEY"
          }
        }
      }
    }
  }
)
```

```go Go highlight={19-26} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "pusherBeams": {
    "interests": [
      "interest-1"
    ],
    "mode": [
      "fcm"
    ]
  }
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"pusher-beams": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"instanceId": "RUNTIME_INSTANCE_ID",
						"secretKey": "RUNTIME_SECRET_KEY",
					},
				},
			},
		},
	},
})
```

```java Java highlight={17-22} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .putAdditionalProperty("pusherBeams", JsonValue.from(java.util.Map.of(
                "interests", java.util.List.of(
                    "interest-1"
                ),
                "mode", java.util.List.of(
                    "fcm"
                )
            )))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("pusher-beams", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "instanceId", "RUNTIME_INSTANCE_ID",
                        "secretKey", "RUNTIME_SECRET_KEY"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={15-22} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'pusherBeams' => [
        'interests' => [
          'interest-1',
        ],
        'mode' => [
          'fcm',
        ],
      ],
    ],
    'providers' => [
      'pusher-beams' => [
        'override' => [
          'config' => [
            'instanceId' => 'RUNTIME_INSTANCE_ID',
            'secretKey' => 'RUNTIME_SECRET_KEY',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={26-41} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "pusherBeams": {
                    "interests": [
                      "interest-1"
                    ],
                    "mode": [
                      "fcm"
                    ]
                  }
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "pusher-beams",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "instanceId": "RUNTIME_INSTANCE_ID",
                            "secretKey": "RUNTIME_SECRET_KEY"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"pusherBeams": {"interests": ["interest-1"], "mode": ["fcm"]}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"pusher-beams": {"override": {"config": {"instanceId": "RUNTIME_INSTANCE_ID", "secretKey": "RUNTIME_SECRET_KEY"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to these Pusher Beams interests with a different instance id.
```

## Provider details

```text theme={null}
pusher-beams
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send rate limits
Source: https://www.courier.com/docs/integrations/send-rate-limits

Set the maximum rate Courier sends to a provider. Sends above the rate are queued, not dropped.

Send to Courier at any rate, and Courier hands those sends to each provider at the rate you set. Without a limit, Courier sends to the provider as fast as possible.

![Provider settings with a Send Rate Limit field and a Per dropdown set to Second](https://mintcdn.com/courier-4f1f25dc/NaVp9cBYP7WR7F2u/assets/integration-send-rate-limit-settings.webp?fit=max\&auto=format\&n=NaVp9cBYP7WR7F2u\&q=85\&s=b1b7c169da648677b46a468201612234)

Send Rate Limit in a provider's settings

Each provider sets its own limits, and they often differ by account or plan. Amazon SES, for example, gives each account a maximum send rate. Set the send rate limit to match your account.

## Set a limit in the console

In Integrations, click the provider, then click **Settings**. Enter a number in **Send Rate Limit** and pick **Second**, **Minute**, or **Hour** under **Per**. Clear the field to remove the limit.

## Set a limit with the API

The limit is `rate_limit` in the provider configuration's `settings`. To set or change it on an existing configuration, send a JSON Patch operation for `/settings/rate_limit` to [Patch a Provider](/docs/api-reference/providers/patch-a-provider). Every other setting, including the provider's credentials, stays as it is.

```json theme={null}
{
  "patch": [
    {
      "op": "add",
      "path": "/settings/rate_limit",
      "value": {
        "rate": 10,
        "period": "second"
      }
    }
  ]
}
```

| Field | Value |
| - | - |
| `rate` | A number greater than 0. Fractions are allowed. |
| `period` | `second`, `minute`, or `hour` |

`add` sets the limit whether or not one exists. To change only the rate, `replace` the path `/settings/rate_limit/rate`.

The interval between sends (`period` divided by `rate`) must be from 1 millisecond to 12 hours. A value outside that range returns a `400` with an `InvalidRateLimit` error.

To remove the limit, send a `remove` operation to the same endpoint.

```json theme={null}
{
  "patch": [
    {
      "op": "remove",
      "path": "/settings/rate_limit"
    }
  ]
}
```

To set a limit on a new configuration, include `rate_limit` in its `settings` when you create it with [Create a Provider](/docs/api-reference/providers/create-a-provider).

## How it works

* **Sends above the rate are queued, not dropped.** Courier sends them to the provider as the rate allows.
* **Each configuration has its own limit.** Two SES configurations each get their own rate, and so does each environment. A limit in Test doesn't apply to Production.
* **Changes apply within 60 seconds.**

## Related docs

> **[Rate limit backoff](/docs/integrations/overview#rate-limit-management)**
>
> How Courier retries when a provider returns a 429.

> **[Amazon SES](/docs/integrations/email/aws-ses)**
>
> Connect SES and match your account's maximum send rate.


# Send SMS with Africa's Talking through Courier
Source: https://www.courier.com/docs/integrations/sms/africas-talking

Connect Africa's Talking with a username and API key, then override the sender ID per send.

## Prerequisites

* [An Africa's Talking account](https://africastalking.com/)
* Your Africa's Talking API Key and Application Username

## Setup

Open the [Africa's Talking integration](https://app.courier.com/integrations/catalog/africastalking-sms) in Courier, enter your API Key and Application Username, then click "Save."

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

A provider override changes what Courier sends to the Africa's Talking SMS API. For example, add a registered short code or alphanumeric sender ID from your Africa's Talking application:

```javascript Node.js highlight={8-14} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+27765559758",
    },
    providers: {
      "africastalking-sms": {
        override: {
          body: {
            from: "12345",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-14} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+27765559758",
        },
        "providers": {
            "africastalking-sms": {
                "override": {
                    "body": {
                        "from": "12345",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-17} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+27765559758"
      },
      "providers": {
        "africastalking-sms": {
          "override": {
            "body": {
              "from": "12345"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-14} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+27765559758"
    },
    providers: {
      "africastalking-sms": {
        override: {
          body: {
            from: "12345"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-16} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+27765559758"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"africastalking-sms": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"from": "12345",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-10} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+27765559758").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("africastalking-sms", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "from", "12345"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-14} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+27765559758',
    ],
    'providers' => [
      'africastalking-sms' => [
        'override' => [
          'body' => [
            'from' => '12345',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-23} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+27765559758" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "africastalking-sms",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "from": "12345"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+27765559758"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"africastalking-sms": {"override": {"body": {"from": "12345"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +27765559758 with my Africa's Talking sender id.
```

Overrides are deep-merged into the request. Fields you set replace their counterparts, and everything you leave out is still sent. The full field list is in the [Africa's Talking SMS API docs](https://developers.africastalking.com/docs/sms/overview).

## Provider details

```text theme={null}
africastalking-sms
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send SMS with Amazon SNS for SMS through Courier
Source: https://www.courier.com/docs/integrations/sms/aws-sns

Connect Amazon SNS for SMS with IAM credentials, then override message attributes per send.

Amazon Simple Notification Service (Amazon SNS, AWS SNS) delivers SMS to a recipient's phone number. Courier's provider key is `aws-sns`.

> [!NOTE]
>
> Amazon SNS also works as a push provider. See [Amazon SNS for push
> DOC](/docs/integrations/push/aws-sns).

## Prerequisites

* [An AWS IAM user that can publish to SNS](https://aws.amazon.com/)
* [That user's Access Key ID and Secret Access Key](https://console.aws.amazon.com/iam/)
* The AWS region you send SMS from

## Setup

**1. Create an AWS access key**

In AWS, create an IAM user with SNS publish permission and copy its [access key ID and secret access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).

**2. Configure in Courier**

Open the [Amazon SNS integration](https://app.courier.com/integrations/catalog/aws-sns) in Courier, enter your Access Key ID and Secret Access Key, choose your region, then click "Complete."

The same form has a Topic ARN field. That applies to push only, so leave it empty for SMS. A `phone_number` on the profile outranks it, so a saved Topic ARN never diverts an SMS.

You add the integration once. It then appears as a provider on both the SMS and push channels.

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

The `config` override swaps the Access Key ID, Secret Access Key, or region at send time. Region defaults to `us-east-1` when neither the override nor the integration sets one.

```javascript Node.js highlight={8-16} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    providers: {
      "aws-sns": {
        override: {
          config: {
            accessKeyId: "RUNTIME_ACCESS_KEY_ID",
            secretAccessKey: "RUNTIME_SECRET_ACCESS_KEY",
            region: "eu-west-1",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-16} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "providers": {
            "aws-sns": {
                "override": {
                    "config": {
                        "accessKeyId": "RUNTIME_ACCESS_KEY_ID",
                        "secretAccessKey": "RUNTIME_SECRET_ACCESS_KEY",
                        "region": "eu-west-1",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-19} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "providers": {
        "aws-sns": {
          "override": {
            "config": {
              "accessKeyId": "RUNTIME_ACCESS_KEY_ID",
              "secretAccessKey": "RUNTIME_SECRET_ACCESS_KEY",
              "region": "eu-west-1"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-16} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    providers: {
      "aws-sns": {
        override: {
          config: {
            accessKeyId: "RUNTIME_ACCESS_KEY_ID",
            secretAccessKey: "RUNTIME_SECRET_ACCESS_KEY",
            region: "eu-west-1"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-18} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"aws-sns": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"accessKeyId": "RUNTIME_ACCESS_KEY_ID",
						"secretAccessKey": "RUNTIME_SECRET_ACCESS_KEY",
						"region": "eu-west-1",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-12} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("aws-sns", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "accessKeyId", "RUNTIME_ACCESS_KEY_ID",
                        "secretAccessKey", "RUNTIME_SECRET_ACCESS_KEY",
                        "region", "eu-west-1"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-16} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'providers' => [
      'aws-sns' => [
        'override' => [
          'config' => [
            'accessKeyId' => 'RUNTIME_ACCESS_KEY_ID',
            'secretAccessKey' => 'RUNTIME_SECRET_ACCESS_KEY',
            'region' => 'eu-west-1',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-25} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "aws-sns",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "accessKeyId": "RUNTIME_ACCESS_KEY_ID",
                            "secretAccessKey": "RUNTIME_SECRET_ACCESS_KEY",
                            "region": "eu-west-1"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"aws-sns": {"override": {"config": {"accessKeyId": "RUNTIME_ACCESS_KEY_ID", "secretAccessKey": "RUNTIME_SECRET_ACCESS_KEY", "region": "eu-west-1"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +12345678901 through SNS in a different region.
```

The `body` override merges into the SNS `Publish` request, so its fields use AWS parameter names rather than Courier's. See the [SNS publish properties](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SNS.html#publish-property).

```javascript Node.js highlight={8-19} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    providers: {
      "aws-sns": {
        override: {
          body: {
            MessageAttributes: {
              "AWS.SNS.SMS.SMSType": {
                DataType: "String",
                StringValue: "Transactional",
              },
            },
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-19} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "providers": {
            "aws-sns": {
                "override": {
                    "body": {
                        "MessageAttributes": {
                            "AWS.SNS.SMS.SMSType": {
                                "DataType": "String",
                                "StringValue": "Transactional",
                            },
                        },
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-22} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "providers": {
        "aws-sns": {
          "override": {
            "body": {
              "MessageAttributes": {
                "AWS.SNS.SMS.SMSType": {
                  "DataType": "String",
                  "StringValue": "Transactional"
                }
              }
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-19} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    providers: {
      "aws-sns": {
        override: {
          body: {
            MessageAttributes: {
              "AWS.SNS.SMS.SMSType": {
                DataType: "String",
                StringValue: "Transactional"
              }
            }
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-21} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"aws-sns": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"MessageAttributes": map[string]any{
							"AWS.SNS.SMS.SMSType": map[string]any{
								"DataType": "String",
								"StringValue": "Transactional",
							},
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-15} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("aws-sns", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "MessageAttributes", java.util.Map.of(
                            "AWS.SNS.SMS.SMSType", java.util.Map.of(
                                "DataType", "String",
                                "StringValue", "Transactional"
                            )
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-19} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'providers' => [
      'aws-sns' => [
        'override' => [
          'body' => [
            'MessageAttributes' => [
              'AWS.SNS.SMS.SMSType' => [
                'DataType' => 'String',
                'StringValue' => 'Transactional',
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-28} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "aws-sns",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "MessageAttributes": {
                              "AWS.SNS.SMS.SMSType": {
                                "DataType": "String",
                                "StringValue": "Transactional"
                              }
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"aws-sns": {"override": {"body": {"MessageAttributes": {"AWS.SNS.SMS.SMSType": {"DataType": "String", "StringValue": "Transactional"}}}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +12345678901 with the SNS publish parameters overridden.
```

## Provider details

```text theme={null}
aws-sns
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send SMS with Azure Communication Services
Source: https://www.courier.com/docs/integrations/sms/azure-sms

Connect Azure Communication Services with a connection string and from number.

## Prerequisites

* [An Azure Communication Services resource with an SMS-capable number](https://azure.microsoft.com/en-us/products/communication-services/)
* [That resource's endpoint URL and access key](https://portal.azure.com/)

## Setup

**1. Create an Azure Communication Services resource**

In Azure, [create a Communication Services resource](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/create-communication-resource) and copy its access key and endpoint.

**2. Configure in Courier**

Open the [Azure SMS integration](https://app.courier.com/integrations/catalog/azure-sms) in Courier, enter your access key, endpoint, and from number, then click "Save."

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

Overrides change the request Courier makes to Azure Communication Services. `config` overrides the `accessKey`, `endpoint`, and `from` number. `body` overrides the `message` text and `to` number.

```javascript Node.js highlight={8-20} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    providers: {
      "azure-sms": {
        override: {
          body: {
            to: "+10987654321",
            message: "Override message content",
          },
          config: {
            from: "<override from number>",
            accessKey: "<override access key>",
            endpoint: "<override endpoint>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-20} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "providers": {
            "azure-sms": {
                "override": {
                    "body": {
                        "to": "+10987654321",
                        "message": "Override message content",
                    },
                    "config": {
                        "from": "<override from number>",
                        "accessKey": "<override access key>",
                        "endpoint": "<override endpoint>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-23} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "providers": {
        "azure-sms": {
          "override": {
            "body": {
              "to": "+10987654321",
              "message": "Override message content"
            },
            "config": {
              "from": "<override from number>",
              "accessKey": "<override access key>",
              "endpoint": "<override endpoint>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-20} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    providers: {
      "azure-sms": {
        override: {
          body: {
            to: "+10987654321",
            message: "Override message content"
          },
          config: {
            from: "<override from number>",
            accessKey: "<override access key>",
            endpoint: "<override endpoint>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-22} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"azure-sms": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"to": "+10987654321",
						"message": "Override message content",
					},
					"config": map[string]any{
						"from": "<override from number>",
						"accessKey": "<override access key>",
						"endpoint": "<override endpoint>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("azure-sms", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "to", "+10987654321",
                        "message", "Override message content"
                    ),
                    "config", java.util.Map.of(
                        "from", "<override from number>",
                        "accessKey", "<override access key>",
                        "endpoint", "<override endpoint>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-20} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'providers' => [
      'azure-sms' => [
        'override' => [
          'body' => [
            'to' => '+10987654321',
            'message' => 'Override message content',
          ],
          'config' => [
            'from' => '<override from number>',
            'accessKey' => '<override access key>',
            'endpoint' => '<override endpoint>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-29} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "azure-sms",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "to": "+10987654321",
                            "message": "Override message content"
                          },
                          "config": {
                            "from": "<override from number>",
                            "accessKey": "<override access key>",
                            "endpoint": "<override endpoint>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"azure-sms": {"override": {"body": {"to": "+10987654321", "message": "Override message content"}, "config": {"from": "<override from number>", "accessKey": "<override access key>", "endpoint": "<override endpoint>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +12345678901 through Azure from a different number.
```

## Provider details

```text theme={null}
azure-sms
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send SMS with Bird through Courier
Source: https://www.courier.com/docs/integrations/sms/bird

Connect Bird with an access key and originator, then override either per send.

## Prerequisites

* [A Bird account](https://bird.com/)
* Your Bird access key
* An originating phone number in Bird

## Setup

**1. Get your Bird access key**

In Bird, open your [workspace](https://app.bird.com/) and copy an access key. The originator is the number or sender ID you send from.

**2. Configure in Courier**

Open the [Bird integration](https://app.courier.com/integrations/catalog/messagebird-sms) in Courier, enter your access key and originator number, then click "Save."

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

Overrides change the request body and config Courier uses to send through Bird. `config` overrides the `accessKey`. `body` overrides any message body field.

Bird was called MessageBird when this integration shipped, so its provider key is still `messagebird-sms`.

```javascript Node.js highlight={8-17} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    providers: {
      "messagebird-sms": {
        override: {
          body: {
            originator: "MyCompany",
          },
          config: {
            accessKey: "<override access key>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-17} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "providers": {
            "messagebird-sms": {
                "override": {
                    "body": {
                        "originator": "MyCompany",
                    },
                    "config": {
                        "accessKey": "<override access key>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-20} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "providers": {
        "messagebird-sms": {
          "override": {
            "body": {
              "originator": "MyCompany"
            },
            "config": {
              "accessKey": "<override access key>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-17} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    providers: {
      "messagebird-sms": {
        override: {
          body: {
            originator: "MyCompany"
          },
          config: {
            accessKey: "<override access key>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-19} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"messagebird-sms": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"originator": "MyCompany",
					},
					"config": map[string]any{
						"accessKey": "<override access key>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-13} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("messagebird-sms", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "originator", "MyCompany"
                    ),
                    "config", java.util.Map.of(
                        "accessKey", "<override access key>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-17} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'providers' => [
      'messagebird-sms' => [
        'override' => [
          'body' => [
            'originator' => 'MyCompany',
          ],
          'config' => [
            'accessKey' => '<override access key>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-26} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "messagebird-sms",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "originator": "MyCompany"
                          },
                          "config": {
                            "accessKey": "<override access key>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"messagebird-sms": {"override": {"body": {"originator": "MyCompany"}, "config": {"accessKey": "<override access key>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +12345678901 through Bird with a different access key.
```

Overrides are deep-merged into the request. Fields you set replace their counterparts, and everything you leave out is still sent. The full field list is in the [Bird SMS API docs](https://developers.messagebird.com/api/sms-messaging/).

## Provider details

```text theme={null}
messagebird-sms
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# SMS providers
Source: https://www.courier.com/docs/integrations/sms/overview

Every SMS provider Courier supports, the phone_number profile field, and per-send overrides.

## Available providers

> **[Twilio](/docs/integrations/sms/twilio)**

> **[Vonage](/docs/integrations/sms/vonage)**

> **[Telnyx](/docs/integrations/sms/telnyx)**

> **[Sinch](/docs/integrations/sms/sinch)**

> **[Plivo](/docs/integrations/sms/plivo)**

> **[Bird](/docs/integrations/sms/bird)**

> **[Sinch Engage](/docs/integrations/sms/sinch-engage)**

> **[Azure Communication Services](/docs/integrations/sms/azure-sms)**

> **[Amazon SNS](/docs/integrations/sms/aws-sns)**

> **[TextUs](/docs/integrations/sms/textus)**

> **[Africa's Talking](/docs/integrations/sms/africas-talking)**

> **[SMSCentral](/docs/integrations/sms/smscentral)**

Amazon SNS also sends [push
DOC](/docs/integrations/push/aws-sns). [Twilio
DOC](/docs/integrations/sms/twilio) is the only one here that carries MMS.

## Profile requirements

Every SMS provider addresses the recipient the same way, by phone number, so the profile you send to needs a `phone_number`. Store it once with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), which merges into the profile and creates it if it doesn't exist:

```javascript Node.js highlight={3} theme={null}
const profile = await client.profiles.create('user_123', {
  profile: {
    phone_number: '+15551234567',
  },
});
```

```python Python highlight={4} theme={null}
profile = client.profiles.create(
    user_id="user_123",
    profile={
        "phone_number": "+15551234567",
    },
)
```

```bash cURL highlight={7} theme={null}
curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "phone_number": "+15551234567"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
profile = courier.profiles.create(
  "user_123",
  profile: {
    phone_number: "+15551234567"
  }
)
```

```go Go highlight={6} theme={null}
profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"phone_number": "+15551234567",
		},
	},
)
```

```java Java highlight={4} theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("phone_number", JsonValue.from("+15551234567"))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);
```

```php PHP highlight={2} theme={null}
$profile = $client->profiles->create('user_123', profile: [
  'phone_number' => '+15551234567',
]);
```

```csharp C# highlight={6} theme={null}
ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "phone_number", JsonSerializer.SerializeToElement("+15551234567") },
    },
};
var profile = await client.Profiles.Create(parameters);
```

```bash CLI highlight={4} theme={null}
courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"phone_number":"+15551234567"}'
```

```text MCP theme={null}
With Courier MCP, create a profile for user_123 with the phone number +15551234567.
```

Store the number in E.164 form, with the country code and a leading `+`. A provider that accepts a local format at its own API doesn't change what Courier stores, and a number without a country code fails at the provider rather than at the send.

## Send to a recipient

**Send to user id**

Courier reads `phone_number` off the saved profile, so preferences apply and the number can change without touching this code.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to user_123 by SMS.
```

**Send to phone number**

A one-off to a number you aren't storing. No profile is created, so no preference applies.

```javascript Node.js highlight={4} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      phone_number: "+15551234567",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={4} theme={null}
response = client.send.message(
    message={
        "to": {
            "phone_number": "+15551234567",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={7} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "phone_number": "+15551234567"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={4} theme={null}
response = courier.send_.message(
  message: {
    to: {
      phone_number: "+15551234567"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+15551234567"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+15551234567").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={4} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'phone_number' => '+15551234567',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+15551234567" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+15551234567"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my template to +15551234567 by SMS.
```

## Channel overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. Most SMS providers accept these two in a provider override.

| Field | Sets |
| :- | :- |
| `body` | The message text, the recipient number, or other request body fields |
| `config` | Credentials or sender numbers, swapped for this one send |

Each provider page documents its own schema.

> [!TIP]
>
> Can't find a provider? Start a chat or email [support@courier.com](mailto:support@courier.com)


# Send SMS with Plivo through Courier
Source: https://www.courier.com/docs/integrations/sms/plivo

Connect Plivo with an Auth ID, Auth Token, and from number. Delivery status is polled.

## Prerequisites

* [A Plivo account](https://www.plivo.com/)
* Your Plivo Auth ID and Auth Token
* An SMS-capable from number in Plivo

## Setup

**1. Get your Plivo credentials**

In Plivo, open the [console](https://console.plivo.com/dashboard/) and copy your Auth ID and Auth Token.

**2. Configure in Courier**

Open the [Plivo Integration](https://app.courier.com/integrations/catalog/plivo) in Courier, enter your Auth ID, Auth Token, and from number, then click "Save."

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins. Plivo reads neither, so a send goes out as the template renders it.

## Delivery tracking

Once the integration is configured, Courier polls Plivo's API for delivery status and shows it in the [message logs](https://app.courier.com/logs).

## Provider details

```text theme={null}
plivo
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send SMS with Sinch through Courier
Source: https://www.courier.com/docs/integrations/sms/sinch

Connect Sinch with a service plan ID and API token, then override credentials or body per send.

## Prerequisites

* [A Sinch account](https://www.sinch.com/)
* Your Sinch Service Plan ID and API token
* An SMS-capable from number in Sinch

## Setup

**1. Get your Sinch credentials**

In Sinch, open the [dashboard](https://dashboard.sinch.com/) and copy your Service Plan ID and API token.

**2. Configure in Courier**

Open the [Sinch Integration](https://app.courier.com/integrations/catalog/sinch) in Courier, enter your Service Plan ID, API token, and from number, then click "Save."

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

Overrides change the request body and config Courier sends to Sinch. Override `apiToken`, `servicePlanId`, and `url` via `config`, and any message body field via `body`.

```javascript Node.js highlight={8-19} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    providers: {
      sinch: {
        override: {
          body: {
            from: "+15555555555",
          },
          config: {
            apiToken: "<override API token>",
            servicePlanId: "<override Service Plan ID>",
            url: "<alternate API url>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-19} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "providers": {
            "sinch": {
                "override": {
                    "body": {
                        "from": "+15555555555",
                    },
                    "config": {
                        "apiToken": "<override API token>",
                        "servicePlanId": "<override Service Plan ID>",
                        "url": "<alternate API url>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-22} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "providers": {
        "sinch": {
          "override": {
            "body": {
              "from": "+15555555555"
            },
            "config": {
              "apiToken": "<override API token>",
              "servicePlanId": "<override Service Plan ID>",
              "url": "<alternate API url>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-19} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    providers: {
      sinch: {
        override: {
          body: {
            from: "+15555555555"
          },
          config: {
            apiToken: "<override API token>",
            servicePlanId: "<override Service Plan ID>",
            url: "<alternate API url>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-21} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"sinch": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"from": "+15555555555",
					},
					"config": map[string]any{
						"apiToken": "<override API token>",
						"servicePlanId": "<override Service Plan ID>",
						"url": "<alternate API url>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-15} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("sinch", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "from", "+15555555555"
                    ),
                    "config", java.util.Map.of(
                        "apiToken", "<override API token>",
                        "servicePlanId", "<override Service Plan ID>",
                        "url", "<alternate API url>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-19} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'providers' => [
      'sinch' => [
        'override' => [
          'body' => [
            'from' => '+15555555555',
          ],
          'config' => [
            'apiToken' => '<override API token>',
            'servicePlanId' => '<override Service Plan ID>',
            'url' => '<alternate API url>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-28} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "sinch",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "from": "+15555555555"
                          },
                          "config": {
                            "apiToken": "<override API token>",
                            "servicePlanId": "<override Service Plan ID>",
                            "url": "<alternate API url>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"sinch": {"override": {"body": {"from": "+15555555555"}, "config": {"apiToken": "<override API token>", "servicePlanId": "<override Service Plan ID>", "url": "<alternate API url>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +12345678901 through Sinch with a different service plan.
```

Overrides deep-merge into the request. Fields you set replace their counterparts, and everything you leave out is still sent. The full field list is in the [Sinch SMS API docs](https://developers.sinch.com/docs/sms/).

## Provider details

```text theme={null}
sinch
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send SMS with Sinch Engage through Courier
Source: https://www.courier.com/docs/integrations/sms/sinch-engage

Connect Sinch Engage (formerly MessageMedia) with an API key and secret, and receive delivery status by webhook.

> [!NOTE]
>
> Sinch Engage is MessageMedia rebranded after the Sinch acquisition. It is a different product from [Sinch
> DOC](/docs/integrations/sms/sinch), which is its own integration with its own credentials.
>
> The catalog also lists **Sinch Engage / MessageMedia** under the provider key `messagemedia`. It takes the same API key and secret and sends the same way, so an integration already on `messagemedia` keeps working and needs no migration. Use `sinch-engage` for a new integration.

## Prerequisites

* [A Sinch Engage account](https://app.sinch.com/)
* Access to API settings in the console

## Setup

In the [console](https://app.sinch.com/api-settings):

**1. Create a new API key**

Create a new API key.

**2. Copy the API key and secret**

Save the `api_secret` now. The console won't show it again.

In Courier, open the [Sinch Engage integration](https://app.courier.com/integrations/catalog/sinch-engage) page, paste your credentials, and click "Save."

![](https://mintcdn.com/courier-4f1f25dc/D_fBeiYVONa8hiXh/assets/sinch-engage-api-key.webp?fit=max\&auto=format\&n=D_fBeiYVONa8hiXh\&q=85\&s=062583e95e29052d31d8115bfb81e520)

API key in the console

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

Overrides change the request body, config, and headers Courier sends to Sinch Engage. Override `apiKey`, `apiSecret`, `isHmacEnabled`, and `url` via `config`, and any [SendMessages](https://developers.app.sinch.com/#tag/Messages/operation/SendMessages) body field via `body`.

```javascript Node.js highlight={8-18} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    providers: {
      "sinch-engage": {
        override: {
          body: {
            source_number: "+15555555555",
          },
          config: {
            apiKey: "<override API key>",
            apiSecret: "<override API secret>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-18} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "providers": {
            "sinch-engage": {
                "override": {
                    "body": {
                        "source_number": "+15555555555",
                    },
                    "config": {
                        "apiKey": "<override API key>",
                        "apiSecret": "<override API secret>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-21} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "providers": {
        "sinch-engage": {
          "override": {
            "body": {
              "source_number": "+15555555555"
            },
            "config": {
              "apiKey": "<override API key>",
              "apiSecret": "<override API secret>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-18} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    providers: {
      "sinch-engage": {
        override: {
          body: {
            source_number: "+15555555555"
          },
          config: {
            apiKey: "<override API key>",
            apiSecret: "<override API secret>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-20} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"sinch-engage": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"source_number": "+15555555555",
					},
					"config": map[string]any{
						"apiKey": "<override API key>",
						"apiSecret": "<override API secret>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-14} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("sinch-engage", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "source_number", "+15555555555"
                    ),
                    "config", java.util.Map.of(
                        "apiKey", "<override API key>",
                        "apiSecret", "<override API secret>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-18} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'providers' => [
      'sinch-engage' => [
        'override' => [
          'body' => [
            'source_number' => '+15555555555',
          ],
          'config' => [
            'apiKey' => '<override API key>',
            'apiSecret' => '<override API secret>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-27} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "sinch-engage",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "source_number": "+15555555555"
                          },
                          "config": {
                            "apiKey": "<override API key>",
                            "apiSecret": "<override API secret>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"sinch-engage": {"override": {"body": {"source_number": "+15555555555"}, "config": {"apiKey": "<override API key>", "apiSecret": "<override API secret>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +12345678901 through Sinch Engage with a different API key.
```

## Delivery tracking

Courier gives the integration a unique webhook URL. Point [the provider's webhooks](https://support.app.sinch.com/hc/en-us/articles/11108120449807-Create-manage-webhooks) at it to sync delivery updates into Courier's message logs.

Copy the URL from the [Sinch Engage integration](https://app.courier.com/integrations) in Courier, then follow these steps in the [console](https://app.sinch.com/api-settings):

**1. Create a new webhook**

Select "New Webhook".

**2. Paste Courier's webhook URL**

Paste the URL you copied.

**3. Select the delivery report events**

Under "Event", select "Message is rejected", "Message has failed", and "Message is delivered" in Delivery reports.

![](https://mintcdn.com/courier-4f1f25dc/D_fBeiYVONa8hiXh/assets/sinch-engage-webhook-event.webp?fit=max\&auto=format\&n=D_fBeiYVONa8hiXh\&q=85\&s=84165955c5ed58b9caa029f2dcd09af4)

Webhook configuration

**4. Map the webhook content**

Under "Content", map the fields passed to Courier's webhook endpoint.

> [!NOTE]
>
> Only `messageId`, `receivedTimestamp`, `status`, and `statusCode` are supported.

![](https://mintcdn.com/courier-4f1f25dc/D_fBeiYVONa8hiXh/assets/sinch-engage-webhook-content.webp?fit=max\&auto=format\&n=D_fBeiYVONa8hiXh\&q=85\&s=9633af62c651ac2b0e57cb3ff653adb8)

Webhook Content Mapping

Delivery updates now appear in the message logs.

![](https://mintcdn.com/courier-4f1f25dc/D_fBeiYVONa8hiXh/assets/sinch-engage-log.webp?fit=max\&auto=format\&n=D_fBeiYVONa8hiXh\&q=85\&s=690d29e6690ff8fe6e9889ef780e4eb7)

Delivery Confirmation

## Provider details

```text theme={null}
sinch-engage
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send SMS with SMSCentral through Courier
Source: https://www.courier.com/docs/integrations/sms/smscentral

Connect SMSCentral with a username and password, then override body and config fields per send.

## Prerequisites

* [An SMSCentral account](https://www.smscentral.com.au/)
* Your SMSCentral username and password

## Setup

Open the [SMSCentral Integration](https://app.courier.com/integrations/catalog/smscentral) in Courier, enter your username and password, then click "Save."

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

Overrides change the request body and credentials Courier sends to SMSCentral. Override `username` and `password` via `config`, and `message`, `originator`, and `reference` via `body`.

```javascript Node.js highlight={8-20} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    providers: {
      smscentral: {
        override: {
          body: {
            message: "Override message content",
            originator: "MyCompany",
            reference: "ref-12345",
          },
          config: {
            username: "<override username>",
            password: "<override password>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-20} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "providers": {
            "smscentral": {
                "override": {
                    "body": {
                        "message": "Override message content",
                        "originator": "MyCompany",
                        "reference": "ref-12345",
                    },
                    "config": {
                        "username": "<override username>",
                        "password": "<override password>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-23} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "providers": {
        "smscentral": {
          "override": {
            "body": {
              "message": "Override message content",
              "originator": "MyCompany",
              "reference": "ref-12345"
            },
            "config": {
              "username": "<override username>",
              "password": "<override password>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-20} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    providers: {
      smscentral: {
        override: {
          body: {
            message: "Override message content",
            originator: "MyCompany",
            reference: "ref-12345"
          },
          config: {
            username: "<override username>",
            password: "<override password>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-22} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"smscentral": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"message": "Override message content",
						"originator": "MyCompany",
						"reference": "ref-12345",
					},
					"config": map[string]any{
						"username": "<override username>",
						"password": "<override password>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("smscentral", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "message", "Override message content",
                        "originator", "MyCompany",
                        "reference", "ref-12345"
                    ),
                    "config", java.util.Map.of(
                        "username", "<override username>",
                        "password", "<override password>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-20} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'providers' => [
      'smscentral' => [
        'override' => [
          'body' => [
            'message' => 'Override message content',
            'originator' => 'MyCompany',
            'reference' => 'ref-12345',
          ],
          'config' => [
            'username' => '<override username>',
            'password' => '<override password>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-29} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "smscentral",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "message": "Override message content",
                            "originator": "MyCompany",
                            "reference": "ref-12345"
                          },
                          "config": {
                            "username": "<override username>",
                            "password": "<override password>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"smscentral": {"override": {"body": {"message": "Override message content", "originator": "MyCompany", "reference": "ref-12345"}, "config": {"username": "<override username>", "password": "<override password>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +12345678901 through SMSCentral with a different originator.
```

SMSCentral doesn't merge arbitrary fields. Courier reads a fixed set: `override.body.message`, `override.body.reference`, `override.body.originator`, `override.config.username`, and `override.config.password`. Any other field is ignored.

## Provider details

```text theme={null}
smscentral
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send SMS with Telnyx through Courier
Source: https://www.courier.com/docs/integrations/sms/telnyx

Connect Telnyx with an API key and messaging profile, then override body and headers per send.

## Prerequisites

* [A Telnyx account](https://telnyx.com/)
* Your Telnyx API key
* An SMS-capable phone number in Telnyx

## Setup

**1. Create a Telnyx API key**

In Telnyx, open [API keys](https://portal.telnyx.com/#/app/api-keys) and create a key.

**2. Configure in Courier**

Open the [Telnyx Integration](https://app.courier.com/integrations/catalog/telnyx) in Courier, enter your API key and originating phone number, then click "Save."

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

Overrides change the request body Courier sends to Telnyx. You can override any field the outgoing call supports:

```javascript Node.js highlight={11-23} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+15551734686",
    },
    data: {
      name: "Sarah Bennett",
    },
    providers: {
      telnyx: {
        override: {
          body: {
            text: "Override message text",
            to: "+17777777777",
          },
          config: {
            apiKey: "<your API Key>",
            from: "+15555555555",
            url: "<alternate url>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={11-23} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+15551734686",
        },
        "data": {
            "name": "Sarah Bennett",
        },
        "providers": {
            "telnyx": {
                "override": {
                    "body": {
                        "text": "Override message text",
                        "to": "+17777777777",
                    },
                    "config": {
                        "apiKey": "<your API Key>",
                        "from": "+15555555555",
                        "url": "<alternate url>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={14-26} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+15551734686"
      },
      "data": {
        "name": "Sarah Bennett"
      },
      "providers": {
        "telnyx": {
          "override": {
            "body": {
              "text": "Override message text",
              "to": "+17777777777"
            },
            "config": {
              "apiKey": "<your API Key>",
              "from": "+15555555555",
              "url": "<alternate url>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={11-23} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+15551734686"
    },
    data: {
      name: "Sarah Bennett"
    },
    providers: {
      telnyx: {
        override: {
          body: {
            text: "Override message text",
            to: "+17777777777"
          },
          config: {
            apiKey: "<your API Key>",
            from: "+15555555555",
            url: "<alternate url>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={13-25} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+15551734686"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
		Providers: shared.MessageProvidersParam{
			"telnyx": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"text": "Override message text",
						"to": "+17777777777",
					},
					"config": map[string]any{
						"apiKey": "<your API Key>",
						"from": "+15555555555",
						"url": "<alternate url>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={9-19} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+15551734686").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett"
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("telnyx", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "text", "Override message text",
                        "to", "+17777777777"
                    ),
                    "config", java.util.Map.of(
                        "apiKey", "<your API Key>",
                        "from", "+15555555555",
                        "url", "<alternate url>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={11-23} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+15551734686',
    ],
    'data' => [
      'name' => 'Sarah Bennett',
    ],
    'providers' => [
      'telnyx' => [
        'override' => [
          'body' => [
            'text' => 'Override message text',
            'to' => '+17777777777',
          ],
          'config' => [
            'apiKey' => '<your API Key>',
            'from' => '+15555555555',
            'url' => '<alternate url>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={13-33} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+15551734686" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "telnyx",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "text": "Override message text",
                            "to": "+17777777777"
                          },
                          "config": {
                            "apiKey": "<your API Key>",
                            "from": "+15555555555",
                            "url": "<alternate url>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+15551734686"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}' \
  --message.providers '{"telnyx": {"override": {"body": {"text": "Override message text", "to": "+17777777777"}, "config": {"apiKey": "<your API Key>", "from": "+15555555555", "url": "<alternate url>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +15551734686 through Telnyx with the body overridden.
```

Override fields are merged at the top level of the request, so each key you set replaces that key outright rather than merging into it. `override.headers` and `override.config.url` are honored too. The full field list is in the [Telnyx Messaging API docs](https://developers.telnyx.com/api/messaging/send-message).

## Provider details

```text theme={null}
telnyx
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send SMS with TextUs through Courier
Source: https://www.courier.com/docs/integrations/sms/textus

Connect TextUs with an auth token and from number, then send to the profile's phone_number.

## Prerequisites

* [A TextUs account](https://textus.com/)
* Your TextUs API auth token
* The from number or email TextUs sends from

## Setup

Open the [TextUs Integration](https://app.courier.com/integrations/catalog/textus) in Courier, enter your auth token and from number or email, then click "Save."

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

Overrides change the request Courier makes to TextUs. Override `authToken`, `from`, and `email` in `config`, and the `body` of the SMS content.

```javascript Node.js highlight={8-20} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    providers: {
      textus: {
        override: {
          body: {
            to: "+10987654321",
            body: "Override message content",
          },
          config: {
            from: "<override from number>",
            authToken: "<override auth token>",
            email: "<override email>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-20} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "providers": {
            "textus": {
                "override": {
                    "body": {
                        "to": "+10987654321",
                        "body": "Override message content",
                    },
                    "config": {
                        "from": "<override from number>",
                        "authToken": "<override auth token>",
                        "email": "<override email>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-23} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "providers": {
        "textus": {
          "override": {
            "body": {
              "to": "+10987654321",
              "body": "Override message content"
            },
            "config": {
              "from": "<override from number>",
              "authToken": "<override auth token>",
              "email": "<override email>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-20} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    providers: {
      textus: {
        override: {
          body: {
            to: "+10987654321",
            body: "Override message content"
          },
          config: {
            from: "<override from number>",
            authToken: "<override auth token>",
            email: "<override email>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-22} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"textus": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"to": "+10987654321",
						"body": "Override message content",
					},
					"config": map[string]any{
						"from": "<override from number>",
						"authToken": "<override auth token>",
						"email": "<override email>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("textus", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "to", "+10987654321",
                        "body", "Override message content"
                    ),
                    "config", java.util.Map.of(
                        "from", "<override from number>",
                        "authToken", "<override auth token>",
                        "email", "<override email>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-20} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'providers' => [
      'textus' => [
        'override' => [
          'body' => [
            'to' => '+10987654321',
            'body' => 'Override message content',
          ],
          'config' => [
            'from' => '<override from number>',
            'authToken' => '<override auth token>',
            'email' => '<override email>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-29} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "textus",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "to": "+10987654321",
                            "body": "Override message content"
                          },
                          "config": {
                            "from": "<override from number>",
                            "authToken": "<override auth token>",
                            "email": "<override email>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"textus": {"override": {"body": {"to": "+10987654321", "body": "Override message content"}, "config": {"from": "<override from number>", "authToken": "<override auth token>", "email": "<override email>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +12345678901 through TextUs from a different number.
```

## Provider details

```text theme={null}
textus
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send SMS with Twilio through Courier
Source: https://www.courier.com/docs/integrations/sms/twilio

Connect Twilio with an Account SID, Auth Token, and Messaging Service SID or from number.

## Prerequisites

* [A Twilio account](https://www.twilio.com/try-twilio)
* [An SMS-capable Twilio phone number](https://www.twilio.com/docs/phone-numbers)
* [A Messaging Service containing that phone number](https://www.twilio.com/docs/sms/send-messages#messaging-services)
* [Your Twilio Account SID and Auth Token](https://www.twilio.com/console/project/settings)
* Your Twilio Messaging Service SID

## Setup

**1. Get your Twilio credentials**

In Twilio, open the [console](https://console.twilio.com/) and copy your Account SID and Auth Token. The Messaging Service SID is on the Messaging Services page.

**2. Configure in Courier**

Open the [Twilio Integration](https://app.courier.com/integrations/twilio) in Courier, enter your Account SID, Auth Token, and Messaging Service SID, then click "Save."

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Trial accounts

> [!NOTE]
>
> Twilio trial accounts may only send to verified numbers. See the [Twilio trial account guide](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

Overrides change the request body Courier sends to Twilio. You can override any field on Twilio's `Messages.json` endpoint, listed in the [Twilio message resource reference](https://www.twilio.com/docs/sms/api/message-resource#create-a-message-resource).

> [!WARNING]
>
> Courier polls Twilio's API for delivery status using the credentials you configured. Swapping those credentials with a `config` override stops delivery status events.

```javascript Node.js highlight={11-22} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    data: {
      name: "Sarah Bennett",
    },
    providers: {
      twilio: {
        override: {
          body: {
            To: "+10987654321",
          },
          config: {
            accountSid: "<your Account SID>",
            authToken: "<your Auth Token>",
            messagingServiceSid: "<your Messaging Service SID>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={11-22} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "data": {
            "name": "Sarah Bennett",
        },
        "providers": {
            "twilio": {
                "override": {
                    "body": {
                        "To": "+10987654321",
                    },
                    "config": {
                        "accountSid": "<your Account SID>",
                        "authToken": "<your Auth Token>",
                        "messagingServiceSid": "<your Messaging Service SID>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={14-25} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "data": {
        "name": "Sarah Bennett"
      },
      "providers": {
        "twilio": {
          "override": {
            "body": {
              "To": "+10987654321"
            },
            "config": {
              "accountSid": "<your Account SID>",
              "authToken": "<your Auth Token>",
              "messagingServiceSid": "<your Messaging Service SID>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={11-22} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    data: {
      name: "Sarah Bennett"
    },
    providers: {
      twilio: {
        override: {
          body: {
            To: "+10987654321"
          },
          config: {
            accountSid: "<your Account SID>",
            authToken: "<your Auth Token>",
            messagingServiceSid: "<your Messaging Service SID>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={13-24} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
		Providers: shared.MessageProvidersParam{
			"twilio": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"To": "+10987654321",
					},
					"config": map[string]any{
						"accountSid": "<your Account SID>",
						"authToken": "<your Auth Token>",
						"messagingServiceSid": "<your Messaging Service SID>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={9-18} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett"
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("twilio", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "To", "+10987654321"
                    ),
                    "config", java.util.Map.of(
                        "accountSid", "<your Account SID>",
                        "authToken", "<your Auth Token>",
                        "messagingServiceSid", "<your Messaging Service SID>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={11-22} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'data' => [
      'name' => 'Sarah Bennett',
    ],
    'providers' => [
      'twilio' => [
        'override' => [
          'body' => [
            'To' => '+10987654321',
          ],
          'config' => [
            'accountSid' => '<your Account SID>',
            'authToken' => '<your Auth Token>',
            'messagingServiceSid' => '<your Messaging Service SID>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={13-32} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "twilio",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "To": "+10987654321"
                          },
                          "config": {
                            "accountSid": "<your Account SID>",
                            "authToken": "<your Auth Token>",
                            "messagingServiceSid": "<your Messaging Service SID>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}' \
  --message.providers '{"twilio": {"override": {"body": {"To": "+10987654321"}, "config": {"accountSid": "<your Account SID>", "authToken": "<your Auth Token>", "messagingServiceSid": "<your Messaging Service SID>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +12345678901 through Twilio with different credentials.
```

> [!NOTE]
>
> The Twilio API uses PascalCase field names (`Body`, `To`, `From`). Courier auto-capitalizes `body` override keys for backwards compatibility, so both `"to"` and `"To"` work.

## Troubleshooting

> **Error 30003: Destination Unavailable**
>
> The destination handset was unreachable.
>
> * Send another test message via the Twilio API Explorer
> * Check device status, signal strength, and carrier network
> * Use the "Fallback to Long Code" feature if needed
> * Open a Twilio support request if the issue persists

> **Error 30005: Unknown or Inactive Destination**
>
> Carrier issue, signal loss, or inactive number.
>
> * Verify the number is active and formatted correctly (E.164)
> * Check device status and signal
> * Test with other devices on the same carrier

> **Error 30006: Landline or Unreachable Carrier**
>
> The message went to a landline or an unreachable carrier.
>
> * Use the [Lookup API](https://www.twilio.com/docs/lookup/v2-api) to check if the number is a landline
> * Try an alternative phone number

> **Error 30007: Message Filtered**
>
> Twilio or the carrier filtered the message for a policy violation.
>
> * Ensure compliance with Twilio's Messaging and Acceptable Use Policies
> * Secure account credentials
> * Open a support request if you suspect a mistake

> **Error 30008: Unknown Delivery Failure**
>
> The message failed for unknown reasons.
>
> * Test with a simpler message and a different sender ID
> * Check device roaming status
> * Contact Twilio support with recent message SIDs if the issue persists

> **Error 20003: Permission Denied**
>
> No permission to access the requested resource.
>
> * Verify the correct Auth Token and Account SID combination
> * Check account type (sub-account vs master, test vs live)
> * Confirm API Key and Auth Token are valid

> **Error 20404: Resource Not Found**
>
> The resource doesn't exist or isn't available.
>
> * Check that the resource exists and verify API case-sensitivity
> * Verify Account SID and base URL

> **Error 21211: Invalid To Phone Number**
>
> The recipient number is invalid or formatted incorrectly.
>
> * Ensure E.164 format with the correct country code
> * Avoid calling or messaging a Twilio number from itself

> **Error 21408: Permission Not Enabled for Region**
>
> * Enable permission in [Geo-Permissions settings](https://www.twilio.com/console/sms/settings/geo-permissions)

> **Error 21610: SMS STOP Filter**
>
> The recipient unsubscribed with the "STOP" keyword.
>
> * Request the recipient text "START" to resubscribe
> * Ensure you have consent for messaging

> **Error 11200: HTTP Retrieval Failure**
>
> Twilio couldn't retrieve content from the given URL.
>
> * Verify web server status and accessibility
> * Check for network issues
> * Ensure proper server configuration for static resources

> **Error 12300: Invalid Content-Type**
>
> Twilio couldn't process the URL's Content-Type.
>
> * Verify the correct Content-Type is returned by the server
> * Ensure the URL refers to a valid, acceptable resource

## Provider details

```text theme={null}
twilio
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Send SMS with Vonage through Courier
Source: https://www.courier.com/docs/integrations/sms/vonage

Connect Vonage with an API key, secret, and from number, then override fields per send.

## Prerequisites

* [A Vonage (formerly Nexmo) account](https://www.vonage.com/)
* Your Vonage API key and API secret
* An SMS-capable from number on that account

## Setup

**1. Get your Vonage API credentials**

In Vonage, open [secret management](https://developer.vonage.com/en/account/secret-management) and copy your API key and API secret.

**2. Configure in Courier**

Open the [Vonage integration](https://app.courier.com/integrations/catalog/vonage) in Courier, enter your API key, API secret, and from number, then save.

> [!NOTE]
>
> The catalog also lists **Vonage (Nexmo)** under the provider key `nexmo`. It takes the same API key, API secret, and from number, and sends the same way, so an integration already on `nexmo` keeps working and needs no migration. Use `vonage` for a new integration. It is the one that reports provider errors back to Courier.

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: [profile requirements
DOC](/docs/integrations/sms/overview#profile-requirements) and [send to a recipient
DOC](/docs/integrations/sms/overview#send-to-a-recipient).

## Overrides

[How overrides work
DOC](/docs/send/overrides#how-overrides-work) covers the two levels and which one wins.

Overrides change the request body and config Courier sends to Vonage. In `config`, override `apiKey`, `apiSecret`, `fromNumber`, and `url`. In `body`, override any message field.

```javascript Node.js highlight={8-20} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    providers: {
      vonage: {
        override: {
          body: {
            text: "Override message text",
          },
          config: {
            apiKey: "<override API key>",
            apiSecret: "<override API secret>",
            fromNumber: "<override from number>",
            url: "<alternate API url>",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-20} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "providers": {
            "vonage": {
                "override": {
                    "body": {
                        "text": "Override message text",
                    },
                    "config": {
                        "apiKey": "<override API key>",
                        "apiSecret": "<override API secret>",
                        "fromNumber": "<override from number>",
                        "url": "<alternate API url>",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-23} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "providers": {
        "vonage": {
          "override": {
            "body": {
              "text": "Override message text"
            },
            "config": {
              "apiKey": "<override API key>",
              "apiSecret": "<override API secret>",
              "fromNumber": "<override from number>",
              "url": "<alternate API url>"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-20} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    providers: {
      vonage: {
        override: {
          body: {
            text: "Override message text"
          },
          config: {
            apiKey: "<override API key>",
            apiSecret: "<override API secret>",
            fromNumber: "<override from number>",
            url: "<alternate API url>"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-22} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"vonage": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"text": "Override message text",
					},
					"config": map[string]any{
						"apiKey": "<override API key>",
						"apiSecret": "<override API secret>",
						"fromNumber": "<override from number>",
						"url": "<alternate API url>",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-16} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("vonage", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "text", "Override message text"
                    ),
                    "config", java.util.Map.of(
                        "apiKey", "<override API key>",
                        "apiSecret", "<override API secret>",
                        "fromNumber", "<override from number>",
                        "url", "<alternate API url>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-20} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'providers' => [
      'vonage' => [
        'override' => [
          'body' => [
            'text' => 'Override message text',
          ],
          'config' => [
            'apiKey' => '<override API key>',
            'apiSecret' => '<override API secret>',
            'fromNumber' => '<override from number>',
            'url' => '<alternate API url>',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-29} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "vonage",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "text": "Override message text"
                          },
                          "config": {
                            "apiKey": "<override API key>",
                            "apiSecret": "<override API secret>",
                            "fromNumber": "<override from number>",
                            "url": "<alternate API url>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"vonage": {"override": {"body": {"text": "Override message text"}, "config": {"apiKey": "<override API key>", "apiSecret": "<override API secret>", "fromNumber": "<override from number>", "url": "<alternate API url>"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to +12345678901 through Vonage from a different number.
```

Overrides are deep-merged into the request. Fields you set replace their counterparts, and fields you leave out are still sent. The full field list is in the [Vonage SMS API docs](https://developer.vonage.com/en/messaging/sms/overview).

## Provider details

```text theme={null}
vonage
```

Courier recommends routing to the channel. Naming this key in `routing.channels` instead is supported, and sends through just this provider.

> **[Send to a specific provider](/docs/send/send-to-a-provider)**
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> **[Set a send rate limit](/docs/integrations/send-rate-limits)**
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.


# Automation Audience Trigger
Source: https://www.courier.com/docs/journeys/automations/audience-trigger

Start an automation for every member of an audience when it changes.

## How it works

The Audience trigger starts an automation run for each user who enters or leaves a [dynamic audience](/docs/recipients/lists-and-audiences/audiences). When a user's profile changes and they newly satisfy (or no longer satisfy) the audience rules, Courier fires an individual automation run for that user.

This is useful for workflows that react to profile changes, such as:

* Sending a welcome sequence when a user upgrades to a premium tier
* Triggering a win-back flow when a user becomes inactive
* Notifying an account manager when a high-value customer changes status

## Configuration

![Audience trigger configuration showing Source, Type, and Audience fields](https://mintcdn.com/courier-4f1f25dc/vtbfWgZJXtOFtHNn/assets/platform/automations/audience-trigger.png?fit=max\&auto=format\&n=vtbfWgZJXtOFtHNn\&q=85\&s=12585f2a26475b1ee85529f55da1c036)

Audience trigger configuration

1. Open the Automation Designer and select **Audience** as the trigger source.
2. Choose the event type:
   * **Match** fires when a user enters the audience.
   * **Unmatch** fires when a user leaves the audience.
3. Choose your audience from the dropdown.

Each time the event fires, Courier creates a separate automation run for that user.

## Run Context

When an audience trigger fires, the automation run context contains **only the user's ID** as the recipient. Stored profile fields (email, phone, custom attributes) and data are **not** automatically loaded.

| Context field | Value |
| - | - |
| `recipient` | The user ID that matched or unmatched |
| `profile` | Empty |
| `data` | Empty |

This differs from API-invoked and Segment-triggered automations, which pre-load profile data before the first step runs.

### Loading Profile Data

If your workflow uses profile fields (for example, in [If/Switch conditions](/docs/journeys/automations/control-flow) or template personalization), add a [GET Profile](/docs/journeys/automations/get-profile) step early in your workflow, before any step that reads profile data. The GET Profile step fetches the user's stored Courier profile and merges it into the run context.

**Audience Trigger** → **[GET Profile](/docs/journeys/automations/get-profile)** → **[If/Switch](/docs/journeys/automations/control-flow)** (profile condition) → **Send**

Without the GET Profile step, profile-based conditions will evaluate against an empty object and always fall through to the default branch.

## Audience Membership Timing

Audience triggers depend on Courier's [pre-computed membership model](/docs/recipients/lists-and-audiences/audiences#how-it-works). A trigger fires when membership changes, not on a fixed schedule. Keep in mind:

* **Profile updates drive membership.** A trigger fires only when a profile change causes a user to enter or leave the audience.
* **Rule changes trigger rebuilds.** If you update an audience's filter rules, Courier rebuilds the membership list. This can take several minutes for large audiences, and triggers may fire as members are re-evaluated.
* **Each match is a separate run.** If you update audience rules and many users match at once, each user gets their own automation run.


# Automation Batching
Source: https://www.courier.com/docs/journeys/automations/batching

Collect events over a window and release them together as one message.

# Batching

This reduces notification frequency and improves the likelihood of recipients engaging with the content.
Batching operates based on the following criteria:

1. **Period of inactivity**: If no events occur within a defined time span (e.g., one hour), all events since the last notification are bundled into a single notification.
2. **Maximum event count**: Notifications are held until a specified number of events (e.g., 100) have accumulated. These events are then summarized in a single notification.
3. **Maximum wait time**: All events that would have triggered notifications within a predefined duration (e.g., 24 hours) are summarized into a single notification.

Batching is supported across various channels (email, SMS, chat, in-app inbox, push) and providers (Twilio, Sendgrid, email SMTP, Slack, MS Teams, WeChat).

## Batching Example Use Cases

### Article Performance Summary

When an article is published on a news website, events are generated for each view, comment, and share.
Instead of sending a notification for each event, these events can be batched within an automation.
Once the initial surge of activity subsides or the maximum wait time is reached, the batch compiles view count, top comments, and share count data.
This summary is then sent to the author via email.

### Data Warehouse Analytics

A company processing large amounts of data may generate reports at different times.
An event is triggered upon each report's completion.
With batching, these reports can be grouped and sent in a single email once all the reports for the day are generated.

### Social Media Engagement

When a user creates a popular post that receives numerous likes within minutes, batching can be used to notify the user once the post hasn't received new likes for a specified period.
For example, "Your post received 17 likes."

## Creating A Batch

To create a batch, use the "Add to Batch" action, then click within the batch node to open the editor in the sidebar.

## Configuring A Batch

To configure a batch, click on the batch node to open the editor in the sidebar.

| Parameter | Description |
| - | - |
| **Wait Period** | Defines the period of inactivity before a batch is considered complete. If no events are received within this time frame, the batch will be finalized and sent to the next step. |
| **Max Wait** | Defines the maximum amount of time to wait before finalizing the batch. If this time frame is reached, the batch will immediately complete, even if an event had been received within the "wait period." |
| **Retain Items** | Defines the number of items to retain and send with the batch. Users can specify any positive integer value. Retention does not affect the tracked count. For example, if `Retain Items` is set to 10 and 15 items are received, the passed count will be 15, but only 10 items will be included in the batch. Options: **First *N***, **Last *N***, **Highest *N*** (requires `Sort Key`), **Lowest *N*** (requires `Sort Key`), where *N* is the user-specified number of items to retain. |
| **Sort Key** | Required when Highest or Lowest is selected for Retain Items. Defines the key of the data object to be used to determine item ordering. For example, if `Sort Key` is set to `refs.data.upvotes`, and the automation is invoked with `{ "data": { "upvotes": 5 }}`, `5` will be the value used to determine the order and position of the event in the items array. |
| **Max Items** | *(Optional)* Defines the maximum number of events to include in a batch before completion. When a batch has received this number of events, it will immediately finalize and send the batch to the next step. |
| **Scope** | Defines the scope of the batch, determining how events are grouped together. Options: **Global** (default), **User**, **Dynamic**. See [Batch Scope](#batch-scope) for more details. |
| **Category Key** | *(Optional)* Allows events to be grouped by categories. See [Working with Categories](#batch-categories) for more details. |

## Batch Scope

The `Scope` parameter in the batch node configuration allows you to define the scope of the batch.
It determines how events are grouped together within the batch.
There are three options for the batch scope:

| Scope | Description |
| - | - |
| **Global (default)** | • Events are grouped together based on the batch step ID. • The batch will trigger and send the grouped events to the next step when either the maximum number of events is reached or the specified time period elapses. |
| **User** | • Events are grouped together based on the unique combination of `user_id` and batch step ID. • The batch will trigger when enough events associated with a specific user are added to the batch or when the specified time period elapses, allowing for user-specific batching of events. |
| **Dynamic** | • Events are grouped together based on the `Batch Key` specified in the batch configuration, regardless of the batch step ID or automation they belong to. • This allows for flexible event grouping based on specific criteria, but may lead to unexpected results as events from different batch steps or automations may be merged. |

> [!NOTE]
>
> To batch messages for a user while grouping them by category (such as tenant or topic), create a `Batch Key` that combines a user identifier and a category identifier. For example, use `'batch_key': 'user_id tenant_id'` and pass it to the batch node with `refs.data.batch_key`. This groups related notifications together into a single batch.

> [!WARNING]
>
> Dynamic scope behavior is subject to change in future revisions of the automation system.

## Invoking an Automation Containing a Batch

* When an automation containing a batch node is invoked, Courier checks for an ongoing batch run for the configured scope.
  * **If none exists:**
    1. A new batch run is created.
    2. The current automation run is marked as pending.
    3. The system waits until the batch is complete before proceeding to the next step.
  * **If an existing batch run is found:**
    1. The data object is added to the existing batch.
    2. The current automation run is terminated.
    3. Steps connected to the batch are not executed, ensuring that nodes following a batch node are only executed once per batch run.

```ts theme={null}
{
  batch: {
    // The number of events received for this category, may be different than items.length
    // depending on item retention configuration.
    count: number;
    // An array of the data objects of each automation added to this batch.
    items: any[];
  }
}
```

**Example:** If a batch automation is invoked 3 times with the following values:

```js Invoke 1 theme={null}
{
  data: {
    like_from: "Drew";
  }
}
```

```js Invoke 2 theme={null}
{
  data: {
    like_from: "Alex";
  }
}
```

```js Invoke 3 theme={null}
{
  data: {
    like_from: "Abby";
  }
}
```

The steps following the batch node would be provided this data object:

```js Completed Batch Data theme={null}
{
  batch: {
    count: 3,
    items: [
      { like_from: "Drew" },
      { like_from: "Alex" },
      { like_from: "Abby" },
    ]
  }
}
```

This data can be accessed from a notification template using variable syntax.

![Accessing batch data from a notification template](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/digests-batching-throttling/batch-data-in-notification-template.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=11e866c4774093eb2a1d2d78790eec44)

Accessing batch data from a notification template

## Batch Categories

When the `Category Key` is set to a dynamic value such as `refs.data.category_key`, events can be grouped by category in a batch run.
In this case, the batch is aggregated by category:

![Accessing batch data from a notification template](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/digests-batching-throttling/dynamic-category-key.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=71de9c063dce338987eed0b5f6e67348)

Dynamic Category Key

**Example:** In the batch node, `Category Key` is set to `refs.data.category_key`.
Each time the automation is invoked, a `category_key` is supplied.

Given the following invocations:

```js Invoke theme={null}
{
  data: {
    category_key: "likes",
    like_from: "Drew"
  }
}
```

```js Invoke theme={null}
{
  data: {
    category_key: "likes",
    like_from: "Alex"
  }
}
```

```js Invoke theme={null}
{
  data: {
    category_key: "comments",
    comment: "Excellent post!"
  }
}
```

The automation steps following the batch node would receive this data object:

```js Completed Batch Data theme={null}
{
  "batch": {
    "likes": {
      "count": 2,
      "items": [
        { "like_from": "Drew" },
        { "like_from": "Alex" }
      ],
    },
    "comments": {
      "count": 1,
      "items": [
        { "comment": "Excellent post!" }
      ],
    },
  }
}
```


# Cancel an Automation Run
Source: https://www.courier.com/docs/journeys/automations/cancel

Stop a scheduled or in-flight automation run with a cancellation token.

## Add a Cancellation Token

To allow an automation to be cancelled, add a cancellation token to the automation.

1. Navigate to the settings tab of the automation you want to cancel.
2. Add a cancellation token. This can be any value desired. Its best to use a dynamic value so
   a specific automation invocation may be cancelled, rather than all running instances. For
   example, you may use `refs.data.user_id`, which would allow the automation run to be associated
   with the user the automation would send to. You can also reference profile fields with `refs.profile.*`.
3. Publish the Automation.
4. Create a new automation
5. Add the `Cancel Automation` node
6. Set the token to the same token from step 2.
7. Publish

## Canceling From the UI

An automation can also be canceled from automation logs.

1. Navigate to the [automation logs page](https://app.courier.com/logs/automations) in Courier.
2. Find your automation in the logs, you can search with a run Id or source.
3. If your automation has not finished processing, a cancel button will be shown in the run summary.
4. Clicking this button will cancel your automation.

![Canceling an automation from logs](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/cancel-button-logs.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=32e466e1fd4e839a789f636e05a61107)

Canceling an Automation from Logs

## Canceling Multiple Automations

When multiple automations share the same cancellation token and a cancel automation is invoked, all automations that have the same token will be simultaneously canceled.

## Templated Cancellation Token

It may be advantageous to create a compound key for your cancellation token. For example, if you want to have a cancellation token that combines two different fields, or a data field and a static string. In automations, most fields support Javascript string interpolation and the cancellation token is an example of one. The documentation above says you can use `refs`, for example `refs.data.user_id` and the following would be identical in the cancellation token field, `${data.user_id}`. For more advanced interpolation you can perform nested interpolations as well.

**Static Fields**

```javascript theme={null}
${`onboarding-flow-${data.user_id}`}
```

**Combining Fields**

```javascript theme={null}
${`${data.user_id}-${data.tenant_id}`}
```


# Automation Conditional Logic
Source: https://www.courier.com/docs/journeys/automations/control-flow

Branch a run with if and switch conditions evaluated on the payload.

![If node example](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/profile-flow-condition-contains.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=0d27397e5e460c84a84da1defc82b1d2)

## Types of Control Flow

### If

The `If` node routes workflow execution based on a single condition. When the condition evaluates to true, the workflow follows the True branch; otherwise, it follows the False branch.

### Switch

The `Switch` node allows routing based on multiple conditions.
It evaluates conditions in order and routes to the first matching branch.
If no conditions match, the workflow follows the default branch.

## Comparison Operators

The following operators are available for Data, Profile, and Step Ref conditions:

| Operator | Description |
| - | - |
| **is** (eq) | Exact match |
| **is not** (neq) | Does not match |
| **is one of** (one\_of) | Matches any value in a comma-separated list |
| **contains** | String contains substring, or array contains value |
| **does not contain** | String/array does not contain value |
| **greater than** (gt) | Numeric greater than |
| **greater than or equal** (gte) | Numeric greater than or equal |
| **less than** (lt) | Numeric less than |
| **less than or equal** (lte) | Numeric less than or equal |
| **starts with** | String starts with prefix |
| **ends with** | String ends with suffix |

## Condition Sources

The `If` and `Switch` nodes can evaluate boolean expressions from four different sources:

| Source | Description |
| - | - |
| **Data** | Compare values from the automation context's data object |
| **Profile** | Compare values from the automation context's profile object |
| **Step Ref** | Monitor status of previous Send steps |
| **JS Condition** | Write custom JavaScript for complex logic |

### Data

*Compare a field within the `data` key of the automation context with a value.*

| Property | Description | Example |
| - | - | - |
| `Field` | The data object to evaluate | `data.foo` |
| `Comparison` | The comparison operator to use | `is one of` |
| `Value` | The value to compare against | `bar, baz` |

### Profile

*Compare a field within the `profile` key of the automation context with a value.*

| Property | Description | Example |
| - | - | - |
| `Field` | The profile object to evaluate | `address.country` |
| `Comparison` | The comparison operator to use | `is` |
| `Value` | The value to compare against | `Canada` |

> [!NOTE]
>
> Profile conditions require profile data to be present in the automation context. Automations started by an [audience trigger](/docs/journeys/automations/audience-trigger) or a schedule do not automatically load stored profile fields. Add a [GET Profile](/docs/journeys/automations/get-profile) step before your If or Switch node so the user's profile is available for comparison.

### Step Ref

*Check the current status of an upstream Send node, using it's reference ID (Ref). The Ref value is defined in the Send node's configuration.*

| Property | Description | Example |
| - | - | - |
| `Ref` | The send node's status object | `welcome_email.status` |
| `Comparison` | The comparison operator to use | `is not` |
| `Value` | The value to compare against | `CLICKED` |

Possible [status](/docs/send/statuses) values are: `CLICKED`, `DELIVERED`, `ENQUEUED`, `FILTERED`, `OPENED`, `SENT`, `UNDELIVERABLE`, `UNMAPPED`, `UNROUTABLE`

### JS Condition

*Use JavaScript expressions when standard comparisons aren't sufficient.*

| Property | Description | Example |
| - | - | - |
| `Expression` | The javascript expression to evaluate | `data.expiry < (new Date()).getTime()` |

```javascript JS Condition examples theme={null}
// Transform and compare values 
data.email.toLowerCase().includes('@company.com')

// Check for key existence or null values 
'preferences' in data && data.preferences !== null

// Compare date diffs as ISO strings 
Date.parse(data.lastLogin) < Date.now() - (30 * 24 * 60 * 60 * 1000)

// Manipulate nested arrays and objects 
data.orders.filter(order => order.total > 100).length > 0
```

#### Javascript Expressions in Value Fields

Javascript expressions can also be used in the `Value` field of Data, Profile, and Step Ref sources.

```javascript Examples theme={null}
// Dynamic timestamps
${(new Date()).getTime()}

// Concatenate values
${data.firstName + ' ' + data.lastName}

// Default values
${profile.language || 'en'}
```


# Automation Debugger
Source: https://www.courier.com/docs/journeys/automations/debugger

Step through a run to see what each node received and what it returned.

# Automation Debugger

Courier's automation debugging tool can be used to run a test event through your automation template and debug any errors you may come across.

## Creating a Test Run Context

Similar to notification templates, automations can now be tested with test run contexts passed in and saved as test events. These tests can mimic an incoming payload passed through [Segment](/docs/journeys/automations/segment), [inbound events](/docs/journeys/automations/inbound-events), or an [adhoc automation call](/docs/journeys/automations/steps). You can create a test event from the `Debug` tab in your automation template.

![Automation Test Event](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/debugger.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=fb8ce99f2619ef29b59478d09a824569)

Automation Test Event

## Running The Test Run Context

With your automation test event configured, you can execute a test run through the debugging tool to simulate the event passed through the automation workflow. When ready, click on the `Run Again` button and select each node to see the data being passed.

![Test Event Trigger](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/debug-trigger.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=5f1eaa92ee45e147420dc3935158d4f0)

Test Event Trigger

### Verifying Test Data

After running your simulated run, you can select each node in your workflow to verify that the data is passed through to each consecutive node. This can be helpful if you have several nodes that rely on incoming data payloads.

![Data Passed to Each Node](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/debug-check.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=4336dfc95f4afb1d833ec1ee9878bac2)

Data Passed to Each Node

## Run your Automation

After testing with the debugger, invoke your automation via API with the data payload you want to pass.

`POST https://api.courier.com/automations/:template_id/invoke`

```json theme={null}
{
  "data": {
    "order_id": "ORD-12345",
    "status": "shipped"
  },
  "profile": {
    "email": "sarah@acme-corp.com",
    "phone_number": "+12345678910",
    "name": "Jane"
  }
}
```

The automation run context shows a successful run with the data you passed.

![Successful Run Context](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/debug-success.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=05a80cd6752db862f59a76d300ecb518)

Successful Run Context

## Testing GET Profile Nodes

Use the debugger to test a [GET Profile](/docs/journeys/automations/get-profile) node before promoting your template to production. The debugger shows the run context passed down your automation after fetching a profile.

![GET Profile Node](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/get-profile-node.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=a32ec4020d914b988eed9eae6fd0b47f)

GET Profile Node


# Automation Designer
Source: https://www.courier.com/docs/journeys/automations/designer

Build an automation visually with a trigger and a sequence of steps.

## Creating an Automation

Start by navigating to the [automations page within the Courier
app](https://app.courier.com/automations). From there, a new automation template can be created by
clicking the `New Automation` Button.

![Automations Home Page](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/automations-list-page.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=8b1551dc96bf415e0c3c5b5c24683a87)

Automations Home Page

## Renaming an Automation

To rename a template, click the name in the upper left hand corner of the designer. By default, the
name is "Untitled Automation". The name is automatically saved after being updated.

![Renaming an automation template](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/renaming.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=aa21dc21c767d5bd34e4b23927dba84c)

Renaming an Automation Template

## Working with Automation Nodes

A new template starts with a placeholder trigger node. A trigger node defines what starts an automation run. The trigger is optional; you can always invoke a template directly via `POST /automations/:template_id/invoke`.

To add nodes, expand from the list on the left and then click and drag a node onto the right. The first trigger and action node will snap into their respective placeholders:

Nodes are executed sequentially through their connections, from top to bottom. To connect two nodes, click and drag from the white dot at the bottom of the source node to the top of the target node:

## Automation Invocation

> [!WARNING]
>
> Be sure to publish the template before invoking (using the publish button on the upper right).

There are a few ways to invoke a template, either directly in the automation template, through a trigger node, or through an api call.

See [Scheduling automations](/docs/journeys/automations/scheduling) or [Triggering With Segment](/docs/journeys/automations/segment) to get
an understanding of how trigger nodes work.

### Difference View

When publishing a template, the automation designer will prompt the user with a difference view confirmation showing the changes between versions. You can confirm the changes on this window.

![Difference Modal](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/diff-view.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=9a46984a0a41863f702ec7667c067d29)

Difference Modal

### Invoking an Automation using the API

To run an automation by api call, grab the automation template id or the alias from the settings section of
the designer and invoke it by calling POST `api/automations/:template_id_here/invoke`. View
[Automations API docs](/docs/api-reference/automations/invoke-an-automation) for
more details.

![Template ID location, settings tab](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/template-id-location.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=8f76335a0228791cf3c92a03e9cb5ef9)

Template ID Location, Settings Tab

### Invoking an Automation from the Designer

You can invoke the automation template directly from the designer in the **Invoke** tab. This can be a good way to test the automation or to invoke very simple automation templates.
*Note:* Invoking from the designer will pass an empty data payload `{}` to the automation run

![Template invoke tab](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/template-invoke.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=aaa89968437e36dd9ee51d33a4e639b9)

Template Invoke Tab


# Automation Digests
Source: https://www.courier.com/docs/journeys/automations/digest

Hold a topic's events and release them on the schedule the user picked.

Courier Automations can create recurring user digests on configured intervals. This is useful for weekly reports, activity summaries, or any periodic notification where you want to aggregate events.

> [!WARNING]
>
> Automation digests require **two separate automations**: one to collect events (with an "Add to Digest" node) and one to release the digest (with a "Digest" trigger). Events won't be delivered if either automation is missing. See [Working with Digests in Automations](#working-with-digests-in-automations) for setup details.

> [!NOTE]
>
> For simpler use cases, Courier offers a [digest feature in the Send API](/docs/guides/send-a-daily-digest) that doesn't require automations.

## Configure Digests in the Preferences Editor

Configure a digest with at least one schedule in the [Preferences Editor](https://app.courier.com/settings/preferences). Create a new subscription topic or open an existing one's settings.

### Schedule a Digest

In the digest section, click **Schedules** to define when the digest releases. At least one schedule is required, but you can configure multiple to give users a choice. Multiple schedules appear as options in the hosted preferences page.

> [!NOTE]
>
> The date-time picker uses local timezone. Users viewing hosted preferences or using front-end preference components see times in their local timezone.

![Digest Schedules](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/digest-schedules.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=57f4542eb127423fe8a997edfe4093cd)

Digest Schedules

### Schedule ID Format

When working with digest APIs, schedule IDs use the format `sch/{uuid}`. You can find the schedule ID in the browser's network panel when viewing the Schedules section of a subscription topic - look for the `pk` field in the response.

> [!NOTE]
>
> The schedule ID includes the `sch/` prefix. When using this ID in API URLs, you must URL-encode the forward slash as `%2F`.

**Examples**:

| Raw Schedule ID | URL-Encoded for API |
| - | - |
| `sch/a3726ea9-3453-465f-93ad-632061ba8f59` | `sch%2Fa3726ea9-3453-465f-93ad-632061ba8f59` |
| `sch/549ef749-7c87-4eea-b695-2e2d23c025ff` | `sch%2F549ef749-7c87-4eea-b695-2e2d23c025ff` |

### Configure Digest Categories

Categories separate different types of data within the same digest. For example, a weekly blog engagement digest might have separate categories for likes and comments.

![Digest Categories](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/digest-categories.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=bf111749846a4a90280e459bca85e231)

Digest Categories

Each category has a `retain` setting that controls which events are kept when the digest releases:

| Retain Option | Description |
| - | - |
| **First 10** | The first 10 events received (default) |
| **Last 10** | The most recent 10 events |
| **10 Highest** | Top 10 sorted by `sort_key` (descending) |
| **10 Lowest** | Bottom 10 sorted by `sort_key` (ascending) |

When using **Highest** or **Lowest**, you must specify a `sort_key` (a data attribute in the event used for sorting).

When the digest releases, each category is delivered in this format:

```json theme={null}
{
  "[category_key]": {
    "count": 15,
    "items": [...]
  }
}
```

* `count`: Total number of events received (may exceed 10)
* `items`: The retained events based on your retain setting (max 10)

### Configure Other Digest Settings

The **Invoke when empty** toggle sends digests to users in an audience even if no events were received during the schedule window. This is useful for fetching custom data in the automation and sending it regardless of event activity.

![Digest Settings](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/digest-settings.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=06ef8cef51baef8e53acf79a535e4688)

Digest Settings

## Mapping a Template to a Digest

Link a notification template to the digest so all accumulated events trigger through an automation.

From the digest settings in preferences, map the notification template you want to use.

![Template Mapping](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/digest-mapping.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=a521298f54fe8ca774b2fbefb6d7ba60)

Template Mapping

Then configure an automation with the appropriate trigger. For example, if digest events come from Segment:

![Automation Digest](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/digest-automation.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=b4729bfc4c7cd4053e4e47d730ad360a)

Automation Digest

After publishing, digested events appear in the logs until the schedule releases the digest.

![Digest Logs](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/digest-logs.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=7c78b0d80d402d627de2ec752e07c93d)

Digest Logs

## Working with Digests in Automations

Two automation nodes handle digest events: one to collect events, one to release them.

### Digest Event Collection

Add an **Add to Digest** node to your automation:

1. Right-click the canvas and select "Add to Digest"
2. Choose the subscription topic where you configured the digest
3. Events accumulate per user, identified by `user_id` or `userId` in the event data

> [!NOTE]
>
> Both `user_id` and `userId` are accepted in the event data for user identification.

### Digest Release

Create a separate automation to process and send the compiled digest:

1. Select the trigger node and choose **Digest** from the Trigger section
2. Select the same subscription topic used for event collection
3. The automation fires at scheduled intervals, processing each user's accumulated data

![Automation digest trigger](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/digest-trigger.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=a37deaaa4cbeed15e290d8b4d0bd1d5e)

Automation Digest Trigger

The digest payload arrives in this structure:

```json theme={null}
{
  "[category_key]": {
    "count": 15,
    "items": [
      { "event": "data", "from": "first_event" },
      { "event": "data", "from": "second_event" }
    ]
  }
}
```

Use this data in your notification template to render the digest summary.

## Testing Digests

1. **Send test events** by invoking your collection automation (see [Adding Events via API](#adding-events-via-api))
2. **Verify accumulation** by [listing digest instances](#listing-digest-instances); confirm `event_count` increments and `status` is `IN_PROGRESS`
3. **Trigger a release** using the [manual trigger endpoint](#releasing-a-digest-early); check that your template receives the digest payload
4. **Verify the email** contains the expected digest items and category data

> [!WARNING]
>
> Do not manually invoke digest trigger automations via the `/automations/{id}/invoke` endpoint. This bypasses the digest accumulation system and will result in empty digest data. Always use the `/digests/schedules/{id}/trigger` endpoint or wait for the scheduled release.

## Timing Considerations

### List Subscriptions and Digest Events

If your automation subscribes a user to a list and then immediately sends a digest event, the subscription may not have propagated before the event is processed. This can cause the event to be dropped because the user isn't yet recognized as a subscriber for the topic.

To avoid this race condition:

* Add a short delay (a few seconds) between the subscription call and the first digest event
* Or subscribe users to lists as a separate, earlier step in your workflow rather than inline with digest event submission

### Scheduled vs Instant Delivery

Scheduled digests batch events until the next scheduled release time. If you send a digest event at 9:05 AM and the schedule is "Daily at 9:00 AM," that event won't be delivered until the following day at 9:00 AM. This is expected behavior; the event is accumulating in a new digest instance.

To test digests without waiting for the schedule, use the [manual trigger endpoint](#releasing-a-digest-early) or add a shorter schedule (every 5-15 minutes) during development.

## Managing Digests via API

If the Preferences Editor UI is unavailable or you need programmatic control over digest schedules, you can manage digests through the API.

### Listing Digest Instances

Check which users have accumulated events for a given schedule:

```bash theme={null}
curl -X GET "https://api.courier.com/digests/schedules/sch%2F{uuid}/instances" \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

Each instance in the response includes `event_count`, `status` (`IN_PROGRESS` or `CLOSED`), and the `user_id`.

### Releasing a Digest Early

Trigger an immediate release without waiting for the scheduled time:

```bash theme={null}
curl -X POST "https://api.courier.com/digests/schedules/sch%2F{uuid}/trigger" \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

This closes all `IN_PROGRESS` instances for the schedule and invokes the digest trigger automation for each user.

### Adding Events via API

You can submit digest events by invoking the collection automation directly:

```bash theme={null}
curl -X POST "https://api.courier.com/automations/{collector-automation-id}/invoke" \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "user_id": "user-123",
      "title": "New comment on your post",
      "body": "Sarah Bennett replied to your thread"
    }
  }'
```

> [!NOTE]
>
> Use the collection automation's ID (the one with the "Add to Digest" node), not the trigger automation's ID. Invoking the trigger automation directly bypasses the digest system and produces empty results.


# Dynamic Automation Steps
Source: https://www.courier.com/docs/journeys/automations/dynamic

Build the step list at invoke time instead of defining it up front.

The `refs` object has access to the following properties:

* `brand`
  * type: string
  * description: A unique identifier that represents the brand that should be used for rendering the notification.
* `data`
  * type: object
  * description: An object that includes any data you want to pass to a message template or accessor type. The data will populate the corresponding template variables.
* `profile`
  * type: object
  * description: an object that includes any key-value pairs required by your chosen Integrations (see our Provider Documentation for the requirements for each Integration.) If profile information is included in the request and that information already exists in the profile for the recipientId, that information will be merged.
* `template`
  * type: string
  * description: A unique identifier that can be mapped to an individual Notification. This could be the "Notification ID” on Notification detail pages (see the Notifications page in the Courier app) or a custom string mapped to the event in settings.
* `recipient`
  * type: string
  * description: A unique identifier associated with the recipient of the delivered message, which can optionally map to a Courier managed profile.

These properties can all be set using the `invoke` api. Additionally, the data property can be initialized by triggers
such as Segment, or modified by actions such as `Fetch Data`.

For example, you can access the `userId` supplied by segment in a send node using `refs.data.userId`

![Accessing userId dynamically using refs.data.userId within the send node](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/new-refs-example.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=e54f8f9a03a68ffe251bd6fe5ea512ae)

Accessing userId dynamically using refs.data.userId within the send node

## Mapping Dynamic Data to Variables

By default, all `data` passed into an automation is passed through to the notification template in a send call. However, there are cases where you want to map specific data attributes to different variables.

1. Open a send node, click on the advanced section, and then click edit next to the `Data` field

![Editing Send Node Data](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/new-send_data.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=4839a7627131b4f9b8f8f9c91d786032)

2. You can either use the interactive JSON editor, or just modify the JSON in the text editor directly. The syntax to map the attribute is as follows:

```json theme={null}
  "<new_attribute>": {
    "$ref": "data.<some_attribute>"
  }
```

### Example: Mapping Dynamic Data to a Variable

Let's say we have a segment event as a trigger for our automation. The event has a `vendor_name` attribute in the segment `properties` object and we want to map that to a `vendor` attribute in our send call.

![Segment Sample Data](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/segment_sample_data.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=02deee15896ea3aac7893d5eadd618b2)

We would use the following syntax:

```json theme={null}
  "vendor": {
    "$ref": "data.properties.vendor_name"
  }
```

![Dynamic Data Mapping](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/new-send_dynamic_data_map.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=583e205a4ba4fb3c57f763f7bd8b02bc)

In the notification template, you are now able to access the `vendor` property directly in a template variable `{vendor}` rather than destructing the data object `{data.properties.vendor_name}`

## URL Interpolation

You can use dynamic data to construct URLs by interpolating values directly into the URL string. This is particularly useful for Fetch Data steps where you need to make API calls with dynamic parameters.

Wrap the entire URL with template literal syntax using `${`...`}` and use `${refs.data.variableName}` to substitute values within the URL string.

### Basic URL Interpolation

```json theme={null}
{
  "type": "fetch",
  "url": "${`https://api.courier.com/profiles/${refs.data.userID}`}",
  "method": "get"
}
```

### Advanced URL Interpolation Examples

**User-specific API calls:**

```json theme={null}
{
  "type": "fetch",
  "url": "${`https://api.example.com/users/${refs.data.userId}/orders/${refs.data.orderId}`}",
  "method": "get"
}
```

**Profile-based endpoints:**

```json theme={null}
{
  "type": "fetch",
  "url": "${`https://api.example.com/accounts/${refs.profile.accountId}/settings`}",
  "method": "get"
}
```

**Query parameters with interpolation:**

```json theme={null}
{
  "type": "fetch",
  "url": "${`https://api.example.com/search?q=${refs.data.searchTerm}&limit=${refs.data.limit}`}",
  "method": "get"
}
```

**Nested data access:**

```json theme={null}
{
  "type": "fetch",
  "url": "${`https://api.example.com/events/${refs.data.event.id}/attendees`}",
  "method": "get"
}
```

### URL Interpolation with Authentication

Combine URL interpolation with authentication headers:

```json theme={null}
{
  "type": "fetch",
  "url": "${`https://api.example.com/users/${refs.data.userId}/profile`}",
  "method": "get",
  "headers": {
    "Authorization": "Bearer ${refs.data.accessToken}",
    "X-User-ID": "${refs.data.userId}"
  }
}
```

> [!NOTE]
>
> **URL Encoding**: Courier automatically handles URL encoding for interpolated values. Special characters in your data will be properly encoded in the final URL.

## Reserved Field values

The following field values are reserved for current and future interpolation features. They can
not be used literally in an input field.

* `refs`
* `data`
* `profile`


# Automation Fetch Data
Source: https://www.courier.com/docs/journeys/automations/fetch-data

Call your own endpoint mid-run and merge the response into the payload.

The Fetch-Data automation step can be used to make GET and POST HTTP calls from an automation workflow. The data fetched will be automatically merged into the automation's run context unless the merge strategy is explicitly defined.

> [!WARNING]
>
> Please note that requests are required to be made in `https`

To start a fetch-data step, add it to your automation canvas and configure your request URL.

![Automation Fetch Data Step](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/automation-fetch-node.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=fd86de4fc26cffb2b8b318c7d154d2ae)

Automation Fetch Data Step

## Merge Strategy

> [!WARNING]
>
> Incoming payloads must be shaped as `objects`. Arrays are not supported.

The merge strategy gives users an option on how they want the data to be populated.

* `replace`
  * overwrite all properties in the Automation Cache with the http response. Removes all properties in the Automation Cache that do not exist in the http response.
* `soft-merge`
  * only overwrite properties in the Automation Cache with the http response properties that do not yet exist in the Automation Cache.
* `overwrite`
  * overwrite all properties in the Automation Cache with the properties from the http response.
* `none`
  * do not make any changes to the Automation Cache if the Automation Cache already exists and has data. Otherwise initialize the Automation Cache.

## Authentication Patterns

The Fetch Data step supports various authentication methods for securing your HTTP requests. Here are the most common patterns:

### 1. Bearer Token Authentication

Use static bearer tokens for simple authentication:

```json theme={null}
{
  "type": "fetch",
  "url": "https://api.example.com/data",
  "method": "get",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN_HERE"
  }
}
```

### 2. Dynamic Bearer Token (from context)

Reference bearer tokens from your automation context:

```json theme={null}
{
  "type": "fetch", 
  "url": "https://api.example.com/data",
  "method": "get",
  "headers": {
    "Authorization": {
      "$ref": "data.bearer_token"
    }
  }
}
```

### 3. Basic Authentication

Use HTTP Basic Authentication with base64-encoded credentials:

```json theme={null}
{
  "type": "fetch",
  "url": "https://api.example.com/data", 
  "method": "get",
  "headers": {
    "Authorization": "Basic dXNlcjpwYXNzd29yZA=="
  }
}
```

### 4. API Key Authentication

Use custom API key headers:

```json theme={null}
{
  "type": "fetch",
  "url": "https://api.example.com/data",
  "method": "get", 
  "headers": {
    "X-API-Key": {
      "$ref": "data.api_key"
    }
  }
}
```

### 5. Custom Headers with Multiple Auth Elements

Combine multiple authentication elements:

```json theme={null}
{
  "type": "fetch",
  "url": "https://api.example.com/data",
  "method": "post",
  "headers": {
    "Authorization": {
      "$ref": "data.auth_token"
    },
    "X-Client-ID": {
      "$ref": "profile.client_id"
    },
    "Content-Type": "application/json"
  }
}
```

### 6. JavaScript Interpolation (V2 Automation)

Use JavaScript expressions for dynamic values:

```json theme={null}
{
  "type": "fetch",
  "url": "https://api.example.com/data",
  "method": "get",
  "headers": {
    "Authorization": "${`Bearer ${data.access_token}`}",
    "X-Timestamp": "${Date.now()}"
  }
}
```

## Security Features

### URL Validation

Courier automatically validates URLs for security. Invalid URLs will cause the step to be skipped with an "Invalid URL" status.

### Request Timeout

All fetch requests have a fixed 10-second timeout to prevent hanging requests. Requests that exceed this timeout will automatically fail with proper error handling.

### Error Handling

Failed requests are automatically logged and tracked. The automation will continue processing subsequent steps unless explicitly configured otherwise.

## Best Practices

1. **Store sensitive tokens in run context data** rather than hardcoding them in your automation configuration
2. **Use step references** for authentication flows that require token refresh
3. **Implement proper error handling** in subsequent steps to handle authentication failures
4. **Validate URLs** when possible for security
5. **Use appropriate merge strategies** to avoid overwriting important context data
6. **Test authentication flows** thoroughly in your automation development environment

## Accessing the Fetched Run Context

Once data is fetched, it will be populated in the data payload for subsequent steps to reference.

![Notification Referencing Data](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/automation-fetch-data-notification.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=cd204d1895e718b2e59e03e6b3a71b91)

Notification Referencing Data

The incoming data payload can be seen in the automation logs run context.

![Notification Referencing Data](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/automation-fetch-run-context.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=e72b608321ff76a155a08bdfdeeb2be0)

Notification Referencing Data

The final rendered result references the data that was fetched in the automation workflow run.

![Template Rendering Fetched Data](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/automation-fetch-rendered.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=9e32638a188989de98bd4538c34fdb59)

Template Rendering Fetched Data


# Automation Get Profile
Source: https://www.courier.com/docs/journeys/automations/get-profile

Load a recipient's stored profile mid-run and branch on what it holds.

## How it works

The GET Profile node fetches a user's Courier profile and attaches it to the automation run context. After this node runs, profile data is available via `refs.profile` in subsequent steps.

Set the user ID to a dynamic value from the data object, such as `refs.data.user_id`.

### When You Need This Step

Not all trigger types automatically load the user's stored profile into the automation context. Use a GET Profile step when your workflow relies on profile fields (for example, in [If/Switch conditions](/docs/journeys/automations/control-flow) or template personalization) and the automation is started by one of these triggers:

| Trigger | Profile auto-loaded? | GET Profile needed? |
| - | - | - |
| API invoke (`/automations` or `/journeys`) | Yes | No |
| Segment | Yes | No |
| [Audience match](/docs/journeys/automations/audience-trigger) | No | Yes |
| Schedule | No | Yes |

Place the GET Profile node early in your workflow, before any step that reads profile data.

> [!TIP]
>
> **Template expressions in step fields:** Many automation fields accept values wrapped in `` `${...}` `` so you can reference the run context (for example `recipient` or fields under `refs`). See [Accessing Dynamic Data](/docs/journeys/automations/dynamic) for how this works across steps.
>
> **Audience and Schedule triggers:** The user id for the run is on `recipient`, not in `data`. In the GET Profile **User ID** field, use `` `${recipient}` `` so this step loads the profile for the user that triggered the run.

![GET Profile Node](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/get-profile-node.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=a32ec4020d914b988eed9eae6fd0b47f)

GET Profile Node

### Ad Hoc Usage

Use the `get-profile` step in an [ad hoc automation](/docs/journeys/automations/steps) to load a user's profile before sending:

```json theme={null}
{
  "automation": {
    "steps": [
      {
        "action": "get-profile",
        "user_id": "user_123",
        "merge_strategy": "none"
      },
      {
        "action": "send",
        "template": "order-update",
        "recipient": "user_123"
      }
    ]
  }
}
```

### Merge Strategy

After the `get-profile` step, the user's stored profile fields (email, phone, custom attributes) are available in the automation context. The `merge_strategy` field controls how fetched data combines with existing context data (defaults to `soft-merge`):

| Strategy | Behavior |
| - | - |
| `soft-merge` | Merge fetched fields into existing context; existing fields are preserved (default) |
| `replace` | Replace the entire context path with fetched data |
| `overwrite` | Overwrite all properties from fetched data |
| `none` | Do not modify context if the path already has data |

See [Fetch Data](/docs/journeys/automations/fetch-data) for more on merge strategies.


# Inbound Events
Source: https://www.courier.com/docs/journeys/automations/inbound-events

Post an event to Courier over the API and start an automation from it.

## Courier Inbound Events

The [CourierJS SDK](https://github.com/trycourier/courier-js/tree/main/packages/courier-js) interfaces with the inbound track API to send client-side application events
to Courier that can be used in Automations trigger nodes.

You can also send events directly via the REST API:

```bash theme={null}
curl --request POST \
  --url https://api.courier.com/inbound/courier \
  --header 'Authorization: Bearer <YOUR_COURIER_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "event": "order-placed",
  "type": "track",
  "userId": "user_123",
  "properties": {
    "order_id": "ORD-98765",
    "total": 59.99
  }
}'
```

The `event` name matches the trigger node's event filter in your automation. The `properties` object is available in the automation context via `refs.data`.

## Segment

With a [Segment third-party integration](/docs/integrations/cdp/segment) both [`track`](https://segment.com/docs/connections/spec/track/)
and [`identify`](https://segment.com/docs/connections/spec/identify/) are automatically ingested using the Segment trigger node in Automations.
Refer to [Segment use cases](/docs/journeys/automations/segment) for more information.

## Rudderstack

With an existing [RudderStack third-party integration](/docs/integrations/cdp/rudderstack) both [`track`](https://www.rudderstack.com/docs/event-spec/standard-events/track/)
and [`identify`](https://www.rudderstack.com/docs/event-spec/standard-events/identify/) are automatically ingested into the Rudderstack trigger node in Automations.


# Automations (Legacy)
Source: https://www.courier.com/docs/journeys/automations/overview

The previous workflow product, still running and superseded by Journeys.

Automations is the previous workflow product. Existing automations keep running. New workflows are built as [Journeys
DOC](/docs/journeys/overview).

Courier's automation engine lets you build notification workflows that go beyond simple message delivery. Create sequences that adapt to user behavior, batch notifications, coordinate across channels, and implement business logic.

## When to Use Automations

If you're sending straightforward transactional messages, you don't need automations. The [Send API](/docs/send/overview) handles rendering, routing, preferences, and delivery in a single call, and that's the right choice for most notifications.

Automations are for when your notification logic involves:

* **Timing** - delays, scheduled delivery, or waiting for business hours
* **Sequences** - multi-step flows like onboarding or reminder chains
* **Batching and digests** - grouping events into a single notification
* **Conditional logic** - branching based on user data, delivery status, or external conditions
* **Cancellation** - aborting a flow when conditions change (e.g., user completes the action before a reminder fires)

Automations use the same templates, users, and preferences as direct sends. Moving a notification into an automation doesn't require changing your content or user setup. See [Choose a Sending Strategy](/docs/send/overview) for a full comparison.

> [!NOTE]
>
> Courier separates **content** (templates) from **logic** (automations): product teams can update templates in the designer without deploys, while engineers manage automation flow. Content changes go live instantly, with no risk to workflow logic.

## Automation Components

Automations are built from three types of nodes: **triggers** that start workflows, **actions** that perform tasks, and **control flow** that adds logic.

### Trigger Nodes

Triggers define how an automation starts. Every automation has one entry point.

| Trigger | Description |
| - | - |
| **API Invoke** | Start via `POST /automations/:template_id/invoke`. Default trigger type. |
| **Schedule** | Run at specific times using cron expressions, recurrence rules, or fixed dates. |
| **Segment** | React to Segment `identify`, `group`, or `track` events. |
| **Audience** | Fire when users match or unmatch an audience. |
| **Inbound Event** | Respond to events from connected sources. |
| **Webhook** | Start from external webhook calls. |
| **Digest** | Release accumulated digest events on schedule. |

See [Audience Trigger](/docs/journeys/automations/audience-trigger), [Webhook Trigger](/docs/journeys/automations/webhook-trigger), [Scheduling](/docs/journeys/automations/scheduling), and [Segment Integration](/docs/journeys/automations/segment) for configuration details.

### Action Nodes

Actions perform tasks in your workflow.

| Action | Description |
| - | - |
| **Send** | Deliver a notification to a user via any channel. |
| **Send to List** | Send to all subscribers of a Courier list. |
| **Delay** | Pause execution for a duration or until a specific time. |
| **Fetch Data** | Make HTTP requests and merge response into automation context. |
| **Update Profile** | Modify a user's Courier profile. |
| **Get Profile** | Load a user profile into the automation context. |
| **Invoke** | Call another automation template. |
| **Cancel** | Cancel a running automation by its cancellation token. |
| **Add to Batch** | Accumulate events for batched delivery. |
| **Add to Digest** | Add events to a user's digest. |
| **Throttle** | Rate-limit notifications per user or globally. |

See [Steps](/docs/journeys/automations/steps), [Batching](/docs/journeys/automations/batching), and [Digests](/docs/journeys/automations/digest) for details.

### Control Flow Nodes

Control flow adds conditional logic and branching.

| Node | Description |
| - | - |
| **If** | Branch based on a single condition (true/false paths). |
| **Switch** | Route to the first matching condition from multiple cases. |
| **Branch** | Multi-path routing with condition groups (V3). |

Conditions can evaluate:

* **Data** fields from the automation context
* **Profile** fields from the user profile
* **Step Ref** status of previous send steps (e.g., `CLICKED`, `DELIVERED`)
* **JS Expression** for complex logic

See [If / Switch](/docs/journeys/automations/control-flow) for operators and examples.

## Common Use Cases

### User Onboarding

Create onboarding sequences that adapt to user progress:

1. Send welcome email immediately after signup
2. Wait 24 hours, then check if user completed first action
3. If not, send a reminder via push notification
4. If completed, send a congratulations message

### Batched Activity Notifications

Reduce notification fatigue by batching activity:

1. Collect events (likes, comments, mentions) as they occur
2. After 1 hour of inactivity (or max 24 hours), release the batch
3. Send a single notification summarizing all activity

See [Batching](/docs/journeys/automations/batching) for configuration.

### Scheduled Digests

Send periodic summaries to users:

1. Configure a digest schedule in [Preferences Editor](https://app.courier.com/settings/preferences)
2. Add events to the digest throughout the period
3. Automation triggers at schedule time with accumulated events
4. Send personalized digest notification

See [Digests](/docs/journeys/automations/digest) for setup.

### Agent-Human Collaboration

Build human-in-the-loop patterns for AI agents and automated systems:

1. Agent triggers an automation requesting human approval
2. Send an actionable notification to Inbox (approve/reject buttons)
3. Wait for user response via webhook or inbound event
4. Branch on the response: proceed, escalate, or cancel

The same pattern works for escalation with timeouts (delay, check delivery status via step ref, escalate if no response) and confirmation flows. Automations provide the timing, branching, and cancellation logic; the Send API and Inbox handle the human interaction.

## Getting Started

1. Navigate to [Automations](https://app.courier.com/automations) in the Courier app
2. Click **New Automation** to create a template
3. Add a trigger node to define how the automation starts
4. Add action nodes for each step in your workflow
5. Add control flow for conditional logic
6. **Publish** the automation to activate it
7. Invoke via API or wait for trigger conditions

For the visual designer interface, see [Designer](/docs/journeys/automations/designer).


# Automation Scheduling
Source: https://www.courier.com/docs/journeys/automations/scheduling

Delay a run until a timestamp, a duration, or the recipient's local time.

* **One-time:** Set the specific time and date to invoke the automation.
* **Recurrence:** Identify a repeat schedule for the automation to be invoked. This is similar to scheduling a repeat event in a calendar application.
* **Cron:** Similar to Recurrence but with more specificity using [crontab expressions](https://crontab.guru/).

Because scheduling is a part of Automations, it can be used across channels (eg. email, SMS, chat, in-app inbox, push) and providers (eg. Twilio, Sendgrid, email SMTP, Slack, MS Teams, WeChat).

## Setup Scheduling

To setup a scheduled automation, drag over the Schedule trigger from the triggers section onto the canvas. Publishing an automation template is sufficient to allow the trigger to invoke the automation on the provided schedule. You do not need to make a separate API call to invoke.

> [!WARNING]
>
> The date picker uses your browser's timezone by default. You can change it using the timezone dropdown. After configuration, the displayed date remains relative to your browser timezone.

> [!NOTE]
>
> The schedule trigger is accurate to within \~12 minutes of the selected time.

![Schedule Trigger](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/automation-schedule.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=210f34e6e19a69a338ee2da1b2684887)

Automation Schedule Trigger


# Automations with Segment
Source: https://www.courier.com/docs/journeys/automations/segment

Trigger an automation from a Segment track event and its properties.

## Segment Automation Trigger Example

In this example, we'll imagine an e-commerce site that sends out an email when a user successfully
checks out, or a reminder to finish checking out when they visit the page, but do not finish their
purchase.

For this, we'll need two automations. One for the reminder condition, the other for the checkout
success condition. We'll start with the reminder condition.

1. Create a new automation

2. Select the Segment trigger and choose correct `track` event. In our case, that is
   "Checkout Page Visited". Note: The track event dropdown is populated with events Courier has
   already received from Segment.

3. The reminder should be sent out a couple of hours after the checkout page was visited, so
   add a delay node with the desired delay time

4. Connect the delay node to a new send node and select the desired template. We set the userId to
   `refs.data.userId`, which is the userId sent to us by segment.

![UserId Referenced](https://mintcdn.com/courier-4f1f25dc/WNdu5qn7yJu4418-/assets/platform/automations/checkout-visited.png?fit=max\&auto=format\&n=WNdu5qn7yJu4418-\&q=85\&s=0f32b3ae405e4c24a161345ecfc7c941)

UserId Referenced

5. If the user successfully checks out, we won't want to send this notification. We'll add a
   cancellation token so we can cancel this run in from our next automation. Navigate to the
   settings tab and set `cancellation` to `refs.data.userId`. This way we can cancel any instance
   of this automation associated with the same user the notification would otherwise be sent to.
6. Click publish to finalize the template

The next automation will cancel the reminder automation from above, and send an invoice on
successful checkout.

1. Create a new automation.
2. Add a Segment trigger node with a track event set to "Checkout Complete"

<video aria-label="New Automation" />

New Automation

3. Add a cancel automation node and set the token to the user id. This will prevent the reminder
   to finish checking out from sending.
4. Send the Checkout Complete notification


# Automation Steps
Source: https://www.courier.com/docs/journeys/automations/steps

Every step an automation can run, from send and delay to fetch and branch.

Ad hoc automations let you define workflows in a single API request without a saved template. Each step has an `action` field that specifies its type.

> [!NOTE]
>
> For visual designer documentation, see [Batching](/docs/journeys/automations/batching), [Digests](/docs/journeys/automations/digest), [Throttle](/docs/journeys/automations/throttle), and [Control Flow](/docs/journeys/automations/control-flow).

## Add to Batch

Add the data object to a batch. Steps after "add-to-batch" are not executed until the batch conditions are met and released. Subsequent steps are invoked only once per batch run.

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the add to batch Automation Step, this value should be `"add-to-batch"`. |
| batch\_key | string | required | A unique id for the batch. This value must be the same for each event expected to be added to the batch |
| wait\_period | string | required | Defines the period of inactivity before the batch is released. Specified as an ISO 8601 duration, [https://en.wikipedia.org/wiki/ISO\_8601#Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) |
| max\_wait\_period | string | required | Defines the maximum wait time before the batch should be released. Must be less than wait period. Maximum of 60 days. Specified as an ISO 8601 duration, [https://en.wikipedia.org/wiki/ISO\_8601#Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) |
| max\_items | number | | If specified, the batch will release as soon as this number is reached |
| retain | object | required | Defines what items should be retained and passed along to the next steps when the batch is released |
| retain.type | string | required | One of `first`, `last`, `highest`, `lowest`. |
| retain.count | number | required | Currently, only 10 is supported |
| retain.sort\_key | string | | Defines the data value `data[sort_key]` that is used to sort the stored items. Required when type is set to `highest` or `lowest`. |
| category\_key | string | | Defines the field of the data object the batch is set to when complete. Defaults to `batch` |

### Schema

```json theme={null}
{
  "action": "add-to-batch",
  "wait_period": "",
  "max_wait_period": "",
  "max_items": 10,
  "retain": {
    "type": "first" | "last" | "highest" | "lowest",
    "count": 10,
    "sort_key": ""
  },
  "category_key": ""
}
```

### Overriding Batches In Flight

When making a batch call, you can make changes to the batching settings to a batching automation mid-flight.

**Retain Settings**

Users can initially set the `retain` parameters when invoking a batch for the first time and make changes to the `retain.count` on subsequent calls. The automation batch will be overwritten with the new retention policy. For example, if you send a batch to retain the first 10 items, and then edit the automation to retain the first 20, the batch will not release until the first 20 are retained while it's less than the `max_items` parameter.

**Send Step**

Send steps cannot be overwritten mid-flight in a batch. The first send step method introduced in the batch will run before the overwritten one takes place.

## Cancel

Cancel an Automation Run that is In Progress.

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the Cancel Automation Step, this value should be `"cancel"`. |
| cancelation\_token | string | | The string that is associated with the cancelable automation run. An Automation Run is cancelable if it has a `cancelation_token` value at execution time. |
| if | string | | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. |
| ref | string | | A pointer to step and its data. |

### Schema

```json theme={null}
{
  "action": "cancel",
  "cancelation_token": "",
  "if": "",
  "ref": ""
}
```

## Delay

Wait a duration of time, before proceeding to the next Automation Step.

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the Delay Automation Step, this value should be `"delay"`. |
| duration | string | | The human readable time duration. A duration value and unit is required, e.g. 5 minutes, 1 hour, 3 days |
| if | string | | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. |
| ref | string | | A pointer to step and its data. |
| until | string | | The ISO 8601 timestamp that describes the length of the delay. |

Either `until` or `duration` is required.

### Schema

```json theme={null}
{
  "action": "delay",
  "if": "",
  "ref": "",
  "until": "",
  "duration": ""
}
```

## Fetch Data

Fetch data via https and write the response to the `data` property of the Automation Run Cache.

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the Fetch Data Automation Step, this value should be `"fetch-data"`. |
| idempotency\_expiry | string | | A unix epoch timestamp (seconds) or an ISO\_8601 date string that describes how long the idempotency\_key is valid. |
| idempotency\_key | string | | A unique value generated by the client which the server uses to recognize subsequent retries of the same request. |
| if | string | | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. |
| merge\_strategy | enum | | `replace`, `soft-merge`, `overwrite`, or `none`. If nothing is specified then the default strategy is `replace`. The strategy to merge the webhook response into the Automation Run Cache. Details below. |
| ref | string | | A pointer to step and its data. |
| webhook | object | | The webhook configuration of the resource that is accessible via http. See the `webhook` schema bellow. |

The `merge_strategy` property can be any of the following values:

* `replace`
  * overwrite all properties in the Automation Cache with the http response. Removes all properties in the Automation Cache that do not exist in the http response.
* `soft-merge`
  * only overwrite properties in the Automation Cache with the http response properties that do not yet exist in the Automation Cache.
* `overwrite`
  * overwrite all properties in the Automation Cache with the properties from the http response.
* `none`
  * do not make any changes to the Automation Cache if the Automation Cache already exists and has data. Otherwise initialize the Automation Cache.

The `webhook` can be configured with any of the following properties:

```json theme={null}
{
  "webhook": {
    "body": {}, // optional
    "headers": {}, // optional
    "params": {}, // optional
    "method": "GET" | "POST", // optional, default GET
    "url": "<API_RESOURCE>"
  }
}
```

### Schema

```json theme={null}
{
  "action": "fetch-data",
  "idempotency_expiry": "",
  "idempotency_key": "",
  "if": "",
  "merge_strategy": "replace" | "none" | "overwrite" | "soft-merge",
  "ref": "",
  "webhook": {
    "body": {}, // optional
    "headers": {}, // optional
    "params": {}, // optional
    "method": "GET" | "POST", // optional, default GET
    "url": "<API_RESOURCE>"
  }
}
```

## GET Profile

Bring a profile stored with Courier into scope. See [GET Profile](/docs/journeys/automations/get-profile) for usage details.

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the GET Profile step, this value should be `"get-profile"`. |
| user\_id | string | required | The user id of the profile to load |
| path | string | | Where the profile should be attached. Can be `profile` or `data.<field-name>`. Defaults to `profile`. |
| merge\_strategy | string | | How to merge the profile with existing context data. `"replace"`, `"none"`, `"overwrite"`, or `"soft-merge"` (default). |
| tenant\_id | string | | Load profile with tenant-specific data |
| if | string | | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. |
| ref | string | | A pointer to step and its data. |

### Schema

```json theme={null}
{
  "action": "get-profile",
  "user_id": "",
  "path": "profile",
  "merge_strategy": "soft-merge",
  "if": "",
  "ref": ""
}
```

## Invoke

Invoke another Automation Template

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the Invoke Automation Step, this value should be `"invoke"`. |
| context | string | | The initial values of the Automation Run Cache to invoke the Automation Template with. |
| if | string | | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. |
| ref | string | | A pointer to step and its data. |
| template | string | required | A unique identifier that can be mapped to an Automation Template. This could be the Template ID or the Alias from the Automation Template Designer. |

### Schema

```json theme={null}
{
  "action": "invoke",
  "context": {
    "brand": "",
    "data": {},
    "profile": {},
    "template": "",
    "recipient": ""
  },
  "if": "",
  "ref": "",
  "template": ""
}
```

## Send (Legacy)

Send a Notification Template

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the Send Automation Step, this value should be `"send"`. |
| recipient | string | required | A unique identifier associated with the recipient of the delivered message. |
| template | string | required | A unique identifier that can be mapped to an individual Notification. This could be the "Notification ID” on Notification detail pages (see the Notifications page in the Courier app) or a custom string mapped to the event in settings. |
| brand | string | | The brand id to be used in the notification. |
| data | string | | An object that includes any data you want to pass to a message template. The data will populate the corresponding template variables. |
| if | string | | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. |
| idempotency\_expiry | string | | A unix epoch timestamp (seconds) or an ISO\_8601 date string that describes how long the idempotency\_key is valid. |
| idempotency\_key | string | | A unique value generated by the client which the server uses to recognize subsequent retries of the same request. |
| override | string | | An object that is merged into the request sent by Courier to the provider to override properties or to gain access to features in the provider API that are not natively supported by Courier. |
| profile | string | | An object that includes any key-value pairs required by your chosen Integrations (see our Provider Documentation for the requirements for each Integration.) If profile information is included in the request and that information already exists in the profile for the recipientId, that information will be merged. |
| ref | string | | A pointer to step and its data. |

### Schema

```json theme={null}
{
  "action": "send",
  "brand": "",
  "data": {},
  "if": "",
  "idempotency_expiry": "",
  "idempotency_key": "",
  "override": {},
  "profile": {},
  "recipient": "",
  "ref": ""
}
```

## Send

Send a Notification Template

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the Send Automation Step, this value should be `"send"`. |
| message | object | required | The Courier Message. For more information see [The Courier Message](/docs/api-reference/send/send-a-message) in the /send API reference. |

### Schema

```json theme={null}
{
  "action": "send",
  "message": {
    "to": {
      // profile
    },
    // either template or content is required but not both
    "template": "",
    "content": {}
  }
}
```

## Send List

Send a message to each recipient in the list. Optionally fetch data for each recipient via http and merge the response into the `data` property of the Automation Run Cache.

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the Send List Automation Step, this value should be `"send-list"`. |
| brand | string | | The brand id to be used in the notification. |
| data | string | | An object that includes any data you want to pass to a message template. The data will populate the corresponding template variables. |
| data\_source | object | | The webhook configuration of the resource that is accessible via http. See the `data_source` schema bellow. |
| idempotency\_expiry | string | | A unix epoch timestamp (seconds) or an ISO\_8601 date string that describes how long the idempotency\_key is valid. |
| idempotency\_key | string | | A unique value generated by the client which the server uses to recognize subsequent retries of the same request. |
| if | string | | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. |
| list | string | required | The Courier List Id. |
| override | string | | An object sent by Courier to the provider to leverage features of the provider API or to simply override properties of the provider api call. |
| template | string | required | A unique identifier that can be mapped to an individual Notification. This could be the "Notification ID” on Notification detail pages (see the Notifications page in the Courier app) or a custom string mapped to the event in settings. |
| ref | string | | A pointer to step and its data. |

The `merge_strategy` property of the steps `data_source` object, can be any of the following values:

* `replace`
  * overwrite all properties in the Automation Cache with the http response. Removes all properties in the Automation Cache that do not exist in the http response.
* `soft-merge`
  * only overwrite properties in the Automation Cache with the http response properties that do not yet exist in the Automation Cache.
* `overwrite`
  * overwrite all properties in the Automation Cache with the properties from the http response.
* `none`
  * do not make any changes to the Automation Cache if the Automation Cache already exists and has data. Otherwise initialize the Automation Cache.

The `webhook` property of the steps `data_source` object, can be configured with any of the following properties:

```json theme={null}
{
  "webhook": {
    "body": {}, // optional
    "headers": {}, // optional
    "params": {}, // optional
    "method": "GET" | "POST", // optional, default GET
    "url": "<API_RESOURCE>"
  }
}
```

### Schema

```json theme={null}
{
  "action": "send-list",
  "brand": "",
  "data": {},
  "data_source": {
    "webhook": {
      "url": "WEBHOOK_URL",
      "method": "GET",
      "headers": {}
    },
    "merge_strategy": "replace"
  },
  "idempotency_expiry": "",
  "idempotency_key": "",
  "if": "",
  "list": "",
  "override": {},
  "ref": "",
  "template": ""
}
```

## Update Profile

Update the Courier Profile given a recipientId.

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the Update Profile Automation Step, this value should be `"update-profile"`. |
| if | string | | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. |
| merge | enum | | `replace`, `soft-merge`, `overwrite`, or `none`. If nothing is specified then the default strategy is `replace`. The strategy to merge new data into the recipient profile. Details below. |
| profile | string | | An object that includes any key-value pairs associated with the recipient profile |
| recipient\_id | string | | A unique identifier associated with the recipient profile you intend to update. |
| ref | string | | A pointer to step and its data. |

The `merge` property can be any of the following values:

* `replace`
  * overwrite all properties in the recipient profile with the http response. Removes all properties in the recipient profile that do not exist in the http response.
* `soft-merge`
  * only overwrite properties in the recipient profile with the http response properties that do not yet exist in the recipient profile.
* `overwrite`
  * overwrite all properties in the recipient profile with the properties from the http response.
* `none`
  * do not make any changes to the recipient profile if the recipient profile already exists and has data. Otherwise initialize the recipient profile

> [!WARNING]
>
> **Profile Merging**: When using update-profile steps, be mindful with the aforementioned merge strategies that can update an existing profile that was [created with a Segment Identify event](/docs/integrations/cdp/segment#identify-calls).

### Schema

```json theme={null}
{
  "action": "update-profile",
  "if": "",
  "merge": "replace",
  "profile": {},
  "recipient_id": "",
  "ref": ""
}
```

## Subscribe

Subscribe a user to a Courier List.

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| action | string | required | The type of element. For the Subscribe Automation Step, this value should be `"subscribe"`. |
| list\_id | string | required | The ID of the Courier List to subscribe the user to. |
| recipient\_id | string | required | The user ID of the recipient to subscribe. |
| subscription | object | | Optional subscription options including preferences. |
| if | string | | A boolean expression whose value is used to determine the execution of the step. Can optionally consume step reference data. |
| ref | string | | A pointer to step and its data. |

### Schema

```json theme={null}
{
  "action": "subscribe",
  "list_id": "my-list-id",
  "recipient_id": "user-123",
  "subscription": {
    "preferences": {}
  },
  "if": "",
  "ref": ""
}
```


# Automation Throttling
Source: https://www.courier.com/docs/journeys/automations/throttle

Cap how often an automation sends to one user over a rolling window.

The throttle node limits how many automation-triggered messages a user or group receives within a set timeframe. Events that exceed the configured limit are dropped and do not pass to the next node.

Because Throttle is a part of Automations, it can apply across channels (eg. email, SMS, chat, in-app inbox, push) and providers (eg. Twilio, Sendgrid, email SMTP, Slack, MS Teams, WeChat).

## Throttle Node Example Use Cases

**Alert Notifications**

When sending alert notifications, you may want to limit the number of notifications sent to a user in a given period to avoid bombarding them with too many alerts.

**Email Campaigns**

If you are running an email campaign, you may want to limit the number of emails sent to a customer within a specific timeframe to avoid overwhelming them with too many messages.

In general, a Throttle step can be useful in any situation where you need to control the flow of data or limit the frequency of an action.

Courier will allow you to specify what next steps should be taken when the throttle is triggered, and what steps should be taken when the throttle is not triggered.

## Creating A Throttle Step

To create a Throttle, use the `throttle` action, then fill out details in the step node.

Specify maximum number of events to allow through the throttle, and the time period to throttle by.

You have the options to throttle by:

| Scope | Usage |
| :- | :- |
| `user_id` | Apply throttling by using `user_id` coming from `data` or `profile` |
| `GLOBAL` | Let Courier decide the throttle parameter. |
| `Dynamic` | You can use arbitrary value available in your `run_context` by referencing it like `refs.data.throttle_key` or `refs.profile.throttle_key` |

Below is an example of a throttle step that allows 1 event to pass through for a given scope in a 7-day period before throttling.

In this example, the throttle is set to be applied dynamically. You have to supply the dynamic key in the following manner to throttle the event. For the `unthrottled` path, you can choose to initiate a different workflow or simply end the automation.

```bash theme={null}
curl --request POST \
  --url https://api.courier.com/automations/<automation_template_id>/invoke \
  --header 'Authorization: Bearer <YOUR_COURIER_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": {
		"throttle_key": "1234567890"
  }
}
```

![Creating throttle step](https://mintcdn.com/courier-4f1f25dc/AtQ7Agb-S0N3tSL2/assets/platform/automations/digests-batching-throttling/throttle-step.png?fit=max\&auto=format\&n=AtQ7Agb-S0N3tSL2\&q=85\&s=b983740d30075670c64642bddd3e9ba7)

Creating Throttle Step


# Automation Webhook Trigger
Source: https://www.courier.com/docs/journeys/automations/webhook-trigger

Start an automation from an inbound webhook you configure in Courier.

## Register an Inbound Webhook

1. Go to [Settings > Webhooks](https://app.courier.com/settings/webhooks), under **Developers**, and find the **Inbound Webhooks** section.
2. Click **Add**, then give the webhook a name and description.
3. Save. Courier generates a unique URL to send events to.

The name is permanent, and it's how you select the webhook when you set up the trigger below. See [Inbound Webhooks](/docs/monitor/webhooks/inbound) for the full reference on registration and payload handling.

### Configure the Webhook

Use the webhook URL that was generated in the previous step to configure the webhook in your system. Exercise a normal workflow to trigger various events to Courier, which will enable them as configuration options in the Automation trigger.

### Inbound Webhook Payload

Courier accepts any payload up to 6Mb in size.

If the payload is a JSON object, Courier will parse the payload and make the data available to you in the Automation. If the payload is not a JSON object, Courier will make the entire payload available to you in the Automation as a raw string.

If the JSON object is an array, Courier will parse each object in the array and trigger an automation for each incoming event.

For JSON objects, Courier will extract the following fields if they are present.

* `event` - The name of the event that triggered the webhook. You can filter by the name when you set up the webhook trigger in Automations. If no string field named event is present, Courier will use "Custom" as the default name.
* `userId` - A user identifier attached to the event. Courier will use this value to identify the user in the Automation, and automatically load associated profile data into the automation context.
* `properties.courier.automation` - A JSON object containing one of the following fields:
  * `template` - The id of an existing automation template to invoke, instead of using a configured webhook trigger.
  * `steps` - A JSON object containing the steps for an ad-hoc automation to execute.

## Using the Webhook trigger in an Automation

1. Go to Automations and create a new automation
2. Drag and drop "Webhook" from the list of triggers.
3. In the Source field, select your registered inbound webhook name.
4. After you select the webhook, you can select the event name from a list of any received events, or Custom if your payload did not contain named events.

The data payload in the webhook will be available to you in the Automation in the normal data object, accessed with `refs.data`.

If you don't see any options in the Event field, make sure you have sent at least one event to the webhook from the source system.


# Build a journey
Source: https://www.courier.com/docs/journeys/build

Build a journey in the canvas or as JSON over the API, then publish and invoke it.

A Journey runs a graph of nodes once per user when you trigger it.

The canvas and the API build the same object, so pick the one that matches who owns the flow. A journey a product manager will keep tuning belongs in the canvas. A journey generated per customer, or checked into your repo, belongs in the API.

**A journey isn't a broadcast.** It runs per user, from an event or an API call, rather than going out to a group at a moment you choose. If you want one message to a list right now, use a [broadcast
DOC](/docs/broadcasts/overview).

## Build in the canvas

**1. Create the Journey**

Open [Journeys](https://app.courier.com/orchestration/journeys), select **New Journey**, and name it. Choose the **API Invoke** trigger so your code starts each run.

![The New Journey dialog with a name field and four trigger options](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/journey-new-journey-trigger.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=7c29c7f4a5f95ec0bb49a95a3b455707)

**2. Add a send node**

Drop a **send** node on the canvas, pick a channel, and select **+ Create** to build its content inline. Each send node owns one Template scoped to this Journey.

**3. Add a delay**

Drag a **delay** node between the trigger and the send. Set it to wait a day. Journeys also offer branch, fetch data, throttle, batch, and digest nodes.

**4. Publish**

Select **Publish** to lock the draft as a version. New runs use it. Runs already in flight finish on the version they started with.

Copy the Journey ID from the editor.

## Build with the API

**1. Create the Journey**

[Create a Journey](/docs/api-reference/journeys/create-a-journey) takes a name and the node list. The list starts with a trigger and ends with an exit, and node ids are left out because the API assigns them. It returns the Journey ID.

```javascript Node.js theme={null}
const journey = await client.journeys.create({
  name: 'Welcome journey',
  nodes: [{ type: 'trigger', trigger_type: 'api-invoke' }, { type: 'exit' }],
});
```

```python Python theme={null}
journey = client.journeys.create(
    name="Welcome journey",
    nodes=[{"type": "trigger", "trigger_type": "api-invoke"}, {"type": "exit"}],
)
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.courier.com/journeys \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Welcome journey",
    "nodes": [{ "type": "trigger", "trigger_type": "api-invoke" }, { "type": "exit" }]
  }'
```

```ruby Ruby theme={null}
journey = courier.journeys.create(
  name: "Welcome journey",
  nodes: [{type: "trigger", trigger_type: "api-invoke"}, {type: "exit"}]
)
```

```go Go theme={null}
journey, err := client.Journeys.New(context.TODO(), courier.JourneyNewParams{
	CreateJourneyRequest: courier.CreateJourneyRequestParam{
		Name: "Welcome journey",
		Nodes: []courier.JourneyNodeUnionParam{
			{OfAPIInvokeTrigger: &courier.JourneyAPIInvokeTriggerNodeParam{
				Type:        courier.JourneyAPIInvokeTriggerNodeTypeTrigger,
				TriggerType: courier.JourneyAPIInvokeTriggerNodeTriggerTypeAPIInvoke,
			}},
			{OfExit: &courier.JourneyExitNodeParam{Type: courier.JourneyExitNodeTypeExit}},
		},
	},
})
```

```java Java theme={null}
CreateJourneyRequest params = CreateJourneyRequest.builder()
    .name("Welcome journey")
    .addNode(JourneyApiInvokeTriggerNode.builder()
        .type(JourneyApiInvokeTriggerNode.Type.TRIGGER)
        .triggerType(JourneyApiInvokeTriggerNode.TriggerType.API_INVOKE)
        .build())
    .addNode(JourneyExitNode.builder()
        .type(JourneyExitNode.Type.EXIT)
        .build())
    .build();
JourneyResponse journey = client.journeys().create(params);
```

```php PHP theme={null}
$journey = $client->journeys->create(
  name: 'Welcome journey',
  nodes: [['type' => 'trigger', 'trigger_type' => 'api-invoke'], ['type' => 'exit']],
);
```

```csharp C# theme={null}
JourneyCreateParams parameters = new()
{
    Name = "Welcome journey",
    Nodes = [new JourneyApiInvokeTriggerNode { Type = "trigger", TriggerType = "api-invoke" }, new JourneyExitNode { Type = "exit" }],
};

var journey = await client.Journeys.Create(parameters);
```

```bash CLI theme={null}
courier journeys create \
  --api-key "$COURIER_API_KEY" \
  --name "Welcome journey" \
  --node '{"type":"trigger","trigger_type":"api-invoke"}' \
  --node '{"type":"exit"}'
```

```text MCP theme={null}
With Courier MCP, create a journey called Welcome journey with an API-invoke trigger and an exit node.
```

**2. Add a scoped Template**

[Create a scoped Template](/docs/api-reference/journeys/create-a-notification-template-scoped-to-a-journey) creates the content a send node uses. These Templates belong to the Journey, separate from your workspace Templates. A run sends each Template's published version, so pass `state: "PUBLISHED"` on create, or publish it later with [Publish a Journey-scoped Notification Template](/docs/api-reference/journeys/publish-a-journey-scoped-notification-template).

```javascript Node.js theme={null}
const template = await client.journeys.templates.create('YOUR_JOURNEY_ID', {
  channel: 'email',
  notification: {
    name: 'Order shipped',
    tags: [],
    brand: null,
    subscription: null,
    content: {
      version: '2022-01-01',
      elements: [
        {
          type: 'channel',
          channel: 'email',
          elements: [{ type: 'text', content: 'Your order {{order_id}} shipped.' }],
        },
      ],
    },
  },
});
```

```python Python theme={null}
template = client.journeys.templates.create(
    template_id="YOUR_JOURNEY_ID",
    channel="email",
    notification={
        "name": "Order shipped",
        "tags": [],
        "brand": None,
        "subscription": None,
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "channel",
                    "channel": "email",
                    "elements": [{"type": "text", "content": "Your order {{order_id}} shipped."}],
                }
            ],
        },
    },
)
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.courier.com/journeys/YOUR_JOURNEY_ID/templates \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "channel": "email",
    "notification": {
      "name": "Order shipped",
      "tags": [],
      "brand": null,
      "subscription": null,
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "channel",
            "channel": "email",
            "elements": [{ "type": "text", "content": "Your order {{order_id}} shipped." }]
          }
        ]
      }
    }
  }'
```

```ruby Ruby theme={null}
template = courier.journeys.templates.create(
  "YOUR_JOURNEY_ID",
  channel: "email",
  notification: {
    name: "Order shipped",
    tags: [],
    brand: nil,
    subscription: nil,
    content: {elements: [{type: "channel", channel: "email", elements: [{type: "text", content: "Your order {{order_id}} shipped."}]}], version: "2022-01-01"}
  }
)
```

```go Go theme={null}
// Elemental nodes carry no typed content field, so pass the notification as raw JSON.
notification := param.Override[courier.JourneyTemplateCreateRequestNotificationParam](json.RawMessage(`{
  "name": "Order shipped",
  "tags": [],
  "brand": null,
  "subscription": null,
  "content": {
    "version": "2022-01-01",
    "elements": [
      {
        "type": "channel",
        "channel": "email",
        "elements": [{ "type": "text", "content": "Your order {{order_id}} shipped." }]
      }
    ]
  }
}`))

template, err := client.Journeys.Templates.New(
	context.TODO(),
	"YOUR_JOURNEY_ID",
	courier.JourneyTemplateNewParams{
		JourneyTemplateCreateRequest: courier.JourneyTemplateCreateRequestParam{
			Channel:      "email",
			Notification: notification,
		},
	},
)
```

```java Java theme={null}
TemplateCreateParams params = TemplateCreateParams.builder()
    .templateId("YOUR_JOURNEY_ID")
    .journeyTemplateCreateRequest(JourneyTemplateCreateRequest.builder()
        .channel("email")
        .notification(JourneyTemplateCreateRequest.Notification.builder()
            .name("Order shipped")
            .tags(java.util.List.of())
            .brand(java.util.Optional.empty())
            .subscription(java.util.Optional.empty())
            .content(JourneyTemplateCreateRequest.Notification.Content.builder()
                // The channel builder has no addElement, so its children go in as an additional property.
                .addElement(ElementalChannelNodeWithType.builder()
                    .type(ElementalChannelNodeWithType.Type.CHANNEL)
                    .channel("email")
                    .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                        java.util.Map.of("type", "text", "content", "Your order {{order_id}} shipped."))))
                    .build())
                .version(JourneyTemplateCreateRequest.Notification.Content.Version._2022_01_01)
                .build())
            .build())
        .build())
    .build();
JourneyTemplateGetResponse template = client.journeys().templates().create(params);
```

```php PHP theme={null}
$template = $client->journeys->templates->create(
  'YOUR_JOURNEY_ID',
  channel: 'email',
  notification: [
    'name' => 'Order shipped',
    'tags' => [],
    'brand' => null,
    'subscription' => null,
    'content' => ['version' => '2022-01-01', 'elements' => [['type' => 'channel', 'channel' => 'email', 'elements' => [['type' => 'text', 'content' => 'Your order {{order_id}} shipped.']]]]],
  ],
);
```

```csharp C# theme={null}
TemplateCreateParams parameters = new()
{
    TemplateID = "YOUR_JOURNEY_ID",
    Channel = "email",
    Notification = new()
    {
        Name = "Order shipped",
        Tags = [],
        Brand = null,
        Subscription = null,
        Content = new()
        {
            // Elemental nodes expose no typed content property, so build the node from raw JSON.
            Elements =
            [
                ElementalChannelNodeWithType.FromRawUnchecked(
                    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                    {
                      "type": "channel",
                      "channel": "email",
                      "elements": [{ "type": "text", "content": "Your order {{order_id}} shipped." }]
                    }
                    """)),
            ],
            Version = "2022-01-01",
        },
    },
};

var template = await client.Journeys.Templates.Create(parameters);
```

```bash CLI theme={null}
courier journeys:templates create \
  --api-key "$COURIER_API_KEY" \
  --template-id YOUR_JOURNEY_ID \
  --channel email \
  --notification '{"name":"Order shipped","tags":[],"brand":null,"subscription":null,"content":{"version":"2022-01-01","elements":[{"type":"channel","channel":"email","elements":[{"type":"text","content":"Your order {{order_id}} shipped."}]}]}}'
```

```text MCP theme={null}
With Courier MCP, add an email template called Order shipped to my journey.
```

**3. Wire the graph**

[Replace a Journey](/docs/api-reference/journeys/replace-a-journey) takes the full node list, in the same body shape as the create call:

* the trigger
* a `send` node referencing the Template ID
* any `delay` or `branch` nodes

**4. Publish**

[Publish a Journey](/docs/api-reference/journeys/publish-a-journey) snapshots the draft as the active version. It doesn't publish the Journey's Templates, so publish those first.

```javascript Node.js theme={null}
await client.journeys.publish('YOUR_JOURNEY_ID');
```

```python Python theme={null}
client.journeys.publish(
    template_id="YOUR_JOURNEY_ID",
)
```

```bash cURL theme={null}
curl --request POST \
  --url https://api.courier.com/journeys/YOUR_JOURNEY_ID/publish \
  --header "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
result = courier.journeys.publish("YOUR_JOURNEY_ID")
```

```go Go theme={null}
_, err := client.Journeys.Publish(
	context.TODO(),
	"YOUR_JOURNEY_ID",
	courier.JourneyPublishParams{},
)
```

```java Java theme={null}
client.journeys().publish("YOUR_JOURNEY_ID");
```

```php PHP theme={null}
$result = $client->journeys->publish('YOUR_JOURNEY_ID');
```

```csharp C# theme={null}
JourneyPublishParams parameters = new() { TemplateID = "YOUR_JOURNEY_ID" };

await client.Journeys.Publish(parameters);
```

```bash CLI theme={null}
courier journeys publish \
  --api-key "$COURIER_API_KEY" \
  --template-id YOUR_JOURNEY_ID
```

```text MCP theme={null}
With Courier MCP, publish my journey so the draft becomes the active version.
```

## Invoke a run

Either path ends the same way. Publishing makes the journey live, and a run starts when your app invokes it by ID or alias.

[Invoke a Journey
DOC](/docs/journeys/invoke) covers the call in every language. It also covers the `Idempotency-Key` that stops a retry starting a second run, and how to inspect or cancel a run by its `runId`.

Editing a send node's content after publishing saves a new template draft. A run sends each template's published version, so the edit takes effect once you publish that template. Publishing the journey doesn't publish its templates.


# Journey experiments
Source: https://www.courier.com/docs/journeys/experiments

A/B test two to ten template variants at one send node and compare results per variant.

An experiment A/B tests more than one version of a message at a single send. A send node runs one **experiment** holding 2 to 10 **variants**, each backed by its own journey template.

Courier assigns each recipient to a variant deterministically and splits traffic by weight. It tracks delivery and engagement per variant, so you can promote one once you have seen enough data.

Use an experiment to compare subject lines, body copy, layouts, or timing without branching the journey or maintaining parallel workflows. Every recipient passes through one send node. Courier decides which variant they receive.

## How experiments work

* **Variants are templates.** Each variant links to a journey template you edit inline, the same way you edit any send node's template. A send node runs either a single template or an experiment, not both.
* **Traffic splits by weight.** Each variant has a relative weight. A variant with weight `3` receives three times the traffic of a variant with weight `1`.
* **Bucketing is deterministic.** Courier hashes a bucketing key to decide which variant a recipient gets, so the same recipient always lands in the same variant. See [Bucketing key and stickiness](#bucketing-key-and-stickiness).
* **Assignments are sticky.** Once a recipient is assigned to a variant, they keep it across sends, even if you change the weights later.
* **Metrics are per variant.** Courier tracks sent, delivered, opened, clicked, and error or undeliverable counts for each variant so you can compare them.
* **You promote manually.** When you've seen enough, you promote one variant. Its template becomes the only template on the node and the experiment ends.

## Create an experiment

**1. Add an experiment**

Create an experiment at the send step you want to test. Courier starts you with two variants, each backed by its own template.

**2. Name the experiment**

Give the experiment a name so you can find it later in the results and metrics views.

**3. Edit each variant's template**

Open each variant and edit its template. Name the variants something you'll recognize later, for example `Short subject` and `Long subject`. Edits to a template show up on its variant right away.

**4. Set traffic allocation**

Give each variant a weight to control how much traffic it receives. Weights are relative, so `3`, `1`, `1` sends 60% of traffic to the first variant and 20% to each of the others. A variant with a weight of `0` receives no traffic.

**5. Publish**

Publish the journey to make the experiment live and start splitting traffic.

## Variants and traffic allocation

An experiment starts with two variants. Add or remove variants up to a maximum of 10. Each variant links to a full journey template, so anything you can build in a template (subject, body, channel-specific content) can differ between variants.

Each variant carries a relative weight that sets its share of traffic. Weights need no particular total: `3`, `1`, `1` splits traffic 60/20/20, and so does `30`, `10`, `10`. Weights must be zero or greater, and at least one variant must have a weight above zero. A variant weighted `0` receives no traffic, which pauses it without removing it.

### Keep only this variant

Before an experiment is published and taking live traffic, each variant shows a **Keep only this variant** control. It collapses the experiment down to that single variant, for example if you change your mind before launching. Once the experiment is live, this control is hidden. To reduce a live experiment to one variant, [promote a variant](#promote-a-variant) instead.

## Bucketing key and stickiness

The **bucketing key** is a path to a value in the invocation, in the recipient's `profile` or the `data` payload, for example `user.id`, `user.email`, or `data.account_id`. It isn't a literal value. Courier reads the value at that path for each recipient and hashes it, together with the variant weights, to pick a variant deterministically. The same value always maps to the same variant. If the path can't be resolved for a recipient, Courier falls back to the user ID, then the email. The key must be non-empty with no leading or trailing whitespace.

Assignments are **sticky**: once a recipient is bucketed into a variant, they stay in that variant across sends, even if you change the weights afterward. This keeps each recipient's experience consistent for the length of the experiment.

> [!WARNING]
>
> Editing a variant's weight, template, or name keeps existing assignments in place. Two changes reset the experiment and re-bucket everyone:
>
> * Adding or removing a variant
> * Changing the bucketing key

## Results and metrics

Courier tracks metrics for each variant: sent, delivered, opened, clicked, and error or undeliverable counts. The **Results** tab breaks these down per variant, including which template each delivered message used. The **Metrics** view groups the experiment with its templates alongside the rest of the journey's analytics.

## Promote a variant

When you've seen enough data, promote the variant you want to keep. Promoting:

* Replaces the experiment with the promoted variant's template, so the node sends that single template
* Removes the other variants from the node
* Ends the experiment

Publish the journey to apply the change. Runs already in progress finish on the version they started with. Only new entrants get the promoted template. In the metrics view, any variant that received traffic stays visible as inactive, so its historical data isn't lost.

Promotion is manual. Courier never picks or promotes a variant for you.

## Common patterns

* **Subject line tests** - Run two or more subject lines against the same body and promote the one with the stronger open rate.
* **Copy and layout tests** - Compare body copy, calls to action, or channel layouts on a single send.
* **Gradual rollout** - Weight a new template low to expose it to a small share of traffic, then raise its weight as you gain confidence. Existing recipients keep their assignment, so raising a weight shifts only new entrants.

## Configure via the API

An experiment lives on a send node in place of `message.template`. The `message` object stays required but can be empty when an experiment is present. `message.to`, `message.delay`, and `message.data` still apply to whichever variant is chosen.

```json theme={null}
{
  "id": "send-welcome",
  "type": "send",
  "message": {},
  "experiment": {
    "name": "Welcome subject-line test",
    "bucketingKey": "user.id",
    "variants": [
      { "id": "control", "name": "Control",      "weight": 6, "templateId": "ntf_control" },
      { "id": "short",   "name": "Short subject", "weight": 3, "templateId": "ntf_short" },
      { "id": "emoji",   "name": "Emoji subject", "weight": 1, "templateId": "ntf_emoji" }
    ]
  }
}
```

For the full field reference, see [Build journeys via the API
DOC](/docs/journeys/build).


# Invoke a journey
Source: https://www.courier.com/docs/journeys/invoke

Start a journey run from the API, find it by run ID, and cancel it.

> [!NOTE]
>
> [Journeys
> DOC](/docs/journeys/overview) covers the snapshot, delays, and cancellation model.

Start a Journey run from the API, then find it by its run ID.

## Prerequisites

* A published journey with an **API** trigger
* [A Courier API key](https://app.courier.com/settings/api-keys)

## Run a journey

**1. Invoke a journey**

Start a run with the invoke endpoint, referencing the journey by its ID or alias in the path.

* `user_id`, or a `profile` with contact info, for the recipient.
* `data`, optional, matching the trigger schema.
* An `Idempotency-Key` header, so a retried request returns the same run instead of starting a second one.

The response returns a `runId`.

```javascript Node.js theme={null}
const journeysInvokeResponse = await client.journeys.invoke('welcome-journey', {
  user_id: 'user_123',
  data: { order_id: 'ORD-9042', order_total: 49.99 },
});
```

```python Python theme={null}
journeys_invoke_response = client.journeys.invoke(
    template_id="welcome-journey",
    user_id="user_123",
    data={
        "order_id": "ORD-9042",
        "order_total": 49.99,
    },
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/journeys/welcome-journey/invoke \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "user_id": "user_123",
    "data": { "order_id": "ORD-9042", "order_total": 49.99 }
  }'
```

```ruby Ruby theme={null}
journeys_invoke_response = courier.journeys.invoke(
  "welcome-journey",
  user_id: "user_123",
  data: {order_id: "ORD-9042", order_total: 49.99}
)
```

```go Go theme={null}
journeysInvokeResponse, err := client.Journeys.Invoke(
	context.TODO(),
	"welcome-journey",
	courier.JourneyInvokeParams{
		JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
			UserID: courier.String("user_123"),
			Data: map[string]any{
				"order_id":    "ORD-9042",
				"order_total": 49.99,
			},
		},
	},
)
```

```java Java theme={null}
JourneyInvokeParams params = JourneyInvokeParams.builder()
    .templateId("welcome-journey")
    .journeysInvokeRequest(JourneysInvokeRequest.builder()
        .userId("user_123")
        .data(JourneysInvokeRequest.Data.builder()
            .putAdditionalProperty("order_id", JsonValue.from("ORD-9042"))
            .putAdditionalProperty("order_total", JsonValue.from(49.99))
            .build())
        .build())
    .build();
JourneysInvokeResponse journeysInvokeResponse = client.journeys().invoke(params);
```

```php PHP theme={null}
$journeysInvokeResponse = $client->journeys->invoke(
  'welcome-journey',
  userID: 'user_123',
  data: ['order_id' => 'ORD-9042', 'order_total' => 49.99],
);
```

```csharp C# theme={null}
JourneyInvokeParams parameters = new()
{
    TemplateID = "welcome-journey",
    UserID = "user_123",
    Data = new Dictionary<string, JsonElement>()
    {
        { "order_id", JsonSerializer.SerializeToElement("ORD-9042") },
        { "order_total", JsonSerializer.SerializeToElement(49.99) },
    },
};

var journeysInvokeResponse = await client.Journeys.Invoke(parameters);
```

```bash CLI theme={null}
courier journeys invoke \
  --api-key "$COURIER_API_KEY" \
  --template-id welcome-journey \
  --user-id user_123 \
  --data '{order_id: ORD-9042, order_total: 49.99}'
```

```text MCP theme={null}
With Courier MCP, start my welcome-journey for user_123 with the order details.
```

**2. Inspect a run**

Take the `runId` from the invoke response, open the journey's **Logs** tab, and search for it. The detail view overlays each node's outcome on the graph. Click a node to see its step context: input data, profile, conditions evaluated, and output. Over the API, [List steps for a Journey run](/docs/api-reference/journeys/list-steps-for-a-journey-run) returns the same steps. See [journey logs
DOC](/docs/monitor/logs#journey-logs) for the run states and what each view shows.

## Cancel a run

Cancel in-flight runs with the cancel endpoint. Target either a `cancelation_token`, which cancels every run sharing it, or a single `run_id`. You set the token in the journey's settings, so runs carry it from the moment they start.

```javascript Node.js theme={null}
const cancelJourneyResponse = await client.journeys.cancel({ cancelation_token: 'order-9042-flow' });
```

```python Python highlight={2} theme={null}
cancel_journey_response = client.journeys.cancel(
    cancelation_token="order-9042-flow",
)
```

```bash cURL highlight={5} theme={null}
curl -X POST https://api.courier.com/journeys/cancel \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelation_token": "order-9042-flow"
  }'
```

```ruby Ruby theme={null}
cancel_journey_response = courier.journeys.cancel(cancel_journey_request: {cancelation_token: "order-9042-flow"})
```

```go Go highlight={3-4} theme={null}
cancelJourneyResponse, err := client.Journeys.Cancel(context.TODO(), courier.JourneyCancelParams{
	CancelJourneyRequest: courier.CancelJourneyRequestUnionParam{
		OfByCancelationToken: &courier.CancelJourneyRequestByCancelationTokenParam{
			CancelationToken: "order-9042-flow",
		},
	},
})
```

```java Java highlight={1-2} theme={null}
CancelJourneyRequest.ByCancelationToken params = CancelJourneyRequest.ByCancelationToken.builder()
    .cancelationToken("order-9042-flow")
    .build();
CancelJourneyResponse cancelJourneyResponse = client.journeys().cancel(params);
```

```php PHP highlight={2} theme={null}
$cancelJourneyResponse = $client->journeys->cancel(
  cancelationToken: 'order-9042-flow'
);
```

```csharp C# highlight={3} theme={null}
JourneyCancelParams parameters = new()
{
    CancelJourneyRequest = new ByCancelationToken("order-9042-flow")
};

var cancelJourneyResponse = await client.Journeys.Cancel(parameters);
```

```bash CLI highlight={3} theme={null}
courier journeys cancel \
  --api-key "$COURIER_API_KEY" \
  --cancelation-token order-9042-flow
```

To cancel one run instead, pass the `run_id` from the invoke response in place of `cancelation_token`. [Cancel Journey runs](/docs/api-reference/journeys/cancel-journey-runs) takes exactly one of the two. Sending both or neither returns `400`.

It returns `202` with the run and its resulting status:

| Status | Meaning |
| - | - |
| `CANCELED` | The run was active (or already canceled), and is canceled. |
| `PROCESSED` | The run had already finished. Nothing changed. |
| `ERROR` | The run had already ended in an error. Nothing changed. |

Only active runs are affected, so canceling is idempotent and always safe. A `run_id` Courier can't find for your workspace returns `404`. To build the token itself, or to cancel from inside a flow, see the [cancel node
DOC](/docs/journeys/nodes/cancel).


# Journey nodes
Source: https://www.courier.com/docs/journeys/nodes

The steps on a journey canvas: send, branch, delay, digest, batch, AI, fetch data, throttle, cancel.

Nodes are the steps on a journey canvas. They send messages, branch on data, wait, aggregate events, call external services, and cancel runs.

| Node | Use it to |
| - | - |
| [Send&#xA;DOC](/docs/journeys/nodes/send) | Deliver a message on one channel, from a journey template. |
| [Branch&#xA;DOC](/docs/journeys/nodes/branch) | Split the path on a condition. |
| [Delay&#xA;DOC](/docs/journeys/nodes/delay) | Wait for a duration, or until a timestamp. |
| [Digest&#xA;DOC](/docs/journeys/nodes/digest) | Roll repeated events into one message on a schedule. |
| [Batch&#xA;DOC](/docs/journeys/nodes/batch) | Collect events and release them together as one payload. |
| [AI&#xA;DOC](/docs/journeys/nodes/ai) | Generate content or make a decision with a model. |
| [Fetch data&#xA;DOC](/docs/journeys/nodes/fetch-data) | Call an external service and use the response later in the run. |
| [Throttle&#xA;DOC](/docs/journeys/nodes/throttle) | Cap how often a run sends. |
| [Cancel&#xA;DOC](/docs/journeys/nodes/cancel) | End this run, or a group of runs sharing a token. |

For how a run moves through them at runtime, see [how journeys run
DOC](/docs/journeys/overview). To split traffic across variants and promote a winner, see [experiments
DOC](/docs/journeys/experiments).

## Digest and Batch aren't the same node

Both hold events back and release them together, and the difference decides which one you want.

A Digest releases on a **schedule** set on the topic, so a reader gets their nine o'clock summary whether two events arrived or twenty. A Batch releases on a **condition**, either a count or a window, so it fires as soon as enough has accumulated.

Reach for Digest when the cadence belongs to the recipient, and Batch when it belongs to the event volume.

## Every node reads the same run context

A node acts on the data the run already carries: the payload it was invoked with, the profile, and anything a [Fetch data
DOC](/docs/journeys/nodes/fetch-data) node added earlier. That is why order matters. A node can't read what a later node produces.

**A condition that references missing data evaluates to false.** The run takes the other path. Check a branch's decisions against a real run before trusting a path that never fires.


# Journey AI node
Source: https://www.courier.com/docs/journeys/nodes/ai

Run an LLM prompt inside a journey with the run's context, and use its structured output.

AI nodes run a large language model prompt as part of a journey. Courier sends the prompt and the run's context to the model you select.

Courier parses the response into structured output and adds it to the journey context under `data.ai_result`.

Downstream nodes use that output to make decisions, personalize messages, or update user data.

**AI nodes run on [AI credits](#billing).** A run fails at the AI node when the workspace has none. Add credits in [Settings → Billing](https://app.courier.com/settings/billing).

AI nodes run in the US datacenter only. In the [EU datacenter
DOC](/docs/workspaces/datacenters), creating, replacing, or publishing a journey with an AI node fails with `AI steps aren't available in this region yet`.

## Configuration

Click the AI node on the canvas to open the summary panel, then click **Configure** to open the full configuration drawer.

![](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/ai-node-edit-drawer.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=85b402f156dc5667b28a1b9f6bd338b2)

AI node configuration drawer with model selector, web search toggle, prompt, and output schema

### AI model

Choose the model that fits what the AI node needs to do. Courier supports models from OpenAI and Anthropic, so each node can balance speed, cost, and output quality.

Use smaller models for predictable structured tasks: classifying users, extracting fields, scoring engagement, or returning simple JSON. Use larger models when the prompt needs more context, nuanced reasoning, or higher-quality generated copy.

Available models:

| Provider | Model | Model ID |
| - | - | - |
| Anthropic | Claude Fable 5.1 | `claude-fable-5-1` |
| Anthropic | Claude Opus 5.5 | `claude-opus-5-5` |
| Anthropic | Claude Sonnet 5.5 | `claude-sonnet-5-5` |
| Anthropic | Claude Haiku 5.5 | `claude-haiku-5-5` |
| OpenAI | GPT-6 Astra | `gpt-6-astra` |
| OpenAI | GPT-5.5 | `gpt-5.5` |
| OpenAI | GPT-5.4 | `gpt-5.4` |
| OpenAI | GPT-6.1 Sol | `gpt-6.1-sol` |
| OpenAI | GPT-6.1 Terra | `gpt-6.1-terra` |
| OpenAI | GPT-5.4 Mini | `gpt-5.4-mini` |
| OpenAI | GPT-5.4 Nano | `gpt-5.4-nano` |
| OpenAI | GPT-6 Luna | `gpt-6-luna` |

When you create or replace a journey through the API, set the AI node's `model` to the model ID and give it a `user_prompt`. Both are required, so a missing or blank one fails with `AI step needs a model` or `AI step needs a prompt`. An ID that isn't in the table fails with `unknown model`, followed by the list of valid IDs. Retired model IDs keep working: Courier runs them on their successor model.

See [Billing](#billing) for credit costs, token overages, and web search pricing.

### Web search

Toggle web search on when the prompt needs current information the journey context doesn't have. The model can then query the internet before generating its structured response.

Web search is available for Anthropic models only. Each invocation with web search enabled costs an additional **2 credits**. Search results also count as input tokens, along with the prompt, output schema, journey context, and resolved variables. If the total input exceeds **3,072 tokens**, input token overage applies.

### Prompt

Write a natural-language prompt describing what you want the model to do. The prompt field supports `{{variable}}` interpolation. Type `{{` to see available fields from the trigger schema, profile, or upstream fetch responses.

For the onboarding nudge example below, the prompt might be:

```text theme={null}
You are a product growth assistant. Based on this user's profile and activity, write a personalized onboarding nudge that encourages them to try the next feature most relevant to their use case.

Rules:
- subject_line should be under 60 characters, personalized, and action-oriented
- body_copy should be 1-2 sentences, friendly, and reference what they've already done
- recommended_feature must be exactly one of: templates, automations, integrations, analytics
- tone must be exactly one of: encouraging, celebratory, urgent

User: {{data.user_name}}
Plan: {{data.plan_name}}
Features used so far: {{data.features_used}}
Days since signup: {{data.days_since_signup}}
```

A token counter in the top-right of the drawer shows prompt + schema size in real time. Most AI node runs stay within the included token limit. Input token overage usually comes from variables, fetch responses, or web search results that add large amounts of text.

### Output schema

The output schema defines the structure of the model's response. Define it in two modes:

**Form mode** (default): Add fields with a name and type (string, number, or boolean). Optionally add a description telling the model what the field should contain.

**JSON mode**: Write a JSON Schema directly. Use this for more complex schemas or when pasting from an existing definition.

For the onboarding nudge example, the form-mode schema would be:

| Field | Type | Description |
| - | - | - |
| `subject_line` | string | Personalized email subject under 60 characters |
| `body_copy` | string | 1-2 sentence nudge referencing the user's activity |
| `recommended_feature` | string | One of: templates, automations, integrations, analytics |
| `tone` | string | One of: encouraging, celebratory, urgent |

The model's response is parsed as JSON and stored in the journey context under `data.ai_result`. Downstream nodes read each field under that key:

* In [branch conditions
  DOC](/docs/journeys/nodes/branch): select `data.ai_result.tone` or `data.ai_result.recommended_feature` as the field
* In [journey templates
  DOC](/docs/journeys/build): use `{{ai_result.subject_line}}` or `{{ai_result.body_copy}}`

**A second AI node overwrites `data.ai_result`.** Read the first node's output before the run reaches the next one.

### Conditions

AI nodes support optional [conditions
DOC](/docs/journeys/nodes/branch). If they aren't met when the run reaches the node, it's skipped and no credits are consumed.

## Testing

Click **Test** in the configuration drawer to open the test panel. Run the prompt against the selected model with sample variable values and see the structured response before publishing the journey.

![](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/ai-node-test-drawer.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=401a429e6bcf8b28fa528d4c6ac55459)

Test drawer showing prompt, output schema, and structured test result

The test result shows the parsed JSON output on the right, or an error message if the request failed.

> [!WARNING]
>
> A test run is billed like a real one. It calls the same model and deducts the same credits, so iterating on a prompt with an expensive model adds up.

## Example: personalized onboarding nudge

A journey that generates tailored onboarding messages from each user's activity:

![](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/ai-node-example-journey.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=847711bd514d06905d48424df7d62342)

Onboarding nudge journey: API trigger → Fetch activity → AI generates personalized copy → branch on tone → send via the right channel

1. **Trigger**: Fires on day 3 after signup. The trigger schema includes `user_name`, `plan_name`, `features_used`, and `days_since_signup`.
2. **Fetch Data**: Pulls the user's recent activity summary from your application API.
3. **AI node**: Given the user's profile and activity, generates a personalized nudge with `subject_line`, `body_copy`, `recommended_feature`, and `tone`. Model: Claude Sonnet 5.5 (1.75 credits per run).
4. **Branch**: Routes based on `data.ai_result.tone`:
   * Path "Celebratory": user has been active → sends a congratulatory email with `{{ai_result.subject_line}}` and `{{ai_result.body_copy}}`.
   * Path "Urgent": user hasn't engaged → sends a push notification to re-engage.
   * Default: sends a standard onboarding email with the AI-generated copy.

## Common patterns

**Score and classify users**: Feed product usage, behavior, and profile data into the LLM. Route the journey based on risk level, intent, engagement, or any structured category the model returns.

**Generate personalized notifications**: Give the model your journey context and get back tailored subject lines, body copy, and recommended actions. Personalized content for every recipient without dozens of template variants.

**Enrich user profiles**: Classify users into personas, derive lifecycle stage, or generate account summaries. Persist outputs to the profile so every future journey starts with richer context.

**Structured output for downstream logic**: Define an output schema with field names, types, and enums. The LLM returns structured JSON that branch conditions, send nodes, and downstream integrations can act on directly.

## Debugging AI nodes

Open the run in [journey logs
DOC](/docs/monitor/logs#read-a-run) and click the AI node step to see:

* The model used and whether web search was enabled
* The resolved prompt (with variables substituted)
* The output schema that was sent to the model
* The structured JSON response
* Token usage (input and output token counts)

**A failed AI node stops the run.** The step and the run both end in `error`, and no node after the AI node runs. The step's error message names the cause:

| Message | Cause |
| :- | :- |
| `This workspace has no AI credits. Add credits in Settings → Billing.` | The workspace has no AI credits |
| `Model "<id>" isn't supported.` | The node's model ID isn't one Courier runs |
| `AI step timed out after 15 minutes` | The model didn't answer within 15 minutes. A late answer is ignored and doesn't resume the run. |
| `AI step failed: <message>` | The model provider returned an error |
| `AI steps aren't available in this region yet` | The workspace is in the EU datacenter |

Read the message on the AI step in [journey logs
DOC](/docs/monitor/logs#read-a-run), or in the step's `error.message` from [List steps for a Journey run](/docs/api-reference/journeys/list-steps-for-a-journey-run).

## Billing

On the Developer plan, AI nodes can't be placed on the canvas, and credit packs can't be bought.

Each AI node invocation consumes credits based on the selected model. Credits are billed at **100 credits per \$1** and bought as packs in the console, separately from your send bill. Auto top-up charges your card for another pack when the balance falls below a threshold, 100 credits by default.

| Provider | Model | Credits per invocation |
| - | - | -: |
| Anthropic | Claude Fable 5.1 | 9 |
| Anthropic | Claude Opus 5.5 | 3.5 |
| Anthropic | Claude Sonnet 5.5 | 1.75 |
| Anthropic | Claude Haiku 5.5 | 0.1 |
| OpenAI | GPT-6 Astra | 9 |
| OpenAI | GPT-5.5 | 5 |
| OpenAI | GPT-5.4 | 2.5 |
| OpenAI | GPT-6.1 Sol | 1.75 |
| OpenAI | GPT-6.1 Terra | 1 |
| OpenAI | GPT-5.4 Mini | 0.75 |
| OpenAI | GPT-5.4 Nano | 0.2 |
| OpenAI | GPT-6 Luna | 0.1 |

The values above are base costs per invocation. Each invocation includes up to **3,072 input tokens** and **1,000 output tokens**. Most AI node runs stay within these included limits.

Input tokens cover everything sent to the model: the prompt, output schema, journey context, resolved variables, upstream fetch responses, and web search results. Input token overage applies when the node sends a large amount of text, such as long variables, large fetch responses, or web search results.

Output tokens are generated by the model response. Output token overage applies only when the model response exceeds 1,000 tokens. Control output length through the prompt and output schema.

| Provider | Model | Input token overage credits / 1K tokens | Output token overage credits / 1K tokens |
| - | - | -: | -: |
| Anthropic | Claude Fable 5.1 | 1.250 | 6.250 |
| Anthropic | Claude Opus 5.5 | 0.500 | 2.500 |
| Anthropic | Claude Sonnet 5.5 | 0.250 | 1.250 |
| Anthropic | Claude Haiku 5.5 | 0.013 | 0.063 |
| OpenAI | GPT-6 Astra | 1.250 | 6.250 |
| OpenAI | GPT-5.5 | 0.625 | 3.750 |
| OpenAI | GPT-5.4 | 0.313 | 1.875 |
| OpenAI | GPT-6.1 Sol | 0.250 | 1.250 |
| OpenAI | GPT-6.1 Terra | 0.125 | 0.625 |
| OpenAI | GPT-5.4 Mini | 0.094 | 0.563 |
| OpenAI | GPT-5.4 Nano | 0.025 | 0.156 |
| OpenAI | GPT-6 Luna | 0.013 | 0.063 |

Web search is available for Anthropic models only. When enabled, each invocation costs an additional **2 credits**. Search results also count as input tokens, so web search can push the total past 3,072 tokens and trigger input token overage.


# Journey batch node
Source: https://www.courier.com/docs/journeys/nodes/batch

Collect events at one point in a journey and release them as a single payload.

The Batch node collects events that arrive at the same point in a journey and releases them together as one aggregated payload. Use it to turn a burst of activity into a single notification, for example "Your post received 17 likes", instead of many.

The first event into a batch owns the run and continues downstream when the batch releases. Later contributing events terminate at the Batch node, so the nodes after a batch run only once per batch.

## When a batch releases

A batch releases as soon as any one of these is true:

* **Max items** collected (`max_items`, default 100, up to 1000).
* **Wait period** elapses with no new contributing event (a quiet, inactivity window).
* **Max wait period** ceiling is reached, measured from the first event into the batch.

The wait period is between 1 minute and 1 day. The max wait period is at least the wait period and at most 7 days. The quiet window releases an idle batch early. The max wait period is the hard ceiling that always releases it.

## Configuration

| Field | Description |
| - | - |
| **Max items** | Release the batch once this many events have collected. Defaults to 100 (1 to 1000). |
| **Wait period** | Quiet window. If no new event arrives within this span, the batch releases. 1 minute to 1 day. |
| **Max wait period** | Hard ceiling from the first event. The batch releases when this elapses, even if events are still arriving. At least the wait period, up to 7 days. |
| **Include event data** | When on, the collected events are attached to the released payload. Configure which ones with Strategy and Count. |
| **Strategy** | Which collected events to retain: **First**, **Last**, **Highest**, or **Lowest**. Highest and Lowest require a sort key (a dot-path into the event, for example `data.priority`). |
| **Count** | How many events to retain (0 to 25). The tracked `count` still reflects the true total, even if fewer items are retained. |
| **Category key** | Optional. A field to group events by inside the batch, written as a reference such as `{{data.category}}`. Events still release together as one batch. See [Categories](#categories). |
| **Conditions** | Optional. Only run the node when the conditions evaluate true. |

Journey batches are scoped per user (`scope: user`), so events are grouped by the recipient.

## Batch payload

When the batch releases, downstream nodes receive a `batch` object with the total `count` and the retained `items`:

```json theme={null}
{
  "batch": {
    "count": 3,
    "items": [
      { "like_from": "Drew" },
      { "like_from": "Alex" },
      { "like_from": "Abby" }
    ]
  }
}
```

How you reference it depends on where:

| Where | Write |
| :- | :- |
| Template text | `{{batch.count}}` |
| A loop over the items | `data.batch.items` |

Template text resolves variables from `data`, so it leaves the root off. A loop's expression runs against `data`, `profile`, and `refs` together, so it names `data` explicitly.

### Categories

Set a category key to count and list events by a field's value, for a digest such as "3 likes and 2 comments". The batch still releases once, and the groups appear under `batch.categories`, keyed by each value:

```json theme={null}
{
  "batch": {
    "count": 5,
    "items": [
      { "type": "like", "from": "Drew" },
      { "type": "like", "from": "Alex" },
      { "type": "comment", "from": "Abby" }
    ],
    "categories": {
      "like": {
        "count": 3,
        "items": [{ "type": "like", "from": "Drew" }, { "type": "like", "from": "Alex" }]
      },
      "comment": {
        "count": 2,
        "items": [{ "type": "comment", "from": "Abby" }]
      }
    }
  }
}
```

| Where | Write |
| :- | :- |
| Template text | `{{batch.categories.like.count}}` |
| A loop over the items | `data.batch.categories.like.items` |

`batch.count` and `batch.items` always cover the whole batch. An event with no value at the category key counts in those totals but in no category, and `categories` is left out when no event had a value.

**`retain` is shared across categories.** A count of 3 keeps 3 events for the whole batch, not 3 per category, so a category's `items` can hold fewer events than its `count`, as `comment` does above.

## Via the API

In a journey definition, a Batch node uses `type: "batch"`:

```json theme={null}
{
  "type": "batch",
  "scope": "user",
  "wait_period": "PT1H",
  "max_wait_period": "P1D",
  "max_items": 100,
  "retain": {
    "type": "first",
    "count": 5
  },
  "category_key": "{{data.category}}"
}
```

`category_key` must be one whole reference. A literal such as `"data.category"`, or a reference inside other text, fails with `category_key must be a reference like "{{data.category}}"`. See [Building Journeys via the API
DOC](/docs/journeys/build) for the full node reference. Durations use ISO 8601 (for example, `PT1H` for one hour, `P1D` for one day).


# Journey branch node
Source: https://www.courier.com/docs/journeys/nodes/branch

Split a journey into paths by conditions on the run data, with a default path.

Branch nodes split the journey into paths. Each path has a set of conditions. The run follows the first path whose conditions all match. If none match, it follows the **Default** path, always present as a fallback.

![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/branch-node-canvas.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=621e9788a0c4ce13fafb489623ff6e11)

A branch node on the canvas with a conditional path and a Default path

## Configuring conditions

Click the branch node to open the condition editor. Each path takes one or more conditions, and each condition has three parts:

* **Field**: a value from the journey context (trigger schema, profile, or fetch response)
* **Operator**: the comparison
* **Value**: what to compare against

Every field starts with one of these roots:

| Root | Reads |
| :- | :- |
| `data.` | The trigger payload, plus anything an upstream fetch or AI node added |
| `profile.` | The recipient's profile |
| `tenant.` | The run's tenant. Only when the trigger sets one |
| `send_status.<nodeId>` | The delivery status of an earlier send node's message, compared with **was** or **was not** |

**Write the root on every field.** No `user.` root exists, so read a profile field as `profile.tier`, not `user.tier`. Creating or replacing a journey through the API checks every condition, on branch paths and on any node's own conditions:

| Message | Cause |
| :- | :- |
| `Condition path "user.tier" must start with data., profile., tenant., or send_status.` | The field has no valid root |
| `Condition path "data.items.#.sku": array wildcards aren't supported` | The field uses `#` to match any array index |
| `Condition path "send_status.<nodeId>" only supports the "was" and "was not" operators` | A `send_status` field uses any other operator |
| `Condition path "tenant.plan" uses tenant., but this journey's trigger doesn't set a tenant` | A `tenant.` field in a journey whose trigger sets no `tenant_id` |

![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/branch-config-panel.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=cd6111a6848bae3fdbf3e3fcedabd272)

Branch configuration panel showing condition groups with field, operator, and value selectors

## Multiple conditions per path

A path supports both AND and OR logic. Click **+ add** inside a condition group to add another condition. All conditions in the same group must be true (AND). Click **+ or** at the bottom to add a separate group. The path executes if any group is satisfied (OR).

For example, route to a VIP path for a first-time buyer with a high-value order, *or* a returning buyer who has spent more:

* **Group 1**: `data.is_first_order` is equal `true` AND `data.order_total` greater than `50`
* **Group 2**: `data.is_first_order` is equal `false` AND `data.order_total` greater than `200`

Click the path name in the condition editor to rename it. Defaults are "Path 1", "Path 2", and so on. The name updates on the canvas label, so "First Order" reads better than "Path 1".

## Common patterns

**Tiered notifications**: Branch on a numeric field (e.g., `data.priority`) to send urgent messages via SMS and lower-priority messages via email.

**Feature gating**: Branch on a boolean field (e.g., `data.is_premium`) to send premium users richer content.

**Fallback handling**: Use the Default path to catch unexpected values and send a generic message or skip sending entirely.

## Debugging branch decisions

When a branch takes an unexpected path, open the run in [journey logs
DOC](/docs/monitor/logs#read-a-run) and click the branch node. The step context shows every condition evaluated, the actual values compared, and the path selected.


# Journey cancel node
Source: https://www.courier.com/docs/journeys/nodes/cancel

Stop in-flight runs from inside a journey, or a group of runs sharing a cancellation token.

The Cancel node stops in-flight journey runs from inside a flow. You can also cancel from your own code with the cancel API, so a Cancel node isn't required to stop a run.

Either way, you target runs one of two ways: a single run by its `run_id`, or a group of runs by a shared **cancellation token**. Courier cancels only **active** runs. Canceling is idempotent, so a run that has already finished or errored is left untouched.

To cancel from your own code, call the cancel endpoint with either key. See [invoke a journey
DOC](/docs/journeys/invoke#cancel-a-run) for the request and its response statuses.

## Cancel a group with a cancellation token

A cancellation token is an addressing key you attach to runs. Cancel a whole set by a business identifier, without tracking individual run IDs. How you build the token decides what it covers:

* `order-{{data.order_id}}` cancels the runs for one order
* `user-{{profile.id}}` cancels every run for a user, even across different journeys
* `black-friday-2026` cancels an entire campaign

Set the token in the journey's **settings**. It's templated, so you build it from run data with `{{data.…}}`, `{{profile.…}}`, or `{{recipient}}`. Use a dynamic value so the token maps to the runs you mean, not every run of the journey.

**A token that references a missing variable is dropped, not rejected.** The run is created without one, so a cancel by token won't find it, even though the node looks configured. Cancel it by run ID instead.

Once runs are tagged, cancel the token two ways:

* **From your code**: [cancel by token
  DOC](/docs/journeys/invoke#cancel-a-run). The field is `cancelation_token`, spelled with one L.
* **From a Cancel node**: add a **Cancel** node and set its **Cancelation Token**. When a run reaches the node, Courier cancels every active run sharing that token. This is how one path cancels another: an "invoice paid" branch routes to a Cancel node set to `invoice-{{data.invoice_id}}`, stopping that invoice's remaining reminders.


# Journey delay node
Source: https://www.courier.com/docs/journeys/nodes/delay

Pause a run for a duration or until a timestamp before the next node.

Delay nodes pause the journey before the next node. Use them to space out messages, wait for a user action, or schedule follow-ups.

![](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/delay-config-panel.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=b23f61746b3e6a8d0e72082cf0904e16)

Delay node configuration panel showing interval type, dynamic interval toggle, and time picker

## Configuration

### Interval type

Toggle between two modes:

* **Duration**: Wait a relative period. Set a numeric value and a unit: Minutes, Hours, Days, or Months. The delay is relative to when the run reaches the node, not when the journey was invoked.
* **Until**: Wait until a specific date and time, chosen in a date-time picker. Use it to hold messages until a launch date or a scheduled window.

### Dynamic interval

Enable the **Dynamic Interval** toggle to read the delay from a field in the journey context instead of a hardcoded value. The time picker becomes a field selector for a trigger schema, profile, or fetch response field.

Your application then controls the delay at runtime. A trigger schema field called `follow_up_delay` could hold an ISO 8601 duration like `PT2H` (2 hours), or an `until` field could hold a datetime string.

### Conditions

Delay nodes support optional [conditions
DOC](/docs/journeys/nodes/branch). If they aren't met when the run reaches the delay, the node is skipped.

## Common patterns

**Onboarding sequences**: Send a welcome email immediately, then delay 24 hours before checking whether the user completed setup.

**Reminder chains**: Delay 3 days after an initial notification, then check delivery status or user action before sending a follow-up.

**Scheduled delivery**: Use the "Until" interval type to hold a message until a launch date or event start time.

Pair a delay with a [branch node
DOC](/docs/journeys/nodes/branch) to check whether the user took an action during the wait. Delay 24 hours, then branch on whether the user completed onboarding.

## Run inspection

Open the run in [journey logs
DOC](/docs/monitor/logs#read-a-run) and click a delay node to see its step details:

* the delay length, as an ISO 8601 duration like `P1D`
* `expectedDelayValue`, the exact datetime the delay will release
* the started and completed timestamps

While the pause is active, the status shows "Waiting." Once the delay expires, it transitions to "Processed" and the run continues.

![](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/delay-run-context.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=c138dadb5ced08c43025228ea9bbb862)

Run context for a delay node showing status, delay length, start/completion times, and the expected release datetime


# Journey digest node
Source: https://www.courier.com/docs/journeys/nodes/digest

Add the run's event to a subscription topic's digest, released on the user's schedule.

The Send to Digest node adds the current event to a digest owned by a subscription topic. Events accumulate per user and release on that topic's schedule.

Use it for periodic summaries, a daily activity email or a weekly report, instead of one notification per event.

Use Send to Digest when releases should follow a fixed schedule that the user controls. Use the [Batch node
DOC](/docs/journeys/nodes/batch) to release based on volume or an inactivity window within the journey itself.

## Configuration

| Field | Description |
| - | - |
| **Subscription topic** | Required. The subscription topic that owns the digest the event is added to. Events accumulate per user, identified by `user_id` (or `userId`) in the event data. |
| **Conditions** | Optional. Only add the event to the digest when the conditions evaluate true. |

## Configure the digest on the topic

The schedule, categories, retention, and template mapping live on the subscription topic, not on the node. Configure them in the [Preferences Editor](https://app.courier.com/~/test/platform/preferences) (**Platform → Preferences**):

* **Schedule**: when the digest releases (at least one schedule is required, multiple appear as choices on the hosted preferences page).
* **Categories**: separate types of data within one digest, each with its own retention (First, Last, Highest, or Lowest N, where Highest and Lowest need a sort key).
* **Template mapping**: the notification template that renders the released digest.

The Send to Digest node only collects. Releases happen when the topic's schedule fires.

## Digest payload

When the digest releases, each category is delivered with the total `count` and the retained `items`:

```json theme={null}
{
  "[category_key]": {
    "count": 15,
    "items": [
      { "event": "data", "from": "first_event" },
      { "event": "data", "from": "second_event" }
    ]
  }
}
```

`count` is the total number of events received (it can exceed the retained count). `items` are the retained events. Reference this data in your digest template.

## Via the API

In a journey definition, a Send to Digest node uses `type: "add-to-digest"`:

```json theme={null}
{
  "type": "add-to-digest",
  "subscription_topic_id": "your-topic-id"
}
```

See [Building Journeys via the API
DOC](/docs/journeys/build) for the full node reference.


# Journey fetch data node
Source: https://www.courier.com/docs/journeys/nodes/fetch-data

Call an external HTTP endpoint during a run and merge the response into the context.

Fetch data nodes make HTTP requests to external services during journey execution. Courier merges the response into the journey context, where downstream nodes read it as variables.

Use it to pull real-time data from your application: whether a user completed an action, order details, or any internal API.

## Configuration

The fetch node has two panels: a summary panel (visible when clicking the node on the canvas) and a full HTTP request editor (opened by clicking **Setup Request**).

![](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/fetch-data-config.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=2f618c6cc98b39170d36a1f2aa5d6fb8)

Fetch node summary panel showing HTTP Request, Merge Strategy, and Conditions

### HTTP request editor

Click **Setup Request** to open the full-screen HTTP request editor. The editor has three columns: setup, input, and output.

![](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/fetch-request-editor.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=3f2f0e6555a13dfaf7d012bbb8c8989d)

HTTP request editor with method, URL, toggleable sections for headers/params/body, a cURL preview, and response output

**Setup (left column):**

* **Import cURL**: Paste an existing cURL command to auto-populate the request configuration.
* **Method**: GET, POST, PUT, or DELETE.
* **URL**: The endpoint to call. Supports [variables](#variables) (e.g., `https://api.example.com/users/{{recipient}}`). Only HTTPS URLs are allowed, and `localhost` is rejected.
* **Headers**: Toggle on to add key-value header pairs. Common use: `Authorization: Bearer {{data.api_token}}`.
* **Query Parameters**: Toggle on to add key-value query parameters appended to the URL.
* **Body**: Toggle on to add a JSON request body (available for POST and PUT only, disabled for GET and DELETE).

**Input (center column):**

If your URL or body contains variables like `{{recipient}}`, this column shows fields for test values. A live cURL preview updates as you fill them in.

**Output (right column):**

Click **Execute Step** to run the request and see the response. On a successful 2xx response, Courier extracts the response schema and saves the available fields. The summary panel then lists those field names and types, so you can confirm what data is available downstream. A "Last tested" timestamp shows when the schema was last captured.

### Variables

The URL, headers, query parameters, and body can each use `{{...}}` variables. Every variable starts with one of these roots:

| Variable | Resolves to |
| :- | :- |
| `{{data.<path>}}` | A field from the trigger payload, or from an upstream fetch or AI node |
| `{{profile.<path>}}` | A field from the recipient's profile |
| `{{tenant.<path>}}` | A field from the run's tenant, when the trigger sets one |
| `{{recipient}}` | The recipient's user ID |

Spaces inside the braces don't matter: `{{ data.user_id }}` resolves the same as `{{data.user_id}}`.

**Write the root on every variable.** `{{user_id}}` doesn't resolve to `data.user_id`. Creating or replacing a journey through the API fails on it with `Variable {{user_id}} won't resolve. Use data., profile., tenant., or recipient.` The API also rejects a URL that starts with a literal host and isn't HTTPS on a public host, with `URL must be https on a public host`.

#### A variable with no value

A variable has no value when its path is missing, `null`, or an empty string in the run. What happens depends on where it sits:

| Where | What happens |
| :- | :- |
| URL, headers, or query parameters | The fetch fails with `Variable {{data.user_id}} has no value in this run`, and the run stops. A request to the wrong URL is worse than no request. |
| Body, as the whole value (`"user_id": "{{data.user_id}}"`) | The value is sent as JSON `null`. |
| Body, inside a longer string (`"note": "Hi {{data.name}}"`) | The variable is removed, so the value is sent as `"Hi "`. In a key, the key keeps its quotes. |

### Merge strategy

The merge strategy controls how the fetch response is combined with the existing journey context. Choose from the dropdown on the summary panel:

| Strategy | Behavior |
| - | - |
| **Soft Merge** (default) | Adds new fields from the response without overwriting existing values. Existing context fields are preserved. |
| **Overwrite** | Deep-merges the response into the context. Response values overwrite existing fields with the same key. |
| **Replace** | Replaces the entire context with the response. Existing fields not in the response are removed. |
| **None** | Doesn't merge. If context already exists, it's left untouched. If empty, uses the response. |

**Soft Merge is the safest default.** Trigger schema fields and profile data are never overwritten by a fetch response.

### Conditions

Fetch nodes support optional [conditions
DOC](/docs/journeys/nodes/branch). If they aren't met, the node is skipped and the journey continues without making the HTTP request.

## Response handling

The response body is parsed as JSON and merged into the journey context using the selected merge strategy. If the fetch returns:

```json theme={null}
{
  "onboarding_complete": true,
  "last_login": "2026-02-09T10:30:00Z"
}
```

These fields become part of the journey's data context. Downstream nodes reference them the same way they reference trigger schema fields:

* In [branch conditions
  DOC](/docs/journeys/nodes/branch): select `data.onboarding_complete` as the field
* In [journey templates
  DOC](/docs/journeys/build): use `{{onboarding_complete}}` or `{{last_login}}`
* In [send node
  DOC](/docs/journeys/nodes/send) recipient overrides: select the field from the dropdown

## When a fetch fails

**A failed fetch stops the run.** The step and the run both end in `error`, and no node after the fetch runs. The step's error message names the cause. `<METHOD>` is the uppercase HTTP method and `<host>` is the URL's host and port. The path and query string are never shown, so a token in the URL stays out of the logs.

| Message | Cause |
| :- | :- |
| `Fetch failed: <METHOD> <host> returned <status>` | The endpoint answered with a status outside the 2xx and 3xx ranges |
| `Fetch failed: <METHOD> <host> redirects are not followed` | The endpoint answered with a 3xx redirect. Point the URL at the final address. |
| `Fetch failed: <METHOD> <host> timed out after 10s` | No response within 10 seconds |
| `Fetch failed: <METHOD> <host> response exceeded 1 MB` | The response body was larger than 1 MB. The request body has the same limit. |
| `Fetch failed: <METHOD> <host> request failed (<code>)` | No response at all, such as `ENOTFOUND` for a host that doesn't resolve |
| `Fetch failed: invalid URL after variables resolved` | The URL wasn't an HTTPS URL on a public host once its variables were filled in |
| `Variable {{<path>}} has no value in this run` | A variable in the URL, headers, or query parameters had no value |

Read the message on the fetch step in [journey logs
DOC](/docs/monitor/logs#read-a-run), or in the step's `error.message` from [List steps for a Journey run](/docs/api-reference/journeys/list-steps-for-a-journey-run).

## Chaining fetch nodes

Fetch nodes can run in sequence. Each one merges its response into the journey context, and all fields are available downstream. For example:

1. **Fetch order details**: merges `order_id`, `total`, `status` into context
2. **Fetch user preferences**: merges `email_frequency`, `locale` into context
3. **Branch**: check `email_frequency` to decide whether to send


# Journey send node
Source: https://www.courier.com/docs/journeys/nodes/send

Send a message on one channel with a journey template, conditions, overrides, and a send window.

Send nodes deliver a message on one channel (email, SMS, push, etc.). Each links to a [journey template
DOC](/docs/journeys/build) that defines the content.

A journey can hold multiple send nodes, each with its own channel, conditions, recipient overrides, and delivery timing.

## Adding a send node

Drag a **Send** node from the palette onto the canvas, or drop it onto an edge between two nodes. Then choose the channel.

### Supported channels

| Channel | Description |
| - | - |
| **Email** | Messages delivered to the recipient's email address |
| **SMS** | Text messages via configured SMS provider |
| **Push** | Mobile or web push notifications |
| **In-app / Inbox** | Messages delivered to Courier's [Inbox&#xA;DOC](/docs/in-app/overview) component |
| **Slack** | Direct messages or channel posts in a connected [Slack&#xA;DOC](/docs/integrations/direct-message/slack) workspace |
| **Microsoft Teams** | Direct messages or channel posts in a connected [Microsoft Teams&#xA;DOC](/docs/integrations/direct-message/microsoft-teams) tenant |

![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/send-node-config.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=cc992b3b650d6bde0ac2637f5f48f957)

Send node configuration panel with an email channel selected and a linked message template

## A/B test with an experiment

A send node can run an **experiment** to A/B test versions of a message. The node holds 2 to 10 **variants**, each linked to its own [journey template
DOC](/docs/journeys/build). Courier splits traffic across them by weight.

Each recipient is assigned one variant deterministically and stays in it across sends. You compare delivery and engagement per variant, then promote one. A send node uses either a single template or an experiment, not both.

For traffic allocation, bucketing keys, stickiness, results, and promotion, see [Experiments
DOC](/docs/journeys/experiments).

## Recipient override

By default, a send node delivers to the user who entered the journey, identified by the `user_id` or `profile` from the [invocation
DOC](/docs/journeys/invoke).

To send to a different recipient, click **Add** next to "Recipient Override" in the node's configuration panel. In the single field that opens, either:

* **Select a field reference** from the dropdown. It lists fields from the trigger schema, profile, and upstream fetch node responses. At runtime, that field's value becomes the recipient address.
* **Type a hardcoded value** (e.g., `ops@yourcompany.com` or `+15551234567`). Type your value and click away to commit it.

The field Courier writes to depends on the channel:

| Channel | Recipient field |
| - | - |
| Email | `email` |
| SMS | `phone_number` |
| Push / Inbox | `email` (user lookup) |
| Slack | **Channel**: channel ID. **Direct message**: user ID or email |
| Microsoft Teams | **Channel**: channel ID, or channel name with team ID. **Direct message**: user ID or email |

Click **Remove** to revert to the default recipient.

Slack and Microsoft Teams have no journey user to fall back on, so you always set their fields on the node. Neither offers a recipient override.

![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/recipient-override-dropdown.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=e70928dc71454383e266e68b022cade0)

Recipient override with the dropdown showing available schema and profile fields

Add a schema field like `manager_email` to your API trigger, then select it as the recipient override on a send node. Your application then controls who receives that notification without changing the journey.

## Slack recipients

A Slack send node needs a destination and an **Access Token** for the workspace it posts into.

Set the destination with **Send to**:

* **Channel** posts to a Slack channel. Enter the channel ID, like `C012AB3CD`. Courier doesn't list your channels, so bring the ID from Slack.
* **Direct message** goes to one person, addressed by **User ID** (like `U01AB2CD3EF`) or **Email**.

Then set **Access Token** to the bot token (`xoxb-...`) for that workspace. Point it at `profile.slack.access_token` or a tenant property so each send picks up the right one.

These map onto the fields the Send API uses:

| Send to | `to.slack` field |
| - | - |
| Channel | `channel` |
| Direct message | `user_id` **or** `email` |
| Every send | `access_token` |

For message content, Block Kit layouts, threading, and provider overrides, see the [Slack integration
DOC](/docs/integrations/direct-message/slack).

## Microsoft Teams recipients

A Teams send node needs a destination, a **Service URL**, and sometimes a **Microsoft tenant ID**.

Set the destination with **Send to**:

* **Channel** posts to a Teams channel. Under **Identify channel by**, choose **Channel ID**, or **Channel Name** plus the **Team ID** that channel belongs to.
* **Direct message** goes to one person. Under **Identify user by**, choose **User ID** or **Email**.

The **Service URL** is regional, like `https://smba.trafficmanager.net/amer`. **Microsoft tenant ID** is needed when you address a direct message by user ID or email, or a channel by channel name.

These map onto the fields the Send API uses:

| Send to | `to.ms_teams` field |
| - | - |
| Channel | `channel_id`, **or** `channel_name` with `team_id` |
| Direct message | `user_id` **or** `email` |
| Every send | `service_url`, plus `tenant_id` when addressing by user ID, email, or channel name |

For adaptive cards, thread replies, and provider overrides, see the [Microsoft Teams integration
DOC](/docs/integrations/direct-message/microsoft-teams).

## Conditions

A send node can carry conditions, evaluated at runtime. If they aren't met, the node is skipped and the journey continues to the next step.

Conditions use the same operators and field references as [branch nodes
DOC](/docs/journeys/nodes/branch). Common patterns:

* Skip a push notification if `profile.push_tokens` is empty
* Only send an email if `data.notification_preference` equals `"email"`
* Send only when a fetch node response indicates the user hasn't completed an action

## Send window

A send window controls when a message is delivered. If the run reaches a send node outside the window, delivery is held until the window opens.

Use it to respect business hours, avoid late-night messages, or batch sends into a time range.

![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/send-window-config.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=014997c2dd7ff2bdf3b8faabaeb0985e)

Send window configuration with per-day time ranges and timezone selection

Enable a send window in the send node's settings:

* **Day-by-day schedule**: Each day of the week has its own row with an opening and closing time (e.g., Mon through Fri, 9:00 AM to 5:00 PM). A day with no time range is blocked entirely.
* **Timezone**: Choose **User's** timezone (resolved from the recipient's profile) or **UTC**. If the recipient has no timezone set, messages are sent in UTC.

## Provider resolution

Courier picks the provider from your workspace's configured integrations. A send node never specifies one.

For example, if your workspace has SendGrid configured for email, an email send node routes through SendGrid with no configuration on the node.

With multiple providers on the same channel, Courier follows your [routing rules
DOC](/docs/send/routing#channel-priority).


# Journey throttle node
Source: https://www.courier.com/docs/journeys/nodes/throttle

Limit how often a user, or everyone, passes a point in the journey within a time window.

Throttle nodes limit how many times a user, or everyone, can pass through a specific point in the journey within a time period. Use them to prevent notification fatigue and enforce rate limits.

![](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/throttle-config.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=4adc0fa206987dbf7738c257a4970e30)

Throttle configuration panel with max allowed, period, and scope settings

## Configuration

| Field | Description |
| - | - |
| **Max allowed** | The maximum number of times a recipient can pass through this throttle within the period |
| **Period** | The time window for the limit (e.g., 1 hour, 24 hours, 7 days) |
| **Scope** | What the limit applies to: **per user** (keyed by user ID) or **global** (across all users) |

When a run hits a throttled node and the limit is reached, Courier skips the node and continues the run to the next node without sending that message.

## Example

Set "max 3 per 24 hours, per user" and the journey can be invoked 10 times that day. Only the first 3 send nodes downstream of the throttle fire.

## Global throttle

Set the scope to **Global** instead of **Per user** to apply a single limit across all users. Use it to cap the total volume of a notification type, whoever receives it.

A global throttle of "max 1000 per hour" on a promotional journey keeps a marketing event from flooding your email provider with thousands of invocations.

## Combining with other nodes

Throttle nodes combine with other logic:

* **Throttle + [Branch
  DOC](/docs/journeys/nodes/branch)**: Throttle first, then branch on priority. Only messages that pass the throttle are evaluated.
* **Throttle + [Delay
  DOC](/docs/journeys/nodes/delay)**: Place the throttle before a delay to prevent too many delayed messages from queuing up.


# Journeys
Source: https://www.courier.com/docs/journeys/overview

Multi-step flows that run once per user when triggered, with sends, delays, and branches.

A journey is a graph of nodes that runs once per user when triggered.

![An onboarding journey on the canvas: an API Invoke trigger, a welcome email, a two-day delay, an AI node, then a branch whose two paths send and rejoin at Exit](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/journey-onboarding-canvas.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=6a6f39c793bb144d382a54d954d65cd1)

You build it visually, publish it, and invoke it from your app or a Segment event. Courier runs the nodes in order, taking branches, waiting on delays, and sending messages until the run ends.

A journey combines the other pieces: a trigger that starts it, [nodes
DOC](/docs/journeys/nodes) that decide what happens between sends, and content written the way a [Template
DOC](/docs/design/templates/overview) is written. Each recipient is a [user
DOC](/docs/recipients/overview) whose profile the run reads once at invoke.

## Which one to use

Most notifications don't need a journey, and the difference is whether the messaging spans steps and time.

| | Send API | Journeys |
| - | - | - |
| Shape | Single call | Multi-step workflow |
| Timing | Immediate (or a delay parameter) | Built-in delays and scheduling |
| Logic | In your code | Built-in branching |
| Debugging | Message logs | Step-by-step run inspection |
| Best for | Transactional messages | Complex messaging experiences |

Use the [Send API
DOC](/docs/send/overview) when one call can say everything. Use a journey when the messaging unfolds over time, with branching, enrichment, or rate limiting between steps.

## How it works

### Trigger, then nodes

Every journey starts with a **trigger** that decides how users enter it:

* **API**: your code calls the invoke endpoint.
* **Segment**: Courier starts the journey when a matching event arrives.

Nodes then run in sequence: `send`, `delay`, `branch`, `fetch` (pull external data), `throttle`, `batch`, `add-to-digest`, and `exit`. A branch splits the flow into conditional paths. The run continues until every path reaches an end.

### A run works from a snapshot of its data

On invoke, Courier loads the recipient's profile once and stores the run's `{ data, profile }` as a snapshot. Every node reads from that snapshot. Editing a user's stored profile or an audience **after** the run starts doesn't re-evaluate the run or update its data. Only in-journey nodes change a run's context mid-flight: a `fetch` node that pulls new data, or an update-profile step. Both merge into the stored context. Branch on data you pass at invoke or fetch during the run, not on edits made elsewhere.

### Delays

A `delay` node waits before continuing, in two modes:

* **Duration** (relative): wait a span, like 3 days.
* **Until** (absolute): wait for a timestamp, which can come from your data, like an `appointment_time` field.

A single delay can wait up to **93 days**. Courier rejects a longer delay. Chain delays for a longer total gap.

### Idempotency

Invoking is safe to retry. Send an `Idempotency-Key` header on the invoke request. For a repeated key, Courier returns the stored result instead of starting a second run, so a network retry doesn't double-send. Without the key, each invoke starts a new run.

### Canceling a run

To stop runs, cancel them. The cancel endpoint takes either a `cancelation_token` (set in the journey's settings and stamped on each run as it starts, cancels every run sharing it) or a single `run_id`. Only active runs are affected. A run that already finished, errored, or was canceled is left as-is. A journey can also cancel itself with an in-journey cancel node. See [Invoke a Journey
DOC](/docs/journeys/invoke).

## Journey Templates

A send node's content is a **Journey Template**: created inline in the send node, scoped to that Journey, and versioned with it. They are separate from the workspace [Templates
DOC](/docs/design/templates/overview) used with the Send API. You can't reference one from a regular send, or import an existing Template into a Journey.

Journey Templates reference the Journey's data with double-brace syntax:

* `{{order_id}}` for a trigger schema field
* `{{first_name}}` for a Profile field
* a field from an upstream fetch node

Publishing the Journey doesn't publish its Templates. A run sends each Template's published version, so publish each Template, then publish the Journey. Editing a Template after publishing creates a new draft that needs its own publish to take effect.

## FAQ

> **What is the difference between Journeys and Automations?**
>
> Journeys is the current v3 surface (visual editor, data contracts, run inspection) on the same engine as the older Automations product. Automations are superseded. Build new workflows as journeys.


# Template, journey, and broadcast analytics
Source: https://www.courier.com/docs/monitor/analytics

See how many messages were sent, delivered, opened, and clicked for each template, journey, and broadcast, and how those rates change over time.

Analytics show how your messages are doing: how many were sent, delivered, opened, and clicked, for each template, journey, and broadcast. To look up a single message, use [Logs
DOC](/docs/monitor/logs).

## What the numbers count

Every analytics view uses the same metrics:

| Metric | What it counts |
| :- | :- |
| **Sent** | Courier handed the message to the provider. |
| **Delivered** | The provider confirmed the message landed. |
| **Opened** | The recipient opened the message, recorded by Courier's tracking pixel. |
| **Clicked** | The recipient clicked a tracked link, recorded by Courier's redirect. |
| **Errors** | A provider attempt failed. A message that failed over to a second provider counts here and still counts as delivered. |
| **Undeliverable** | The provider rejected the message or couldn't deliver it. The message never landed. |

Opened and Clicked only fill in on channels Courier can track, so a `0` in Opened on SMS means "not measured", not "nobody read it". [Tracking
DOC](/docs/monitor/tracking) lists what each channel reports.

### Set up delivery tracking

Delivered comes from your provider, not from Courier. Each provider reports delivery once you set it up, and until then its messages stay at `SENT`. How you set it up depends on the provider:

| Provider reports by | What you do | Providers |
| :- | :- | :- |
| **Webhook** | Paste Courier's webhook URL into the provider's settings. | [SendGrid&#xA;DOC](/docs/integrations/email/sendgrid#delivery-tracking), [Amazon SES&#xA;DOC](/docs/integrations/email/aws-ses#delivery-tracking), [Mailgun&#xA;DOC](/docs/integrations/email/mailgun), [Resend&#xA;DOC](/docs/integrations/email/resend), [Sinch Engage&#xA;DOC](/docs/integrations/sms/sinch-engage) |
| **Polling** | Turn on delivery tracking in the provider's integration settings in Courier. | SendGrid, Mailgun, [Twilio&#xA;DOC](/docs/integrations/sms/twilio), [Postmark&#xA;DOC](/docs/integrations/email/postmark), [Mandrill&#xA;DOC](/docs/integrations/email/mandrill), [Plivo&#xA;DOC](/docs/integrations/sms/plivo) |
| **Your app** | Use a Courier mobile SDK, or `POST` to the `trackingUrl` in the push payload. | [APNs, FCM, Expo, and OneSignal&#xA;DOC](/docs/integrations/push/overview#tracking) |

Slack, Microsoft Teams, and other chat providers confirm delivery when they accept the message, so they need no setup. Messages sent after you turn tracking on start filling in the Delivered column. [Message statuses
DOC](/docs/send/statuses#delivery-tracking-is-per-provider) has the full provider list.

## Templates

The [Analytics](https://app.courier.com/analytics) page shows the whole workspace:

* **Send volume**: messages sent over time.
* **Template performance**: sends and error rates for each template.

![The Analytics page, with send volume above the template performance table](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/analytics-tab.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=6041f120aac19bd1cd447c0633d1958d)

One dropdown sets the time range for both: Last 7 days, Last 30 days, Last 90 days, or **Custom range**. A custom range reaches back to January 1 of last year, which is as far as the analytics store goes.

Select a template to see its numbers split by channel and provider. Use it to compare channels for one notification, or to spot a provider with an unusually high error rate.

![One template's metrics, split by channel and provider](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/template-analytics.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=0e66e41fdb01aabdc4105e1e79657233)

## Journeys

Open a journey and select its **Metrics** tab, next to Editor and Logs. Choose Last 7 days, Last 30 days, or Last 90 days to change the chart and the table together.

![A journey's Metrics tab, with the send volume chart above the template table](https://mintcdn.com/courier-4f1f25dc/66t_J9wvizdshWJp/assets/monitor/journey-metrics.png?fit=max\&auto=format\&n=66t_J9wvizdshWJp\&q=85\&s=8c811404baf087d9ef11953cdaef6aa4)

* **Total sent**: a stacked bar chart with one bar per day and one color per journey template, so you can see which send node carries the volume.
* **Template table**: one row per template in the journey.

| Column | What it shows |
| :- | :- |
| **Template** | The journey template, named as it is on the send node |
| **Type** | The channel: email, SMS, push, and so on |
| **Sent** | Messages sent in the time range |
| **Delivered** | Delivered as a percentage of sent, excluding errors |
| **Opened** | Opened as a percentage of sent |
| **Clicked** | Clicked as a percentage of sent |

A column shows `--` when there isn't enough data yet.

Select a row to open that template's detail panel. It has five charts (total sent, delivery rate, open rate, click rate, and error rate), a table of the same numbers per provider, and its own time range.

Templates removed in a later version of the journey stay in the table with an **Inactive** prefix, so their history doesn't disappear.

For a journey with an A/B test, per-variant results are on the experiment's **Results** tab. See [Journey experiments
DOC](/docs/journeys/experiments).

## Broadcasts

Every sent broadcast has a **Performance** tab.

![A broadcast's Performance tab, with aggregate rates above the per-recipient log](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/broadcast-performance.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=de242699501487e48013e642be593f69)

The top of the tab summarizes the whole send:

| Metric | What it shows |
| :- | :- |
| **Total sent** | Messages sent |
| **Delivery rate** | The percentage delivered |
| **Open rate** | The percentage opened |
| **Click rate** | The percentage clicked |
| **Error rate** | The percentage that errored |

Below it, the per-recipient log lists every recipient with a timestamp and status. Filter by All, Delivered, Opened, Clicked, or Errors, or search for one recipient. Select **View in logs** on a row to open that message in [Logs
DOC](/docs/monitor/logs).

To send something similar again, open a past broadcast and select **Duplicate broadcast**. Courier copies its content and setup into a new draft.

## Get the numbers by API

The [Metrics API
DOC](/docs/monitor/template-metrics) returns one template's numbers as a time series, split by provider and channel, so you can chart them in your own dashboard or alert on them.

## Limits & behavior

* **Time ranges are in UTC.** "Last 7 days" covers 7 UTC days, which can differ from your local reporting day.
* **Analytics are per environment.** A message sent with a Test key appears only in Test.
* **Messages without a template don't appear** in template analytics. A message sent with inline content has no template to count it under.
* **There's no roll-up by tenant, list, or audience.** Template analytics are per template, and broadcast analytics are per broadcast.
* **Numbers start with the first send.** A draft or scheduled broadcast has no Performance data.

## FAQ

> **Why is my delivery rate lower than expected?**
>
> Delivery rate counts messages a provider confirmed. Most providers need delivery tracking set up first, and some never confirm, so messages sit at `SENT`. [Set up delivery tracking
> DOC](#set-up-delivery-tracking) for each provider you send with.

> **Why is my open rate lower or higher than expected?**
>
> Open tracking depends on a pixel that some email clients block and some security scanners load automatically. Read open rates as a trend across sends. [Tracking
> DOC](/docs/monitor/tracking) covers why.

> **Why don't my Test messages show up?**
>
> Analytics are scoped to the environment of the key that sent the message. Switch the dashboard to the Test environment.

> **Can I pull these numbers into my own dashboard?**
>
> The [Metrics API
> DOC](/docs/monitor/template-metrics) returns a template's numbers as a time series. For a workspace-wide view, list your templates and call it for each one.


# Message and journey logs
Source: https://www.courier.com/docs/monitor/logs

Every message and journey run in one place: status, timeline, content sent, and why it failed.

Logs show what happened to every message: who got it, which provider carried it, what it said, and whether it was delivered, opened, or clicked. Journey logs do the same for each step of a run.

Search them in the Courier dashboard, no code needed, or fetch the same records [over the API or MCP](#read-logs-over-the-api-or-mcp).

| You want to know | Look at |
| :- | :- |
| Whether a message was delivered | The message's status in [Message logs](#message-logs) |
| Why a message failed | The **Error Encountered** event in [its timeline](#read-a-message) |
| Exactly what the recipient received | [The rendered content](#see-the-rendered-content) |
| What a journey did for one user | [Journey logs](#journey-logs) |
| Why a journey took the wrong branch | [The step context](#read-a-run) on the branch node |
| Any of the above in your own code or AI agent | [The API or MCP](#read-logs-over-the-api-or-mcp) |

## Message logs

[Logs](https://app.courier.com/logs) lists every message in the current environment, newest first. Each row shows the message's status, template, recipient, and the channels it went out on.

![The message logs list](https://mintcdn.com/courier-4f1f25dc/66t_J9wvizdshWJp/assets/monitor/logs-list.png?fit=max\&auto=format\&n=66t_J9wvizdshWJp\&q=85\&s=ddad3817aaccdb992d3bd84d028c2379)

### Find a message or a recipient

The histogram at the top shows message volume per day, colored by status. Drag across it to filter the list to that date range.

![The logs histogram, with daily message volume colored by status](https://mintcdn.com/courier-4f1f25dc/66t_J9wvizdshWJp/assets/monitor/logs-histogram.png?fit=max\&auto=format\&n=66t_J9wvizdshWJp\&q=85\&s=86a0423398065166fd2b8dbdd199be54)

Filter the list by any combination of:

| Filter | Matches |
| :- | :- |
| **Date** | A date range inside your log retention window |
| **Recipient** | An email address or a user ID |
| **Notification** | One template |
| **Status** | One or more of Queued, Sent, Delivered, Opened, Clicked, Undeliverable, and Unmapped |
| **Errors** | Messages with an error anywhere in their timeline |
| **Provider** | One or more of your connected providers |

The `requestId` the Send API returns is the message ID. It's the same ID the [Get message](/docs/api-reference/messages/get-message) endpoint and [outbound webhooks
DOC](/docs/monitor/webhooks/outbound) use.

### Read a message

Select a message to open its detail view:

* **Summary**: the message ID, the recipient ID, and a timestamp for each stage, such as enqueued, sent, and first delivery.
* **Timeline**: every event in the message's life, in order. Select an event to see its details, including the provider's raw response.

![A message's detail view, with the summary above the timeline of events](https://mintcdn.com/courier-4f1f25dc/66t_J9wvizdshWJp/assets/monitor/logs-detail.png?fit=max\&auto=format\&n=66t_J9wvizdshWJp\&q=85\&s=e54d1cbf46d24509fbaa3ce7f5be7a21)

When a message fails, the timeline has an **Error Encountered** event. Select it to read the error.

![The Error Encountered event open in the timeline, showing the error message](https://mintcdn.com/courier-4f1f25dc/66t_J9wvizdshWJp/assets/monitor/logs-error.png?fit=max\&auto=format\&n=66t_J9wvizdshWJp\&q=85\&s=ba44745a5edffdd349def820cfedcb42)

A message's status only moves forward. `DELIVERED` comes from your provider, and `OPENED` and `CLICKED` come from Courier's own tracking, so a message can show an open before its delivery is confirmed. [Message statuses and errors
DOC](/docs/send/statuses) lists every status, and [Tracking
DOC](/docs/monitor/tracking) explains which channels report opens and clicks.

### See the rendered content

Teammates with Full log access see the rendered message in the dashboard. To get it in code, call [Get message content](/docs/api-reference/messages/get-message-content). It returns what the recipient received, per channel: the subject, HTML, and text body for email, and the message text for SMS and push.

```bash theme={null}
curl https://api.courier.com/messages/1-612fa552-15f7d6ba51bf229857c037a7/output \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

## Journey logs

Every time a journey is invoked, Courier records a run: the full trace of that journey for that user, identified by the `runId` the invoke call returns.

Open a journey and select its **Logs** tab to see its runs. To see runs across every journey, open the Journeys logs page, which adds a template ID column. Over the API, [List Journey runs](/docs/api-reference/journeys/list-journey-runs) lists runs and [List steps for a Journey run](/docs/api-reference/journeys/list-steps-for-a-journey-run) returns each step a run took.

![A journey's Logs tab listing its runs](https://mintcdn.com/courier-4f1f25dc/66t_J9wvizdshWJp/assets/monitor/journey-run-list.png?fit=max\&auto=format\&n=66t_J9wvizdshWJp\&q=85\&s=850ae3e7bba54212122749ab566ac71b)

### Find a run

Search by run ID or template ID, or filter by status, date range, or recipient. A run has one of these statuses:

| Status | Meaning |
| :- | :- |
| **Processing** | The run is executing. |
| **Waiting** | The run is paused on a delay or throttle node. |
| **Processed** | Every node finished. |
| **Error** | A node failed. |
| **Canceled** | The run was stopped before it finished. See [Cancel a run&#xA;DOC](/docs/journeys/invoke#cancel-a-run). |

### Read a run

Select a run to see it on the journey canvas, with each node marked by what happened to it. The view shows which nodes ran and in what order, which path each branch took, where a waiting run is paused, and which node failed.

![A run shown on the journey canvas, with the outcome marked on each node](https://mintcdn.com/courier-4f1f25dc/66t_J9wvizdshWJp/assets/monitor/journey-run-detail.png?fit=max\&auto=format\&n=66t_J9wvizdshWJp\&q=85\&s=c1dc11889e6769b0da6862fc61d8c524)

Select a node to see its step context:

| Field | What it shows |
| :- | :- |
| **Input data** | The data the node received |
| **Profile data** | The user's profile at that step |
| **Conditions evaluated** | Each condition on a branch or conditional node, and whether it passed |
| **Output** | The response for a fetch data node, or the delivery status for a send node |

Step context answers most "why" questions. If a branch took the wrong path, the conditions show the value it compared, such as `data.plan` being `free` instead of `pro`. If a send failed, the profile shows the missing field, such as an empty `email`.

![The step context for one node, showing its input data, profile, and output](https://mintcdn.com/courier-4f1f25dc/66t_J9wvizdshWJp/assets/monitor/journey-step-context.png?fit=max\&auto=format\&n=66t_J9wvizdshWJp\&q=85\&s=72cc91e5861dff8fd0922021ab6f6910)

Over the API, every step that [List steps for a Journey run](/docs/api-reference/journeys/list-steps-for-a-journey-run) returns carries the same reason. `error.message` is set on a failed step, such as `Fetch failed: GET api.example.com returned 404`. `skip_reason` is set on a skipped step, such as `Node conditions not met`. Both are `null` otherwise.

A run always shows the journey version it started on, even after you publish changes, so you see what that user went through.

## Read logs over the API or MCP

Everything in the Logs page is available over the API, for support tools, scripts, and AI agents:

| To get | Call |
| :- | :- |
| Messages, filtered by recipient, template, status, provider, or tag | [List messages](/docs/api-reference/messages/list-messages) |
| One message's status and delivery timestamps | [Get message](/docs/api-reference/messages/get-message) |
| Every status change, in order | [Get message history](/docs/api-reference/messages/get-message-history) |
| The content the recipient received | [Get message content](/docs/api-reference/messages/get-message-content) |
| Journey runs | [List Journey runs](/docs/api-reference/journeys/list-journey-runs) |
| Each step a journey run took | [List steps for a Journey run](/docs/api-reference/journeys/list-steps-for-a-journey-run) |

With the [Courier MCP server
DOC](/docs/resources/mcp) connected, your AI agent can look up messages for you. Ask it something like "why didn't Sarah Bennett get her receipt?" and it uses the `list_messages`, `get_message`, `get_message_history`, and `get_message_content` tools to find the message and read its timeline.

## Other logs

* **Broadcasts**: each recipient gets their own entry in message logs. The per-recipient view for one broadcast is in [Analytics
  DOC](/docs/monitor/analytics#broadcasts).
* **Preference changes**: open a user in [Users](https://app.courier.com/users) and select their preference log to see when they opted in or out of each topic. Over the API, [List preference changes](/docs/api-reference/preference-topics/list-preference-changes) returns the change history for one user or the whole environment.
* **Automations**: runs for the previous workflow product are covered in [Automations (Legacy)
  DOC](/docs/journeys/automations/debugger).
* **Workspace changes**: who changed which setting, and when, is in the [audit trail
  DOC](/docs/workspaces/audit-trail).

## Troubleshoot a message

If a message shows `SENT` and the recipient doesn't have it:

1. Open the `SENT` event in the timeline and read the provider's response.
2. Look the message up in your provider's own activity log, such as SendGrid Activity or the SES console, for a bounce, block, or deferral.
3. Check SPF, DKIM, and DMARC on your sending domain.

If a message shows `DELIVERED` and the recipient still doesn't have it, the recipient's mail server accepted it. A spam filter or security gateway on their side is the usual cause.

[Debug email delivery
DOC](/docs/guides/debug-delivery) walks through each case.

## Limits & behavior

* **`SENT` is not a failure.** Courier handed the message to the provider and hasn't heard back, which usually means delivery tracking isn't set up for that provider. [Set up delivery tracking
  DOC](/docs/monitor/analytics#set-up-delivery-tracking) to get `DELIVERED`.
* **Logs are per environment.** Test messages appear only in Test logs.
* **Retention depends on your plan.** Developer and Business keep 30 days of message history. Enterprise keeps 365 days. Searches and reads are clipped to that window, so export anything you need to keep longer. A message's own event history is capped at roughly 93 days on every plan, so an older message still lists but returns no timeline.

## FAQ

> **How do I check whether a notification was delivered?**
>
> Search Courier's message logs for the recipient's email address or user ID and open the message. `DELIVERED` means the provider confirmed it, and `SENT` means Courier is still waiting to hear back.

> **Can I see the exact email a user received?**
>
> The dashboard shows the rendered message to teammates with Full log access. Over the API, [Get message content](/docs/api-reference/messages/get-message-content) returns the content per channel, including the subject and HTML for email.

> **How long does Courier keep message logs?**
>
> Developer and Business keep 30 days of message history, and Enterprise keeps 365 days. A message's own event history is capped at roughly 93 days on every plan.

> **Do I need to be a developer to use Courier logs?**
>
> Logs are in the Courier dashboard, and anyone on the workspace can search them by recipient, template, or status without writing code. On Enterprise, roles set how much detail they see: Level 1 shows a summary, Level 2 adds status detail and the request data, and Full also shows the rendered message. See [Team access, roles, and SSO
> DOC](/docs/workspaces/team-access).

> **How do I match a log entry to my API call?**
>
> The `requestId` in your Send API response is the message ID. Fetch the message with it through the Messages API, or match it to `message:updated` webhook events.

> **Why does a message show OPENED before DELIVERED?**
>
> Courier records opens and clicks the moment they happen. `DELIVERED` waits for the provider's confirmation, which can take minutes or never arrive.

> **How do I find a journey run from my code?**
>
> The invoke call returns a `runId`. Search for it in the journey's Logs tab.

> **Why does an old journey run look different from my current journey?**
>
> A run shows the version that was published when it started, not your latest draft.


# Observability
Source: https://www.courier.com/docs/monitor/observability

Send Courier delivery metrics and logs to Datadog, New Relic, or any OpenTelemetry endpoint.

Courier sends its delivery metrics and logs to the monitoring tool you already use. Notification failures show up next to the rest of your telemetry.

> [!NOTE]
>
> Observability integrations require the **Enterprise** plan. See [Courier pricing](https://www.courier.com/pricing).

## Choose a destination

> **[Datadog](/docs/integrations/observability/datadog)**
>
> API key and site. Includes a ready-made dashboard.

> **[New Relic](/docs/integrations/observability/new-relic)**
>
> License key, with optional metrics and logs endpoints.

> **[OpenTelemetry](/docs/integrations/observability/open-telemetry)**
>
> Any OTLP endpoint, with basic auth or a bearer token.

## Observability or webhooks

| Use | When |
| :- | :- |
| **Observability** | You want charts, dashboards, and alerts on Courier's health, such as delivery rate by channel or undeliverable spikes. |
| **[Outbound webhooks&#xA;DOC](/docs/monitor/webhooks/outbound)** | Your own code needs to act on each event, such as updating an order when its receipt is delivered. |

## What Courier sends

Courier aggregates metrics over a 10-second window and sends them as messages are sent, delivered, or marked undeliverable. Logs go to the same destination in near real time.

Metrics and logs are tagged with your Courier `environment`, `production` or `test`, so you can filter by it.

### Metrics

| Group | Metrics |
| :- | :- |
| **Messages** | `courier.message.received`, `.sent`, `.delivered`, `.filtered`, `.throttled`, `.unmapped`, `.unroutable`, `.undeliverable`, `.unique.sent`, `.unique.opened`, `.unique.clicked`, `.total.opened`, `.total.clicked` |
| **Channels** | `courier.[channel].sent`, `.delivered`, `.error`, `.undeliverable`, where `[channel]` is `email`, `sms`, `push`, `inbox`, `direct_message`, `webhook`, or `banner` |
| **Users** | `courier.user.created`, `.updated`, `.deleted` |
| **Accounts** | `courier.account.created`, `.updated`, `.deleted`, `courier.account.user.added`, `.removed` |
| **Lists** | `courier.list.subscribed`, `.unsubscribed`, `.subscribe.failed` |
| **Audiences** | `courier.audience.matched`, `.unmatched` |
| **Inbox connections** | `courier.inbox.connection_attempt`, `.connection_error`, `.notification_attempt`, `.reconnection_attempt` |
| **Automations** | `courier.automation.invoked`, `.throttled`, `.digest.triggered`, `.batch.triggered`, `.fetch-data-step.errored` |

Slack, Microsoft Teams, and other chat providers report under `direct_message`. There's no `chat` channel.

Each destination's page lists anything specific to it, such as Datadog's extra metrics and tags.

## Limits & behavior

* **Datadog has no backfill.** Courier starts sending metrics when you activate the integration.
* **Metrics count status changes, not messages.** One message moves through several statuses, so metric totals don't match the number of messages in your logs.
* **Per environment.** Filter on the `environment` tag to separate Test from Production.

## FAQ

> **Which observability tools does Courier support?**
>
> Datadog, New Relic, and any platform that accepts OpenTelemetry over OTLP, such as Grafana Cloud or your own collector.

> **Why don't my metric counts match my message logs?**
>
> Courier emits a metric per status change. A message that's sent, delivered, and opened adds to three metrics, while it's one row in logs.


# Monitoring your messages
Source: https://www.courier.com/docs/monitor/overview

Look up any message, see how templates and journeys perform, track opens and clicks, and send delivery events to your own systems.

Courier records what happens to every message you send: who got it, which provider carried it, and whether it was delivered, opened, or clicked.

## Look up a message

[Logs
DOC](/docs/monitor/logs) show one message or journey run at a time, with its timeline, the provider's response, and the content sent. Search them in the dashboard, or fetch them over the API.

## See how messages perform

[Analytics
DOC](/docs/monitor/analytics) show delivery, open, and click rates for each template, journey, and broadcast. The [Metrics API
DOC](/docs/monitor/template-metrics) returns the same numbers as JSON.

## Track opens and clicks

Courier records opens and clicks itself. Delivery comes from your provider, once you [set up delivery tracking
DOC](/docs/monitor/analytics#set-up-delivery-tracking). [Tracking
DOC](/docs/monitor/tracking) covers which channels report opens and clicks, and how to control them.

## Connect other systems

[Outbound webhooks
DOC](/docs/monitor/webhooks/outbound) post every status change to your endpoint. [Observability
DOC](/docs/monitor/observability) sends metrics and logs to Datadog, New Relic, or any OpenTelemetry endpoint. [Inbound webhooks
DOC](/docs/monitor/webhooks/inbound) bring events from other systems into Courier.


# Metrics API
Source: https://www.courier.com/docs/monitor/template-metrics

Get a template's delivery funnel as a time series, by provider and channel, over the REST API.

Get one template's delivery funnel as JSON, split by provider and channel and bucketed over a window you choose.

```javascript Node.js theme={null}
import Courier from "@trycourier/courier";

const client = new Courier();

const metrics = await client.notifications.getMetrics("nt_01kx4h2jdafq8bk9aftxak4b40", {
  lookback: "P7D",
  granularity: "DAY",
});

for (const bucket of metrics.series) {
  const sent = bucket.data.reduce((total, entry) => total + entry.sent, 0);
  console.log(bucket.period, sent);
}
```

```python Python theme={null}
from courier import Courier

client = Courier()

metrics = client.notifications.get_metrics(
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
    lookback="P7D",
    granularity="DAY",
)

for bucket in metrics.series:
    print(bucket.period, sum(entry.sent for entry in bucket.data))
```

```bash cURL theme={null}
curl --request GET \
  --url 'https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40/metrics?lookback=P7D&granularity=DAY' \
  --header "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new

metrics = courier.notifications.get_metrics(
  "nt_01kx4h2jdafq8bk9aftxak4b40",
  lookback: "P7D",
  granularity: "DAY"
)

metrics.series.each do |bucket|
  puts [bucket.period, bucket.data.sum(&:sent)].join(" ")
end
```

```go Go theme={null}
package main

import (
	"context"
	"fmt"

	"github.com/trycourier/courier-go/v4"
)

func main() {
	client := courier.NewClient()

	metrics, err := client.Notifications.GetMetrics(
		context.TODO(),
		"nt_01kx4h2jdafq8bk9aftxak4b40",
		courier.NotificationGetMetricsParams{
			Lookback:    courier.String("P7D"),
			Granularity: courier.NotificationGetMetricsParamsGranularityDay,
		},
	)
	if err != nil {
		panic(err)
	}

	for _, bucket := range metrics.Series {
		fmt.Println(bucket.Period, len(bucket.Data))
	}
}
```

```java Java theme={null}
import com.courier.client.CourierClient;
import com.courier.models.notifications.NotificationGetMetricsParams;
import com.courier.models.notifications.NotificationMetricsResponse;

CourierClient client = CourierClient.builder().build();

NotificationMetricsResponse metrics = client.notifications().getMetrics(
    NotificationGetMetricsParams.builder()
        .id("nt_01kx4h2jdafq8bk9aftxak4b40")
        .lookback("P7D")
        .granularity(NotificationGetMetricsParams.Granularity.DAY)
        .build()
);
```

```php PHP theme={null}
<?php

use Courier\Client;

$client = new Client();

$metrics = $client->notifications->getMetrics(
    'nt_01kx4h2jdafq8bk9aftxak4b40',
    ['lookback' => 'P7D', 'granularity' => 'DAY'],
);

foreach ($metrics->series as $bucket) {
    echo $bucket->period, PHP_EOL;
}
```

```csharp C# theme={null}
using TryCourier;
using TryCourier.Models.Notifications;

var client = new CourierClient();

var metrics = await client.Notifications.GetMetrics(
    new NotificationGetMetricsParams
    {
        ID = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Lookback = "P7D",
        Granularity = Granularity.Day,
    }
);
```

```bash CLI theme={null}
courier notifications get-metrics \
  --id nt_01kx4h2jdafq8bk9aftxak4b40 \
  --lookback P7D \
  --granularity DAY
```

```text MCP theme={null}
With Courier MCP, show me the last 7 days of daily send metrics for template nt_01kx4h2jdafq8bk9aftxak4b40.
```

[Analytics
DOC](/docs/monitor/analytics) shows the same funnel in the UI. [Get Notification Template Metrics](/docs/api-reference/templates/get-notification-template-metrics) returns it as JSON, so you can chart it in your own dashboard.

Address the template by its `nt_` ID or by an alias. Authenticate with a workspace [API key
DOC](/docs/workspaces/environments#api-keys) as a bearer token.

Each bucket breaks the funnel out **per provider and channel**. When a message fails over between providers, the series shows which one errored and which one delivered.

## Choosing the window

Ask for a window in one of two ways:

* **Relative**: `lookback`, an ISO 8601 duration counted back from now: `?lookback=P90D`, `?lookback=P12W`, `?lookback=PT12H`.
* **Absolute**: `start` and `end`, ISO 8601 timestamps: `?start=2026-04-01T00:00:00Z&end=2026-05-01T00:00:00Z`.

`start` and `end` are pair-or-nothing. Sending one without the other is a `400`, as is a `start` that isn't earlier than `end`.

Pick one form or the other. A request carrying both a `lookback` and an absolute pair is a `400`, not a silent preference for one of them, because the two spell the same thing and honoring both would discard whichever lost. A request with none of the three defaults to `lookback=P30D`.

An `end` in the future is accepted and not clamped. Buckets past now come back empty.

### Boundaries are snapped, and echoed back

Courier widens the window you asked for onto the granularity grid: the start is floored to its bucket, the end is ceiled to the next boundary. That way every bucket your window touches is returned whole rather than half-counted.

The response echoes the **snapped** boundaries as `start` and `end`. Chart against those, not against what you sent:

```json theme={null}
// GET /notifications/nt_01kx4h2jdafq8bk9aftxak4b40/metrics?start=2026-08-18T09:30:00Z&end=2026-08-20T11:00:00Z&granularity=DAY
{
  "notificationId": "nt_01kx4h2jdafq8bk9aftxak4b40",
  "granularity": "DAY",
  "start": "2026-08-18T00:00:00Z",
  "end": "2026-08-21T00:00:00Z",
  "series": [ /* three DAY buckets */ ]
}
```

Every boundary is UTC, so a "daily" series is UTC days. Convert on your side if your reporting day starts elsewhere.

> [!NOTE]
>
> `WEEK` buckets start on **Sunday**, matching the analytics store Courier queries. A Monday-based week has to be assembled from `DAY` buckets.

## Granularity

`granularity` sets the bucket size: `HOUR`, `DAY`, `WEEK`, or `MONTH`. It defaults to `DAY`.

Fine granularities are capped by how much window they can cover, so a single response stays a reasonable size:

| Granularity | Maximum window |
| - | - |
| `HOUR` | 7 days |
| `DAY` | 90 days |
| `WEEK` | No limit |
| `MONTH` | No limit |

Both caps are measured on the **snapped** window, and each carries an allowance of a bucket at either edge. That is why a `P90D` window at `DAY` passes even though snapping widens it past 90 days.

Asking for a finer granularity than the window allows is a `400`. The fix is a coarser granularity or a shorter window, not a retry:

```json theme={null}
{
  "message": "Granularity HOUR is too fine for the requested 90 day range.",
  "type": "invalid_params"
}
```

`WEEK` and `MONTH` have no window cap. No response carries more than **1000 buckets**, and beyond that you get a `400` too.

## Reading the response

`series` holds one entry per bucket, oldest first. Each entry carries the bucket's start (`period`) and a `data` array with one row per provider and channel that handled a message in that bucket.

```json theme={null}
{
  "notificationId": "nt_01kx4h2jdafq8bk9aftxak4b40",
  "granularity": "DAY",
  "start": "2026-08-17T00:00:00Z",
  "end": "2026-08-19T00:00:00Z",
  "series": [
    {
      "period": "2026-08-17T00:00:00Z",
      "data": []
    },
    {
      "period": "2026-08-18T00:00:00Z",
      "data": [
        {
          "provider": "sendgrid",
          "channel": "email",
          "sent": 412,
          "delivered": 408,
          "opened": 173,
          "clicked": 41,
          "errors": 0,
          "undeliverable": 4
        },
        {
          "provider": "twilio",
          "channel": "sms",
          "sent": 96,
          "delivered": 95,
          "opened": 0,
          "clicked": 12,
          "errors": 1,
          "undeliverable": 0
        }
      ]
    }
  ]
}
```

Sum the rows in `data` for a bucket's total, or filter them by `channel` to chart one channel on its own.

Rates are yours to compute from those sums:

```javascript theme={null}
function totals(bucket) {
  return bucket.data.reduce(
    (acc, row) => ({
      sent: acc.sent + row.sent,
      delivered: acc.delivered + row.delivered,
      opened: acc.opened + row.opened,
    }),
    { sent: 0, delivered: 0, opened: 0 }
  );
}

for (const bucket of metrics.series) {
  const { sent, delivered, opened } = totals(bucket);
  console.log(bucket.period, {
    deliveryRate: sent ? delivered / sent : null,
    openRate: delivered ? opened / delivered : null,
  });
}
```

Guard every division. A quiet bucket has a `sent` of zero.

Before you plot it:

* **Every bucket in the window comes back, including the quiet ones**, with `data` set to `[]`. The series is directly plottable, so you never reconstruct missing periods yourself.
* **`errors` counts provider attempts, not lost messages.** A message that SendGrid rejected and Mailgun then delivered contributes to `errors` on one row and `delivered` on another. `undeliverable` is the one that means the message never landed on that channel.
* **`opened` and `clicked` are `0` on channels with no tracking**, such as SMS without link tracking. A zero there means "not measured", not "nobody read it".
* **Sends without a template never appear.** A message sent with inline content has no template to attribute, so it is counted nowhere in this endpoint.
* **An unknown template id returns `200` with an all-empty series**, not a `404`. That is indistinguishable from a real template that has sent nothing. Validate template ids against [List Notification Templates](/docs/api-reference/templates/list-notification-templates) if you need to tell the two apart.

## Plan limits

**Lookback** is capped by plan, measured from the snapped `start`:

| Plan | Maximum lookback |
| - | - |
| Developer | 30 days |
| Business | 90 days |
| Enterprise | No limit |

On Enterprise the API itself imposes no lookback cap, so how far back you can reach is whatever the analytics store still holds. The [Analytics
DOC](/docs/monitor/analytics) dashboard is narrower than the API here, because its custom-range calendar stops at January 1 of last year.

Reaching past the cap is a `402`, not an empty result:

```json theme={null}
{
  "message": "Requested date range exceeds your plan's maximum lookback of 30 days.",
  "type": "payment_required"
}
```

**Rate limits** on metrics reads are per second, per workspace: 1/s on Developer, 2/s on Business, 5/s on Enterprise. Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`, and a `429` adds `Retry-After`. If you're backfilling a dashboard, walk the windows sequentially rather than fanning out.

## Errors

| Status | `type` | When it happens |
| - | - | - |
| 400 | `invalid_params` | A malformed duration or timestamp, one of `start`/`end` without the other, a `start` that isn't earlier than `end`, a `lookback` combined with `start`/`end`, a granularity too fine for the window, or more than 1000 buckets. |
| 402 | `payment_required` | The window reaches further back than your plan's lookback cap. |
| 429 | `rate_limit_exceeded` | Over the per-second limit for your plan. Wait the seconds in `Retry-After`. |
| 503 | `service_unavailable` | The analytics store is briefly unavailable. Retry the same request after `Retry-After`. |

A `400` and a `402` both mean the request as written can never succeed, so retrying it unchanged spends rate limit for nothing. Narrow the window or coarsen the granularity instead.

## Covering a whole workspace

The endpoint is per template. For a workspace-wide view, list your templates with [List Notification Templates](/docs/api-reference/templates/list-notification-templates) and call metrics for each one, sequentially. At 1 to 5 requests per second, fanning out concurrently returns a `429`.

> [!NOTE]
>
> The endpoint currently serves the **US region** only. Workspaces in the EU region can't query it yet.


# Open and click tracking
Source: https://www.courier.com/docs/monitor/tracking

How Courier records opens and clicks on each channel, and how to control and brand tracked links.

Courier records opens and clicks itself, separately from the delivery confirmation your provider sends back. That's why a message can show `OPENED` before `DELIVERED`, or without it.

## What each channel reports

| Channel | Opened | Clicked | How Courier records it |
| :- | :- | :- | :- |
| **Email** | Yes, when open tracking is on | Yes, when click-through tracking is on | A tracking pixel for opens, a redirect on each link for clicks |
| **Push** | No | Yes | The Courier mobile SDK posts to the message's `trackingUrl` when the user taps it |
| **Inbox** | Yes | Yes | The Courier client SDK reports opened and clicked events from the inbox |
| **SMS** | No | No | Delivery status only |
| **Chat** (Slack, Microsoft Teams, and others) | No | No | Delivery status only |

A `0` in an Opened or Clicked column means "not measured", not "nobody read it", on any channel that can't report that event.

## Turn on email tracking

Open and click tracking for email are two workspace settings in [Settings → Tracking](https://app.courier.com/settings/general):

* **Email-open tracking** adds a tracking pixel to every email.
* **Click-through tracking** rewrites every link in an email to pass through Courier's redirect first.

Both apply to every environment in the workspace. Turning either one on or off is recorded in the [audit trail
DOC](/docs/workspaces/audit-trail).

Courier adds the pixel after the email is rendered, so it works on templates built in Design Studio and on templates that use your own HTML.

> [!WARNING]
>
> Links must use absolute URLs. Courier doesn't attach tracking to a relative URL: the email still sends, but the click doesn't get counted.

## Turn tracking off for one link

With click-through tracking on, you can still leave individual links untracked. Deep links into a mobile app are the usual case, since a redirect can stop the operating system from opening the app.

**Design Studio**

Select the button, or the link inside a text block, and turn off tracking in its settings.

**HTML**

Add `data-courier-link-tracking="false"` to the `<a>` tag:

```html theme={null}
<a data-courier-link-tracking="false" href="https://example.com/app/orders/1234">Open in app</a>
```

**Elemental**

Set `disable_tracking` to `true` on the [action element
DOC](/docs/design/elemental/elements/action), or on a link inside a [text element
DOC](/docs/design/elemental/elements/text):

```json theme={null}
{
  "type": "action",
  "content": "Open in app",
  "href": "https://example.com/app/orders/1234",
  "disable_tracking": true
}
```

## Turn off open tracking for one send

Set `tracking.open` to `false` in the email channel override. The workspace setting stays as it is for every other send.

```javascript Node.js highlight={8} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    channels: {
      email: {
        override: {
          tracking: { open: false },
        },
      },
    },
  },
});
```

```python Python highlight={8} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "channels": {
            "email": {
                "override": {
                    "tracking": {"open": False},
                },
            },
        },
    },
)
```

```bash cURL highlight={11} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "channels": {
        "email": {
          "override": {
            "tracking": { "open": false }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    channels: {
      email: {
        override: {
          tracking: { open: false }
        }
      }
    }
  }
)
```

```go Go highlight={12} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Channels: shared.MessageChannelsParam{
			"email": shared.ChannelParam{
				Override: map[string]any{
					"tracking": map[string]any{"open": false},
				},
			},
		},
	},
})
```

```java Java highlight={7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .channels(MessageChannels.builder()
            .putAdditionalProperty("email", JsonValue.from(java.util.Map.of(
                "override", java.util.Map.of("tracking", java.util.Map.of("open", false)))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'channels' => [
      'email' => [
        'override' => [
          'tracking' => ['open' => false],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={15} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Channels = new Dictionary<string, Channel>
        {
            {
                "email",
                new Channel
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        { "tracking": { "open": false } }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.channels '{"email": {"override": {"tracking": {"open": false}}}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with email open tracking turned off.
```

The other email override fields are listed in [Email providers
DOC](/docs/integrations/email/overview).

## Push tracking

Every push Courier sends carries a `trackingUrl` in its data. Posting an event to that URL updates the message:

* `DELIVERED` when the push arrives on the device.
* `CLICKED` when the user taps it.

The Courier mobile SDKs post both for you once your app is wired up. [Set up mobile push
GUIDE](/docs/guides/set-up-mobile-push#delivery-and-click-tracking) shows which part of your app reports each event on iOS and Android.

If you handle notifications outside the SDK's hooks, post the event yourself:

```bash theme={null}
curl -X POST https://api.courier.com/e/123_channelTrackingId \
  -H "Content-Type: application/json" \
  -d '{"event":"CLICKED"}'
```

## Inbox tracking

The Courier client SDKs report opened, read, and clicked events from the inbox as users interact with it, so inbox messages fill in their own engagement without any setup.

When a template sends to both email and the inbox, opening the email marks the inbox message as read. This uses the email's tracking pixel, so it needs open tracking on. Reading the inbox message doesn't mark the email as opened.

## Where tracked events show up

| Where | What you see |
| :- | :- |
| [Message logs&#xA;DOC](/docs/monitor/logs) | `OPENED` and `CLICKED` events on each message's timeline |
| [Get message](/docs/api-reference/messages/get-message) | `opened` and `clicked`: timestamps of the first open and the first click, in milliseconds since the Unix epoch |
| [Outbound webhooks&#xA;DOC](/docs/monitor/webhooks/outbound) | A `message:updated` event each time the status changes to `OPENED` or `CLICKED` |
| [Analytics&#xA;DOC](/docs/monitor/analytics) | Open and click rates per template, journey, and broadcast |
| [Metrics API&#xA;DOC](/docs/monitor/template-metrics) | `opened` and `clicked` counts as a time series |

Every message keeps any `metadata` you sent with it, including `utm` (`source`, `medium`, `campaign`, `term`, `content`), `tags`, and `trace_id`. It comes back on the message and on every webhook event, so you can join engagement to your own campaign data.

## Custom tracking domain

Tracked links go through Courier's `ct0.app` domain by default. A custom tracking domain, such as `tracking.acme-corp.com`, puts your own domain in every link instead. Recipients see a domain they recognize, and some spam filters treat it more kindly than a shared tracking domain.

> [!NOTE]
>
> A custom tracking domain is available on the Business and Enterprise plans. Setup is done with Courier support.

**1. Send Courier your subdomain**

Email [support](mailto:support@courier.com) the subdomain you want to use, for example `tracking.acme-corp.com`.

**2. Add the DNS records**

Courier sends you two records to add at your DNS provider:

* A certificate validation record, so Courier can serve HTTPS on your subdomain.
* A CNAME that points your subdomain at Courier's tracking infrastructure:

```text theme={null}
tracking.acme-corp.com  CNAME  tracking.ct0.app
```

**3. Wait for activation**

Once the records propagate, Courier support turns the domain on for your workspace. From then on, every tracked link in every email uses it.

**4. Verify**

Send yourself an email with a link in it and hover over the link. It should point at your subdomain, not `ct0.app`.

## Why open rates are unreliable

Open tracking depends on the pixel loading. Inbox security scanners and Apple Mail Privacy Protection load images automatically, which records an open before anyone reads the email, or when no one does. A scanner can even load the pixel on an email that later bounced.

Email clients that block images, common in corporate mail, don't load the pixel, so those opens go unrecorded.

## Limits & behavior

* **Tracking is separate from delivery.** `DELIVERED` comes from your provider. `OPENED` and `CLICKED` come from Courier. Either can arrive without the other.
* **Only the first open and first click are timestamped** on the message. Later opens and clicks don't change `opened` or `clicked`.
* **Push and inbox engagement comes from the SDKs.** It's reported regardless of the email tracking settings.
* **The tracking domain is workspace-wide.** It applies to every tracked link in the workspace, across every template and tenant.

## FAQ

> **Why are my open rates higher than expected?**
>
> Inbox scanners and Apple Mail Privacy Protection load the tracking pixel automatically, and Courier records that as an open. Weigh clicks more heavily when you judge engagement.

> **Why does a message show OPENED but not DELIVERED?**
>
> Opens come from Courier's pixel and delivery comes from your provider, independently. Either the provider hasn't confirmed delivery yet, or delivery tracking isn't set up for it. See [Set up delivery tracking
> DOC](/docs/monitor/analytics#set-up-delivery-tracking).

> **Why don't my SMS messages have an open rate?**
>
> A text message can't carry a tracking pixel, so SMS reports delivery status but not opens or clicks.

> **Why aren't clicks on my push notifications showing up?**
>
> The Courier mobile SDK reports push clicks. If your app handles notifications without the SDK's hooks, post `CLICKED` to the message's `trackingUrl` yourself.

> **How do I stop Courier from rewriting a deep link?**
>
> Turn off tracking on that link: in Design Studio's link settings, with `data-courier-link-tracking="false"` in HTML, or with `disable_tracking` in Elemental.

> **Do I need a custom tracking domain?**
>
> `ct0.app` works out of the box, with no custom domain required. A custom domain helps if you want your own brand in every link, or if your recipients' filters are wary of shared tracking domains.


# Webhook event types
Source: https://www.courier.com/docs/monitor/webhooks/events

Every event an outbound webhook sends, when it fires, and an example payload for each.

Every event arrives as `{ "type": "...", "data": {...} }`. Branch on `type`, and ignore types you don't recognize, since Courier may add new ones.

| Event type | Fires when |
| :- | :- |
| [`message:updated`](#messageupdated) | A message changes status |
| [`notification:submitted`](#notificationsubmitted) | A template is submitted for review |
| [`notification:submission_canceled`](#notificationsubmission_canceled) | A pending submission is canceled |
| [`notification:published`](#notificationpublished) | A template is published |
| [`audiences:created`](#audience-events) | An audience is created |
| [`audiences:updated`](#audience-events) | An audience's definition changes |
| [`audiences:deleted`](#audience-events) | An audience is deleted |
| [`audiences:calculated`](#audiencescalculated) | Courier finishes recalculating an audience |
| [`audiences:user:matched`](#audiencesusermatched) | A user starts matching an audience |
| [`audiences:user:unmatched`](#audiencesuserunmatched) | A user stops matching an audience |
| [`preferences:user:updated`](#preferencesuserupdated) | A user changes a subscription preference |

## Message events

### message:updated

Fires every time a message changes status. `data` is the same object the [Get message](/docs/api-reference/messages/get-message) endpoint returns, including any `metadata` you sent (`trace_id`, `tags`, `event`, `utm`).

Timestamps accumulate as the message moves along, so a `CLICKED` event still carries `enqueued`, `sent`, `delivered`, and `opened`. A `DELIVERED` event:

```json theme={null}
{
  "type": "message:updated",
  "data": {
    "id": "1-612fa552-15f7d6ba51bf229857c037a7",
    "event": "SFTYJKSF0241SVH2TWY97TTFFTQG",
    "notification": "SFTYJKSF0241SVH2TWY97TTFFTQG",
    "recipient": "b19fb0e0-8cd6-4337-b41c-92c780c80d1a",
    "recipientId": "b19fb0e0-8cd6-4337-b41c-92c780c80d1a",
    "status": "DELIVERED",
    "enqueued": 1630512466717,
    "sent": 1630512468691,
    "delivered": 1630512501708,
    "providers": [
      {
        "provider": "slack",
        "status": "DELIVERED",
        "channel": {
          "key": "direct_message:slack",
          "name": "Slack",
          "template": "SFTYJKSF0241SVH2TWY97TTFFTQG"
        },
        "reference": {
          "channel": "C04EXAMPLE",
          "ts": "1630512468.000700"
        },
        "sent": 1630512468691,
        "delivered": 1630512501708
      }
    ]
  }
}
```

What each status adds to `data`:

| Status | Adds |
| :- | :- |
| `ENQUEUED` | `enqueued` |
| `SENT` | `sent`, and `sent` on the matching entry in `providers` |
| `DELIVERED` | `delivered`, and `delivered` on the matching entry in `providers` |
| `OPENED` | `opened` |
| `CLICKED` | `clicked` |
| `UNROUTABLE` | `reason`, such as `NO_PROVIDERS`, and `error`. `providers` is empty. |
| `UNDELIVERABLE` | `reason`, such as `UNSUBSCRIBED`, and `error`, plus `error` on the failing entry in `providers` |

`DELIVERED` comes from your provider and `OPENED` and `CLICKED` come from Courier's tracking, so engagement events can arrive before the delivery event, or without it. See [Tracking
DOC](/docs/monitor/tracking).

## Template events

Use these to connect a translation management system or a custom approval workflow.

### notification:submitted

Fires when a template is submitted for review and hasn't been published yet. `submission_id` is the submission's timestamp.

```json theme={null}
{
  "type": "notification:submitted",
  "data": {
    "id": "nt_01kx4h2jdafq8bk9aftxak4b40",
    "submission_id": 1620095270807
  }
}
```

### notification:submission\_canceled

Fires when a pending submission is canceled before it's published.

```json theme={null}
{
  "type": "notification:submission_canceled",
  "data": {
    "id": "nt_01kx4h2jdafq8bk9aftxak4b40",
    "canceled_at": 1620095280807,
    "submission_id": 1620095270807
  }
}
```

### notification:published

Fires when a template is published, either directly or when an approved submission publishes. Listen for this one to sync template content to another system.

```json theme={null}
{
  "type": "notification:published",
  "data": {
    "id": "nt_01kx4h2jdafq8bk9aftxak4b40",
    "published_at": 1620095270807
  }
}
```

## Audience events

`audiences:created`, `audiences:updated`, and `audiences:deleted` fire when an audience is created, changed, or deleted. An `audiences:updated` event:

```json theme={null}
{
  "type": "audiences:updated",
  "data": {
    "audience_id": "software-engineers",
    "audience_version": 11,
    "filter": {
      "path": "title",
      "value": "Software Engineer",
      "operator": "EQ"
    }
  }
}
```

### audiences:calculated

Fires when Courier finishes recalculating an audience's membership. This runs every time an audience is created or updated, and takes longer the more users your workspace has.

```json theme={null}
{
  "type": "audiences:calculated",
  "data": {
    "audience_id": "software-engineers",
    "user_count": 1,
    "total_users": 28,
    "total_users_filtered": 27
  }
}
```

### audiences:user:matched

Fires when a user starts matching an audience's filter, usually because their profile was created or updated. It's the same event behind the journey audience trigger, so you can react to it with a webhook or by starting a journey.

```json theme={null}
{
  "type": "audiences:user:matched",
  "data": {
    "audience_id": "software-engineers",
    "audience_version": 11,
    "reason": "EQ('title', 'Software Engineer') => true",
    "user_id": "user_123"
  }
}
```

### audiences:user:unmatched

Fires when a user stops matching an audience's filter, because their profile changed or was deleted.

```json theme={null}
{
  "type": "audiences:user:unmatched",
  "data": {
    "audience_id": "software-engineers",
    "audience_version": 12,
    "reason": "EQ('title', 'Software Engineer') => false",
    "user_id": "user_123"
  }
}
```

## Preference events

### preferences:user:updated

Fires when a user changes their subscription preference for a topic, whether they change it on the hosted preferences page, unsubscribe link, or through the API. One event covers every kind of change: opting in, opting out, and editing which channels a topic uses.

`data` describes a single change to a single topic.

```json theme={null}
{
  "type": "preferences:user:updated",
  "data": {
    "id": "eb4023e3-62cc-4488-a4fc-d98230994f6a",
    "timestamp": "2026-09-24T18:12:04.442Z",
    "user_id": "user_123",
    "tenant_id": "acme-corp",
    "topic_id": "pt_01kx4h2jdafq8bk996nn92357r",
    "topic_name": "Product updates",
    "status": "OPTED_OUT",
    "custom_routing": [],
    "has_custom_routing": false,
    "previous": {
      "status": "OPTED_IN",
      "custom_routing": ["email"],
      "has_custom_routing": true
    }
  }
}
```

`custom_routing` lists the channels a user picked for the topic and is empty unless `has_custom_routing` is true. `tenant_id` is absent when the change wasn't made in a tenant.

`previous` is absent when the earlier state isn't known, such as the first time a user changes their preference for a topic.

## Limits & behavior

* **One message produces several events.** `message:updated` fires on every status change, so key your handler on `data.id` and `data.status`.
* **`data.id` identifies the resource, not the event.** Retries and status changes can share it.
* **No timestamp in the body.** The send time is on the `courier-signature` header.

## FAQ

> **How many events does one message produce?**
>
> One per status change. A delivered and opened email produces at least four `message:updated` events: enqueued, sent, delivered, and opened.

> **Can I get the metadata I sent with the message?**
>
> `data` on `message:updated` carries the `metadata` from your send, including `trace_id`, `tags`, `event`, and `utm`.


# Inbound webhooks
Source: https://www.courier.com/docs/monitor/webhooks/inbound

Point an external system's webhooks at a Courier URL to update profiles and start journeys.

An inbound webhook is a Courier URL that another system posts events to. Use one when a third-party system can send an HTTP request but can't call the Courier API, most often to start a journey with a [webhook trigger
DOC](/docs/journeys/invoke).

## Register a webhook

1. Go to [Settings → Webhooks](https://app.courier.com/settings/webhooks) and find **Inbound Webhooks**.
2. Select **Add**, then give the webhook a name and description.
3. Save. Courier generates a unique URL in the form `https://api.courier.com/inbound/webhook/<token>`.

The name is permanent. You select the webhook by name wherever you consume its events, so make it recognizable.

## Send events

Point the source system at that URL and `POST` your JSON. No API key or auth header is needed. The URL carries a signed token that identifies your workspace.

> [!WARNING]
>
> Treat the webhook URL as a secret. Anyone who has it can send events into your workspace. If it leaks, delete the webhook and create a new one for a fresh URL.

```bash theme={null}
curl -X POST https://api.courier.com/inbound/webhook/YOUR_WEBHOOK_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order-shipped",
    "userId": "user_123",
    "properties": {
      "order_id": "ORD-9042",
      "carrier": "UPS"
    }
  }'
```

Send real traffic before you build against the webhook. Courier learns event names and payload shape from events it has received. Event pickers and variable hints stay empty until the first one arrives.

## Payload handling

Courier accepts any payload up to 6 MB.

| Payload | What Courier does |
| - | - |
| JSON object | Parses it and exposes the fields as data |
| JSON array | Unpacks it and treats each object as its own event |
| Anything else | Keeps the payload as a string on a `raw` field, and names the event `custom` |

Courier answers `202` when it accepts the request. A `404` means the URL is wrong or no longer exists.

## Reserved fields

Courier reads two fields from a JSON payload, if present.

| Field | Purpose |
| - | - |
| `event` | The event name, used to pick which events start a workflow. Must be a string. Without it, Courier names the event `custom`. |
| `userId` | Identifies the recipient. Courier resolves the [user&#xA;DOC](/docs/recipients/overview) from it and loads their profile data. A string or number, coerced to a string. |

Every other field is yours. Courier passes them through as data to whatever consumes the event.

## Limits & behavior

* **`userId` must match an existing Courier user.** With no recipient to send to, the event will not start a journey.
* **The URL is the credential.** There's no separate auth header.
* **Payloads cap at 6 MB.** Larger requests are rejected.

## FAQ

> **Why is my event picker empty?**
>
> Courier learns event names from traffic it has received. Post one real event and the name appears.

> **What if the webhook URL leaks?**
>
> Delete the webhook and create a new one. That issues a fresh URL, and the old one stops accepting events.

> **Can I send a batch of events at once?**
>
> Post a JSON array. Courier treats each object in it as its own event.


# Outbound webhooks
Source: https://www.courier.com/docs/monitor/webhooks/outbound

Get a signed POST at your endpoint every time a message changes status, a user changes a preference, or a template or audience changes.

An outbound webhook sends Courier's events to an endpoint you own, as a signed `POST`. Use it when your own system needs to react to a message's status, such as updating an order record when a receipt is delivered.

## Add a destination

**1. Open the webhook settings**

Go to [Settings → Webhooks](https://app.courier.com/settings/webhooks) and find **Outbound Webhooks**.

**2. Add the endpoint**

Select **Add**, give the destination a name, and enter its URL. The endpoint has to accept a `POST`.

**3. Save the signing secret**

Courier creates a `whsec_...` secret for the destination. Store it where your handler can read it, so you can [verify each request
DOC](/docs/monitor/webhooks/security).

> [!WARNING]
>
> Destinations belong to one environment. A destination added in Test receives only Test events. Add one in each environment you need.

## Handle events

Every event arrives as `{ "type": "...", "data": {...} }`:

```json theme={null}
{
  "type": "message:updated",
  "data": {
    "id": "1-612fa552-15f7d6ba51bf229857c037a7",
    "status": "DELIVERED",
    "recipient": "user_123",
    "delivered": 1630512501708
  }
}
```

1. **Verify the signature** before you trust the body. See [Verify webhook signatures
   DOC](/docs/monitor/webhooks/security).
2. **Branch on `type`.** Every destination receives every event type, so ignore the ones you don't need, and ignore types you don't recognize, since Courier may add new ones. [Webhook event types
   DOC](/docs/monitor/webhooks/events) lists them all.
3. **Return a `2xx` within 10 seconds.** Acknowledge first and do the real work in a queue or background job, so a slow dependency doesn't turn into a failed delivery.
4. **Make your handler idempotent.** A retry can deliver the same event twice, and one message produces several `message:updated` events that share its `data.id`.

## Retries

Courier retries a delivery when the failure looks temporary:

| Outcome | Retried |
| :- | :- |
| Network error, or no response within 10 seconds | Yes |
| `408`, `429`, or any `5xx` | Yes |
| Any other `4xx` | No |

Retries start a few seconds apart, grow to 15-minute intervals, and continue for about a day. After that the event is dropped. A destination is never turned off automatically, so a broken endpoint keeps getting retries until each event ages out.

To recover events you missed during an outage, read the messages from the [Messages API
DOC](/docs/api-reference/messages/get-message) and preference changes from the [change history
DOC](/docs/recipients/preferences/api#track-preference-changes).

## Limits & behavior

* **Setup is in the dashboard.** There's no API for creating destinations.
* **No timestamp in the body.** The send time is on the `courier-signature` header.

## FAQ

> **Can I subscribe to only one event type?**
>
> Every destination receives every event type. Filter on the `type` field in your handler.

> **What happens if my endpoint is down?**
>
> Courier retries with an increasing backoff for about a day, then drops the event. Events that aged out during the outage are gone, so backfill from the Messages API if you need them.

> **Should I use webhooks or an observability integration?**
>
> Use webhooks when your own code needs to act on each event. Use [observability integrations
> DOC](/docs/monitor/observability) to see Courier's metrics and logs in Datadog, New Relic, or another OpenTelemetry tool.

> **What's the difference between outbound and inbound webhooks?**
>
> Outbound webhooks send Courier's events to you. [Inbound webhooks
> DOC](/docs/monitor/webhooks/inbound) let another system send events into Courier, usually to start a journey.


# Verify webhook signatures
Source: https://www.courier.com/docs/monitor/webhooks/security

Check the courier-signature header on every outbound webhook before you trust the event.

Courier signs every outbound webhook request. Check the signature before you act on an event, so a forged request can't reach your handler.

## Read the header

Each destination gets a `whsec_...` secret when you create it. Courier signs every request with HMAC-SHA256 in a `courier-signature` header:

```
courier-signature: t=1631816343012,signature=33777cdae0468ff0939b3609d02d14e6e80ca093c2ea233455f0767055218875
```

## Compare the signature

Split the header on `,` and `=` to read `t`, a millisecond timestamp, and `signature`. Compute `HMAC_SHA256(secret, "<t>.<raw_body>")` and compare it to `signature` in constant time:

```javascript Node.js theme={null}
import crypto from "crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`, "utf8")
    .digest("hex");
  const digest = Buffer.from(expected, "hex");
  const provided = Buffer.from(parts.signature ?? "", "hex");

  // timingSafeEqual throws unless both buffers are the same length, so compare
  // lengths first. Without this a malformed or absent signature is an exception
  // rather than a rejection.
  return provided.length === digest.length && crypto.timingSafeEqual(digest, provided);
}
```

```python Python theme={null}
import hashlib
import hmac

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(kv.split("=", 1) for kv in header.split(","))
    expected = hmac.new(
        secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts["signature"])
```

```ruby Ruby theme={null}
require "openssl"

def verify(raw_body, header, secret)
  parts = header.split(",").map { |kv| kv.split("=", 2) }.to_h
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{parts['t']}.#{raw_body}")
  OpenSSL.secure_compare(expected, parts["signature"])
end
```

```go Go theme={null}
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strings"
)

func verify(rawBody []byte, header, secret string) bool {
	parts := map[string]string{}
	for _, kv := range strings.Split(header, ",") {
		if key, value, ok := strings.Cut(kv, "="); ok {
			parts[key] = value
		}
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(parts["t"] + "."))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(parts["signature"]))
}
```

```java Java theme={null}
import java.security.MessageDigest;
import java.util.Arrays;
import java.util.HexFormat;
import java.util.Map;
import java.util.stream.Collectors;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

boolean verify(byte[] rawBody, String header, String secret) throws Exception {
    Map<String, String> parts = Arrays.stream(header.split(","))
        .map(kv -> kv.split("=", 2))
        .collect(Collectors.toMap(kv -> kv[0], kv -> kv[1]));
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));
    mac.update((parts.get("t") + ".").getBytes());
    String expected = HexFormat.of().formatHex(mac.doFinal(rawBody));
    return MessageDigest.isEqual(expected.getBytes(), parts.get("signature").getBytes());
}
```

```php PHP theme={null}
function verify(string $rawBody, string $header, string $secret): bool
{
    parse_str(strtr($header, ',', '&'), $parts);
    $expected = hash_hmac('sha256', "{$parts['t']}.{$rawBody}", $secret);
    return hash_equals($expected, $parts['signature']);
}
```

```csharp C# theme={null}
using System.Security.Cryptography;
using System.Text;

static bool Verify(byte[] rawBody, string header, string secret)
{
    var parts = header.Split(',')
        .Select(kv => kv.Split('=', 2))
        .ToDictionary(kv => kv[0], kv => kv[1]);
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var signed = Encoding.UTF8.GetBytes(parts["t"] + ".").Concat(rawBody).ToArray();
    var expected = Convert.ToHexString(hmac.ComputeHash(signed)).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(parts["signature"]));
}
```

Sign against the **raw** request body, not a re-serialized object, so the bytes match what Courier hashed.

Retries and timeouts are covered in [Outbound webhooks
DOC](/docs/monitor/webhooks/outbound#retries).

## Limits & behavior

* **Verify against the raw body.** Re-serializing the JSON changes the bytes, so the signature won't match.
* **Use a constant-time comparison.** A plain string comparison leaks timing information.

## FAQ

> **How do I know a request really came from Courier?**
>
> Verify the `courier-signature` header. Compute `HMAC_SHA256(secret, "<t>.<raw_body>")` with your webhook's `whsec_` secret and compare it to the header's `signature`. Reject anything that does not match.

> **Why does my signature check keep failing?**
>
> Almost always because the body was parsed and re-serialized before hashing. Hash the raw bytes of the request instead.


# Courier docs: send and automate customer messages
Source: https://www.courier.com/docs/overview

Send and automate customer messages across email, SMS, push, Slack, chat, and in-app, all from one API.

Courier is a customer messaging orchestration platform. It helps you send and manage your product's notifications across email, SMS, push, Slack, Microsoft Teams, WhatsApp, and in-app, all in one place.

Everything you need is built in, from a visual template editor and multi-step journeys to user preferences, an in-app notification center, and analytics on every message you send.

Courier turns notifications from code you maintain into something your whole team can shape. You change a message, a workflow, or a channel without shipping a release, and your AI coding agent can build them with you through [Courier Skills](/docs/resources/skills) and the [MCP server](/docs/resources/mcp).

## Where to start

> **[Build with AI](/docs/get-started/build-with-ai)**
>
> Set up Claude Code, Cursor, or Codex to build with Courier.

> **[Send your first message](/docs/get-started/send-a-message)**
>
> Go from an API key to a delivered message, in any server language.

> **[Build your first journey](/docs/get-started/build-your-first-journey)**
>
> Build a three-email welcome series with the Journeys API.

> **[Add an in-app inbox](/docs/in-app/overview)**
>
> A real-time message center for web, iOS, and Android.

## Why use Courier

* **Design once, send anywhere.** Build a template in [Design Studio](/docs/design/templates/design-studio), and Courier formats it for email, SMS, push, chat, and the inbox. Your team changes wording and design without a deploy.
* **Automate the whole flow.** [Journeys](/docs/journeys/overview) run multi-step sequences like onboarding or a trial ending, with triggers, delays, branches, digests, and experiments.
* **Let users choose.** With [preferences](/docs/recipients/preferences/overview), users pick which notifications they get and on which channel. Courier checks those choices on every send.
* **Put an inbox in your app.** The [in-app inbox](/docs/in-app/overview) adds a real-time message center and toasts to web, iOS, Android, React Native, and Flutter apps.
* **Serve every customer their way.** [Tenants](/docs/tenants/overview) give each of your customers their own branding, preferences, and routing.
* **See what happened.** [Logs](/docs/monitor/logs) show every message, and [analytics](/docs/monitor/analytics) track delivery, open, and click rates per template, journey, and broadcast.
* **Keep your providers.** Courier sends through the accounts you already have, such as SendGrid, Amazon SES, Twilio, Firebase Cloud Messaging, and APNs, and can fail over to a backup.

## Explore the platform

> **[Templates](/docs/design/templates/overview)**
>
> Design content once and render it for every channel.

> **[Journeys](/docs/journeys/overview)**
>
> Automate multi-step flows with triggers, delays, and branches.

> **[Broadcasts](/docs/broadcasts/overview)**
>
> Send one message to a whole list or audience.

> **[In-app messaging](/docs/in-app/overview)**
>
> Embed an inbox, toasts, and a preference center in your app.

> **[Preferences](/docs/recipients/preferences/overview)**
>
> Let users choose what they receive, per topic and channel.

> **[Embedded designer](/docs/design/embedded-designer/overview)**
>
> Let your customers design their own templates in your app.

> **[User profiles](/docs/recipients/overview)**
>
> Store each recipient's contact details and device tokens.

> **[Lists and audiences](/docs/recipients/lists-and-audiences/overview)**
>
> Group users into static lists and dynamic audiences.

> **[Logs and analytics](/docs/monitor/overview)**
>
> See what happened to every message, and how each template performs.

> **[Webhooks](/docs/monitor/webhooks/outbound)**
>
> Get delivery, open, and click events in your own system.

> **[Tenants](/docs/tenants/overview)**
>
> Scope branding, preferences, and routing per customer.

## Developer tools

> **[SDKs](/docs/sdk-libraries/sdks-overview)**
>
> Server and client libraries for your language.

> **[CLI](/docs/resources/cli)**
>
> Operate the Courier API from your terminal.

> **[MCP](/docs/resources/mcp)**
>
> Give an AI agent access to the Courier API.

> **[API Reference](/docs/reference/api-overview)**
>
> Every endpoint, with request and response schemas.

## FAQ

> **What channels and providers does Courier support?**
>
> Courier delivers across email, SMS, push, an in-app inbox, and chat apps including Slack, Microsoft Teams, and WhatsApp. You bring your own provider accounts, such as SendGrid, Postmark, Amazon SES, Twilio, or Firebase Cloud Messaging, and [connect them](/docs/integrations/overview) once. Courier routes each message to the right provider, and fails over to a backup if one is unavailable. See [how sending works](/docs/send/overview).

> **Do I bring my own providers, or does Courier send messages for me?**
>
> You bring your own providers. Courier sits on top of the delivery services you already use, so you keep your sender reputation, domains, and provider pricing. Courier adds routing, failover, templating, preferences, and analytics, and bills separately per send.

> **How much does Courier cost?**
>
> Courier has three plans and bills on notifications sent, not team size or channels. The Developer plan is free for up to 10,000 sends per month. The Business plan is pay-as-you-go at \$0.005 per send. Enterprise is custom-priced with volume discounts. See [Courier pricing](https://www.courier.com/pricing) for the full comparison.

> **Is Courier built for developers, product teams, or marketers?**
>
> Courier is built for all three, and for AI agents. You can work in code with the REST API, SDKs, and CLI, or without code in [Design Studio](/docs/design/templates/design-studio) and [journeys](/docs/journeys/overview). AI coding agents work through the MCP server and CLI.

> **Can Courier handle both transactional notifications and lifecycle marketing?**
>
> Courier runs both on the same platform. Transactional notifications include password resets, receipts, and alerts. Lifecycle marketing includes onboarding, re-engagement, and announcement sequences. [Journeys](/docs/journeys/overview) automate multi-step flows with triggers, delays, branches, batching, and digests.

> **What are Journeys?**
>
> Journeys are visual, multi-step workflows that automate when and how messages send. You add triggers, delays, branches, and send steps. Batch and digest nodes bundle activity into a single notification. Build and edit them in the dashboard, or manage them through the [Journeys API](/docs/journeys/overview).

> **How do notification preferences work?**
>
> Users control what they receive, per topic and per channel. Host a ready-made [preference page](/docs/guides/build-a-preference-center#hosted-page), or embed preference components in your app. Courier enforces those choices automatically on every send. See [preferences](/docs/recipients/preferences/overview).

> **How do I see whether a message was delivered?**
>
> Every send gets a log entry with its status, timeline, the content sent, and the provider's response. Search [logs](/docs/monitor/logs) in the dashboard by recipient, template, or status, or subscribe to [outbound webhooks](/docs/monitor/webhooks/outbound) to get each status change in your own system.

> **Does Courier support multi-tenant applications?**
>
> Courier supports multi-tenant apps with tenants, which scope branding, routing, and preferences per customer or workspace. One integration serves many end customers, each with their own look and delivery rules. See [multi-tenancy](/docs/tenants/overview).

> **Does Courier provide an API and SDKs?**
>
> Courier is API-first, with a REST API for sending, users, preferences, and more. Server SDKs cover Node, Python, Go, Ruby, Java, PHP, and C#. Client SDKs cover React, JavaScript, iOS, Android, React Native, and Flutter, for building in-app inboxes and embedding preferences. Start from the [API reference](/docs/reference/api-overview) or [SDK libraries](/docs/sdk-libraries/sdks-overview).

> **Can I use Courier with AI coding agents?**
>
> Courier offers a [CLI](/docs/resources/cli), an [MCP server](/docs/resources/mcp), and [agent skills](/docs/resources/skills). AI coding agents use them to send messages, manage users, and build notification workflows from your development environment. See [Build with AI](/docs/get-started/build-with-ai) to get set up.

> **Is Courier SOC 2 compliant?**
>
> Courier maintains SOC 2 Type II, HIPAA, and PCI DSS programs, and supports GDPR and CCPA obligations. The [Security Portal](https://security.courier.com/) holds the current reports for a vendor review. See [Compliance](/docs/workspaces/compliance).

> **Can I self-host Courier?**
>
> Courier is a managed cloud platform, with no self-hosted or on-premise option. If data residency is the concern, the [EU datacenter](/docs/workspaces/datacenters) keeps notification data in Europe.


# Audiences
Source: https://www.courier.com/docs/recipients/lists-and-audiences/audiences

Rule-based groups that update as profiles change, addressed with audience_id.

An audience is a group Courier maintains. You write rules, and membership updates as profiles change.

Target one on a send with `audience_id`:

```json theme={null}
{
  "to": { "audience_id": "active-business-users" }
}
```

Create or update an audience with [Update an Audience](/docs/api-reference/audiences/update-an-audience), passing a `filter`. See the [Audiences API](/docs/api-reference/audiences/get-an-audience) for the full schema.

## How it works

Each condition in a filter names a profile `path`, an `operator`, and a `value`.

### Audience operators

Console labels and their API values:

| Category | Console | Code | Use case |
| - | - | - | - |
| Equality | is | `EQ` | Match an exact value (a plan, role, or status) |
| | isn't | `NEQ` | Exclude a value |
| String | includes | `INCLUDES` | Substring match (email domain, title) |
| | doesn't include | `OMIT` | Exclude a substring |
| | starts with | `STARTS_WITH` | Prefix match |
| | ends with | `ENDS_WITH` | Suffix match (`@acme-corp.com`) |
| Numeric | is greater than | `GT` | Above a threshold |
| | is greater than or equal to | `GTE` | At or above a limit |
| | is less than | `LT` | Below a threshold |
| | is less than or equal to | `LTE` | At or below a cap |
| Date | is after | `IS_AFTER` | After a date |
| | is before | `IS_BEFORE` | Before a date |
| Existence | exists | `EXISTS` | The field is present |

### Combining conditions

A filter is a group with an `operator` and a `filters` array. Use `AND` so every condition must match, or `OR` so at least one must. A condition inside `filters` can be another group. That nests rules like "on the pro plan AND (admin OR owner)":

```json theme={null}
{
  "filter": {
    "operator": "AND",
    "filters": [
      { "operator": "EQ", "path": "profile.custom.plan", "value": "pro" },
      {
        "operator": "OR",
        "filters": [
          { "operator": "EQ", "path": "profile.custom.role", "value": "admin" },
          { "operator": "EQ", "path": "profile.custom.role", "value": "owner" }
        ]
      }
    ]
  }
}
```

### How membership works

Courier pre-computes membership instead of evaluating every rule against every profile at send time. When a profile changes, Courier updates whether that user belongs to each audience. Changing an audience's rules starts a rebuild of its membership list.

At send time, Courier reads the stored membership. A rebuild of a large audience can take many minutes. A send during the rebuild reads a partially updated list. Wait for membership to settle before a large send. Check [Get an Audience](/docs/api-reference/audiences/get-an-audience) and spot-check [List Audience members](/docs/api-reference/audiences/list-audience-members). A [list
DOC](/docs/recipients/lists-and-audiences/lists) member, by contrast, is present the moment you add them.

### Scoping a send to a tenant

`context.tenant_id` on a send controls branding, preferences, and template variables for that tenant. It does **not** restrict which audience members receive the message. To send only to users in one tenant, add an inline `filters` array on the recipient. Use the `MEMBER_OF` operator with `path: tenant_id`:

```json theme={null}
{
  "to": {
    "audience_id": "active-business-users",
    "filters": [
      { "operator": "MEMBER_OF", "path": "tenant_id", "value": "acme-corp" }
    ]
  },
  "context": { "tenant_id": "acme-corp" }
}
```

A user must have tenant membership to pass the filter. Set it with [Add a user to a Tenant](/docs/api-reference/tenant-memberships/add-a-user-to-a-tenant).

## FAQ

> **Should I use an audience or a list?**
>
> Use an audience when membership follows from profile data and should update itself, like all pro-plan users. Use a [list
> DOC](/docs/recipients/lists-and-audiences/lists) when you decide membership by hand.

> **Can I nest AND and OR in one filter?**
>
> Any condition in a `filters` array can be a group with its own `operator` and `filters`.


# Lists
Source: https://www.courier.com/docs/recipients/lists-and-audiences/lists

Curated groups of users, addressed with list_id, including list ID patterns and wildcards.

A list is a group of users you curate. Membership changes only when you change it, and a member is in the list the moment you add them.

Use a list for hand-picked groups: beta testers, a VIP cohort, an internal team. When membership should follow from profile data, use an [audience
DOC](/docs/recipients/lists-and-audiences/audiences).

Browse lists and their members under [Directory → Lists](https://app.courier.com/directory/lists), or manage them over the API as below.

## How it works

Each list has a dotted-namespace `list_id` such as `acme-corp.beta-testers`. Target one on a send with `list_id`:

```json theme={null}
{
  "to": { "list_id": "acme-corp.beta-testers" }
}
```

The [Lists API](/docs/api-reference/lists/get-a-list) manages lists and their members. [Update a List](/docs/api-reference/lists/update-a-list) is an upsert, so it also creates one. The `/lists/{list_id}/subscriptions` endpoints add, replace, read, and remove members. [Subscribe a user Profile to a List](/docs/api-reference/lists/subscribe-a-user-profile-to-a-list) subscribes one user.

### List patterns

Because `list_id` is a dotted namespace, one pattern can target many lists at once. Set `list_pattern` on the recipient. `*` matches any single part. `**` is a trailing wildcard:

```json theme={null}
{
  "to": { "list_pattern": "acme-corp.*.beta-testers" }
}
```

The same pattern syntax filters lists on [List Lists](/docs/api-reference/lists/list-lists) through its `pattern` parameter.

Naming a list after an entity, such as `document.doc_a1b2.watchers`, turns this into per-entity subscriptions. [Notify everyone watching
GUIDE](/docs/guides/notify-everyone-watching) walks that pattern end to end.

#### Valid ids and patterns

A `list_id` holds up to six dot-separated segments. It can't be empty, include `*`, `#`, or a space, start or end with a period, or hold two periods in a row.

A wildcard replaces one whole segment, never part of one, so every `*` follows a period. Courier rejects these patterns:

| Pattern | Why |
| - | - |
| `*`, `**` | Matches every list. At least one segment has to be literal. |
| `*.*` | Same reason: nothing but wildcards and periods. |
| `news*` | A wildcard can't match part of a segment. Use `news.*`. |
| `news.*.**` | A `*` can't be followed later by `**`. |
| `news.***` | At most two consecutive asterisks. |
| `news.**.weekly` | `**` is trailing only. |
| `.news`, `news.` | Can't start or end with a period. |
| `news..weekly` | No consecutive periods. |
| `news weekly` | No spaces. |

### Scoping a list send to a tenant

`context.tenant_id` controls branding, preferences, and template variables. It does **not** restrict which list members receive the message. To send only to users in one tenant, add an inline `filters` array with the `MEMBER_OF` operator:

```json theme={null}
{
  "to": {
    "list_id": "acme-corp.beta-testers",
    "filters": [
      { "operator": "MEMBER_OF", "path": "tenant_id", "value": "acme-corp" }
    ]
  },
  "context": { "tenant_id": "acme-corp" }
}
```

Users must have tenant membership, set with [Add a user to a Tenant](/docs/api-reference/tenant-memberships/add-a-user-to-a-tenant), to pass the filter.

## FAQ

> **Should I use a list or an audience?**
>
> Use a list when you pick members by hand and want membership exact, like beta testers or VIPs. Use an [audience
> DOC](/docs/recipients/lists-and-audiences/audiences) when membership follows from profile data and should update itself.

> **Can I send to several lists at once?**
>
> Use `list_pattern` with `*` for a single part, or `**` as a trailing wildcard, to match many `list_id`s in one send.


# Lists and audiences
Source: https://www.courier.com/docs/recipients/lists-and-audiences/overview

Address a group instead of naming each person: curated lists or rule-based audiences.

Address a group instead of naming every person. Courier resolves membership at send time and delivers one message per member.

There are two kinds of group, and the difference is who decides membership.

> **[Lists](/docs/recipients/lists-and-audiences/lists)**
>
> You choose the members. Add and remove them yourself, and membership changes the moment you do.

> **[Audiences](/docs/recipients/lists-and-audiences/audiences)**
>
> You write a rule about profile data. Courier keeps membership current as profiles change.

## Which one to use

| | List | Audience |
| - | - | - |
| Membership decided by | You, one member at a time | A rule you write about profile data |
| Send with | `list_id` | `audience_id` |
| A member appears | Immediately | Once the profile change propagates |
| Best for | A set that doesn't follow from your data, like a beta cohort or a webinar signup | A set your data already describes, like every admin on a paid plan |

Use a list when you can't express the group as a query. Use an audience when you can, so you never maintain it by hand.

A list member is present the moment you add them. A large audience rebuild takes minutes, and a send reads the stored membership, so let a rule change settle before a critical send.

To scope a send to one tenant, use the `MEMBER_OF` operator inline on the recipient. It's a send-time filter, not part of a list or audience definition.

Preferences still apply either way. A member who opted out of the template's topic is recorded as `UNSUBSCRIBED` rather than delivered.


# Users and profiles
Source: https://www.courier.com/docs/recipients/overview

Store a user's email, phone, tokens, and chat IDs once, then send by user_id.

A user is the stored record Courier uses to reach one person. Send by `user_id` and Courier resolves the addresses.

That record is the profile. It holds email, phone number, device tokens, locale, timezone, and custom attributes, so you never repeat contact details on a request. Preferences, lists, and audiences attach to it.

```json theme={null}
{
  "profile": {
    "name": "Sarah Bennett",
    "email": "sarah@acme-corp.com",
    "phone_number": "+15551234567",
    "locale": "en-us",
    "custom": { "company": "Acme Corp", "plan": "business" }
  }
}
```

## Save a user

Creating and updating are the same call, so this is safe to run whenever your own record changes:

```javascript Node.js theme={null}
await client.profiles.create("user_123", {
  profile: {
    email: "sarah@acme-corp.com",
    phone_number: "+15551234567",
  },
});
```

```python Python theme={null}
client.profiles.create(
    "user_123",
    profile={
        "email": "sarah@acme-corp.com",
        "phone_number": "+15551234567",
    },
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "email": "sarah@acme-corp.com",
      "phone_number": "+15551234567"
    }
  }'
```

```ruby Ruby theme={null}
courier.profiles.create(
  "user_123",
  profile: {
    email: "sarah@acme-corp.com",
    phone_number: "+15551234567"
  }
)
```

```go Go theme={null}
_, err := client.Profiles.New(context.TODO(), "user_123", courier.ProfileNewParams{
	Profile: map[string]any{
		"email":        "sarah@acme-corp.com",
		"phone_number": "+15551234567",
	},
})
```

```java Java theme={null}
ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .putAdditionalProperty("phone_number", JsonValue.from("+15551234567"))
        .build())
    .build();

client.profiles().create(params);
```

```php PHP theme={null}
$client->profiles->create(
  'user_123',
  profile: [
    'email' => 'sarah@acme-corp.com',
    'phone_number' => '+15551234567',
  ],
);
```

```csharp C# theme={null}
await client.Profiles.Create(
    "user_123",
    new()
    {
        Profile = new Dictionary<string, JsonElement>
        {
            { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
            { "phone_number", JsonSerializer.SerializeToElement("+15551234567") },
        },
    }
);
```

```bash CLI theme={null}
courier profiles create user_123 \
  --api-key "$COURIER_API_KEY" \
  --profile '{"email": "sarah@acme-corp.com", "phone_number": "+15551234567"}'
```

```text MCP theme={null}
With Courier MCP, save user_123 with the email sarah@acme-corp.com and the phone number +15551234567.
```

The `user_id` is yours to choose. Use whatever your own system already calls that person, so you never keep a mapping table.

## What each channel needs

One field per channel, and Courier picks the right one per send:

| Channel | Field on the profile | Example |
| :- | :- | :- |
| Email | `email` | `sarah@acme-corp.com` |
| SMS | `phone_number`, in E.164 | `+15551234567` |
| WhatsApp | `phone_number`, in E.164 | `+15551234567` |
| Push | none. Device tokens are stored outside the profile | Registered by the [mobile SDK&#xA;DOC](/docs/sdk-libraries/sdks-overview) or the Token API |
| Inbox | none. The `user_id` is the address | |
| Chat | the provider's own object, such as `slack` or `ms_teams` | `{ "access_token": "xoxb-…", "email": "…" }` |

A profile holds every field at once. Save `email` and `phone_number` together and one template can reach either channel without a second write.

Each category introduction carries its own providers' fields: [email
DOC](/docs/integrations/email/overview), [SMS
DOC](/docs/integrations/sms/overview), [push
DOC](/docs/integrations/push/overview), and [chat
DOC](/docs/integrations/direct-message/overview).

## Send by user id

Once the profile exists, a send names the person and nothing else:

```javascript Node.js highlight={3} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});
```

```python Python highlight={3} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

```bash cURL highlight={6} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby highlight={3} theme={null}
response = courier.send_.message(
  message: {
    to: {user_id: "user_123"},
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)
```

```go Go highlight={4} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .template("nt_01kx4h2jdafq8bk9aftxak4b40")
    .build();

client.send().message(SendMessageParams.builder().message(message).build());
```

```php PHP highlight={3} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40
```

```text MCP theme={null}
With Courier MCP, send my welcome template to user_123.
```

Which channel it goes out on is the template's and [routing
DOC](/docs/send/routing)'s decision, not the recipient's.

## Address someone you haven't saved

An address in the `to` object sends with no stored profile. It reaches the recipient without creating or updating one, so there's nothing there for preferences to attach to. A [saved user](#send-by-user-id) stays the norm, because preferences, lists, tenants, and the inbox all key off one.

Each channel takes its own field or object:

**Email**

```json theme={null}
{ "to": { "email": "sarah@acme-corp.com" } }
```

Every [email provider
DOC](/docs/integrations/email/overview) reads this field.

**SMS**

```json theme={null}
{ "to": { "phone_number": "+15551234567" } }
```

E.164 only. Every [SMS provider
DOC](/docs/integrations/sms/overview) reads it, and [WhatsApp
DOC](/docs/integrations/direct-message/whatsapp) reads the same field.

**Push**

```json theme={null}
{ "to": { "apn": { "token": "YOUR_APNS_TOKEN" } } }
```

One key per provider: `apn`, `firebase-fcm`, or `expo`. Each takes a `token` or a `tokens` array. See [push providers
DOC](/docs/integrations/push/overview).

**Slack**

```json theme={null}
{ "to": { "slack": { "access_token": "xoxb-xxxxx", "email": "sarah@acme-corp.com" } } }
```

Address by `email`, `channel`, or `user_id`, always with the `access_token`. See [Slack
DOC](/docs/integrations/direct-message/slack).

**Microsoft Teams**

```json theme={null}
{ "to": { "ms_teams": { "tenant_id": "YOUR_TEAMS_TENANT_ID", "service_url": "https://smba.trafficmanager.net/amer/", "user_id": "TEAMS_USER_ID" } } }
```

`tenant_id` and `service_url` are always required. Then one of `user_id`, `email`, `channel_id`, `channel_name`, or `conversation_id`. See [Microsoft Teams
DOC](/docs/integrations/direct-message/microsoft-teams).

**Discord**

```json theme={null}
{ "to": { "discord": { "channel_id": "DISCORD_CHANNEL_ID" } } }
```

A `channel_id` for a channel, or a `user_id` for a direct message. See [Discord
DOC](/docs/integrations/direct-message/discord).

**Webhook**

```json theme={null}
{ "to": { "webhook": { "url": "https://api.acme-corp.com/courier-events" } } }
```

Takes `method`, `headers`, and an `authentication` object as well. See [Webhook
DOC](/docs/integrations/other/webhook-integration).

**Inbox**

```json theme={null}
{ "to": { "user_id": "user_123" } }
```

The inbox has no direct form. The `user_id` is the address, because that is who the SDK signs in as. See [Inbox
DOC](/docs/in-app/overview).

> [!NOTE]
>
> **The two combine.** Courier merges an inline value over the saved profile **for that message only**, so this sends to the override address and never changes the profile:
>
> ```json theme={null}
> { "to": { "user_id": "user_123", "email": "billing@acme-corp.com" } }
> ```

## When to write a profile

**On signup**, in the same handler that creates the user in your own database. [Clerk
GUIDE](/docs/guides/notify-from-clerk), [Supabase
GUIDE](/docs/guides/notify-from-supabase), [Firebase Auth
GUIDE](/docs/guides/notify-from-firebase-auth), and [Auth0
GUIDE](/docs/guides/notify-from-auth0) each show that call in place.

**Whenever an address changes.** `POST` merges, so writing one field leaves the rest alone.

**Not on every send.** A profile write per send costs a round trip and buys nothing, because the profile is already there.

## The profile object

A profile accepts three kinds of field:

* **OpenID Connect standard claims.** `email`, `phone_number`, `name`, `given_name`, `family_name`, `locale`, `zoneinfo`, `birthdate`, and more.
* **`custom`.** A free-form object for anything specific to your app. Courier also accepts top-level keys outside the OIDC claim set, but they read clearest under `custom`.
* **Provider-specific keys.** `apn`, `airship`, and others, for inline channel tokens.

```json theme={null}
{
  "profile": {
    "name": "Sarah Bennett",
    "email": "sarah@acme-corp.com",
    "phone_number": "+15551234567",
    "locale": "en-us",
    "custom": {
      "company": "Acme Corp",
      "plan": "business",
      "role": "admin"
    }
  }
}
```

Every profile field is available in templates. Reference top-level fields as `{profile.name}` and custom data as `{profile.custom.company}`.

Courier also reads `locale` at send time to pick which [translation
DOC](/docs/design/elemental/locales) of a template to send. Codes match exactly, including case, so store the same form your templates use, such as `es` or `es-mx`.

### Merge, replace, or patch

The Profiles API has four operations on `/profiles/{user_id}`. They differ in what happens to fields you leave out:

| Operation | Method | Effect on omitted fields |
| - | - | - |
| Merge / create | `POST` | Preserved. Supplied values are merged into the existing profile, or create it. |
| Replace | `PUT` | Removed. The profile becomes exactly what you send. |
| Patch | `PATCH` | Untouched. Applies a list of JSON-patch operations (`op`, `path`, `value`). |
| Delete | `DELETE` | The whole profile is removed. |

Use `POST` for everyday updates so you never drop data. Use `PUT` only for a deliberate full overwrite. The Node SDK names these `profiles.create`, `profiles.replace`, `profiles.update` for patch, and `profiles.delete`.

The Profiles API carries no published per-second rate limit, unlike the [Send API](/docs/api-reference/send/send-a-message). For a large sync, throttle your loop or import a CSV in the console.

### Device tokens

Push reaches a device, not an address, so a user carries a device token per device they sign in on. The Courier mobile SDKs register and refresh those tokens for you, on iOS, Android, Flutter, and React Native.

[Set up push notifications
GUIDE](/docs/guides/set-up-mobile-push) walks the whole thing: a provider, the SDK, and a test push to your own device.

Tokens attach to the `user_id` rather than to the profile body, so Courier expires a dead one without touching the profile, and replacing a profile with `PUT` doesn't remove stored tokens either. A backend that manages tokens itself writes them with the [Device Tokens API](/docs/api-reference/device-tokens/add-a-token-to-a-user).

## FAQ

> **What should I use for the user\_id?**
>
> The id your own system already uses for that person. Courier accepts any string, so matching your database means no mapping table and no second lookup.

> **Does sending to a new user\_id create the profile?**
>
> A send looks up an existing profile, it doesn't persist one from the `to` object. Create the profile with [Create a Profile](/docs/api-reference/user-profiles/create-a-profile) first, or pass inline contact details for a one-off. The Inbox is the exception. Authenticating a user registers them.

> **Does saving a profile twice create two users?**
>
> `user_id` is the key, so a second write to the same id updates that user. [Create a Profile](/docs/api-reference/user-profiles/create-a-profile) is an upsert.

> **Can one user hold email, phone, and a Slack token at once?**
>
> One profile holds every address at once, which is the point. Save every address you have and the same send reaches whichever channel the template and [routing
> DOC](/docs/send/routing) pick.

> **Where do push device tokens get saved?**
>
> The mobile SDKs register them on `signIn`, or your backend writes them with [Add a token to a user](/docs/api-reference/device-tokens/add-a-token-to-a-user). Either way they attach to the `user_id` rather than to the profile body. See [Set up mobile push
> GUIDE](/docs/guides/set-up-mobile-push).

> **Can I export or dump all of my users?**
>
> Courier has no endpoint to list every `user_id`, export all profiles, or return a total user count. Retrieve profiles one at a time with [Get a Profile](/docs/api-reference/user-profiles/get-a-profile). List the users in one tenant with [Get users in Tenant](/docs/api-reference/tenants/get-users-in-tenant).

> **Is 'recipient' the same as 'user'?**
>
> Courier uses them interchangeably. A recipient identified by `user_id` is a stored user profile.

> **What is the difference between POST and PUT on a profile?**
>
> `POST` merges, so fields you omit are preserved. `PUT` replaces, so the profile becomes exactly the object you send and omitted fields are removed. Use `POST` for partial updates, `PUT` only for a deliberate full overwrite.

> **How do I store data that is not an OIDC claim?**
>
> Put it under `custom`. It is free-form, and every key is available in templates as `{profile.custom.plan}`.


# Manage user preferences with the API
Source: https://www.courier.com/docs/recipients/preferences/api

Read and update a user's topic preferences and channel routing, per user or per tenant, and track changes.

> [!NOTE]
>
> The [preferences model & API surface
> DOC](/docs/recipients/preferences/model) and [how preferences resolve
> DOC](/docs/recipients/preferences/overview) cover the concepts behind this API.

The User Preferences API reads and writes one user's topic opt-ins and per-topic channel choices, one topic at a time or the whole set at once. Call it from your backend with your workspace API key (the examples below), or from your frontend with a [client SDK](#client-sdks) as the signed-in user. Every call needs a `user_id`, the same ID you send to, and single-topic calls also need a `topic_id`.

## Prerequisites

* [Your subscription topics under Platform → Preferences](https://app.courier.com/~/test/platform/preferences)
* [A Courier API key](https://app.courier.com/settings/api-keys)

## Read a user's preferences

Reading a user's preferences returns every topic they have an override for, with their `status`, the topic's `default_status`, and any `custom_routing`. Fetch them from the [get preferences endpoint](/docs/api-reference/user-preferences/get-users-preferences):

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const preference = await client.users.preferences.retrieve('user_123');

console.log(preference.items);
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
preference = client.users.preferences.retrieve(
    user_id="user_123",
)
print(preference.items)
```

```bash cURL theme={null}
curl -X GET https://api.courier.com/users/user_123/preferences \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

preference = courier.users.preferences.retrieve("user_123")

puts(preference)
```

```go Go theme={null}
preference, err := client.Users.Preferences.Get(
	context.TODO(),
	"user_123",
	courier.UserPreferenceGetParams{},
)
```

```java Java theme={null}
PreferenceRetrieveResponse preference = client.users().preferences().retrieve("user_123");
```

```php PHP theme={null}
$preference = $client->users->preferences->retrieve('user_123');
```

```csharp C# theme={null}
PreferenceRetrieveParams parameters = new() { UserID = "user_123" };

var preference = await client.Users.Preferences.Retrieve(parameters);
```

```bash CLI theme={null}
courier users:preferences retrieve \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123
```

```text MCP theme={null}
With Courier MCP, show me user_123's notification preferences.
```

## Update one topic

Updating one topic creates or changes a single preference. Wrap it in a `topic` object with a `status` of `OPTED_IN` or `OPTED_OUT`. `REQUIRED` is a topic default set in the editor, not a user choice, and the API rejects opting a user out of a required topic. To set the channels the user wants, add `has_custom_routing: true` and list them in `custom_routing` (`email`, `sms`, `push`, `inbox`, `direct_message`, `webhook`). To opt out entirely, send `{ "topic": { "status": "OPTED_OUT" } }` with no routing. To put the user on one of the topic's digest schedules, add `digest_schedule_id`, as in [Which schedule a user is on
GUIDE](/docs/guides/send-a-daily-digest#which-schedule-a-user-is-on). Call the [update topic endpoint](/docs/api-reference/user-preferences/update-or-create-user-preferences-for-a-subscription-topic):

> [!NOTE]
>
> Where custom routing over the API isn't available, the single-topic write returns `402`, the bulk `PUT` returns `400`, and the bulk `POST` returns `200` with a per-item error. Only `status` is written.

```javascript Node.js highlight={9-10} theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const response = await client.users.preferences.updateOrCreateTopic('pt_01kx4h2jdafq8bk996nn92357r', {
  user_id: 'user_123',
  topic: {
    status: 'OPTED_IN',
    has_custom_routing: true,
    custom_routing: ['inbox', 'email'],
  },
});

console.log(response.message);
```

```python Python highlight={7-8,10-11} theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.users.preferences.update_or_create_topic(
    topic_id="pt_01kx4h2jdafq8bk996nn92357r",
    user_id="user_123",
    topic={
        "status": "OPTED_IN",
        "has_custom_routing": True,
        "custom_routing": ["inbox", "email"],
    },
)
print(response.message)
```

```bash cURL highlight={4} theme={null}
curl -X PUT https://api.courier.com/users/user_123/preferences/pt_01kx4h2jdafq8bk996nn92357r \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topic": { "status": "OPTED_IN", "has_custom_routing": true, "custom_routing": ["inbox", "email"] } }'
```

```ruby Ruby highlight={5,8} theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.users.preferences.update_or_create_topic(
  "pt_01kx4h2jdafq8bk996nn92357r",
  user_id: "user_123",
  topic: {status: :OPTED_IN}
)

puts(response)
```

```go Go highlight={6-7} theme={null}
response, err := client.Users.Preferences.UpdateOrNewTopic(
	context.TODO(),
	"pt_01kx4h2jdafq8bk996nn92357r",
	courier.UserPreferenceUpdateOrNewTopicParams{
		UserID: "user_123",
		Topic: courier.UserPreferenceUpdateOrNewTopicParamsTopic{
			Status:           shared.PreferenceStatusOptedIn,
			HasCustomRouting: courier.Bool(true),
			CustomRouting:    []shared.ChannelClassification{shared.ChannelClassificationInbox, shared.ChannelClassificationEmail},
		},
	},
)
```

```java Java highlight={3-5} theme={null}
PreferenceUpdateOrCreateTopicParams params = PreferenceUpdateOrCreateTopicParams.builder()
    .userId("user_123")
    .topicId("pt_01kx4h2jdafq8bk996nn92357r")
    .topic(PreferenceUpdateOrCreateTopicParams.Topic.builder()
        .status(PreferenceStatus.OPTED_IN)
        .build())
    .build();
PreferenceUpdateOrCreateTopicResponse response = client.users().preferences().updateOrCreateTopic(params);
```

```php PHP highlight={4-5} theme={null}
$response = $client->users->preferences->updateOrCreateTopic(
  'pt_01kx4h2jdafq8bk996nn92357r',
  userID: 'user_123',
  topic: [
    'status' => PreferenceStatus::OPTED_IN,
    'customRouting' => [
      ChannelClassification::INBOX, ChannelClassification::EMAIL
    ],
    'hasCustomRouting' => true,
  ],
);
```

```csharp C# highlight={5,7} theme={null}
PreferenceUpdateOrCreateTopicParams parameters = new()
{
    UserID = "user_123",
    TopicID = "pt_01kx4h2jdafq8bk996nn92357r",
    Topic = new()
    {
        Status = PreferenceStatus.OptedIn,
        CustomRouting =
        [
            ChannelClassification.Inbox, ChannelClassification.Email
        ],
        HasCustomRouting = true,
    },
};

var response = await client.Users.Preferences.UpdateOrCreateTopic(parameters);
```

```bash CLI highlight={1,4-5} theme={null}
courier users:preferences update-or-create-topic \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --topic-id pt_01kx4h2jdafq8bk996nn92357r \
  --topic '{status: OPTED_IN}'
```

```text MCP theme={null}
With Courier MCP, opt user_123 into that topic and route it to inbox and email.
```

To reset a topic to its default, [delete the topic override](/docs/api-reference/user-preferences/delete-user-subscription-topic).

## Client SDKs

From your frontend, a client SDK updates the **signed-in user's** own preferences. It authenticates with a short-lived JWT rather than your API key, issued for that user with the `read:preferences` and `write:preferences` scopes. See [Authenticate users
DOC](/docs/in-app/authenticate-users) for the token flow. It can only read and write that one user's data. The [embedded preference center
GUIDE](/docs/guides/build-a-preference-center#embedded-component) calls this same client.

Every client SDK exposes the same `preferences` methods: `getUserPreferences()` to list, `getUserPreferenceTopic()` to read one, and `putUserPreferenceTopic()` to opt a topic in or out and set its channels. On the web, React, Web Components, Vue, and Angular all call the shared `@trycourier/courier-js` client (React also through the `useCourier()` hook). The mobile SDKs expose an identical client.

```tsx React highlight={6} theme={null}
import { useCourier } from "@trycourier/courier-react";

// After courier.shared.signIn({ userId, jwt }) for the signed-in user:
const courier = useCourier();

await courier.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_OUT",
  hasCustomRouting: true,
  customRouting: ["email", "push"],
});
```

```typescript Web Components highlight={5} theme={null}
import { Courier } from "@trycourier/courier-js";

Courier.shared.signIn({ userId: "user_123", jwt });

await Courier.shared.client?.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_OUT",
  hasCustomRouting: true,
  customRouting: ["email", "push"],
});
```

```typescript Vue highlight={6} theme={null}
// Vue uses the same @trycourier/courier-js client behind its component wrapper.
import { Courier } from "@trycourier/courier-js";

Courier.shared.signIn({ userId: "user_123", jwt });

await Courier.shared.client?.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_OUT",
  hasCustomRouting: true,
  customRouting: ["email", "push"],
});
```

```typescript Angular highlight={6} theme={null}
// Angular uses the same @trycourier/courier-js client behind its component wrapper.
import { Courier } from "@trycourier/courier-js";

Courier.shared.signIn({ userId: "user_123", jwt });

await Courier.shared.client?.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_OUT",
  hasCustomRouting: true,
  customRouting: ["email", "push"],
});
```

```swift iOS highlight={3} theme={null}
let client = CourierClient(jwt: jwt, userId: "user_123")

try await client.preferences.putUserPreferenceTopic(
    topicId: "TOPIC_ID",
    status: .optedOut,
    hasCustomRouting: true,
    customRouting: [.email, .push]
)
```

```kotlin Android highlight={3} theme={null}
val client = CourierClient(jwt = jwt, userId = "user_123")

client.preferences.putUserPreferenceTopic(
    topicId = "TOPIC_ID",
    status = CourierPreferenceStatus.OPTED_OUT,
    hasCustomRouting = true,
    customRouting = listOf(CourierPreferenceChannel.EMAIL, CourierPreferenceChannel.PUSH)
)
```

```dart Flutter highlight={3} theme={null}
final client = CourierClient(jwt: jwt, userId: "user_123");

await client.preferences.putUserPreferenceTopic(
  topicId: "TOPIC_ID",
  status: CourierUserPreferencesStatus.optedOut,
  hasCustomRouting: true,
  customRouting: [CourierUserPreferencesChannel.email, CourierUserPreferencesChannel.push],
);
```

```tsx React Native highlight={9} theme={null}
import {
  CourierClient,
  CourierUserPreferencesStatus,
  CourierUserPreferencesChannel,
} from "@trycourier/courier-react-native";

const client = new CourierClient({ userId: "user_123", jwt });

await client.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: CourierUserPreferencesStatus.OptedOut,
  hasCustomRouting: true,
  customRouting: [CourierUserPreferencesChannel.Email, CourierUserPreferencesChannel.Push],
});
```

## Import a full preference set (bulk)

Two bulk endpoints set many topics for a user in one request, up to 50 topics each. They differ in what happens to the topics you don't send.

* **Replace** makes the body the user's complete override set. Topics you send are created or updated, and any existing override you leave out is reset to its default. Validation is atomic: one invalid topic fails the whole request.
* **Update** is additive. It touches only the topics you send and processes each independently, returning successes in `items` and failures in `errors`.

Send the [replace](/docs/api-reference/user-preferences/replace-user-preferences-in-bulk) or [update](/docs/api-reference/user-preferences/update-user-preferences-in-bulk) bulk request:

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const response = await client.users.preferences.bulkReplace('user_123', {
  topics: [
    {
      topic_id: 'pt_01kx4h2jdafq8bk996nn92357r',
      status: 'OPTED_IN',
      has_custom_routing: true,
      custom_routing: ['inbox', 'email'],
    },
  ],
});

console.log(response.deleted);
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.users.preferences.bulk_replace(
    user_id="user_123",
    topics=[{
        "topic_id": "pt_01kx4h2jdafq8bk996nn92357r",
        "status": "OPTED_IN",
        "has_custom_routing": True,
        "custom_routing": ["inbox", "email"],
    }],
)
print(response.deleted)
```

```bash cURL theme={null}
curl -X PUT https://api.courier.com/users/user_123/preferences \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topics": [ { "topic_id": "pt_01kx4h2jdafq8bk996nn92357r", "status": "OPTED_IN", "has_custom_routing": true, "custom_routing": ["inbox", "email"] } ] }'
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.users.preferences.bulk_replace(
  "user_123",
  topics: [{status: :OPTED_IN, topic_id: "pt_01kx4h2jdafq8bk996nn92357r"}]
)

puts(response)
```

```go Go theme={null}
response, err := client.Users.Preferences.BulkReplace(
	context.TODO(),
	"user_123",
	courier.UserPreferenceBulkReplaceParams{
		Topics: []courier.UserPreferenceBulkReplaceParamsTopic{{
			TopicID:          "pt_01kx4h2jdafq8bk996nn92357r",
			Status:           "OPTED_IN",
			HasCustomRouting: courier.Bool(true),
			CustomRouting:    []shared.ChannelClassification{shared.ChannelClassificationInbox, shared.ChannelClassificationEmail},
		}},
	},
)
```

```java Java theme={null}
PreferenceBulkReplaceParams params = PreferenceBulkReplaceParams.builder()
    .userId("user_123")
    .addTopic(PreferenceBulkReplaceParams.Topic.builder()
        .status(PreferenceBulkReplaceParams.Topic.Status.OPTED_IN)
        .topicId("pt_01kx4h2jdafq8bk996nn92357r")
        .build())
    .build();
PreferenceBulkReplaceResponse response = client.users().preferences().bulkReplace(params);
```

```php PHP theme={null}
$response = $client->users->preferences->bulkReplace(
  'user_123',
  topics: [
    [
      'status' => 'OPTED_IN',
      'topicID' => 'pt_01kx4h2jdafq8bk996nn92357r',
      'customRouting' => [
        ChannelClassification::INBOX, ChannelClassification::EMAIL
      ],
      'hasCustomRouting' => true,
    ],
  ],
);
```

```csharp C# theme={null}
PreferenceBulkReplaceParams parameters = new()
{
    UserID = "user_123",
    Topics =
    [
        new()
        {
            Status = Status.OptedIn,
            TopicID = "pt_01kx4h2jdafq8bk996nn92357r",
            CustomRouting =
            [
                ChannelClassification.Inbox, ChannelClassification.Email
            ],
            HasCustomRouting = true,
        },
    ],
};

var response = await client.Users.Preferences.BulkReplace(parameters);
```

```bash CLI theme={null}
courier users:preferences bulk-replace \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --topic '{status: OPTED_IN, topic_id: pt_01kx4h2jdafq8bk996nn92357r}'
```

Replace is the usual way to bring subscription data from another system into Courier. Send only the topics where a user differs from the default. The rest fall back automatically. Because it is idempotent, you can re-run the import safely, keep users in sync with a source of truth, or resume a backfill mid-loop. Each bulk call covers one user and up to 50 topics, so a backfill iterates your user base. Throttle the loop as you go.

## Scope to a tenant

If your app uses [Tenants
DOC](/docs/tenants/overview), scope any read or write to one Tenant with a `tenant_id`. On REST that is the `?tenant_id=` query parameter. On the SDKs it is the `tenant_id` argument on any method above. A user's per-tenant preferences are independent of their global preferences.

The read endpoint returns the topic-level `default_status`, not a tenant's default preferences, even with a `tenant_id`. To set what a tenant defaults to, see [Set tenant default preferences
DOC](/docs/tenants/preferences).

## Track preference changes

Courier records each time a user opts in, opts out, or changes a topic's channels.

### Read the change history via API

[List preference changes](/docs/api-reference/preference-topics/list-preference-changes) returns entries newest first. Each is one change to one topic, and `previous` holds the value it replaced. Pass `since` for changes from a date or time onward, and `user_id` for one user's history. Add `tenant_id` with `user_id` to narrow to one tenant.

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const changes = await client.workspacePreferences.listLogs({
  since: '2026-09-01',
});

console.log(changes.items);
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
changes = client.workspace_preferences.list_logs(
    since="2026-09-01",
)
print(changes.items)
```

```bash cURL theme={null}
curl -X GET "https://api.courier.com/preferences/logs?since=2026-09-01" \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

changes = courier.workspace_preferences.list_logs(since: "2026-09-01")

puts(changes)
```

```go Go theme={null}
changes, err := client.WorkspacePreferences.ListLogs(
	context.TODO(),
	courier.WorkspacePreferenceListLogsParams{
		Since: courier.String("2026-09-01"),
	},
)
```

```java Java theme={null}
PreferenceLogsListResponse changes = client.workspacePreferences().listLogs(
    WorkspacePreferenceListLogsParams.builder()
        .since("2026-09-01")
        .build()
);
```

```php PHP theme={null}
$changes = $client->workspacePreferences->listLogs(since: '2026-09-01');
```

```csharp C# theme={null}
WorkspacePreferenceListLogsParams parameters = new() { Since = "2026-09-01" };

var changes = await client.WorkspacePreferences.ListLogs(parameters);
```

```bash CLI theme={null}
courier workspace-preferences list-logs \
  --api-key "$COURIER_API_KEY" \
  --since 2026-09-01
```

A page holds 25 entries by default and up to 100 with `limit`. While `paging.more` is `true`, pass `paging.cursor` back as `cursor` to get the next page. The endpoint allows one request every two seconds, so fetch pages one at a time.

### Receive changes as webhook events

Courier also sends each change to your [outbound webhooks
DOC](/docs/monitor/webhooks/outbound) as a `preferences:user:updated` [event
DOC](/docs/monitor/webhooks/events#preferencesuserupdated). Its `data` is the same entry the change history returns, with the same `id`, so you can match an event to its entry.

### Mirror preferences in another system

To keep a copy of users' choices in your CRM or database:

1. Load each user's current preferences with [Get user's Preferences](/docs/api-reference/user-preferences/get-users-preferences).
2. Apply each `preferences:user:updated` event as it arrives.
3. After your endpoint has been down, read the change history with `since` set to the last `timestamp` you applied. Apply the entries oldest first, and skip any `id` you've already applied.

Resetting a topic to its default removes the user's override, so it doesn't add an entry or send an event. That includes calls to [Delete user Subscription Topic](/docs/api-reference/user-preferences/delete-user-subscription-topic) and the topics a bulk replace lists in `deleted`. Apply those resets to your copy when your code makes the calls.

## Verify

**1. Update a topic and read it back**

Update a topic to `OPTED_OUT`, then [read it back](/docs/api-reference/user-preferences/get-user-subscription-topic) and confirm the `status`.

**2. Confirm the send is blocked**

Send a message mapped to that topic and confirm the log shows it blocked as `UNSUBSCRIBED`.

**3. Re-run an import**

For an import, re-run the same bulk replace and confirm the result is unchanged (it is idempotent).


# Subscription topics and sections
Source: https://www.courier.com/docs/recipients/preferences/model

Topics, sections, default states, and custom routing, and the API that reads and writes them.

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
DOC](/docs/recipients/preferences/preferences-editor). 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
DOC](/docs/recipients/preferences/overview).

## 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
  DOC](/docs/recipients/preferences/overview#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 user's Preferences](/docs/api-reference/user-preferences/get-users-preferences) | List a user's preferences. |
| [Replace user Preferences in bulk](/docs/api-reference/user-preferences/replace-user-preferences-in-bulk) | Replace a user's entire override set (bulk, atomic). |
| [Update user Preferences in bulk](/docs/api-reference/user-preferences/update-user-preferences-in-bulk) | Additively update preferences without touching others (bulk, partial). |
| [Get user Subscription Topic](/docs/api-reference/user-preferences/get-user-subscription-topic) | Get one topic's preference. |
| [Update or create user Preferences for a Subscription Topic](/docs/api-reference/user-preferences/update-or-create-user-preferences-for-a-subscription-topic) | Create or update one topic's preference. |
| [Delete user Subscription Topic](/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
DOC](/docs/recipients/preferences/api).

### Reading current state

[Get user's Preferences](/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
DOC](/docs/recipients/preferences/overview).

### Topic and section catalog

The Workspace Preferences API manages the topics and sections themselves. List a section's topics with [List Topics in Section](/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
DOC](/docs/recipients/preferences/preferences-editor) instead of by hand.

## Digest schedules

A digest collects a topic's messages and delivers them together on a schedule. A busy topic becomes one daily or weekly summary instead of a stream. You configure digests **per subscription topic**, in the [Preferences Editor
GUIDE](/docs/guides/build-a-preference-center#configure-the-topics) or with the topic's `digest` object over the API. Either way you link a digest template and define the schedule options recipients choose from.

**How a digest sends:** when a recipient is on a digest schedule for a topic, Courier collects the topic's messages instead of delivering each one. It renders the digest template at the scheduled time. Collected messages show a `DIGESTED` status in your logs. Recipients on the **Instant** schedule receive each message immediately, with no batching.

**Schedule options** are the frequencies recipients can pick (up to four per topic): Instant, Daily, Weekly, Every weekday, Multiple days, or Monthly. Each scheduled option carries a time and timezone. The option marked default is where users start, or the first option when none is marked.

**Categories** (up to five per topic) separate kinds of items within one digest, each with a retain rule (first, last, highest, or lowest ten). The digest template receives the collected items grouped by category name:

```json theme={null}
{
  "category_name": {
    "count": 25,
    "items": []
  }
}
```

**Trigger empty:** by default Courier skips a scheduled digest that collected nothing. Turn on Trigger empty to send it anyway, useful when your own system supplies the data the digest renders.

The API covers all of this. The `digest` object on [Create Topic in Section](/docs/api-reference/preference-topics/create-topic-in-section) and its replace counterpart sets the template, schedules, categories, and Trigger empty, and topic reads return each schedule's `schedule_id`. Creating a topic with a `digest` object that has no schedules gets rejected. Send `digest: null` on a replace to turn a digest off. A user's own schedule is `digest_schedule_id` on their topic preference. The API also offers [Release a digest early](/docs/api-reference/digests/release-a-digest-early) and [List digest instances](/docs/api-reference/digests/list-digest-instances). For time-based batching inside a workflow, see the [Digest node
DOC](/docs/journeys/nodes/digest).

## Audit trail

Courier records a history of preference changes. In the dashboard, open the [Users section](https://app.courier.com/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, [List preference changes](/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
DOC](/docs/monitor/webhooks/events#preferencesuserupdated). To read the history or keep another system in sync, see [Track preference changes
DOC](/docs/recipients/preferences/api#track-preference-changes).

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

## FAQ

> **Is there a bulk preferences endpoint?**
>
> Two bulk endpoints exist, both per user. [Replace user Preferences in bulk](/docs/api-reference/user-preferences/replace-user-preferences-in-bulk) replaces a user's full override set atomically. [Update user Preferences in bulk](/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.

> **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
> GUIDE](/docs/guides/send-a-daily-digest).

> **Is there a webhook for preference changes?**
>
> The `preferences:user:updated` [webhook event
> DOC](/docs/monitor/webhooks/events#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 [List preference changes](/docs/api-reference/preference-topics/list-preference-changes).

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


# Notification preferences
Source: https://www.courier.com/docs/recipients/preferences/overview

How Courier decides at send time whether a user gets a message, and on which channels.

Preferences resolve at send time. Courier decides whether each recipient gets the message, and on which channels.

Courier layers the topic's default, any tenant defaults, and the user's own choices. You write no routing logic. Map a template to a subscription topic and Courier enforces every layer.

To let users make those choices themselves, add a [preference center
DOC](/docs/in-app/preference-center) to your app or link them to the hosted page.

```mermaid theme={null}
flowchart LR
    A["Send on a topic"] --> B{"Resolved status?"}
    B -->|OPTED_IN| C{"Custom routing?"}
    C -->|Yes| D["User's channels"]
    C -->|No| E["Template's channels"]
    B -->|REQUIRED| F["Deliver"]
    B -->|OPTED_OUT| G["Blocked: UNSUBSCRIBED"]
    B -->|Opt-in, unset| H["Blocked: OPT_IN_REQUIRED"]
```

## How it works

Courier resolves a preference in two stages. First it works out the topic's **effective status** for that user. Then it decides whether that status **delivers or blocks** the send, and on which channels.

### Status precedence

The effective status starts from the topic's default. Each layer below overrides the one above it, and only for fields that were explicitly set:

| Layer | Set in | Overrides |
| - | - | - |
| 1. Topic default | [Preferences Editor&#xA;DOC](/docs/recipients/preferences/preferences-editor) (each topic's default state) | The baseline for every user |
| 2. Parent tenant default | An ancestor tenant's [default preferences&#xA;DOC](/docs/tenants/preferences) | The topic default, inherited down the [tenant hierarchy&#xA;DOC](/docs/tenants/context#hierarchy-and-inheritance) |
| 3. Tenant default | The tenant's own [default preferences&#xA;DOC](/docs/tenants/preferences) | Its parent's default, for users sent in that tenant's context |
| 4. User preference | The user's own opt-in or opt-out (page or [API&#xA;DOC](/docs/recipients/preferences/api)) | Every default above it |
| 5. User preference for this tenant | The same call with a [`tenant_id`&#xA;DOC](/docs/recipients/preferences/api#scope-to-a-tenant) | That user's global preference, in this tenant only |
| Short-circuit | A topic default of `REQUIRED` | Everything below it: user choices are ignored |

Layer 5 is what gives one person separate settings in each organization they belong to. Someone who works with two of your customers can leave alerts on at one and off at the other, from the same account.

A default is one of three states:

* **`OPTED_IN` (on):** users receive the topic unless they opt out.
* **`OPTED_OUT` (off):** users receive nothing until they opt in.
* **`REQUIRED`:** users can't opt out. Courier ignores any user record for the topic and always delivers. Use it for critical messages like security alerts.

Unsubscribe links still render for a `REQUIRED` topic, but opting out has no effect. Leave them off templates mapped to one.

### Delivery and channel routing

Courier then decides delivery:

* **`REQUIRED`** always delivers.
* **`OPTED_OUT`** blocks the send for that topic. The message log shows the reason `UNSUBSCRIBED`.
* An opt-in topic whose resolved status isn't `OPTED_IN` blocks the send with the reason `OPT_IN_REQUIRED`.
* **`OPTED_IN`** proceeds to channel routing.

For an opted-in topic, channels resolve the same way. A user's per-topic channel choice (`custom_routing`) overrides the template's routing when `has_custom_routing` is true and the topic has channel selection enabled in the editor. Without both, the template's channel routing applies.

Courier evaluates preferences to route a send, so a blocked send still counts toward usage. To skip a message before any routing runs, use [send conditions
DOC](/docs/send/overrides) instead of a preference.

> [!NOTE]
>
> Where custom routing over the API isn't available, the single-topic write returns `402`, the bulk `PUT` returns `400`, and the bulk `POST` returns `200` with a per-item error. Only `status` is written.

## FAQ

> **Why is my topic opted-in but nothing sends?**
>
> The topic likely resolves to no deliverable channel. An opted-in topic whose channels are all disabled or unsupported produces an unroutable message with the reason `MISSING_PROVIDER_SUPPORT`, not a delivery. That's different from the preference block reason `UNSUBSCRIBED`, so the log tells you routing stopped it, not preferences. Add an available channel to the topic or template, or configure a provider for the channel you expect.

> **Do I need a user\_id to read tenant preferences?**
>
> Preferences are keyed by user, and by tenant only when you pass `tenant_id` alongside the `user_id`. Without a `user_id` you get topic defaults, not a resolved preference. The read API returns the topic-level default even with a `tenant_id`. To see what a tenant sets, read the [tenant's default preferences
> DOC](/docs/tenants/preferences) instead. Tenant defaults apply at send time, so confirm with a test send rather than a preferences read.

> **If a user unsubscribes under one tenant, are they unsubscribed everywhere?**
>
> Opt-outs are scoped to the tenant context they were set in, so an opt-out under tenant B doesn't affect sends under tenant C. Global and per-tenant preferences are stored separately and don't propagate into one another. Honoring a global opt-out across every tenant is off by default. Contact support to enable it per tenant.

> **Can a user opt out of a required topic?**
>
> A topic whose default is `REQUIRED` always delivers, and the API rejects an attempt to opt a user out of it. Only a tenant or workspace default can change a topic's required status, not a user.


# Preferences Editor
Source: https://www.courier.com/docs/recipients/preferences/preferences-editor

Build the preference center: page settings, sections, topics, digests, and publishing.

The Preferences Editor is where you set up the topics users can control, group them into sections, and design the preference page. It's fully customizable: the branding, wording, sections, topics, and channels are all yours to define.

Courier checks these preferences on every send, and changes save as a draft until you publish.

The editor is organized top down:

* **Page settings** apply to the whole preference page: its brand, heading, description, and channel names.
* **Sections** group related topics under a heading you name yourself, such as "Account notifications" or "Marketing."
* **Topics** are the categories users opt in or out of. You name and configure each one, and every topic lives in a section.
* **Templates** map to a topic, so every send respects the user's choice automatically, with no extra logic in your code.

![Courier Preferences Editor showing page settings, sections, and subscription topics](https://mintcdn.com/courier-4f1f25dc/Yy12YQJXNoKdo-Rl/assets/platform/preferences/preferences-editor-zoomed-in.png?fit=max\&auto=format\&n=Yy12YQJXNoKdo-Rl\&q=85\&s=65e7064c87b2154af9a0f31f1cb30db6)

An example preference page. Every part, from the branding to the topics, is customizable.

## Page settings

These settings apply to the whole page, across every section and topic.

* **Brand:** the [brand
  DOC](/docs/design/brands) applied to the page, with your logo and colors.
* **Heading:** the title at the top of the page, like "Manage your messaging preferences."
* **Description:** the subtitle under the heading.
* **Channel names:** the labels users see for each channel across the page. Rename them to match your product's voice, for example "In-App" to "Inbox" or "Push" to "Mobile Push".

![Page settings in the Preferences Editor: brand, heading, description, and channel names](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/page-settings-2.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=0f05064fe34ebeabdd997784e5b2b992)

## Sections and channel selection

Sections group related topics under their own heading and set which channels users can adjust for the topics inside. Add as many as you need, name each one yourself (the "Account notifications" and "Marketing" tabs above are examples), and reorder them to control how they appear.

Each section has:

* **ID:** the section's unique identifier, generated automatically by Courier and used in the API.
* **Heading:** the section title users see.
* **Description:** optional text shown under the heading.

![Section settings with the auto-generated section ID, heading, and description](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/section-settings-1.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=bce73873bb44861c00a459f30d2e51a1)

### Channel selection

Turn on channel selection for a section to let users choose how they receive its notifications, from the channels you make available (email, SMS, push, in-app, and more). Users see the channel names you set in page settings, not the raw values. In the API, channels use the `custom_routing` enum: `direct_message`, `email`, `inbox`, `push`, `sms`, `webhook`.

When a user customizes their channels, those choices appear in the `custom_routing` array from the [user preferences API
DOC](/docs/api-reference/user-preferences/get-users-preferences). The array only populates for sections where you've enabled channel selection:

```json theme={null}
{
  "topic": {
    "custom_routing": [
      "email",
      "push",
      "webhook"
    ],
    "has_custom_routing": true,
    "default_status": "OPTED_IN",
    "section_id": "5p8ROfompcN6Sg_2WR92A",
    "section_name": "Notifications",
    "status": "OPTED_IN",
    "topic_id": "FPPGTQRQTRM8TSPZGZAY9296WB37",
    "topic_name": "Product Updates"
  }
}
```

## Subscription topics

Subscription topics are the categories users control independently. You name and customize each one, for example marketing, security, or product updates. Each topic lives in a section and groups related notifications a user might want to receive or skip.

![Subscription topic settings with name, section, and default state](https://mintcdn.com/courier-4f1f25dc/Yy12YQJXNoKdo-Rl/assets/platform/preferences/preferences-topic-settings.png?fit=max\&auto=format\&n=Yy12YQJXNoKdo-Rl\&q=85\&s=22e1a54bfd6dced7ade4af0d29859145)

### Topic configuration

Each topic has:

* **Name:** the user-facing label for the category.
* **Section:** which section the topic belongs to.
* **Default state:** how users start out, described below.

### Default states

The default state sets how a topic behaves before a user changes it:

* **On:** users receive these notifications unless they opt out.
* **Off:** users receive nothing until they opt in.
* **Required:** users can't opt out. Use it for critical notifications like security alerts.

For a Required topic, unsubscribe links (`{$.urls.unsubscribe}` or `{{var "urls.unsubscribe"}}`) still render and the confirmation page still loads, but opting out does nothing and the user stays subscribed. Leave unsubscribe links out of templates mapped to Required topics so users aren't misled.

### Topic data

Attach arbitrary metadata to a topic through the API and use it to build [custom preference pages
DOC](/docs/in-app/add-a-preference-center). For example:

* Filter topics by metadata.
* Drive custom logic for how preferences display or apply.
* Store your own topic descriptions.

## Map templates to topics

Mapping a template to a topic is what makes Courier enforce the user's preference whenever that template sends. Each template maps to a single topic, and you set the mapping on the template itself, in Design Studio or through the API.

### In Design Studio

Open a template in [Design Studio
DOC](/docs/design/templates/design-studio), go to its [template settings
DOC](/docs/design/templates/template-settings), and choose a subscription topic. You can change it anytime.

![Assigning a subscription topic to a template in Courier Design Studio](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/manage-subscription-topic-on-template.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=29df445058b5c66d4c7f007cf4944f82)

Assigning a subscription topic to a template in Design Studio

### Through the API

A template's topic is the `subscription` field on the [Notification Templates API
DOC](/docs/design/templates/api), set to `{ "topic_id": "<TOPIC_ID>" }` or `null`. Include it when you [create a template
DOC](/docs/api-reference/templates/create-notification-template):

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/notifications \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification": {
      "name": "Order shipped",
      "tags": [],
      "brand": null,
      "subscription": { "topic_id": "TOPIC_ID" },
      "routing": null,
      "content": { "version": "2022-01-01", "elements": [] }
    }
  }'
```

To change an existing template's topic, use [Replace Notification Template](/docs/api-reference/templates/replace-notification-template). It replaces the whole template, so [fetch the template
DOC](/docs/api-reference/templates/get-notification-template) first, update `subscription`, then send the full payload back.

## Digests

A topic can deliver its notifications as a digest: batched into one message on a schedule instead of sent one at a time. You set this up in the topic's digest settings by linking a digest template and defining the schedules users choose from, like Instant, Daily, or Weekly.

See the [complete guide to configuring digests
DOC](/docs/guides/send-a-daily-digest).

## Unsubscribe headers

When a user opts out of a topic, Courier can add a `List-Unsubscribe` header to outgoing emails for that topic, so users can unsubscribe from their email client. `List-Unsubscribe` is a standard header, so you enable it in your email provider's settings, like SendGrid or [Mailgun](https://help.mailgun.com/hc/en-us/articles/203306610-Unsubscribe-Handling-Links#01HNZH48NP73S3Q0KVR9B40SV5).

## Drafts, preview, and publishing

Editing preferences never affects users right away. Every change saves as a **draft**, and users keep seeing the last published version until you publish. The editor gives you three controls:

* **Save** keeps your latest changes as a draft.
* **Preview Page** opens the preference page exactly as a user would see it, with your unpublished changes and a "Draft mode" banner so you know it isn't live yet.
* **Publish** makes the draft the version users see. After publishing, **View Page** opens the live page.

Your preference center can live in two places, and both read from the preferences you configure here.

### Courier-hosted

Courier hosts the preference page for you, so there's no frontend to build. You style and brand it in the editor, then drop a link to it into your emails or app, and users get a responsive page they can manage themselves. This is the page **Preview Page** and **View Page** open. See [Hosted preference center
DOC](/docs/guides/build-a-preference-center).

### Embedded in your app

To keep users inside your product, embed the same preference center with Courier's SDKs, for [React
DOC](/docs/sdk-libraries/courier-react-web) or any framework using [web components
DOC](/docs/sdk-libraries/courier-web-components). Embedded preferences reflect whatever you've published, so use **Preview Page** above to check a draft before it goes live.


# Courier API reference
Source: https://www.courier.com/docs/reference/api-overview

Authentication, request format, payload limits, idempotency, and pagination for the REST API.

Courier is one REST API: send messages, build journeys, manage templates and brands, and read delivery logs.

Anything you can do in the console, you can do through the API.

| | |
| - | - |
| **Base URL** | `https://api.courier.com`, or `https://api.eu.courier.com` for the [EU datacenter&#xA;DOC](/docs/workspaces/datacenters) |
| **Protocol** | HTTPS only |
| **Authentication** | Bearer token (API key) |
| **Format** | JSON request and response bodies |
| **Machine-readable docs** | [llms.txt](https://www.courier.com/docs/llms.txt) |

Every endpoint is listed in the sidebar, starting with [Send a message](/docs/api-reference/send/send-a-message). The conventions below apply to all of them.

* **New to Courier?** Send your first notification with the [Quickstart
  DOC](/docs/get-started/send-a-message).
* **Building with Claude Code, Codex, or Cursor?** Connect Courier over MCP or the CLI. Start with [AI onboarding
  DOC](/docs/get-started/build-with-ai).
* **Prefer a GUI?** Explore every endpoint in the [Postman collection
  DOC](/docs/resources/postman).

## Client libraries

Server SDKs wrap this API with typed methods, retries, and idempotency helpers. Prefer them over raw HTTP. Each page carries the install command and the current version.

> **[Node.js](/docs/sdk-libraries/node)**

> **[Python](/docs/sdk-libraries/python)**

> **[Ruby](/docs/sdk-libraries/ruby)**

> **[Go](/docs/sdk-libraries/go)**

> **[Java](/docs/sdk-libraries/java)**

> **[PHP](/docs/sdk-libraries/php)**

> **[C# / .NET](/docs/sdk-libraries/csharp)**

Client SDKs embed prebuilt UI instead of calling this API directly: an [in-app notification center
DOC](/docs/in-app/overview) and a [preference center
DOC](/docs/recipients/preferences/overview). See [all SDKs
DOC](/docs/sdk-libraries/sdks-overview) for the nine client platforms.

## Authentication

Pass your API key as a bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_COURIER_API_KEY
```

Requests without a valid key return `401 Unauthorized`. Keys are scoped to one [environment
DOC](/docs/workspaces/environments), such as Test or Production, so a Test key only reads and writes Test data. Create and rotate keys in [Settings → API Keys](https://app.courier.com/settings/api-keys).

> [!WARNING]
>
> Your API key is a secret. Use it only in server-side code, never in a browser, mobile app, or committed source. To authenticate a client for Inbox or preferences, issue a short-lived [user token](/docs/api-reference/authentication/create-a-jwt).

## Requests and responses

* All requests and responses use JSON. Send `Content-Type: application/json` on requests with a body.
* Timestamps are Unix epoch milliseconds (`int64`), not ISO 8601 strings.
* Send responses return a `requestId`. Use it to [look up a message](/docs/api-reference/messages/get-message) or trace delivery in Message Logs.

## Payload limits

Request bodies cap at **6 MB** on all endpoints. Larger requests return `413 Payload Too Large`.

Base64 content, such as inline attachments, inflates size by roughly 33%. A 6 MB payload holds about 4.5 MB of raw attachment data. For anything larger, host the file and pass a URL.

## Idempotency

Send an idempotency key to retry safely without sending duplicates. Use a unique value, such as a UUID, per logical request, and reuse it when you retry. Server SDKs take it as a parameter and set the `Idempotency-Key` header for you.

```javascript Node.js theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
  "Idempotency-Key": "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
    idempotency_key="6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Idempotency-Key: 6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: {user_id: "user_123"},
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  },
  idempotency_key: "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91"
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
	IdempotencyKey: courier.String("6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91"),
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .idempotencyKey("6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91")
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
  idempotencyKey: '6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91',
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
    IdempotencyKey = "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
};

var response = await client.Send.Message(parameters);
```

```bash CLI wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --idempotency-key 6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91
```

Courier caches the first response for that key, including its status code and any error, and replays it on retries. The request runs only once.

**A key is scoped to the endpoint it was sent to.** The stored key is the value plus the request path, so the same key sent to two endpoints is two independent keys. Generate one per call you want deduplicated, not one per logical operation spanning several calls.

Idempotency applies to `POST` only. Sending the header on any other method is accepted and does nothing, because the other methods are already idempotent by definition.

### How long a response is replayed

Courier replays a response for 25 hours by default. Send `x-idempotency-expiration` to hold a key longer, as an ISO 8601 datetime or a Unix epoch in milliseconds, up to one year. Anything else returns `400 Expiration is not a valid date`.

```javascript Node.js theme={null}
const { requestId } = await courier.send.message({
  message: { to: { user_id: "user_123" }, template: "nt_01kx4h2jdafq8bk9aftxak4b40" },
  "Idempotency-Key": "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
  xIdempotencyExpiration: "2027-01-31T00:00:00Z",
});
```

```python Python theme={null}
response = client.send.message(
    message={"to": {"user_id": "user_123"}, "template": "nt_01kx4h2jdafq8bk9aftxak4b40"},
    idempotency_key="6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
    x_idempotency_expiration="2027-01-31T00:00:00Z",
)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91" \
  -H "x-idempotency-expiration: 2027-01-31T00:00:00Z" \
  -d '{ "message": { "to": { "user_id": "user_123" }, "template": "nt_01kx4h2jdafq8bk9aftxak4b40" } }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: { to: { user_id: "user_123" }, template: "nt_01kx4h2jdafq8bk9aftxak4b40" },
  idempotency_key: "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
  x_idempotency_expiration: "2027-01-31T00:00:00Z"
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
	IdempotencyKey:         courier.String("6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91"),
	XIdempotencyExpiration: courier.String("2027-01-31T00:00:00Z"),
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .idempotencyKey("6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91")
    .xIdempotencyExpiration("2027-01-31T00:00:00Z")
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
  idempotencyKey: '6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91',
  xIdempotencyExpiration: '2027-01-31T00:00:00Z',
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new SendMessageParamsMessage
    {
        To = new UserRecipient { UserId = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
    IdempotencyKey = "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
    XIdempotencyExpiration = "2027-01-31T00:00:00Z",
};
var response = await client.Send.Message(parameters);
```

```bash CLI wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40"}' \
  --idempotency-key "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91" \
  --x-idempotency-expiration "2027-01-31T00:00:00Z"
```

Three details decide how it behaves:

* **It is per endpoint, not global.** The same key sent to `/send` and to `/profiles/{user_id}` creates two independent records.
* **Not every `POST` supports it.** Supported endpoints declare `Idempotency-Key` among their parameters. They include [Send a message](/docs/api-reference/send/send-a-message), [Invoke a Journey](/docs/api-reference/journeys/invoke-a-journey), [Create a Profile](/docs/api-reference/user-profiles/create-a-profile), and [Update user Preferences in bulk](/docs/api-reference/user-preferences/update-user-preferences-in-bulk).
* **Keys are retained 25 hours by default.** Hold one for up to a year with `x-idempotency-expiration`, as described in [How long a response is replayed](#how-long-a-response-is-replayed).

## Pagination

List endpoints use cursor-based pagination. Every response includes a `paging` object with a `more` boolean and a `cursor`:

```json theme={null}
{
  "paging": { "more": true, "cursor": "MTpFWUNFRkRRN0c1WERTRTU2" },
  "results": [ /* ... */ ]
}
```

When `paging.more` is `true`, pass `paging.cursor` back as the `cursor` query parameter to fetch the next page:

```javascript Node.js theme={null}
const page = await courier.messages.list({
  cursor: "MTpFWUNFRkRRN0c1WERTRTU2",
});
```

```python Python theme={null}
page = client.messages.list(cursor="MTpFWUNFRkRRN0c1WERTRTU2")
```

```bash cURL wrap theme={null}
curl "https://api.courier.com/messages?cursor=MTpFWUNFRkRRN0c1WERTRTU2" \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
page = courier.messages.list(cursor: "MTpFWUNFRkRRN0c1WERTRTU2")
```

```go Go theme={null}
page, err := client.Messages.List(context.TODO(), courier.MessageListParams{
	Cursor: courier.String("MTpFWUNFRkRRN0c1WERTRTU2"),
})
```

```java Java theme={null}
MessageListParams params = MessageListParams.builder()
    .cursor("MTpFWUNFRkRRN0c1WERTRTU2")
    .build();
MessageListResponse page = client.messages().list(params);
```

```php PHP theme={null}
$page = $client->messages->list(cursor: 'MTpFWUNFRkRRN0c1WERTRTU2');
```

```csharp C# theme={null}
MessageListParams parameters = new() { Cursor = "MTpFWUNFRkRRN0c1WERTRTU2" };

var page = await client.Messages.List(parameters);
```

```bash CLI wrap theme={null}
courier messages list \
  --api-key "$COURIER_API_KEY" \
  --cursor MTpFWUNFRkRRN0c1WERTRTU2
```

```text MCP theme={null}
With Courier MCP, list my messages and show me the next page.
```

The data array field name varies by endpoint. [List messages](/docs/api-reference/messages/list-messages) returns `results`, while [List Lists](/docs/api-reference/lists/list-lists) and [List all Audiences](/docs/api-reference/audiences/list-all-audiences) return `items`. Check the endpoint's own schema before you parse it.

## Errors

Courier uses standard HTTP status codes. `2xx` is success, `4xx` is a problem with your request, and `5xx` is a Courier-side error.

| Status | Meaning | What to do |
| - | - | - |
| `400` Bad Request | Malformed request or invalid parameters | Fix the request body or parameters |
| `401` Unauthorized | Missing or invalid API key | Check the `Authorization` header and key |
| `403` Forbidden | Key lacks access to the resource | Verify environment and key scope |
| `404` Not Found | Resource doesn't exist | Check the ID and path |
| `413` Payload Too Large | Body exceeds 6 MB | Reduce payload or host files externally |
| `429` Too Many Requests | Rate limit exceeded | Back off and retry |
| `5xx` Server Error | Courier-side error | Retry with backoff, then contact support if it persists |

Error responses include a JSON body with a human-readable `message` and a machine-readable `type`:

```json theme={null}
{ "message": "Example message text", "type": "invalid_request_error" }
```

### Message statuses

A `202` from [Send a message](/docs/api-reference/send/send-a-message) means Courier accepted the request, not that the message was delivered. Track the outcome with [Get message](/docs/api-reference/messages/get-message), which returns one of these statuses:

`ENQUEUED`, `ROUTED`, `SENT`, `DELIVERED`, `OPENED`, `CLICKED`, `DELAYED`, `DIGESTED`, `THROTTLED`, `FILTERED`, `CANCELED`, and three failure states:

* `UNROUTABLE`: no channel could be resolved (missing provider, or no channel data on the profile)
* `UNDELIVERABLE`: the provider rejected the recipient (invalid address or blocked domain)
* `UNMAPPED`: the referenced template couldn't be found

Failed messages also carry a `reason`, such as `BOUNCED`, `NO_PROVIDERS`, `OPT_IN_REQUIRED`, or `UNSUBSCRIBED`.

## Rate limits

[Send a message](/docs/api-reference/send/send-a-message) is **not rate-limited by request count**, so you can send at volume. Instead, the [send limits
DOC](/docs/send/statuses#send-limits) you configure per user, topic, or tenant govern message volume.

Three management endpoints are limited per workspace:

| Endpoint | Limit |
| - | - |
| [Update a List](/docs/api-reference/lists/update-a-list) | 60 requests / minute |
| [Update user Preferences in bulk](/docs/api-reference/user-preferences/update-user-preferences-in-bulk) or [Replace user Preferences in bulk](/docs/api-reference/user-preferences/replace-user-preferences-in-bulk) | 50 requests / second |
| [Resend message](/docs/api-reference/messages/resend-message) | 1 request / 2 seconds, per message |

Endpoints not listed here aren't request-count limited today. Limited responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining` so you can pace requests. Exceeding a limit returns `429 Too Many Requests`.

## FAQ

> **What can you do with the Courier API?**
>
> Anything you can do in the Courier console. Send notifications across email, SMS, push, chat, and in-app, and manage user profiles, preferences, lists, templates, brands, and tenants.

> **What is the Courier API base URL?**
>
> Requests go to `https://api.courier.com` over HTTPS, or to `https://api.eu.courier.com` for notifications you send through the EU datacenter.

> **How do I authenticate with the Courier API?**
>
> Pass your API key as a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_COURIER_API_KEY`. Keys are scoped per environment (such as Test or Production) and used only in server-side code.

> **Which languages have official Courier SDKs?**
>
> Courier maintains official server SDKs for Node.js, Python, Ruby, Go, Java, PHP, and C# / .NET, plus client SDKs for React, React Native, iOS, Android, and Flutter. Any language can call the REST API directly.

> **What are the Courier API rate limits?**
>
> [Send a message](/docs/api-reference/send/send-a-message) isn't limited by request count. Three management endpoints are limited per workspace (see the table above). Exceeding a limit returns `429 Too Many Requests`.

> **How do I avoid sending duplicate notifications on retry?**
>
> Set an `Idempotency-Key` header with a unique value. Courier replays the original response for 25 hours, so a retried request runs only once.


# Courier CLI
Source: https://www.courier.com/docs/resources/cli

Install the CLI, learn its resource and verb command structure, and read JSON output.

A native binary covering the full [Courier REST API
DOC](/docs/reference/api-overview). Runs on macOS, Linux, and Windows with no runtime dependencies.

## Install

**npm**

```bash theme={null}
npm install -g @trycourier/cli
```

A postinstall step downloads the binary for your platform. Node.js isn't needed afterwards.

**Direct download**

Download the binary for your platform from [GitHub Releases](https://github.com/trycourier/courier-cli/releases), extract it, and add it to your `PATH`.

Then set your key from [Settings → API Keys](https://app.courier.com/settings/api-keys):

```bash theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
courier --version
```

## Command structure

```bash theme={null}
courier [resource] <command> [flags...]
```

Add `--help` to any command for its flags. Send a notification:

```bash theme={null}
courier send message \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40" \
  --message.data '{"commenter": "Sara", "file": "Homepage Redesign"}'
```

## Resources

A colon joins a resource to its sub-resource, so a user's push tokens live under `users:tokens`. Run `courier --help` for the full list.

| Resource | Commands |
| - | - |
| `send` | `message` |
| `messages` | `list`, `retrieve`, `history`, `content`, `cancel`, `resend` |
| `profiles` | `create`, `retrieve`, `update`, `replace`, `delete` |
| `profiles:lists` | `retrieve`, `subscribe`, `delete` |
| `users:tokens` | `list`, `retrieve`, `add-single`, `add-multiple`, `update`, `delete` |
| `users:preferences` | `retrieve`, `retrieve-topic`, `update-or-create-topic`, `bulk-update`, `bulk-replace`, `delete-topic` |
| `users:tenants` | `list`, `add-single`, `add-multiple`, `remove-single`, `remove-all` |
| `lists` | `list`, `retrieve`, `update`, `delete`, `restore` |
| `lists:subscriptions` | `list`, `add`, `subscribe`, `subscribe-user`, `unsubscribe-user` |
| `audiences` | `list`, `retrieve`, `update`, `delete`, `list-members` |
| `notifications` | `list`, `create`, `retrieve`, `retrieve-content`, `put-content`, `put-element`, `put-locale`, `replace`, `publish`, `list-versions`, `get-metrics`, `archive` |
| `brands` | `list`, `create`, `retrieve`, `update`, `delete` |
| `tenants` | `list`, `retrieve`, `update`, `delete`, `list-users` |
| `tenants:templates` | `list`, `retrieve`, `replace`, `publish`, `delete` |
| `journeys` | `list`, `create`, `retrieve`, `replace`, `publish`, `invoke`, `cancel`, `list-versions`, `archive` |
| `journeys:runs` | `list`, `retrieve`, `list-steps` |
| `journeys:templates` | `list`, `create`, `retrieve`, `retrieve-content`, `put-content`, `put-locale`, `replace`, `publish`, `list-versions`, `archive` |
| `broadcasts` | `list`, `create`, `retrieve`, `update`, `put-content`, `retrieve-content`, `send`, `schedule`, `cancel`, `duplicate`, `archive` |
| `bulk` | `create-job`, `add-users`, `run-job`, `retrieve-job`, `list-users` |
| `digests:schedules` | `list-instances`, `release` |
| `providers` | `list`, `create`, `retrieve`, `update`, `delete` |
| `routing-strategies` | `list`, `create`, `retrieve`, `replace`, `list-notifications`, `archive` |
| `workspace-preferences` | `list`, `create`, `retrieve`, `replace`, `publish`, `archive` |
| `auth` | `issue-token` |

## Output

`--format` sets the shape: `auto` (default), `json`, `yaml`, `pretty`, `raw`, `explore`, or `jsonl` for streaming. `auto` is human-readable in terminals and JSON in pipes.

`--transform` filters output with [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md):

```bash theme={null}
courier messages list --format json --transform "results.#.id"
courier messages list --format json --transform "results.#(status=UNDELIVERABLE)"
```

Other global flags:

* `--api-key` overrides `COURIER_API_KEY` for one command.
* `--base-url` points at a custom API URL.
* `--debug` prints the HTTP request and response.

## Recipes

[Recipes
DOC](/docs/resources/cli/recipes) carries one command block per task: sending, debugging a delivery, profiles and push tokens, templates, journeys, broadcasts, bulk jobs, pagination, and CI.


# Courier CLI recipes: send, debug, and script notifications
Source: https://www.courier.com/docs/resources/cli/recipes

Copy-paste Courier CLI commands for sending, debugging deliveries, profiles, push tokens, journeys, broadcasts, bulk jobs, pagination, and CI pipelines.

One block per task, checked against CLI v5.6.0. [Install the CLI
DOC](/docs/resources/cli) first, and export `COURIER_API_KEY`.

```bash theme={null}
export COURIER_API_KEY=YOUR_COURIER_API_KEY
```

## How flags build the request

Every command maps to one REST endpoint, and its flags become the request body. Three rules decide the shape, and the first two are behind most failed commands.

* **The first positional argument fills the command's ID.** `courier profiles retrieve user_123` and `--user-id user_123` send the same request. A second positional is rejected, so a command with two IDs takes named flags for both.
* **A repeated flag builds an array.** `--user`, `--list`, `--patch`, and `--status` each take one item. Pass the flag once per item, not a JSON array, which the CLI rejects.
* **A dotted flag sets one nested field.** `--message.to` writes `message.to`, so you can build a send one field at a time.

Add `--help` to any command for its flags, and `--debug` to print the request it sent.

## Send

### Send a template to a user

Only a published template sends. The response carries a `requestId`, which is also the message ID for a single-recipient send.

```bash theme={null}
courier send message \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40" \
  --message.data '{"orderId": "ORD-456"}'
```

### Send to an email address without a template

`content` replaces `template`, so send one or the other. `routing` with `method: single` sends on the first channel in the list that can reach the recipient.

```bash theme={null}
courier send message \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"title": "Your export is ready", "body": "Download it from your dashboard."}' \
  --message.routing '{"method": "single", "channels": ["email"]}'
```

### Retry a send without sending twice

The CLI sets the `Idempotency-Key` header. Reuse the key when a call times out or the connection drops, and Courier replays the first response instead of sending again. **The replay includes errors.** For 24 hours a key that got a `400` keeps returning it, so use a new key once you fix the request.

```bash theme={null}
courier send message \
  --idempotency-key "order-456-confirmation" \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40"
```

### Tag a send so you can find it later

Set `tags` or a `trace_id` in the send's metadata, then filter the message list by either. A `trace_id` from your own system, such as an order ID, finds every message one request produced without storing Courier's IDs.

```bash theme={null}
courier send message \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40" \
  --message.metadata '{"tags": ["onboarding"], "trace_id": "order-456"}'

courier messages list --tag onboarding
courier messages list --trace-id order-456
```

### Send a body from a file

The CLI reads a JSON request body from stdin. **A flag doesn't override a piped body.** Where both set the same field, the file wins without a warning, so put everything in the file.

```bash theme={null}
courier send message < message.json
```

### Send to a list

Subscribe the user to the list, then send to the list ID. Every subscriber gets the message.

```bash theme={null}
courier lists retrieve acme-corp.beta-testers
courier profiles:lists subscribe user_123 --list '{"listId": "acme-corp.beta-testers"}'
courier send message \
  --message.to '{"list_id": "acme-corp.beta-testers"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40"
```

### Send in bulk

Four calls in order. The job holds the recipients, and nothing sends until you run it. `message.event` is required and takes a template ID. Put the email in `profile.email`, not `to.email`, because routing reads the profile. `courier bulk list-users JOB_ID` shows the per-recipient outcome once the job has run. See [Send in bulk
DOC](/docs/guides/send-in-bulk) for the full walkthrough.

```bash theme={null}
courier bulk create-job --message '{"event": "nt_01kx4h2jdafq8bk9aftxak4b40", "data": {"company_name": "Acme Corp"}}'
courier bulk add-users --job-id JOB_ID \
  --user '{"to": {"user_id": "user_123"}, "profile": {"email": "sarah@acme-corp.com"}}' \
  --user '{"to": {"user_id": "user_456"}, "profile": {"email": "kai@acme-corp.com"}}'
courier bulk run-job JOB_ID
courier bulk retrieve-job JOB_ID
```

## Debug a delivery

### Read what happened to one message

**`history` is the one to reach for first.** It returns each status change with its reason, which tells you whether a message was never routed, was rejected by the provider, or was delivered and never opened. `content` shows what actually rendered, which separates a template bug from a delivery one.

```bash theme={null}
courier messages history <message_id>
courier messages content <message_id>
```

### Find failed messages

Filter by status and time, then trim the output with `--transform`. It takes a [GJSON path](https://github.com/tidwall/gjson/blob/master/SYNTAX.md), so the output is one `{id, status, reason}` object per message. [Message statuses
DOC](/docs/send/statuses) lists what each status and reason means.

```bash theme={null}
courier messages list \
  --status UNDELIVERABLE --status UNROUTABLE \
  --enqueued-after 2026-09-22T00:00:00Z \
  --format json \
  --transform 'results.#.{id,status,reason}'
```

### Resend or cancel a message

`resend` creates a new message with a new ID. `cancel` only stops a message that is still in the delivery pipeline.

```bash theme={null}
courier messages resend <message_id>
courier messages cancel <message_id>
```

### Check a template's delivery rates

`get-metrics` returns sent, delivered, opened, and clicked counts over time. The counters are nested, so every delivered message is also counted in `sent`. Read them as rates, not as parts of a total. [Template metrics
DOC](/docs/monitor/template-metrics) covers the window limits.

```bash theme={null}
courier notifications get-metrics \
  --id nt_01kx4h2jdafq8bk9aftxak4b40 \
  --lookback P7D \
  --granularity DAY
```

## Manage recipients

### Create, update, and delete a profile

`create` merges into an existing profile. `replace` overwrites it, so include every field you want to keep. `update` takes JSON Patch operations, one `--patch` flag per operation.

```bash theme={null}
courier profiles create user_123 --profile '{"email": "sarah@acme-corp.com"}'
courier profiles retrieve user_123
courier profiles update user_123 --patch '{"op": "replace", "path": "/phone_number", "value": "+15555550123"}'
courier profiles delete user_123
```

### Import profiles from a CSV

Loop over the rows and create one profile per line. **End each call with `< /dev/null`.** Without it the CLI reads the rest of the file as its request body, so the loop stops after the first row with a merge error. `jq` builds the JSON, which keeps a stray quote in the data from breaking the command.

```bash theme={null}
tail -n +2 users.csv | while IFS=, read -r user_id email; do
  courier profiles create "$user_id" \
    --profile "$(jq -nc --arg email "$email" '{email: $email}')" < /dev/null
done
```

### Register a push token

`--provider-key` is `firebase-fcm`, `apn`, `expo`, or `onesignal`. Use the key of the provider that issued the token.

```bash theme={null}
courier users:tokens add-single \
  --user-id user_123 \
  --token YOUR_DEVICE_TOKEN \
  --provider-key firebase-fcm
```

### Issue a JWT for Inbox

Issue the token a client SDK, such as Inbox, signs in with. The `user_id` scope decides whose messages it can read, so issue one per signed-in user and never share one across users.

```bash theme={null}
courier auth issue-token \
  --scope "user_id:user_123 inbox:read:messages inbox:write:events" \
  --expires-in "7 days"
```

### Manage preferences

Send `has_custom_routing` and the full `custom_routing` array together, because the write replaces the topic's routing rather than merging into it.

```bash theme={null}
courier users:preferences retrieve user_123
courier users:preferences update-or-create-topic \
  --user-id user_123 \
  --topic-id YOUR_TOPIC_ID \
  --topic '{"status": "OPTED_IN", "has_custom_routing": true, "custom_routing": ["email"]}'
```

### Add a user to a tenant

`tenants update` creates the tenant or replaces it, so pass every field you want to keep, such as `--brand-id`.

```bash theme={null}
courier tenants update acme-corp --name "Acme Corp"
courier users:tenants add-single --user-id user_123 --tenant-id acme-corp
courier tenants list-users acme-corp
```

## Manage templates

**A write leaves a draft.** `publish` is what makes it live, and a send resolves the published version, so a content change nothing published reaches no recipient. Read the draft with `--version draft` before you publish it.

```bash theme={null}
courier notifications list
courier notifications retrieve-content nt_01kx4h2jdafq8bk9aftxak4b40 --version draft
courier notifications put-content nt_01kx4h2jdafq8bk9aftxak4b40 \
  --content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "Your order shipped."}]}'
courier notifications publish nt_01kx4h2jdafq8bk9aftxak4b40
```

## Run journeys and broadcasts

### Start a journey for a user

Only a published journey starts. `data` is available to every node for conditions and template variables.

```bash theme={null}
courier journeys invoke \
  --template-id user-onboarding \
  --user-id user_123 \
  --data '{"first_name": "Sarah", "has_activated": false}'
```

### Find journey runs that failed

`list-steps` shows each node the run reached and what happened there, including the message ID of every send. Runs are kept for 95 days.

```bash theme={null}
courier journeys:runs list --template-id user-onboarding --status ERROR --format json --transform 'runs.#.run_id'
courier journeys:runs list-steps --run-id RUN_ID
```

### Cancel journey runs

Cancel by token or by run ID, not both, or the call returns `400`. A token cancels every run that shares it, and you set it in the journey's settings. See [Invoke a journey
DOC](/docs/journeys/invoke).

```bash theme={null}
courier journeys cancel --cancelation-token order-9042-flow
courier journeys cancel --run-id RUN_ID
```

### Schedule a broadcast

`--scheduled-to` has no offset, because `--timezone` supplies it. Use `broadcasts send` with the same recipient flags to send now. A scheduled broadcast locks its content, so cancel with `broadcasts cancel` before editing it.

```bash theme={null}
courier broadcasts create --name "March product update" --channel email
courier broadcasts put-content --broadcast-id BROADCAST_ID \
  --content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "Here is what shipped in March."}]}'
courier broadcasts schedule --broadcast-id BROADCAST_ID \
  --recipient-type list --recipient-id acme-corp.beta-testers \
  --scheduled-to 2026-10-01T09:00:00 --timezone America/New_York
```

### Release a digest early

`release` sends every recipient's held digest for that schedule now, instead of at its next scheduled time.

```bash theme={null}
courier digests:schedules release sch_01m26nhsf7fzxr5kngwf8p0b2c
```

## Script the CLI

### Page through every result

List commands return one page at a time. `paging.more` says whether another exists, and `paging.cursor` fetches it. The `args` array keeps the loop working in both bash and zsh.

```bash theme={null}
cursor=""
while :; do
  args=()
  [ -n "$cursor" ] && args=(--cursor "$cursor")
  page=$(courier messages list --recipient user_123 --format json "${args[@]}")
  echo "$page" | jq -c '.results[]'
  [ "$(echo "$page" | jq -r '.paging.more')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.paging.cursor')
done
```

### Pull one field into a variable

Combine `--transform` with `--raw-output` to capture one value. `--raw-output` drops the JSON quotes from a string result, so the variable holds the bare ID.

```bash theme={null}
request_id=$(courier send message \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40" \
  --format json --transform requestId --raw-output)
```

### Use it in CI

Pass the key from your secret store and read `json`, because the default human format isn't a stable contract. **Double-quote any JSON that holds a shell variable.** Inside single quotes `$USER_ID` is sent literally, and the send goes to a user named `$USER_ID`.

The CLI exits non-zero on an API error, so a failed send fails the step without extra handling.

```bash theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to "{\"user_id\": \"$USER_ID\"}" \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40" \
  --format json
```

## Global flags

Every command takes these.

| Flag | Use it to |
| - | - |
| `--api-key` | Override `COURIER_API_KEY` for one call. |
| `--format` | Set the output format: `auto`, `json`, `jsonl`, `pretty`, `raw`, `yaml`, or `explore`. Use `json` for anything a script reads. |
| `--transform` | Reshape the response with a GJSON path before it prints. |
| `--raw-output`, `-r` | Print a string result without JSON quotes. |
| `--format-error` / `--transform-error` | The same two, applied to an error response. |
| `--base-url` | Point at a different API host. |
| `--debug` | Print the request and response, for when a call fails and the error isn't enough. |

## FAQ

> **What can the Courier CLI do?**
>
> The Courier CLI covers the full REST API from a terminal: sends, profiles, lists, templates, journeys, broadcasts, bulk jobs, tenants, preferences, and delivery logs. Each command maps to one endpoint, so anything in the [API reference
> DOC](/docs/reference/api-overview) has a CLI equivalent.

> **Why does a Courier CLI command reject a JSON array?**
>
> A Courier CLI flag that takes a list, such as `--user`, `--list`, `--patch`, or `--status`, takes one item per flag. Repeat the flag once per item and the CLI builds the array. Passing the whole array to one flag fails with a parse error.

> **How do I pass two IDs to a Courier CLI command?**
>
> The Courier CLI accepts one positional argument, which fills the command's first ID. A command that needs two, such as a user and a topic, takes named flags like `--user-id` and `--topic-id` for both.

> **Should I use the Courier CLI or the MCP server?**
>
> Use the CLI for scripts, CI pipelines, and commands you run yourself, because its output is predictable and it exits non-zero on failure. Use the [MCP server
> DOC](/docs/resources/mcp) when an AI agent should decide which calls to make. Both call the same API with the same key.

> **Does the Courier CLI need Node.js?**
>
> The Courier CLI is a native binary. npm installs it and downloads the binary for your platform, and after that it runs without Node.js. You can also download the binary directly from GitHub Releases.


# Glossary
Source: https://www.courier.com/docs/resources/glossary

Courier terms and every generated ID prefix, defined in plain language.

Most terms link to the page that explains them.

## ID prefixes

An ID Courier generates carries a prefix naming what it is. An ID you supply doesn't, so a `list_id`, `audience_id`, `tenant_id`, or `user_id` is whatever string you chose. Reading a prefix tells you which resource an ID belongs to without looking it up.

| Prefix | Resource |
| - | - |
| `nt_` | Notification template |
| `rs_` | Routing strategy |
| `env_` | Workspace environment |
| `elem_` | Element |
| `ptl_` | Partial, or shared content |
| `pc_` | Provider configuration |
| `exp_` | Experiment |
| `bst_` | Broadcast |
| `wrk_` | Workspace |
| `bnd_` | Brand |
| `jry_` | Journey |
| `ps_` | Preference section |
| `pt_` | Preference topic |

Those thirteen are the whole set. **A prefix that isn't on this list isn't a Courier ID format.** An example showing one for a resource you supply the ID for is wrong, not a variant.

## A

**[API Key
DOC](/docs/workspaces/environments#api-keys)** - A secret token that authenticates requests to Courier's REST API.

**[Audience
DOC](/docs/recipients/lists-and-audiences/audiences)** - A user group defined by filter rules, updated automatically.

**[Automation
DOC](/docs/journeys/overview)** - A multi-step workflow with conditional logic, delays, digests, and send steps.

## B

**[Batching
DOC](/docs/journeys/nodes)** - An automation step that groups several triggers into one action.

**[Brand
DOC](/docs/design/brands)** - A visual template that styles email notifications with your logo, colors, and layout.

**[Bulk Send
GUIDE](/docs/guides/announce-to-a-list)** - Sending one notification to many recipients through a job-based API workflow.

## C

**[Channel
DOC](/docs/integrations/overview)** - A communication method: email, SMS, push, in-app inbox, or direct message (Slack, Discord).

**[Channel Priority
DOC](/docs/send/routing#channel-priority)** - The order Courier tries channels when delivering a notification.

**[Conditions
DOC](/docs/design/templates/design-studio)** - Logic that turns content blocks, channels, or whole notifications on and off based on data.

**[Content Block
DOC](/docs/design/templates/design-studio)** - A reusable, responsive component (text, image, action button) used inside a template.

**[Courier Create
DOC](/docs/design/embedded-designer/overview)** - An embeddable designer that lets your users edit notification templates inside your app.

## D

**[Digest category
GUIDE](/docs/guides/send-a-daily-digest#set-up-a-topic-digest)** - A split within one digest, such as tasks against comments. Its retain rule picks which events appear: first, last, or highest or lowest by a sort key.

**[Delay
DOC](/docs/send/delay-and-schedule)** - An automation step that waits for a duration, or until a specific time.

**Delivery** - The final step, where a provider gets the message to the recipient.

**[Designer
DOC](/docs/design/templates/design-studio)** - Courier's visual editor for notification templates.

**Device Token** - An identifier for one app on one device, issued by Apple (APNs) or Google (FCM).

**[Digest
DOC](/docs/guides/send-a-daily-digest)** - Batching several notifications into one message, to cut notification fatigue.

**[DIGESTED
DOC](/docs/send/statuses)** - The status of a send held for a digest rather than delivered. It means the recipient is on a digest schedule for that topic.

**[Draft / Published
DOC](/docs/design/templates/overview)** - The two states of a notification template.

## E

**[Elemental
DOC](/docs/design/elemental/overview)** - A JSON syntax for describing notification content across every channel.

**[Environment
DOC](/docs/workspaces/environments)** - An isolated stage of a workspace, such as Production, Test, or a custom environment like Staging, so development never touches live notifications.

**Event** - A trigger identifier, usually the template ID passed in a send request's `template` field.

## F

**[Failover
DOC](/docs/send/routing#failover)** - Automatic switching to a backup provider when the primary one fails.

**[Feed
DOC](/docs/in-app/overview)** - A filtered stream of messages in the Inbox component.

## G

**[Guardrails
DOC](/docs/send/statuses#send-limits)** - Send limits that prevent accidental sends to large audiences, or too many messages to one user.

## H

**[Handlebars
DOC](/docs/design/templates/variables)** - A templating language for dynamic values, conditionals, and loops in templates.

## I

**[Idempotency Key
DOC](/docs/reference/api-overview#idempotency)** - An identifier sent with a request to prevent duplicate processing.

**[Inbox
DOC](/docs/in-app/overview)** - Courier's in-app notification center component for web and mobile.

**Inline Content** - Content defined in the Send API request body instead of a stored template.

**[Integration
DOC](/docs/integrations/overview)** - A connection between Courier and a provider (SendGrid, Twilio) that delivers your messages.

**[Instant
GUIDE](/docs/guides/send-a-daily-digest#which-schedule-a-user-is-on)** - A digest schedule that delivers immediately, so a user on it opts out of digesting. Making it the topic default means every user who never chose a schedule delivers immediately.

## J

**[Jsonnet
DOC](/docs/integrations/direct-message/overview)** - A data templating language for transforming data in content blocks and the [webhook designer
DOC](/docs/design/templates/data-mapping).

**[JWT (JSON Web Token)
DOC](/docs/in-app/authenticate-users)** - A token for client-side authentication, required by Inbox and other frontend SDKs.

## L

**[List
DOC](/docs/recipients/lists-and-audiences/lists)** - A static group of users you manage by hand, unlike an audience.

**[Locale
DOC](/docs/design/elemental/locales)** - A language code, such as `es` or `es-mx`, that picks which translation of a template a recipient gets.

**[Logs
DOC](/docs/monitor/overview)** - A timeline of sent messages with delivery status, provider responses, and rendered content.

## M

**[MCP (Model Context Protocol)
DOC](/docs/resources/mcp)** - A protocol that lets AI agents work with Courier.

**Message** - One notification sent to one recipient.

**[Message Status
DOC](/docs/monitor/overview)** - The delivery state of a message: enqueued, sent, delivered, opened, clicked, or undeliverable.

## N

**Notification** - A reusable message template with [variables
DOC](/docs/design/templates/variables), sendable on one or more channels.

## O

**Override** - A change to the request body Courier sends a provider, for provider options the designer doesn't expose.

**[Outbound Webhook
DOC](/docs/monitor/webhooks/outbound)** - A webhook Courier fires on events like sent or delivered, to sync delivery data elsewhere.

## P

**[Preferences
DOC](/docs/recipients/preferences/overview)** - User-controlled settings for which notifications they get, and on which channels.

**[Profile
DOC](/docs/recipients/overview#the-profile-object)** - A JSON object storing a user's contact information, device tokens, and custom attributes.

**[Provider
DOC](/docs/integrations/overview)** - The downstream service (Twilio, SendGrid) that delivers notifications to recipients.

## R

**Recipient** - The end user who receives notifications, identified by their [profile
DOC](/docs/recipients/overview#the-profile-object).

**[Routing
DOC](/docs/send/routing)** - The logic that picks which channels and providers deliver a notification.

## S

**[Send Conditions
DOC](/docs/design/templates/design-studio)** - Rules evaluated at send time that decide whether a notification goes out.

**[Schedule
GUIDE](/docs/guides/send-a-daily-digest#schedules)** - When a topic's digests release, as a recurrence such as daily, weekly, or monthly. It lives on the preference topic. Each user picks theirs in the preference center, or your backend sets it with `digest_schedule_id`.

**[Send Limit
DOC](/docs/send/statuses#send-limits)** - A cap on notifications sent to a user, topic, or tenant per time period.

**[Send Rate Limit
DOC](/docs/integrations/send-rate-limits)** - The maximum rate Courier sends to one provider configuration. Sends above it are queued, not dropped.

**[Subscription Topic
DOC](/docs/recipients/preferences/overview)** - A notification category ("Marketing", "Order Updates") users can opt in or out of.

## T

**[Template
DOC](/docs/design/templates/design-studio)** - A reusable message design, built in the Designer and sent to many recipients.

**[Template Approval
DOC](/docs/design/templates/api#approval-workflow)** - A review step required before a template can be published to production.

**[Tenant
DOC](/docs/tenants/overview)** - A customer organization in a multi-tenant app, with its own branding, preferences, and data.

**[Throttle
DOC](/docs/journeys/nodes)** - An automation step that caps how often a notification triggers for a scope (per-user, global, or dynamic key).

**[Toast
DOC](/docs/in-app/add-toasts)** - A pop-up the Inbox SDK components show when a new message arrives.

**Trigger** - An action or event that starts an [automation
DOC](/docs/journeys/overview) or sends a notification.

## V

**[Variable
DOC](/docs/design/templates/variables)** - A template placeholder (`{name}`, `{order_id}`) replaced with real data at send time.

## W

**[Workspace
DOC](/docs/workspaces/overview)** - The top-level container for all your Courier resources, environments, team members, and settings.


# Support and status
Source: https://www.courier.com/docs/resources/help

How to reach support, check status, read the changelog, and find security reports.

> **[Contact support](mailto:support@courier.com)**
>
> [support@courier.com](mailto:support@courier.com)

> **[Status](https://status.courier.com/)**
>
> Infrastructure health, with alerts you can subscribe to.

> **[Changelog](https://www.courier.com/changelog/)**
>
> New releases and bug fixes.

> **[Security & compliance](https://security.courier.com/)**
>
> Certifications, data handling, and security posture.

The **Developer** plan includes email support. **Business** adds chat. **Enterprise** adds onboarding and training, a shared Slack channel, and an SLA. See [Courier pricing](https://www.courier.com/pricing).


# Courier MCP server
Source: https://www.courier.com/docs/resources/mcp

Connect an AI agent to the hosted MCP server at mcp.courier.com to use the Courier API as tools.

The hosted MCP server at `https://mcp.courier.com` exposes the [Courier REST API
DOC](/docs/reference/api-overview) as typed tools. Your agent discovers them automatically.

Authenticate with an API key from [Settings → API Keys](https://app.courier.com/settings/api-keys). Each client takes the key as a header, flag, or config field.

## Installation

**Claude Code**

Run:

```bash theme={null}
claude mcp add --transport http courier https://mcp.courier.com --header api_key:YOUR_COURIER_API_KEY
```

> [!TIP]
>
> This registers the server for the current project. Add `--scope user` to register it in every project.

**Cursor**

**Quick install**

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=courier\&config=eyJ1cmwiOiJodHRwczovL21jcC5jb3VyaWVyLmNvbSIsImhlYWRlcnMiOnsiYXBpX2tleSI6IllPVVJfQ09VUklFUl9BUElfS0VZIn19)

**Manual install**

In Cursor, go to **Cursor > Cursor Settings > Tools & Integrations > MCP Tools > New MCP Server** and add:

```json theme={null}
{
  "mcpServers": {
    "courier": {
      "url": "https://mcp.courier.com",
      "headers": {
        "api_key": "YOUR_COURIER_API_KEY"
      }
    }
  }
}
```

> [!TIP]
>
> Courier MCP works best with Agent mode enabled.

**Codex**

Add this to `~/.codex/config.toml` (create the file if it doesn't exist), then restart Codex:

```toml theme={null}
[mcp_servers.courier]
url = "https://mcp.courier.com"
http_headers = { "api_key" = "YOUR_COURIER_API_KEY" }
```

> [!TIP]
>
> The Codex CLI and the Codex IDE extension share this config file, so one entry covers both. `codex mcp add` doesn't support custom headers, so edit the file directly.

**Antigravity**

Antigravity's IDE, CLI, and Agent Manager share one MCP config. Add this to `~/.gemini/config/mcp_config.json` (create the file if it doesn't exist):

```json theme={null}
{
  "mcpServers": {
    "courier": {
      "serverUrl": "https://mcp.courier.com",
      "headers": {
        "api_key": "YOUR_COURIER_API_KEY"
      }
    }
  }
}
```

Then refresh the server list:

* In the Antigravity IDE, go to **Settings > Customizations > Installed MCP Servers** and click **Refresh**.
* In the Antigravity CLI, run `/mcp` to confirm the courier server is connected.

> [!TIP]
>
> Antigravity requires `serverUrl` for remote servers. It doesn't support the `url` or `httpUrl` fields other clients use.

**VS Code**

Create `.vscode/mcp.json` in your project and add:

```json theme={null}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "courier-api-key",
      "description": "API key for Courier service",
      "password": true
    }
  ],
  "servers": {
    "courier": {
      "url": "https://mcp.courier.com",
      "type": "http",
      "headers": {
        "api_key": "${input:courier-api-key}"
      }
    }
  }
}
```

Open the chat window, click the Gear icon, then **MCP Servers**, and start the "courier" server.

> [!TIP]
>
> VS Code works best when you prefix chat prompts with `#`. For example: `#get_user_profile_by_id example_user_id`.

**Windsurf**

Add the following to `~/.codeium/windsurf/mcp_config.json` (create the file if it doesn't exist):

```json theme={null}
{
  "mcpServers": {
    "courier": {
      "serverUrl": "https://mcp.courier.com",
      "headers": {
        "api_key": "YOUR_COURIER_API_KEY"
      }
    }
  }
}
```

> [!TIP]
>
> Windsurf uses `serverUrl` for remote servers, not `url`.

**Gemini CLI**

Add the following to `~/.gemini/settings.json` for every project, or `.gemini/settings.json` for one project:

```json theme={null}
{
  "mcpServers": {
    "courier": {
      "httpUrl": "https://mcp.courier.com",
      "headers": {
        "api_key": "YOUR_COURIER_API_KEY"
      }
    }
  }
}
```

> [!TIP]
>
> Use `httpUrl`, which selects the streamable HTTP transport the Courier server speaks. `url` selects SSE instead. Paste the key itself: Gemini CLI doesn't expand environment variables inside `headers`.

**Grok Build**

In a terminal, run:

```bash theme={null}
grok mcp add --transport http courier https://mcp.courier.com --header "api_key: YOUR_COURIER_API_KEY"
```

Or add the server to `~/.grok/config.toml` directly:

```toml theme={null}
[mcp_servers.courier]
url = "https://mcp.courier.com"
headers = { "api_key" = "YOUR_COURIER_API_KEY" }
```

> [!TIP]
>
> Pass `--scope project` to store the server in `.grok/config.toml` inside the repository instead. `grok mcp list` shows configured servers and `grok mcp doctor courier` checks connectivity.

**OpenCode**

Add the following to `opencode.json` in your project:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "courier": {
      "type": "remote",
      "url": "https://mcp.courier.com",
      "enabled": true,
      "headers": {
        "api_key": "{env:COURIER_API_KEY}"
      }
    }
  }
}
```

> [!TIP]
>
> `{env:COURIER_API_KEY}` reads the key from your environment so it never lands in the file. Replace it with the key itself if you prefer.

**Zed**

Open your settings file (`zed: open settings file` from the command palette) and add:

```json theme={null}
{
  "context_servers": {
    "courier": {
      "url": "https://mcp.courier.com",
      "headers": {
        "api_key": "YOUR_COURIER_API_KEY"
      }
    }
  }
}
```

> [!TIP]
>
> Zed calls MCP servers context servers. Remote servers take `url` and `headers`. Leave `command` out.

**Warp**

In Warp, go to **Settings > Agents > MCP servers**, click **+ Add**, and paste:

```json theme={null}
{
  "courier": {
    "url": "https://mcp.courier.com",
    "headers": {
      "api_key": "YOUR_COURIER_API_KEY"
    }
  }
}
```

> [!TIP]
>
> Warp supports the streamable HTTP transport the Courier server uses. The top-level key is the server name.

**Devin**

In the Devin web app, go to **Customize > MCPs** and click **Add custom MCP**. Fill in:

* **Transport:** HTTP
* **URL:** `https://mcp.courier.com`
* **Auth method:** Auth Header
* **Header name:** `api_key`
* **Header value:** your Courier API key

> [!TIP]
>
> MCP servers in Devin are configured for the whole organization, so every member shares this connection. Use a dedicated API key for it rather than a personal one.

**Claude Desktop**

In Claude Desktop, go to **Claude > Settings > Developer > Edit Config**, then add:

```json theme={null}
{
  "mcpServers": {
    "courier": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.courier.com", "--header", "api_key: YOUR_COURIER_API_KEY"]
    }
  }
}
```

## What it covers

[Tools
DOC](/docs/resources/mcp/tools) lists every tool the server exposes, by resource, and marks which ones write.
170 tools across the API surface:

| Area | What the agent can do |
| - | - |
| Send | Send to a user, List, or Template, and cancel or resend a message |
| Messages | List, retrieve, read history, content, and delivery status, and trace a delivery in one call |
| Users | Create, merge, replace, and patch Profiles, and manage push tokens |
| Lists & Audiences | Create Lists, subscribe and unsubscribe users, query Audience members |
| Templates | Create, publish, archive, and read or replace content, elements, and locales |
| Journeys | Create, publish, invoke, cancel, and version Journeys and their Templates, and read run logs |
| Preferences | Read and write Topics, Sections, digests, and per-user and per-tenant preferences |
| Broadcasts | Create, schedule, and send a Broadcast to a List or Audience |
| Previews | Render a Template on real email clients, read the screenshots back, and manage device sets |
| Tenants | Create Tenants, manage membership, and set Tenant Templates and preferences |
| Brands & Providers | Create and update Brands, Providers, and Routing Strategies |
| Automations | Invoke a Template or ad-hoc Automation, and cancel a run |
| Analytics | Read audit events, digest instances, and the provider catalog |

Ask your agent to list its Courier tools for the current set. The [API reference
DOC](/docs/reference/api-overview) documents the endpoints behind them.


# Courier MCP tools: every tool, grouped by resource
Source: https://www.courier.com/docs/resources/mcp/tools

All 170 Courier MCP server tools, grouped by resource, with write tools marked, what each group is for, and which tools an agent chains for common tasks.

The hosted MCP server exposes 170 tools, one per Courier API operation. [Connect it
DOC](/docs/resources/mcp) first, then describe the job to your agent and it picks the tools.

A request like the one below maps to `list_messages` filtered to the recipient, then `trace_message` on the match, which returns the event history and the status reason.

```text MCP theme={null}
With Courier MCP, find out why user_123 didn't get their order confirmation yesterday.
```

## How an agent uses these tools

Your agent reads each tool's name, description, and input schema when it connects. The descriptions below come from the same tool registry, trimmed to one line. You never call a tool by name yourself.

**The API key decides where every tool acts.** A key belongs to one [environment
DOC](/docs/workspaces/environments), and each environment has its own templates, users, and logs. Connect a Test key while the agent is learning your workspace, because Test's built-in email provider only delivers to the address you signed up with.

**Write** in the tables marks a tool that changes workspace state, including every send. Everything unmarked is a read. If your client can require approval per tool, require it for the write tools.

**A template edit is a draft until something publishes it.** The `put_` and `replace_` tools for templates and journeys write the draft, and sends use the published version. An agent that edits content and stops there has changed nothing a recipient sees, so ask it to publish.

## Common tasks

| Task | Tools, in order |
| - | - |
| Send a template to a user | `list_notifications`, `send_message_template` |
| Find out why a message failed | `list_messages`, `trace_message` |
| Edit and ship a template | `get_notification_draft_content`, `put_notification_content`, `publish_notification` |
| Translate a template | `get_notification_draft_content`, `put_notification_locale`, `publish_notification` |
| Check a template's delivery rates | `get_notification_metrics` |
| Start a journey for a user | `list_journeys`, `invoke_journey` |
| Debug a journey run | `list_journey_runs`, `list_journey_run_steps`, `trace_message` |
| Announce something to a list | `create_broadcast`, `put_broadcast_content`, `send_broadcast` or `schedule_broadcast` |
| See a template on real email clients | `list_preview_device_sets`, `create_preview_run`, `get_preview_run` |
| Onboard a customer organization | `create_or_update_tenant`, `add_user_to_tenant` |
| Connect a provider | `list_provider_catalog`, `create_provider` |
| Add Courier to an app | `courier_installation_guide` |

## Send

`send_message` and `send_message_to_list` take an inline title and body. The `_template` versions send a published template. A list send reaches every subscriber at once. For an announcement you want to schedule, use Broadcasts.

| Tool | What it does | Write |
| - | - | - |
| `send_message` | Send a message to a user using inline title and body content (no template). | Yes |
| `send_message_template` | Send a message to a user using a published notification template. | Yes |
| `send_message_to_list` | Send a message to all subscribers of a list using inline title and body content. | Yes |
| `send_message_to_list_template` | Send a message to all subscribers of a list using a notification template. | Yes |

## Messages

Every read here comes from the message logs. **`trace_message` is the one to reach for first.** Give it a `message_id`, or the `metadata.trace_id` you set on a send, and it returns each matching message with its event history and status reason. [Message statuses
DOC](/docs/send/statuses) explains what each status means.

| Tool | What it does | Write |
| - | - | - |
| `list_messages` | List messages you've previously sent. | |
| `get_message` | Get the full details and status of a single message by its ID. | |
| `get_message_content` | Get the rendered content (HTML, text, subject) of a previously sent message. | |
| `get_message_history` | Get the event history for a message, showing each step in the delivery pipeline (enqueued, sent, delivered, etc.). | |
| `cancel_message` | Cancel a message that is currently being delivered. | Yes |
| `resend_message` | Resend a previously sent message. | Yes |
| `trace_message` | Trace delivery in one call. | |

## Profiles

Three writes that behave differently. `create_or_merge_user` merges into an existing profile, `replace_profile` overwrites every field, and `patch_profile` applies JSON Patch operations. Ask for a merge when you mean "add this field", or a replace can drop the fields you left out.

| Tool | What it does | Write |
| - | - | - |
| `get_user_profile_by_id` | Get a user profile by their ID. | |
| `create_or_merge_user` | Create a new user profile or merge supplied values into an existing profile (POST). | Yes |
| `replace_profile` | Fully replace a user profile (PUT). | Yes |
| `patch_profile` | Partially update a user profile via JSON Patch (RFC 6902). | Yes |
| `delete_profile` | Delete a user profile permanently. | Yes |
| `get_user_list_subscriptions` | Get all list subscriptions for a user. | |
| `subscribe_user_to_lists` | Subscribe a user to one or more lists. | Yes |
| `delete_user_list_subscriptions` | Delete all list subscriptions for a user. | Yes |

## Lists

A list is a set of users you subscribe explicitly. **`bulk_subscribe_to_list` replaces every subscriber**, while `add_subscribers_to_list` appends. Say "add" when you mean add, or the agent can pick the tool that removes everyone else.

| Tool | What it does | Write |
| - | - | - |
| `list_lists` | Get all lists. | |
| `get_list` | Get a list by its ID. | |
| `get_list_subscribers` | Get all subscribers of a list. | |
| `create_list` | Create or update a list by list ID. | Yes |
| `subscribe_user_to_list` | Subscribe a user to a list. | Yes |
| `unsubscribe_user_from_list` | Unsubscribe a user from a list. | Yes |
| `delete_list` | Delete a list by its ID. | Yes |
| `restore_list` | Restore a previously deleted list. | Yes |
| `bulk_subscribe_to_list` | Replace all subscribers on a list with the given recipients. | Yes |
| `add_subscribers_to_list` | Append subscribers to a list without removing existing subscribers. | Yes |

## Audiences

An audience is a filter on profile fields, so its membership updates as profiles change. You never add users to it, and a broadcast can target it.

| Tool | What it does | Write |
| - | - | - |
| `get_audience` | Get an audience by its ID, including its filter definition. | |
| `list_audience_members` | List all members of an audience. | |
| `list_audiences` | List all audiences in the workspace. | |
| `update_audience` | Create or update an audience with a filter definition. | Yes |
| `delete_audience` | Delete an audience by its ID. | Yes |

## Notification templates

Content is Elemental JSON, and writes land on the draft. `publish_notification` makes the draft live. `put_notification_locale` sets one locale's translations and merges them into what's there. `put_notification_element` replaces an element with only the fields it takes (`type`, `data`, `channels`, `if`, `loop`, `ref`), so change an element's text or translations with `put_notification_content` or `put_notification_locale`.

| Tool | What it does | Write |
| - | - | - |
| `list_notifications` | List notification templates. | |
| `get_notification_content` | Get the published content blocks of a notification template. | |
| `get_notification_draft_content` | Get the draft (unpublished) content blocks of a notification template. | |
| `create_notification` | Create a notification template. | Yes |
| `get_notification` | Retrieve a notification template by ID. | |
| `replace_notification` | Replace a notification template entirely (full document PUT). | Yes |
| `archive_notification` | Archive a notification template by ID. | Yes |
| `get_notification_metrics` | Get one template's delivery funnel over time: sent, delivered, opened, clicked, errors, and undeliverable, per provider and channel. | |
| `list_notification_versions` | List version history for a notification template. | |
| `publish_notification` | Publish a notification template, making it available for sending. | Yes |
| `list_notification_checks` | List checks for a notification submission. | |
| `update_notification_checks` | Update check statuses for a notification submission. | Yes |
| `put_notification_content` | Replace the elemental content of a notification template. | Yes |
| `put_notification_element` | Update a single element within a notification template. | Yes |
| `put_notification_locale` | Set locale-specific content overrides for a notification template. | Yes |
| `cancel_notification_submission` | Cancel a notification template submission. | Yes |

## Brands

A brand holds the styling a template renders with. `update_brand` replaces the whole brand, so read it first and send every field back.

| Tool | What it does | Write |
| - | - | - |
| `create_brand` | Create a new brand. | Yes |
| `get_brand` | Get a brand by its ID. | |
| `list_brands` | List all brands in the workspace. | |
| `update_brand` | Replace an existing brand with new values. | Yes |
| `delete_brand` | Delete a brand by its ID. | Yes |

## Auth

`generate_jwt_for_user` issues the token a client SDK, such as Inbox, signs in with. Scope each token to one user.

| Tool | What it does | Write |
| - | - | - |
| `generate_jwt_for_user` | Generate a JWT authentication token for a user. | Yes |

## Device tokens

Push tokens stored on a user, for Firebase FCM, APNs, Expo, and OneSignal.

| Tool | What it does | Write |
| - | - | - |
| `list_user_push_tokens` | List all push/device tokens for a user. | |
| `get_user_push_token` | Get a specific push/device token for a user. | |
| `create_or_replace_user_push_token` | Create or replace a push/device token for a user. | Yes |
| `bulk_add_user_tokens` | Add multiple push/device tokens for a user in one request. | Yes |
| `patch_user_token` | Apply a JSON Patch (RFC 6902) to a specific push token. | Yes |
| `delete_user_token` | Delete a specific push token for a user. | Yes |

## Bulk

Same order as the API: create the job, add users, then run it. Nothing sends until `run_bulk_job`, and `get_bulk_job` reports progress.

| Tool | What it does | Write |
| - | - | - |
| `create_bulk_job` | Create a new bulk job for sending messages to multiple recipients. | Yes |
| `add_bulk_users` | Add users to an existing bulk job. | Yes |
| `run_bulk_job` | Run a bulk job, triggering delivery to all added users. | Yes |
| `get_bulk_job` | Get the status of a bulk job. | |
| `list_bulk_users` | List the users in a bulk job. | |

## Tenants

A tenant is one of your customer organizations. Tenant templates override a workspace template for that one tenant, and tenant preferences set the defaults its users start from.

| Tool | What it does | Write |
| - | - | - |
| `get_tenant` | Get a tenant by its ID. | |
| `create_or_update_tenant` | Create or replace a tenant. | Yes |
| `list_tenants` | List all tenants in the workspace. | |
| `delete_tenant` | Delete a tenant by its ID. | Yes |
| `list_tenant_users` | List users associated with a tenant. | |
| `update_tenant_preference` | Set the default notification preference for a subscription topic on a tenant. | Yes |
| `delete_tenant_preference` | Remove default notification preference for a topic from a tenant. | Yes |
| `list_tenant_templates` | List notification templates configured for a tenant. | |
| `get_tenant_template` | Get a tenant notification template association by template ID. | |
| `replace_tenant_template` | Create or replace a tenant notification template (draft unless published is true). | Yes |
| `publish_tenant_template` | Publish a version of a tenant notification template. | Yes |
| `get_tenant_template_version` | Get a specific version of a tenant notification template: `latest`, `published`, or a version such as `v1`. | |
| `delete_tenant_template` | Delete a tenant notification template. | Yes |

## Users

Per-user preferences and tenant membership. `bulk_update_user_preferences` adds to what the user already has, and `bulk_replace_user_preferences` replaces their whole set.

| Tool | What it does | Write |
| - | - | - |
| `get_user_preferences` | Get a user's notification preferences (subscriptions, opt-outs, channel preferences). | |
| `get_user_preference_topic` | Get a user's preference for a specific subscription topic. | |
| `update_user_preference_topic` | Update a user's preference for a specific subscription topic (opt in, opt out, or set channel preferences). | Yes |
| `delete_user_preference_topic` | Delete a user's preference for a specific subscription topic, reverting it to the topic's default status. | Yes |
| `list_user_tenants` | List all tenants a user belongs to. | |
| `add_user_to_tenant` | Add a user to a tenant, with optional tenant-scoped profile overrides. | Yes |
| `remove_user_from_tenant` | Remove a user from a tenant. | Yes |
| `bulk_add_user_tenants` | Add a user to multiple tenants at once. | Yes |
| `remove_all_user_tenants` | Remove a user from all tenants. | Yes |
| `bulk_update_user_preferences` | Additively create or update a user's preferences for one or more topics in a single request. | Yes |
| `bulk_replace_user_preferences` | Replace a user's complete set of preference overrides in one request. | Yes |

`update_user_preference_topic` takes `tenant_id` to write the preference in one tenant's context, and `digest_schedule_id` to move the user onto another of the topic's digest schedules.

## Routing strategies

A routing strategy is a reusable channel and provider order that templates reference. `list_routing_strategy_notifications` shows which templates a change would affect.

| Tool | What it does | Write |
| - | - | - |
| `create_routing_strategy` | Create a routing strategy defining how notifications are delivered across channels and providers. | Yes |
| `get_routing_strategy` | Retrieve a routing strategy by ID. | |
| `replace_routing_strategy` | Replace a routing strategy. | Yes |
| `archive_routing_strategy` | Archive a routing strategy. | Yes |
| `list_routing_strategies` | List routing strategies in the workspace. | |
| `list_routing_strategy_notifications` | List notification templates associated with a routing strategy. | |

## Journeys

A journey has a draft and published versions, like a template, and only a published journey can be invoked. Journey-scoped templates live inside one journey and publish separately. `list_journey_run_steps` shows what happened at each node of a run.

| Tool | What it does | Write |
| - | - | - |
| `list_journeys` | List journey templates in the workspace, returning the journey IDs and version state of each. | |
| `invoke_journey` | Invoke a journey run from a journey template. | Yes |
| `create_journey` | Create a new journey. | Yes |
| `get_journey` | Get a journey by ID. | |
| `replace_journey` | Replace (update) a journey draft. | Yes |
| `publish_journey` | Publish the current draft of a journey, making it live and invokable. | Yes |
| `archive_journey` | Archive a journey. | Yes |
| `list_journey_versions` | List published versions of a journey, ordered most recent first. | |
| `list_journey_templates` | List notification templates scoped to a journey. | |
| `create_journey_template` | Create a notification template scoped to a journey, as a draft. | Yes |
| `get_journey_template` | Get a journey-scoped notification template by notification ID. | |
| `replace_journey_template` | Replace the draft of a journey-scoped notification template. | Yes |
| `archive_journey_template` | Archive a journey-scoped notification template. | Yes |
| `publish_journey_template` | Publish the current draft of a journey-scoped notification template. | Yes |
| `list_journey_template_versions` | List published versions of a journey-scoped notification template, ordered most recent first. | |
| `get_journey_template_content` | Fetch the elemental content of a journey-scoped notification template. | |
| `put_journey_template_content` | Replace the elemental content of a journey-scoped notification template. | Yes |
| `put_journey_template_locale` | Set locale-specific content overrides for a journey-scoped notification template. | Yes |
| `cancel_journey` | Cancel journey runs. | Yes |
| `list_journey_runs` | List journey runs, newest first. | |
| `get_journey_run` | Get one journey run by id: its journey, status, and timestamps. | |
| `list_journey_run_steps` | List the steps of a journey run in order, with each node and what happened at it. | |

## Broadcasts

One message to a list or audience on one channel, sent now or scheduled. A scheduled broadcast locks its content, so call `cancel_broadcast_schedule` before editing it.

| Tool | What it does | Write |
| - | - | - |
| `list_broadcasts` | List broadcasts in the workspace. | |
| `create_broadcast` | Create a broadcast: a one-off message to a list or audience on a single channel. | Yes |
| `get_broadcast` | Get a broadcast by id, including its channel and send or schedule state. | |
| `rename_broadcast` | Rename a broadcast. | Yes |
| `delete_broadcast` | Delete a broadcast. | Yes |
| `get_broadcast_content` | Get a broadcast's Elemental content. | |
| `put_broadcast_content` | Replace a broadcast's content with an Elemental document. | Yes |
| `send_broadcast` | Send a broadcast now to every member of a list or audience. | Yes |
| `schedule_broadcast` | Schedule a broadcast to send later to a list or audience. | Yes |
| `cancel_broadcast_schedule` | Cancel a broadcast's scheduled send. | Yes |
| `duplicate_broadcast` | Copy a broadcast into a new draft. | Yes |

## Previews

Render a template's email on real email clients and read the screenshots back. A run is billed to the workspace's previews add-on and finishes asynchronously, so poll `get_preview_run` until its status is `COMPLETED` or `FAILED`. Every workspace has a read-only Courier Recommended device set to start from.

| Tool | What it does | Write |
| - | - | - |
| `list_preview_devices` | List the email clients a preview can render on. | |
| `list_preview_device_sets` | List saved preview device sets. | |
| `create_preview_device_set` | Create a named, reusable set of preview devices. | Yes |
| `get_preview_device_set` | Get a preview device set by id. | |
| `replace_preview_device_set` | Replace a preview device set's name and devices. | Yes |
| `archive_preview_device_set` | Archive a preview device set. | Yes |
| `create_preview_run` | Render a template's email on real email clients and capture screenshots. | Yes |
| `list_preview_runs` | List a template's preview runs, newest first. | |
| `get_preview_run` | Get a preview run with its per-device results and screenshot URLs. | |

## Requests

One send request can produce several messages. Archiving the request archives all of them.

| Tool | What it does | Write |
| - | - | - |
| `archive_request` | Archive a send request and all its associated messages by request ID. | Yes |

## Providers

A provider configuration holds your credentials for one delivery service. `list_provider_catalog` returns the fields each provider type needs, which the agent reads before `create_provider`.

| Tool | What it does | Write |
| - | - | - |
| `list_providers` | List configured provider integrations for the workspace. | |
| `get_provider` | Fetch a single provider configuration by ID. | |
| `list_provider_catalog` | List available provider types from the catalog with their configuration schemas. | |
| `create_provider` | Create a new provider (integration) configuration. | Yes |
| `update_provider` | Replace an existing provider configuration. | Yes |
| `delete_provider` | Delete a provider configuration. | Yes |

## Translations

Workspace `.po` files for the [`\{\{t\}\}` helper
DOC](/docs/design/elemental/locales#workspace-translation-strings), one per locale. Only the `default` domain exists today.

| Tool | What it does | Write |
| - | - | - |
| `get_translation` | Get a translation for a specific locale, such as `en_US` or `fr_FR`. | |
| `update_translation` | Create or update a translation for a specific locale. | Yes |

## Inbound

Sends an event into Courier that can trigger automations.

| Tool | What it does | Write |
| - | - | - |
| `track_inbound_event` | Track an inbound event that can trigger automations. | Yes |

## Audit events

A record of who changed what in the workspace.

| Tool | What it does | Write |
| - | - | - |
| `get_audit_event` | Get a specific audit event by its ID. | |
| `list_audit_events` | List audit events in the workspace. | |

## Preferences

Workspace-level preference setup. Sections group topics, and a topic is what a user opts in or out of. `publish_preferences` pushes changes to the hosted preferences page.

| Tool | What it does | Write |
| - | - | - |
| `list_preference_sections` | List the workspace's preference sections. | |
| `create_preference_section` | Create a preference section in your workspace. | Yes |
| `get_preference_section` | Retrieve a preference section by id, including its topics. | |
| `replace_preference_section` | Replace a preference section. | Yes |
| `archive_preference_section` | Archive a preference section. | Yes |
| `publish_preferences` | Publish the workspace's preferences page. | Yes |
| `list_preference_topics` | List the topics in a preference section. | |
| `create_preference_topic` | Create a subscription preference topic inside a section. | Yes |
| `get_preference_topic` | Retrieve a topic within a section. | |
| `replace_preference_topic` | Replace a topic within a section. | Yes |
| `archive_preference_topic` | Archive a topic within a section. | Yes |

`create_preference_topic` and `replace_preference_topic` take a `digest` object: its template, schedules, and categories. Leaving `digest` out of a replace keeps the topic's digest, and `null` turns it off.

## Digests

`release_digest` sends every recipient's held digest for a schedule now. `release_user_digest` does the same for one recipient and topic.

| Tool | What it does | Write |
| - | - | - |
| `release_digest` | Release a digest schedule early, sending what users have collected so far instead of waiting for the scheduled time. | Yes |
| `list_digest_instances` | List the digest instances for a schedule. | |
| `release_user_digest` | Release one recipient's held digest for a topic now, instead of waiting for its schedule. | Yes |

## Automations (legacy)

Automations is the previous workflow product. Existing automations keep running, and new workflows are built as [Journeys
DOC](/docs/journeys/overview).

| Tool | What it does | Write |
| - | - | - |
| `list_automations` | List automation templates in the workspace, with each template ID and its version state. | |
| `invoke_automation_template` | Invoke an automation run from an existing automation template. | Yes |
| `invoke_ad_hoc_automation` | Invoke an ad-hoc automation with inline steps. | Yes |
| `cancel_automation` | Cancel a running automation by its `cancelation_token`. | Yes |

## Docs

Returns the SDK install steps for a platform, so an agent adding Courier to your app installs the current package.

| Tool | What it does | Write |
| - | - | - |
| `courier_installation_guide` | Get the Courier SDK installation guide for a specific platform. | |

## Diagnostics

Reports the key, base URL, and package version a session is using, which answers "which workspace is this agent talking to?"

| Tool | What it does | Write |
| - | - | - |
| `get_environment_config` | Check which Courier API key, base URL, and package version this MCP session is using. | |

## FAQ

> **How many tools does the Courier MCP server have?**
>
> The hosted Courier MCP server exposes 170 tools, covering sends, message logs, profiles, lists, audiences, templates, journeys, broadcasts, email previews, tenants, preferences, providers, and more. Ask your agent to list its Courier tools to see the set it loaded.

> **Which Courier MCP tools change data?**
>
> Every Courier MCP tool marked Write on this page changes workspace state, and that includes every send. The unmarked tools only read. Require approval for the write tools if your client supports it.

> **Can an AI agent send real notifications through Courier MCP?**
>
> The Courier MCP send tools deliver through the providers configured in the API key's environment, so a Production key reaches real customers. Connect a Test key while you experiment. Test's built-in email provider only delivers to the address you signed up with.

> **Why didn't a template change made through Courier MCP reach recipients?**
>
> Template writes through Courier MCP land on the draft, and sends use the published version. Ask the agent to call `publish_notification`, or `publish_journey_template` for a template inside a journey.

> **What is the difference between Courier MCP and Courier Skills?**
>
> The Courier MCP server gives an agent tools that call the Courier API on your workspace. [Courier Skills
> DOC](/docs/resources/skills) gives a coding agent instructions for writing Courier code in your app. Most setups use both: Skills while the agent writes code, MCP when it needs to read or change the workspace.


# Postman collection
Source: https://www.courier.com/docs/resources/postman

Try every Courier endpoint in Postman with the official collection.

Test the Courier API in Postman with no integration code.

The collection is updated with every release, so it always reflects the latest endpoints.

> **[Open the Courier collection in Postman](https://www.postman.com/trycourier/courier-s-api-collections/collection/aiy9mtt/courier)**
>
> Fork it into your workspace, then add your API key and send.

## Set up

**1. Fork the collection**

Open the collection above and click **Fork**. Your copy stays linked to the source, so you can pull in updates. Requires a [Postman account](https://www.postman.com/).

**2. Add bearer auth**

On the forked collection's **Authorization** tab, set **Auth Type** to **Bearer Token** and enter `{{auth_token}}`.

**3. Create an environment**

In **Environments**, add `Courier Test` with a variable `auth_token`. Paste your [Test API key](https://app.courier.com/~/test/platform/api-keys) into **Current value** (not Initial value, which syncs to Postman's cloud). Repeat for Production, then pick an environment.

## Send your first request

With `Courier Test` active, open **Send a Message** ([Send a message](/docs/api-reference/send/send-a-message)), add a body, and click **Send**. `template` is the ID or alias of a published [template
DOC](/docs/design/templates/overview). `data` supplies its variables:

```javascript Node.js theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Sarah Bennett",
    },
    routing: {
      method: "single",
      channels: [
        "email",
      ],
    },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "name": "Sarah Bennett",
        },
        "routing": {
            "method": "single",
            "channels": [
                "email",
            ],
        },
    },
)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": {
        "name": "Sarah Bennett"
      },
      "routing": {
        "method": "single",
        "channels": [
          "email"
        ]
      }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Sarah Bennett"
    },
    routing: {
      method: "single",
      channels: [
        "email"
      ]
    }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("email")},
			},
			Method: "single",
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "name", "Sarah Bennett"
        )))
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("email")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => [
      'name' => 'Sarah Bennett',
    ],
    'routing' => [
      'method' => 'single',
      'channels' => [
        'email',
      ],
    ],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
        Routing = new() { Channels = ["email"], Method = Send::Method.Single },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"name": "Sarah Bennett"}' \
  --message.routing '{"method": "single", "channels": ["email"]}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123.
```

Courier returns a `requestId` you can track in your [message logs
DOC](/docs/monitor/overview).

> [!NOTE]
>
> Treat your API key like a password. Use [Postman Vault](https://learning.postman.com/docs/use/postman-vault/manage-vault-secrets/) for team keys, and [rotate it
> DOC](/docs/workspaces/environments#api-keys) if it leaks.


# Courier Skills: the agent skill for building notifications
Source: https://www.courier.com/docs/resources/skills

Install Courier Skills so Claude Code, Cursor, or Codex gets your Courier integration right the first time and debugs the Courier code you already have.

Courier Skills is an agent skill: a set of markdown files your coding agent reads before it writes Courier code. Install it once and the agent builds against the APIs Courier ships today, not the ones it half-remembers.

## Install Courier Skills

**Any assistant (recommended)**

```bash theme={null}
npx skills add trycourier/courier-skills
```

Works with Cursor, Claude Code, Codex, Windsurf, Cline, and any tool that supports agent skills. Run `npx skills update courier` to pick up changes.

**Claude Code (plugin)**

The plugin self-updates and connects the Courier docs MCP server, so the agent can search the docs with no extra setup:

```
/plugin marketplace add trycourier/courier-skills
/plugin install courier@courier-skills
```

Run `/plugin update courier@courier-skills` to pick up changes.

**Manual clone**

For any tool that reads a skills directory, clone [courier-skills on GitHub](https://github.com/trycourier/courier-skills) and copy the skill into your assistant's skills folder:

```bash theme={null}
git clone https://github.com/trycourier/courier-skills.git /tmp/courier-skills
cp -R /tmp/courier-skills/skills/courier ~/.cursor/skills/   # or ~/.claude/skills/
```

Agents discover the skill from the `name` and `description` frontmatter in `SKILL.md`. There is exactly one, named `courier`, and nothing else to configure.

## Verify the skill is loaded

Confirm the installer put the skill where your agent reads it:

```bash theme={null}
npx skills list
```

`courier` should appear in the list. The Claude Code plugin doesn't show up there, so skip to the next step if you installed that way.

Then ask your agent a question only the skill can answer:

```text theme={null}
Which Courier skill files would you read to add a one-time passcode flow?
```

An agent with the skill loaded names files such as `transactional.md` and `sms.md`. Those files exist only in the skill, so an agent answering from memory can't name them.

**Most agents load skills when a session starts.** If `npx skills list` shows the skill but the agent doesn't know it, start a new session.

## What the skill does for your agent

Courier Skills gives your agent Courier's own guidance on building notifications: how to call the API, which Courier feature fits each job, and the rules each channel needs. Your agent writes working Courier code on the first try, and it can debug the notification code you already have, including why a message didn't deliver.

The agent reads `SKILL.md` first, which points it at the one or two files a task needs. It loads only those, so it codes faster and spends fewer tokens than it would searching the docs or retrying calls that fail.

## What you can build with it

| You ask | The agent builds |
| - | - |
| "Add a notification center to my React app" | Courier Inbox with JWT auth and real-time updates |
| "Batch these into a daily digest" | A digest on a preference topic, released on each user's schedule |
| "Fall back from push to email if push fails" | A routing strategy with ordered channels |
| "Send an OTP and an order receipt" | Transactional sends with idempotency keys, never batched or delayed |
| "Build a 5-day onboarding series" | A journey with delay and branch nodes |
| "Why didn't this message deliver?" | A trace from the `requestId` to the message history, then the provider |

## What the skill covers

| Area | What the agent knows |
| - | - |
| Email | Deliverability, SPF, DKIM, and DMARC, sender setup, bounce handling |
| SMS | 10DLC registration, segment math, sender setup, quiet hours |
| Push | APNs and FCM setup, device tokens, permission priming |
| Inbox | Sending to the inbox, JWT auth, and rendering in React, Web Components, React Native, iOS, Android, and Flutter |
| Slack and Microsoft Teams | Block Kit and OAuth for Slack, Adaptive Cards and bot setup for Teams |
| WhatsApp | Approved templates and the 24-hour window |
| Transactional | Password resets, OTPs, receipts, dunning, appointment reminders, and security alerts, each mapped to a Courier primitive |
| Lifecycle | Onboarding, adoption, re-engagement, referral, and campaigns |
| Platform | Journeys, templates and Elemental, routing, preferences, digests, brands, tenants, audiences, bulk sends, webhooks, metrics, the CLI, and MCP |

## FAQ

> **Do I need a Courier API key to install Courier Skills?**
>
> Courier Skills needs no API key. It is a set of instructions the agent reads, and it touches nothing in your workspace. The code the agent writes needs a key to run, and so do the MCP server and CLI.

> **How is Courier Skills different from the MCP server?**
>
> Courier Skills changes the code your agent writes. The [MCP server](/docs/resources/mcp) and the [Courier CLI](/docs/resources/cli) call the Courier API, so the agent can create templates, send notifications, and read delivery logs in your workspace. Most setups install Skills and the MCP server together.

> **Which AI coding tools support Courier Skills?**
>
> Courier Skills installs into Claude Code, Cursor, Codex, Windsurf, Cline, and any other tool that loads agent skills from a `SKILL.md` file. Claude Code can also install it as a plugin that self-updates.

> **Is Courier Skills open source?**
>
> Courier Skills is MIT-licensed and public at [trycourier/courier-skills on GitHub](https://github.com/trycourier/courier-skills).


# Courier Android SDK
Source: https://www.courier.com/docs/sdk-libraries/android

Prebuilt inbox and preferences UI, push token sync, and Kotlin APIs for Android.

The Courier Android SDK gives you prebuilt UI components and Kotlin APIs. It handles authentication, token management, and real-time message delivery.

This page is the Android reference: what to install, how to configure Gradle, and the Kotlin API surface. Each flow is written once and applies to every platform.

| To do this | Read |
| :- | :- |
| Render the inbox | [Add an inbox&#xA;DOC](/docs/in-app/add-an-inbox?lang=Android) |
| Theme it, handle taps, or build your own UI | [Customize the inbox&#xA;DOC](/docs/in-app/customize-the-inbox?lang=Android) |
| Set up push, from provider to device | [Set up push notifications&#xA;GUIDE](/docs/guides/set-up-mobile-push) |
| Add the preference center | [Add a preference center&#xA;DOC](/docs/in-app/add-a-preference-center?lang=Android) |
| Mint the JWT you sign in with | [Authenticate users&#xA;DOC](/docs/in-app/authenticate-users?lang=Android) |

Available on
[ GitHub](https://github.com/trycourier/courier-android).

| Requirement | Value |
| - | - |
| Min Android SDK | 23 |
| Gradle | 8.4+ |
| Package manager | Jitpack |

## Installation

**1. Add the Jitpack repository**

In your `settings.gradle` or `settings.gradle.kts`:

```gradle theme={null}
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
```

**2. Add the dependency**

In your app's `build.gradle`:

```gradle theme={null}
dependencies {
    implementation 'com.github.trycourier:courier-android:LATEST_VERSION'
}
```

Replace `LATEST_VERSION` with the current version from [GitHub Releases](https://github.com/trycourier/courier-android/releases).

**3. Initialize the SDK**

Call `Courier.initialize()` in your `Application` class before using other SDK features. This gives Courier access to `SharedPreferences` to persist state across sessions.

```kotlin theme={null}
class YourApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Courier.initialize(this)
    }
}
```

**4. Use a Material theme**

The prebuilt inbox and preference center only render correctly when your app theme extends `Theme.MaterialComponents`. Set it in `res/values/themes.xml`.

```xml theme={null}
<style name="Theme.YourApp" parent="Theme.MaterialComponents.DayNight.NoActionBar">
    <!-- your attributes -->
</style>
```

> [!NOTE]
>
> If you only use [`CourierClient`](#courierclient) APIs directly, skip the `initialize` and theme steps.

## Authentication

Courier authenticates with a **JWT** that your backend mints with your Courier API key, never in client code. [Authenticate users
DOC](/docs/in-app/authenticate-users?lang=Android) covers the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See [EU setup
DOC](/docs/in-app/authenticate-users?lang=Android#connect-to-the-eu-datacenter).

Credentials persist across app sessions, so you sign in once per user rather than on every launch.

```kotlin theme={null}
lifecycleScope.launch {
  Courier.shared.signIn(accessToken = jwt, userId = "your_user_id")
  Courier.shared.signOut()
}
```

## Inbox

[Add an inbox
DOC](/docs/in-app/add-an-inbox?lang=Android) is the setup flow. These are the types it uses on Android.

| Type | What it is |
| :- | :- |
| `CourierInbox()` | The prebuilt inbox as a Jetpack Compose composable |
| `com.courier.android.ui.inbox.CourierInbox` | The same inbox as an XML layout view |
| `CourierInboxTheme` | Fonts, colors, unread indicators, swipe actions, button styles |
| `addInboxListener` | Raw message data and events, for a UI you render yourself |

Every callback and action these expose is documented per platform in [Data and actions
DOC](/docs/in-app/build-a-custom-inbox?lang=Android#data-and-actions).

### Inbox theme

`CourierInboxTheme` is a constructor argument on the composable, and a property on the view. Light and dark themes are separate.

```kotlin theme={null}
CourierInbox(
    modifier = Modifier.padding(innerPadding),
    canSwipePages = true,
    lightTheme = yourLightTheme,
    darkTheme = yourDarkTheme,
    ...
)
```

![Default Inbox](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/android-inbox-default.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=817cf39df7f5c01b47a61a6d267257fb)

![Styled Inbox](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/android-inbox-styled.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=3c22892996909ce834922f4b4434f391)

Default and styled Inbox on Android

Branding from [Courier Studio](https://app.courier.com/designer/brands) also applies. The SDK reads primary color and footer visibility from your brand settings.

## Push notifications

[Set up push notifications
GUIDE](/docs/guides/set-up-mobile-push) is the setup flow, from connecting FCM to a device that receives push. It covers the `FirebaseMessagingService` and `CourierActivity` wiring, `setToken`, permission, and reading the payload on tap.

> [!NOTE]
>
> **Firebase is a separate dependency.** From Courier Android 6.x the SDK no longer bundles Firebase Messaging. Declare your own Firebase BoM and `firebase-messaging` artifact so you can subclass `FirebaseMessagingService`.

```gradle theme={null}
dependencies {
    implementation platform('com.google.firebase:firebase-bom:33.1.2')
    implementation "com.google.firebase:firebase-messaging"
}
```

> [!NOTE]
>
> Push notifications require a physical device and a release build for reliable token registration and delivery. Emulators are best-effort.

Two entry points are Android-only, and neither has a counterpart on the other platforms.

| Call | When |
| :- | :- |
| `Courier.shared.refreshFcmToken()` | Force Firebase to hand the SDK a fresh token |
| `Courier.shared.isPushPermissionGranted(context)` | Read permission without prompting |

## Preferences

[Add a preference center
DOC](/docs/in-app/add-a-preference-center?lang=Android) is the setup flow. These are the types it uses on Android.

| Type | What it is |
| :- | :- |
| `CourierPreferences()` | The prebuilt preference center as a composable |
| `com.courier.android.ui.preferences.CourierPreferences` | The same view for XML layouts |
| `mode` | `Mode.Topic` or `Mode.Channels(listOf(PUSH, SMS, EMAIL))` |
| `CourierPreferencesTheme` | Fonts, colors, toggle styles, section headers |

> [!NOTE]
>
> The composable renders the default channels mode. Set `mode` on the XML view for topic mode.

> [!NOTE]
>
> Topics and sections are configured in the [Preferences Editor
> GUIDE](/docs/guides/build-a-preference-center#configure-the-topics). See [Preferences Overview
> DOC](/docs/recipients/preferences/overview) for how preference enforcement works at send time.

### Preferences theme

Light and dark themes are separate, and [Courier Studio branding](https://app.courier.com/designer/brands) applies automatically when you supply a `brandId`.

<video aria-label="Default Preferences" />

<video aria-label="Styled Preferences" />

Default and styled Preferences on Android

## CourierClient

For advanced use cases, `CourierClient` is a low-level wrapper around the Courier API. Each client holds its own credentials, so you can spin up as many as you need.

### Initialization

```kotlin theme={null}
val client = CourierClient(
    jwt          = "...",          // Optional. Required for most authenticated calls
    userId       = "your_user_id",
    connectionId = "...",          // Optional. Used for the inbox websocket
    tenantId     = "...",          // Optional. Scopes the client to a tenant
    apiUrls      = CourierClient.ApiUrls.eu(), // Optional. Use for EU users
    showLogs     = true            // Optional. Defaults to your build configuration
)

val options = client.options
client.log("...")
client.warn("...")
client.error("...")
```

### Token management

```kotlin theme={null}
client.tokens.putUserToken(
    token = "...",
    provider = "firebase-fcm"
)

// Customize device metadata stored alongside the token
val device = CourierDevice(
    appId        = "APP_ID",
    adId         = "AD_ID",
    deviceId     = "DEVICE_ID",
    platform     = "android",
    manufacturer = "Google",
    model        = "Pixel 8"
)

// Or use what the SDK can detect about the current device
// CourierDevice.current(context)

client.tokens.putUserToken(
    token = "...",
    provider = "firebase-fcm",
    device = device
)

client.tokens.deleteUserToken(token = "...")
```

### Inbox

```kotlin theme={null}
val messages = client.inbox.getMessages(
    paginationLimit = 25,
    startCursor = null
)

val archived = client.inbox.getArchivedMessages(
    paginationLimit = 25,
    startCursor = null
)

val unreadCount = client.inbox.getUnreadMessageCount()

client.inbox.open(messageId = "...")
client.inbox.read(messageId = "...")
client.inbox.unread(messageId = "...")
client.inbox.archive(messageId = "...")
client.inbox.readAll()
```

### Inbox websocket

Receive real-time updates across devices:

```kotlin theme={null}
val socket = client.inbox.socket

socket.onOpen  = { print("Socket opened") }
socket.onClose = { code, reason -> print("Socket closed: $code, $reason") }
socket.onError = { error -> print(error) }

socket.receivedMessage = { message -> print(message) }
// Fires only when the event comes from a different connectionId
// Available events: READ, UNREAD, MARK_ALL_READ, OPENED, ARCHIVE
socket.receivedMessageEvent = { event -> print(event) }

lifecycleScope.launch {
    socket.connect()
    socket.sendSubscribe()

    // When done:
    socket.disconnect()
}
```

### Preferences

```kotlin theme={null}
val prefs = client.preferences.getUserPreferences(paginationCursor = null)

val topic = client.preferences.getUserPreferenceTopic(topicId = "...")

client.preferences.putUserPreferenceTopic(
    topicId = "...",
    status = CourierPreferenceStatus.OPTED_IN,
    hasCustomRouting = true,
    customRouting = listOf(CourierPreferenceChannel.PUSH)
)
```

### Branding

```kotlin theme={null}
val brand = client.brands.getBrand(brandId = "...")
```

### URL tracking

Pass any tracking URL found inside a push notification payload or inbox message:

```kotlin theme={null}
// Available events: CLICKED, DELIVERED, OPENED, READ, UNREAD
client.tracking.postTrackingUrl(
    url = "courier_tracking_url",
    event = CourierTrackingEvent.DELIVERED
)
```

See the full [Courier API reference
DOC](/docs/reference/api-overview).


# Courier Angular SDK
Source: https://www.courier.com/docs/sdk-libraries/courier-angular-web

Inbox, toast, and preferences components for Angular, plus the CourierService.

The Angular SDK wraps Courier's in-app components as standalone Angular components, plus an injectable service that exposes the client behind them.

* `<courier-inbox>`: inbox for displaying and managing messages
* `<courier-inbox-popup-menu>`: popup menu version of the inbox
* `<courier-toast>`: toast notifications for time-sensitive alerts
* `<courier-preferences>`: preference center for topic subscriptions and delivery
* `CourierService`: injectable service for custom UIs

> [!TIP]
>
> See these components in the [interactive Inbox demo](https://www.courier.com/inbox-demo). No setup required.

## Installation

Available on
[ GitHub](https://github.com/trycourier/courier-web/tree/main/%40trycourier/courier-angular)
and [ npm](https://www.npmjs.com/package/@trycourier/courier-angular).

```bash theme={null}
npm install @trycourier/courier-angular
```

`@angular/core` (>= 17), `@angular/common` (>= 17), and `rxjs` (>= 7) are peer dependencies.

> [!NOTE]
>
> The Courier Angular components are **standalone**. Import the component classes
> (`CourierInboxComponent`, `CourierInboxPopupMenuComponent`, `CourierToastComponent`,
> `CourierPreferencesComponent`) directly into a component's `imports` array, or into a
> standalone bootstrap. No NgModule is required.

> [!NOTE]
>
> Not using Angular? Use the
> [Web Components SDK
> DOC](/docs/sdk-libraries/courier-web-components) instead. Its elements work in any JavaScript project.

## Authentication

Courier authenticates with a **JWT** that your backend mints with your Courier API key, never in client code. [Authenticate users
DOC](/docs/in-app/authenticate-users?lang=Angular) is the full guide: the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See [EU setup
DOC](/docs/in-app/authenticate-users?lang=Angular#connect-to-the-eu-datacenter).

```ts theme={null}
private readonly courier = inject(CourierService);

this.courier.signIn({ userId, jwt });  // also accepts tenantId, apiUrls, showLogs
this.courier.signOut();
this.courier.auth$.subscribe(({ userId }) => { /* emits on sign-in and sign-out */ });
```

## Quick start

Import `CourierInboxComponent` into your standalone component. Inject `CourierService` to authenticate.

```ts theme={null}
import { AfterViewInit, Component, inject } from "@angular/core";
import { CourierInboxComponent, CourierService } from "@trycourier/courier-angular";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [CourierInboxComponent],
  template: `<courier-inbox></courier-inbox>`,
})
export class AppComponent implements AfterViewInit {
  private readonly courier = inject(CourierService);

  ngAfterViewInit(): void {
    // Generate a JWT for your user on your backend server
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

    // Authenticate the user
    this.courier.signIn({ userId: "user_123", jwt });
  }
}
```

> [!TIP]
>
> Follow the [inbox guide
> DOC](/docs/in-app/add-an-inbox?lang=Angular) for step-by-step guidance, including backend JWT generation.

## Component reference

Each component's inputs, theme, outputs, and custom-render surface live with the feature. These links open on the Angular tab.

| To do this | Go here |
| - | - |
| Embed the inbox, or render it as a popup | [Add an inbox&#xA;DOC](/docs/in-app/add-an-inbox?lang=Angular) |
| Theme it, handle clicks, replace parts of it | [Customize the inbox&#xA;DOC](/docs/in-app/customize-the-inbox?lang=Angular) |
| Split it into filtered tabs and feeds | [Tabs and feeds&#xA;DOC](/docs/in-app/tabs-and-feeds?lang=Angular) |
| Add toasts, and set auto-dismiss | [Add toasts&#xA;DOC](/docs/in-app/add-toasts?lang=Angular) |
| Theme a toast or replace it | [Customize toasts&#xA;DOC](/docs/in-app/customize-toasts?lang=Angular) |
| Add a preference center | [Add a preference center&#xA;DOC](/docs/in-app/add-a-preference-center?lang=Angular) |
| Theme preferences, or build your own | [Customize preferences&#xA;DOC](/docs/in-app/customize-preferences?lang=Angular) |
| Send a message that reaches the inbox | [Send to the inbox&#xA;DOC](/docs/in-app/send-to-the-inbox) |

**Angular takes the callbacks as outputs, not as props.** Where the other web SDKs pass `onMessageClick`, Angular binds `(messageClick)` and hands you the payload on `$event`. Every sample in the pages above shows the Angular form.

The `CourierInboxTheme`, `CourierToastTheme`, and `CourierPreferencesTheme` objects are the same on React, Vue, Angular, and the Web Components, so each is documented once: [inbox theme
DOC](/docs/in-app/customize-the-inbox#courierinboxtheme-reference), [toast theme
DOC](/docs/in-app/customize-toasts#theme), [preferences theme
DOC](/docs/in-app/customize-preferences#theme).

## CourierService

The injectable `CourierService` gives you programmatic access to Courier. Use it to build custom UIs. It exposes auth/inbox/toast state as RxJS observables plus imperative action methods. Inject it with `inject(CourierService)` or constructor injection. It is `providedIn: "root"`.

### When to use the service vs components

* **Components** (`<courier-inbox>`, `<courier-toast>`): quick integration with the default UI
* **Service** (`CourierService`): custom UIs, programmatic control, state management
* **Both together**: the service manages state, components render

### Reactive state

| Observable | Emits |
| :- | :- |
| `auth$` | `{ userId?: string }` |
| `inbox$` | `{ feeds: Record<string, InboxDataSet>, totalUnreadCount?: number, error?: Error }` |
| `toast$` | `{ error?: Error }` |

**Call `listenForUpdates()` after authentication to open the realtime connection.** Without it, the inbox loads once from the initial fetch and doesn't update again.

**Complete example**: authentication, inbox setup, real-time updates, and displaying messages with the `async` pipe:

```ts theme={null}
import { Component, OnInit, inject } from "@angular/core";
import { AsyncPipe } from "@angular/common";
import { CourierService, defaultFeeds } from "@trycourier/courier-angular";

@Component({
  selector: "app-inbox-list",
  standalone: true,
  imports: [AsyncPipe],
  template: `
    <div *ngIf="courier.inbox$ | async as inbox">
      <div>Total Unread: {{ inbox.totalUnreadCount ?? 0 }}</div>
      <ul>
        <li *ngFor="let message of inbox.feeds['all_messages']?.messages ?? []">
          {{ message.title }}
        </li>
      </ul>
    </div>
  `,
})
export class InboxListComponent implements OnInit {
  readonly courier = inject(CourierService);

  async ngOnInit(): Promise<void> {
    this.courier.signIn({
      userId: "user_123",
      jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    });
    this.courier.registerFeeds(defaultFeeds());
    await this.courier.listenForUpdates();
    await this.courier.load();
  }
}
```

### Methods

| Method | Description |
| :- | :- |
| `signIn(props)` / `signOut()` | Authenticate / sign out the current user. |
| `load(props?)` | Load messages. Optional `{ canUseCache }`. |
| `fetchNextPageOfMessages({ datasetId })` | Fetch next page. Returns `InboxDataSet \| null`. |
| `setPaginationLimit(limit)` | Set messages per page. |
| `registerFeeds(feeds)` | Register feeds and tabs with the datastore. |
| `listenForUpdates()` | Start WebSocket connection for real-time updates. **Required after auth.** |
| `readMessage` / `unreadMessage` / `archiveMessage` / `unarchiveMessage` / `clickMessage` / `openMessage` `(message)` | Per-message actions. |
| `readAllMessages()` | Mark all as read. |
| `addToastMessage(message)` / `removeToastMessage(message)` | Add / remove a message from the toast stack. |
| `getUserPreferences(props?)` and other preferences methods | Read and update notification preferences. |

The service flattens what the other web SDKs nest. Where React reads `inbox.readMessage(message)`, Angular calls `courier.readMessage(message)` and reads the data off `inbox$`. [Data and actions
DOC](/docs/in-app/build-a-custom-inbox?lang=Angular#data-and-actions) covers what each one does.

## Advanced

### Custom-element schema

The Courier Angular components render native custom elements internally. They are self-contained standalone components, so you don't need `CUSTOM_ELEMENTS_SCHEMA` in your own components. Import the component classes.

### Server-side rendering

Courier Inbox and Toast render client-side only. They wire up in `ngAfterViewInit`, which doesn't run on the server. They work with Angular Universal / SSR setups, rendering once on the client.

### Troubleshooting

> **Inbox not updating in real-time**
>
> Call `listenForUpdates()` on `CourierService` after authentication. It opens the WebSocket connection required for real-time updates.
>
> ```ts theme={null}
> this.courier.signIn({ userId, jwt });
> this.courier.registerFeeds(defaultFeeds());
> await this.courier.listenForUpdates(); // Required for real-time
> await this.courier.load();
> ```

> **Messages not loading**
>
> **Possible causes:**
>
> 1. Not authenticated: call `signIn()`
> 2. Feeds not registered: call `registerFeeds()` before `load()`
> 3. Network errors: subscribe to `inbox$` and check its `error`
> 4. JWT expired: generate a new token

> **Authentication errors**
>
> * **Invalid JWT**: generate the JWT correctly on your backend
> * **Expired JWT**: JWTs expire. Generate a new one
> * **Missing scopes**: include `inbox:read:messages` and `inbox:write:events` in the JWT
> * **Wrong user ID**: the `userId` must match the user the JWT was issued for

> **Custom slots not rendering**
>
> Custom render slots are named `<ng-template>` children (e.g. `<ng-template #listItem let-props>`), read by the component via `@ContentChild`. The ref name must match exactly: `#header`, `#listItem`, `#emptyState`, `#loadingState`, `#errorState`, `#paginationItem`, `#menuButton`, `#toastItem`, `#toastItemContent`.

> **TypeScript errors**
>
> Import types directly from the package:
>
> ```ts theme={null}
> import { CourierService, type InboxMessage, type CourierInboxFeed } from "@trycourier/courier-angular";
> ```

### Best practices

* **JWT security**: always generate JWTs server-side. Cache on the client, refresh before expiration (standard: `'1d'`), and include only the scopes you need.
* **Performance**: `canUseCache: true` (default) serves cached data. Set a suitable `setPaginationLimit()`. Prefer the `async` pipe over manual subscriptions so Angular manages teardown.
* **Testing**: provide a mock `CourierService` in `TestBed` to return test data:

```ts theme={null}
import { of } from "rxjs";

TestBed.configureTestingModule({
  providers: [
    {
      provide: CourierService,
      useValue: {
        inbox$: of({ feeds: { all_messages: { messages: mockMessages } }, totalUnreadCount: 5 }),
        signIn: () => {},
      },
    },
  ],
});
```

## TypeScript types

**type InboxMessage**

```typescript theme={null}
type InboxMessage = {
  messageId: string;
  title?: string;
  body?: string;
  read?: string;     // ISO timestamp
  opened?: string;   // ISO timestamp
  archived?: string; // ISO timestamp
  tags?: string[];
  trackingIds?: { clickTrackingId?: string; openTrackingId?: string; };
  actions?: InboxAction[];
  data?: Record<string, unknown>;
}
```

**type InboxDataSet**

```typescript theme={null}
type InboxDataSet = {
  id: string;
  messages: InboxMessage[];
  unreadCount: number;
  canPaginate: boolean;
  paginationCursor: string | null;
}
```

**type CourierInboxFeed**

```typescript theme={null}
type CourierInboxFeed = {
  feedId: string;
  title: string;
  iconSVG?: string;
  tabs: CourierInboxTab[];
}
```

**type CourierInboxTab**

```typescript theme={null}
type CourierInboxTab = {
  datasetId: string;
  title: string;
  filter: CourierInboxDatasetFilter;
}
```

**type CourierInboxDatasetFilter**

```typescript theme={null}
type CourierInboxDatasetFilter = {
  tags?: string[];
  archived?: boolean;
  status?: 'read' | 'unread';
}
```

All filter properties are AND'd together. `{ tags: ['important'], status: 'unread' }` shows unread messages tagged 'important'.

**type CourierToastItemFactoryProps**

```typescript theme={null}
type CourierToastItemFactoryProps = {
  message: InboxMessage;
  autoDismiss: boolean;
  autoDismissTimeoutMs: number;
  dismiss: () => void;
}
```


# Courier JS SDK
Source: https://www.courier.com/docs/sdk-libraries/courier-js-web

Read and update inbox and preferences data in the browser without UI components.

> [!TIP]
>
> `@trycourier/courier-js` exposes the Courier APIs for browser applications.
>
> Want ready-made UI components? See [Courier React
> DOC](/docs/sdk-libraries/courier-react-web/) or [Courier UI Web Components
> DOC](/docs/sdk-libraries/courier-web-components).

## Installation

Available on
[ GitHub](https://github.com/trycourier/courier-web/tree/main/%40trycourier/courier-js)
and [ npm](https://www.npmjs.com/package/@trycourier/courier-js).

```bash theme={null}
npm install @trycourier/courier-js
```

## Usage

Instantiate the Courier client.

```ts theme={null}
const courierClient = new CourierClient({
    userId: 'user_123-id',
    jwt: 'eyJ.mock.jwt',
});
```

### `CourierClient` options

| Option | Type | Required | Description |
| - | - | - | - |
| userId | string | Yes | The user to authenticate and whose messages should be fetched. This is the same user ID to which you should send a message. |
| jwt | string | Yes | The access token (JWT) minted for the user. |
| tenantId | string | No | Optional: The tenant to which messages should be scoped. See [Inbox and Tenants&#xA;DOC](/docs/in-app/send-to-the-inbox#scope-the-inbox-to-a-tenant) for more information. |
| apiUrls | `CourierApiUrls` | No | Optional: base URLs for the Courier and inbox APIs. Defaults to **US** hosts. For EU, see [Connect to the EU datacenter&#xA;DOC](/docs/in-app/authenticate-users#connect-to-the-eu-datacenter). Type: [`CourierApiUrls`](#courierapiurls) under Models. |
| showLogs | boolean | No | Optional: Enable debugging console logs from the Courier SDK. Defaults to `process.env.NODE_ENV === 'development'`. |

## Authentication

Courier authenticates with a **JWT** that your backend mints with your Courier API key, never in client code. [Authenticate users
DOC](/docs/in-app/authenticate-users) covers the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See [EU setup
DOC](/docs/in-app/authenticate-users#connect-to-the-eu-datacenter).

`CourierClient` takes the user and token at construction. See [`CourierClient` options](#courierclient-options) above. The higher-level packages call `Courier.shared.signIn` instead:

```ts theme={null}
import { Courier } from '@trycourier/courier-js';

Courier.shared.signIn({ userId: 'user_123-id', jwt: 'eyJ.mock.jwt' });
Courier.shared.signOut();
Courier.shared.addAuthenticationListener(({ userId }) => { /* ... */ });
```

## Inbox APIs

The Courier Inbox APIs read and update inbox messages.

Pass an optional `filter` to `getMessages()` to narrow results by tags, archive state, read status, or a **creation time lower bound** (`from`, an ISO 8601 datetime string). `getUnreadCounts()` takes the same shape. See [Unread counts](#unread-counts).

```ts theme={null}
import { CourierClient } from '@trycourier/courier-js';

const courierClient = new CourierClient({
    userId: 'user_123-id',
    jwt: 'eyJ.mock.jwt',
});

// Fetch inbox messages for the authenticated user
const inboxMessages = await courierClient.inbox.getMessages();

// Messages created on or after a given time (e.g. last 7 days)
const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
const recent = await courierClient.inbox.getMessages({
  filter: { from: since },
});

// Fetch archived messages for the authenticated user
const archivedMessages = await courierClient.inbox.getArchivedMessages();

// Get the message id and tracking ids for the first message
const { messageId, trackingIds } = inboxMessages.data.messages.nodes[0];

// Mark a message "clicked"
await courierClient.inbox.click({
    messageId,
    trackingId: trackingIds.clickTrackingId,
});

// Mark a message "read"
await courierClient.inbox.read({ messageId });

// Mark a message "unread"
await courierClient.inbox.unread({ messageId });

// Mark a message "opened"
await courierClient.inbox.open({ messageId });

// Archive a message
await courierClient.inbox.archive({ messageId });

// Unarchive a message
await courierClient.inbox.unarchive({ messageId });

// Mark all messages "read"
await courierClient.inbox.readAll();

// Archive all "read" messages
await courierClient.inbox.archiveRead();

// Archive all inbox messages
await courierClient.inbox.archiveAll();
```

## Unread counts

There are three ways to show unread badges or totals in a custom UI:

* a single global count
* batched counts per filter, for tabs or feeds
* the `unreadCount` field returned with `getMessages()`

For live updates, connect the inbox WebSocket and refetch counts when message events arrive.

### `getUnreadMessageCount()`

Returns a `Promise<number>`: the total unread inbox messages for the authenticated user. If you pass `tenantId` to `CourierClient`, the count is scoped to that tenant.

```ts theme={null}
const unreadCount = await courierClient.inbox.getUnreadMessageCount();
```

### `getUnreadCounts(filtersMap)`

Fetches unread counts for several named filters in **one** request. Use it for per-tab or per-feed badges without multiple round trips.

| Argument | Type | Description |
| - | - | - |
| `filtersMap` | `Record<string, CourierGetInboxMessagesQueryFilter>` | Map from your own dataset ID (e.g. tab key) to the same filters you use with `getMessages()` (`tags`, `archived`, `status`, `from`). |

Returns `Promise<Record<string, number>>`: the same keys as `filtersMap`, each mapped to an unread count.

If a filter sets `status: 'read'`, the client returns `0` for that key **without** calling the server (there are no unread messages in a read-only view).

```ts theme={null}
const counts = await courierClient.inbox.getUnreadCounts({
  all: {},
  important: { tags: ['important'] },
  billing: { tags: ['billing'] },
});
// counts.all, counts.important, counts.billing
```

Combine `from` with other fields so per-tab badges only count messages after a cutoff. Use the same ISO 8601 string as `getMessages()`.

```ts theme={null}
const since = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();

const counts = await courierClient.inbox.getUnreadCounts({
  last30Days: { from: since },
});
```

### Unread count from `getMessages()`

`getMessages()` responses include both `count` (total messages matching the list filter) and `unreadCount`. Unless your filter already sets `status`, `unreadCount` reflects the unread subset that matches your `tags`, `archived`, `from`, and tenant constraints.

```ts theme={null}
const response = await courierClient.inbox.getMessages({
  filter: { tags: ['important'] },
});

const unreadInImportantTab = response.data?.unreadCount;
const page = response.data?.messages;
```

### Real-time updates

The SDK doesn't push a numeric unread total over the socket. Subscribe to inbox message events, then refetch counts (or reload your message list) when relevant events fire.

1. Call `courierClient.inbox.socket.connect()` so the WebSocket is open.
2. Register listeners with `addMessageEventListener`. It returns a function. Call that function to unsubscribe.
3. Optionally compare `envelope.event` to `InboxMessageEvent` (exported from `@trycourier/courier-js`).

```ts lines theme={null}
import {
  CourierClient,
  InboxMessageEvent,
  type InboxMessageEventEnvelope,
} from '@trycourier/courier-js';

const courierClient = new CourierClient({
  userId: 'user_123-id',
  jwt: 'eyJ.mock.jwt',
});

await courierClient.inbox.socket.connect();

const removeListener = courierClient.inbox.socket.addMessageEventListener(
  async (envelope: InboxMessageEventEnvelope) => {
    if (
      envelope.event === InboxMessageEvent.Read ||
      envelope.event === InboxMessageEvent.Unread ||
      envelope.event === InboxMessageEvent.NewMessage ||
      envelope.event === InboxMessageEvent.MarkAllRead
    ) {
      const updated = await courierClient.inbox.getUnreadMessageCount();
      // Update your UI (e.g. nav badge)
      console.log('Unread count:', updated);
    }
  }
);

// When you no longer need updates:
removeListener();
```

`InboxMessageEvent` includes: `NewMessage` (`'message'`), `Read`, `Unread`, `Archive`, `ArchiveAll`, `ArchiveRead`, `Clicked`, `MarkAllRead`, `Opened`, `Unarchive`, and `Unopened`. Listen to whichever events should trigger a refresh.

> [!TIP]
>
> Building with React? [Courier React
> DOC](/docs/sdk-libraries/courier-react-web/) components and the `useCourier()` hook expose `totalUnreadCount`, per-tab unread counts, and real-time updates with no socket wiring. See [CourierInboxPopupMenu
> DOC](/docs/sdk-libraries/courier-react-web/) and the `useCourier()` section on that page.

## Preferences APIs

The Courier Preferences APIs read and update a user's Preferences per topic. See the [Preferences API reference](/docs/api-reference/user-preferences/get-users-preferences).

```jsx theme={null}
// Get list of preferences
const preferences = await courierClient.preferences.getUserPreferences();

// Get a preference topic
const topic = await courierClient.preferences.getUserPreferenceTopic({
    topicId: 'HVS...'
});

// Update a preference topic
const topic = await courierClient.preferences.putUserPreferenceTopic({
    topicId: 'HVS...',
    status: 'OPTED_IN',               // 'OPTED_IN' | 'OPTED_OUT' | 'REQUIRED'
    hasCustomRouting: true,           // true | false
    customRouting: ['inbox', 'push'], // Array of: 'direct_message' | 'inbox' | 'email' | 'push' | 'sms' | 'webhook'
});
```

## Brands APIs

The Courier Brands APIs read custom Brand settings. See the [Brands API reference](/docs/api-reference/brands/list-brands).

```jsx theme={null}
// Gets a brand by id
const brand = await courierClient.brands.getBrand({
    brandId: 'YF1...'
});
```

## Lists

The Courier Lists APIs subscribe and unsubscribe users to Lists. See the [Lists API reference](/docs/api-reference/lists/list-lists).

```jsx theme={null}
// Subscribes the authenticated user to listId
await courierClient.lists.putSubscription({
    listId: 'your_list_id'
});

// Unsubscribes the authenticated user from listId
await courierClient.lists.deleteSubscription({
    listId: 'your_list_id'
});
```

## Models

### Inbox

#### `InboxMessage`

```ts theme={null}
export interface InboxMessage {
    messageId: string;
    title?: string;
    body?: string;
    preview?: string;
    actions?: InboxAction[];
    data?: Record<string, any>;
    created?: string;
    archived?: string;
    read?: string;
    opened?: string;
    tags?: string[];
    trackingIds?: {
        archiveTrackingId?: string;
        openTrackingId?: string;
        clickTrackingId?: string;
        deliverTrackingId?: string;
        unreadTrackingId?: string;
        readTrackingId?: string;
    };
}
```

#### `InboxAction`

```ts theme={null}
export interface InboxAction {
    content?: string;
    href?: string;
    data?: Record<string, any>;
    background_color?: string;
    style?: string;
}
```

#### `CourierGetInboxMessagesQueryFilter`

Optional filters for `getMessages()` and entries in `getUnreadCounts()`. Fields combine with **AND** logic.

```ts theme={null}
export interface CourierGetInboxMessagesQueryFilter {
  tags?: string[];
  archived?: boolean;
  status?: 'read' | 'unread';
  /** ISO 8601 datetime; only messages created at or after this time are included */
  from?: string;
}
```

#### `CourierApiUrls`

The type of `CourierClient` `apiUrls`, and of the same option on `signIn` in the React and UI packages. It holds the base URLs the SDK talks to, grouped under `courier` and `inbox`.

Build one from a preset rather than by hand. A preset is the only supported way to target a region, and it keeps working when a host changes:

```ts theme={null}
import {
  EU_COURIER_API_URLS,
  getCourierApiUrlsForRegion,
  type CourierApiRegion,
  type CourierApiUrls,
} from '@trycourier/courier-js';

const eu: CourierApiUrls = EU_COURIER_API_URLS;
const region: CourierApiRegion = 'eu';        // 'us' | 'eu'
const resolved: CourierApiUrls = getCourierApiUrlsForRegion(region);
```

`CourierApiUrls` is exported, so your editor shows the full field list if you need it. For EU setup, see [Connect to the EU datacenter
DOC](/docs/in-app/authenticate-users#connect-to-the-eu-datacenter).

### Preferences

#### `CourierUserPreferencesTopic`

```ts theme={null}
export interface CourierUserPreferencesTopic {
    topicId: string;
    topicName: string;
    sectionId: string;
    sectionName: string;
    status: CourierUserPreferencesStatus;
    defaultStatus: CourierUserPreferencesStatus;
    hasCustomRouting: boolean;
    customRouting: CourierUserPreferencesChannel[];
}
```

#### `CourierUserPreferencesStatus`

```ts theme={null}
export type CourierUserPreferencesStatus =
  | "OPTED_IN"
  | "OPTED_OUT"
  | "REQUIRED"
  | "UNKNOWN";
```

#### `CourierUserPreferencesChannel`

```ts theme={null}
export type CourierUserPreferencesChannel =
  | "direct_message"
  | "inbox"
  | "email"
  | "push"
  | "sms"
  | "webhook"
  | "unknown";
```

### Brands

#### `CourierBrand`

```jsx theme={null}
export interface CourierBrand {
    id: string;
    name: string;
    created: number;
    updated: number;
    published: number;
    version: string;
    settings?: CourierBrandSettings;
}
```


# Courier React v8 migration guide
Source: https://www.courier.com/docs/sdk-libraries/courier-react-v8-migration-guide

Move from @trycourier/react-inbox and react-provider to courier-react v8 and up.

![](https://mintcdn.com/courier-4f1f25dc/LdpdyPjJHKHJqFY9/assets/courier-inbox-react-banner.webp?fit=max\&auto=format\&n=LdpdyPjJHKHJqFY9\&q=85\&s=6bad47bf2a7f6fe99cf306472bdb823d)

## What's new in React v8+

v8+ is a major update to Courier's web SDKs. It brings:

* A redesigned UI with built-in dark mode
* Themeable components
* A smaller JavaScript bundle with no third-party dependencies

> [!TIP]
>
> **Pins** aren't yet supported in v8+. A message can't be pinned to the top of the inbox. If your app needs them, stay on v7 for now.
>
> **Tags** carry over, but the model changed. v7 added and removed a message's tags from the client. In v8+ a tag is a read filter: you set tags on the send, and a [tab](#4d-feeds-and-tabs) shows the messages carrying them.

## What's in this guide

Migration steps for:

* [Courier Inbox components](#4-upgrade-inbox-components)
* [Courier Toast components](#5-upgrade-toast-components)
* [Courier Preferences components](#6-upgrade-preferences-components)

All three share the same first steps: upgrade dependencies and authentication. After those, skip to [Toasts](#5-upgrade-toast-components) or [Preferences](#6-upgrade-preferences-components) if you have no Inbox components to migrate.

## Migration steps

### 1. Upgrade dependencies

v8+ ships as one package: `@trycourier/courier-react` for React 18+, or `@trycourier/courier-react-17` for React 17. The two are identical. The examples below work with either, and your app should install only one.

Earlier Courier React SDKs required several packages, such as `@trycourier/react-provider` and `@trycourier/react-inbox`. Remove them as part of this migration.

```bash React 18+ theme={null}
npm install --save @trycourier/courier-react
```

```bash React 17 theme={null}
npm install --save @trycourier/courier-react-17
```

In your app's `package.json`, remove existing `@trycourier` React dependencies:

```json React 18+ lines theme={null}
{
  "dependencies": {
    "@trycourier/react-provider": "^7.4.0", // [!code --]
    "@trycourier/react-inbox": "^7.4.0", // [!code --]
    "@trycourier/react-toast": "^7.4.0", // [!code --]
    "@trycourier/courier-react": "^8.2.0", // [!code ++]
    "react": "^19.1.1",
    "react-dom": "^19.1.1"
  }
}
```

```json React 17 lines theme={null}
{
  "dependencies": {
    "@trycourier/react-provider": "^7.4.0", // [!code --]
    "@trycourier/react-inbox": "^7.4.0", // [!code --]
    "@trycourier/react-toast": "^7.4.0", // [!code --]
    "@trycourier/courier-react-17": "^8.2.0", // [!code ++]
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  }
}
```

### 2. Generate JWTs

> [!TIP]
>
> Already generating JWTs (JSON Web Tokens) for Courier SDKs? Skip this step.

Earlier Courier React SDKs accepted *client keys*: a stable, Base64 encoded identifier, with or without an HMAC signature. v8+ replaces them with JWTs, short-lived signed tokens your backend mints with your Courier API key. Client keys no longer authenticate anything, so every app needs a backend endpoint that issues a token.

[Authenticate users
DOC](/docs/in-app/authenticate-users) covers minting the token, the scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See [EU setup
DOC](/docs/in-app/authenticate-users?lang=React#connect-to-the-eu-datacenter).

Inbox and Toast components need the three required scopes in [Scopes
DOC](/docs/in-app/authenticate-users#scopes). Migrating Preferences components too? Add `read:preferences` and `write:preferences`.

### 3. Authenticate the Courier SDK

Replace every `<CourierProvider>` with one call to `courier.shared.signIn()`. That method lives on the singleton `useCourier()` returns. [Sign in on the client
DOC](/docs/in-app/authenticate-users#2-sign-in-on-the-client) covers `signOut` and token refresh.

> [!TIP]
>
> The Courier SDK shares authentication between components, so one call to `courier.shared.signIn` is enough.
>
> Using only Courier toasts? Skip to [Upgrade Toast components](#5-upgrade-toast-components) for the `<CourierToast>` version of this example.

```tsx App.tsx lines theme={null}
import { CourierProvider } from "@trycourier/react-provider"; // [!code --]
import { Inbox } from "@trycourier/react-inbox"; // [!code --]
import { useEffect, useState } from "react"; // [!code ++]
import { CourierInbox, useCourier } from "@trycourier/courier-react"; // [!code ++]

function App() {
  const [courierJwt, setCourierJwt] = useState<string>();
  const courier = useCourier(); // [!code ++]

  const generateCourierJwt = async () => {
    // Call your backend to generate a JWT
    setCourierJwt(result);
  };

  // When the userId in the app changes,
  // generate a new JWT to sign in to the Courier SDK
  useEffect(() => {
    generateCourierJwt();
  }, [userId]);

  // When courierJwt has been updated, call signIn
  useEffect(() => { // [!code ++]
    // Authenticate the user with the inbox // [!code ++]
    courier.shared.signIn({ userId, jwt: courierJwt }); // [!code ++]
  }, [courierJwt]); // [!code ++]

  return (
    <CourierProvider // [!code --]
      authentication={courierJwt} // [!code --]
      clientKey={clientKey}> // [!code --]
      <Inbox /> // [!code --]
    </CourierProvider> // [!code --]
    <CourierInbox /> // [!code ++]
  );
}
```

### 4. Upgrade Inbox components

#### 4a. Theming

v8+ drops styled-components and themes natively.

The theme definition changed. Compare the [v7 theme](https://github.com/trycourier/courier-react/tree/bee3903dead18caeaaf791792e806efd3723330e/packages/react-inbox#theme) with the [v8+ theme
DOC](/docs/in-app/customize-the-inbox#courierinboxtheme-reference) types.

```tsx App.tsx lines theme={null}
import { Inbox } from "@trycourier/react-inbox"; // [!code --]
import { CourierProvider } from "@trycourier/react-provider"; // [!code --]
import { CourierInbox, CourierInboxTheme } from "@trycourier/courier-react"; // [!code ++]

function App() {
  // `CourierInboxTheme` is exposed in `@trycourier/courier-react` and may provide
  // helpful hints in your code editor.
  const theme: CourierInboxTheme = {
    // In v8+, inbox theme values are nested under `inbox`
    inbox: { // [!code ++]
      header: {
        background: "#0f0f0f", // [!code --]
        backgroundColor: "#0f0f0f" // [!code ++]
      },

      messageList: { // [!code --]
        container: { // [!code --]
          background: "red", // [!code --]
        }, // [!code --]
      }, // [!code --]
      list: { // [!code ++]
        backgroundColor: "red", // [!code ++]
      }, // [!code ++]

      item: { // [!code ++]
        backgroundColor: "purple", // [!code ++]
        hoverBackgroundColor: "steelblue", // [!code ++]
      }, // [!code ++]
    }, // [!code ++]

    // In v8+, message theme values are nested under `inbox.item`
    message: { // [!code --]
      container: { // [!code --]
        background: "purple", // [!code --]
      }, // [!code --]
      "&:hover": { // [!code --]
        background: "steelblue", // [!code --]
      }, // [!code --]
    }, // [!code --]

    // The Courier watermark is removed in v8+,
    // so footer theming is no longer applicable
    footer: { // [!code --]
      background: "pink", // [!code --]
    }, // [!code --]
  };

  return (
    <CourierProvider> // [!code --]
      <Inbox theme={theme} /> // [!code --]
    </CourierProvider> // [!code --]
    <CourierInbox lightTheme={theme} darkTheme={theme} mode="light" /> // [!code ++]
  );
}
```

##### Dark mode

React Inbox v8+ switches between light and dark mode automatically, following system preferences.

```tsx App.tsx lines theme={null}
import { Inbox } from "@trycourier/react-inbox"; // [!code --]
import { CourierProvider } from "@trycourier/react-provider"; // [!code --]
import { CourierInbox, CourierInboxTheme } from "@trycourier/courier-react"; // [!code ++]
import { appTheme } from "./theme";

function App() {
  // In v8+, the entire dark mode theme can be customized
  const darkThemeVariables = { // [!code --]
    background: "black", // [!code --]
  }; // [!code --]

  const lightTheme: CourierInboxTheme = { // [!code ++]
    ...appTheme, // [!code ++]
    // Light mode overrides... // [!code ++]
  }; // [!code ++]

  const darkTheme: CourierInboxTheme = { // [!code ++]
    ...appTheme, // [!code ++]
    // Dark mode overrides... // [!code ++]
  }; // [!code ++]

  return (
    <CourierProvider theme={{ colorMode: "dark", variables: darkThemeVariables }}> // [!code --]
      <Inbox theme={darkTheme} /> // [!code --]
    </CourierProvider> // [!code --]

    // In v8+, themes can be set for both light and dark mode
    // Use the `mode` prop to force the "light", "dark", or "system" color mode
    <CourierInbox lightTheme={lightTheme} darkTheme={darkTheme} mode="system" /> // [!code ++]
  );
}
```

#### 4b. Custom components

You can override most components in the default UI.

Some prop names and method signatures for passing components changed in v8+. See [using custom components
DOC](/docs/in-app/build-a-custom-inbox) and [customizing user interactions
DOC](/docs/in-app/customize-the-inbox#handle-interaction).

```tsx App.tsx lines theme={null}
import { Inbox } from "@trycourier/react-inbox"; // [!code --]
import { CourierProvider } from "@trycourier/react-provider"; // [!code --]
import { // [!code ++]
  CourierInbox, // [!code ++]
  type CourierInboxHeaderFactoryProps, // [!code ++]
  type CourierInboxListItemFactoryProps // [!code ++]
} from '@trycourier/courier-react'; // [!code ++]

export default function App() {
  const CustomHeader = (props: CourierInboxHeaderFactoryProps) => { // [!code ++]
    const selectedFeed = props.feeds.find(feed => feed.isSelected); // [!code ++]
    const selectedTab = selectedFeed?.tabs.find(tab => tab.isSelected); // [!code ++]
    // [!code ++]
    return ( // [!code ++]
      <div style={{ // [!code ++]
        background: "red", // [!code ++]
        fontSize: "24px", // [!code ++]
        padding: "24px", // [!code ++]
        width: "100%" // [!code ++]
      }}> // [!code ++]
        {selectedFeed?.title ?? 'No feed selected'} | {selectedTab?.title ?? 'No tab selected'} // [!code ++]
      </div> // [!code ++]
    ); // [!code ++]
  }; // [!code ++]

  const CustomListItem = (
    // In v8+, the full message and its index within the inbox are available
    message => ( // [!code --]
    { message, index }: CourierInboxListItemFactoryProps) => ( // [!code ++]
      <pre style={{
        padding: '24px',
        borderBottom: '1px solid #e0e0e0',
        margin: '0'
      }}>
        {JSON.stringify({ message }, null, 2)}
      </pre>
    );

  return (
    <CourierProvider> // [!code --]
      <Inbox renderMessage={(props) => { // [!code --]
        return <CustomListItem {...props} /> // [!code --]
      }} /> // [!code --]
    </CourierProvider> // [!code --]
    <CourierInbox // [!code ++]
      renderHeader={(props: CourierInboxHeaderFactoryProps) => { // [!code ++]
        if (!props) return null; // [!code ++]
        return <CustomHeader {...props} />; // [!code ++]
      }} // [!code ++]
      renderListItem={(props: CourierInboxListItemFactoryProps) => { // [!code ++]
        return <CustomListItem {...props} /> // [!code ++]
      }} // [!code ++]
    /> // [!code ++]
  );
}
```

###### Custom component prop changes

Inbox components:

| v7 prop | v8+ prop |
| :- | :- |
| `renderMessage` | `renderListItem` |
| `renderNoMessages` | `renderEmptyState` |
| `renderHeader` | `renderHeader` |
| New in v8+ | `renderLoadingState` |
| New in v8+ | `renderErrorState` |
| New in v8+ | `renderPaginationItem` |
| `renderPin` | Pins aren't yet supported in v8+ |
| `renderFooter` | The Courier watermark footer is removed in v8+. |

> [!NOTE]
>
> In v8+, `renderHeader` receives `CourierInboxHeaderFactoryProps`, which holds a `feeds` array, not `feedType`. Each feed has `feedId`, `title`, `iconSVG`, `tabs`, and `isSelected`.

#### 4c. React hooks

> [!TIP]
>
> Pins aren't yet supported in v8+, and neither is changing a message's tags from the client. Reading and filtering by tag both work, through [feeds and tabs](#4d-feeds-and-tabs).

A custom UI fetches messages and holds inbox state itself, with hooks.

Courier's React hooks now ship inside `@trycourier/courier-react`. Remove any dependency on `@trycourier/react-hooks`.

```json package.json lines theme={null}
{
  "dependencies": {
    "@trycourier/react-hooks": "^7.4.0", // [!code --]
    "@trycourier/courier-react": "^8.0.28" // [!code ++]
  }
}
```

Change `useInbox()` to `useCourier()` and update the changed method signatures. The [full set of updated hooks](#method-signature-changes) follows.

```tsx App.tsx lines theme={null}
import { useInbox } from "@trycourier/react-hooks"; // [!code --]
import { useCourier, type CourierInboxFeed } from "@trycourier/courier-react"; // [!code ++]

const MyCustomInbox = () => {
  const inbox = useInbox(); // [!code --]
  const { inbox } = useCourier(); // [!code ++]

  useEffect(() => {
    // Register feeds (new in v8+) // [!code ++]
    const feeds: CourierInboxFeed[] = [ // [!code ++]
      { // [!code ++]
        feedId: 'inbox', // [!code ++]
        title: 'Inbox', // [!code ++]
        tabs: [{ datasetId: 'all_messages', title: 'All', filter: {} }] // [!code ++]
      } // [!code ++]
    ]; // [!code ++]
    inbox.registerFeeds(feeds); // [!code ++]

    // Set up socket listener for real-time updates (new in v8+) // [!code ++]
    await inbox.listenForUpdates(); // [!code ++]

    inbox.fetchMessages(); // [!code --]
    await inbox.load(); // [!code ++]
  }, []);

  const handleRead = (message) => (event) => {
    event.preventDefault();

    inbox.markMessageRead(message.messageId); // [!code --]
    inbox.readMessage({ message }); // [!code ++]
  };

  const handleUnread = (message) => (event) => {
    event.preventDefault();

    inbox.markMessageUnread(message.messageId); // [!code --]
    inbox.unreadMessage(message) // [!code ++]
  };

  const handleArchive = (message) => (event) => {
    event.preventDefault();

    inbox.markMessageArchived(message.messageId); // [!code --]
    inbox.archiveMessage(message); // [!code ++]
  };

  // Access messages by datasetId (new in v8+) // [!code ++]
  const messages = inbox.feeds['all_messages']?.messages || []; // [!code ++]

  return (
    <Container>
      {inbox.messages.map((message) => { // [!code --]
      {messages.map((message) => { // [!code ++]
        return (
          <Message message={message}>
            {message.read ? (
              <>
                <button onClick={handleUnread(message)}>Mark Unread</button>
                <button onClick={handleArchive(message)}>Archive</button>
              </>
            ) : (
              <button onClick={handleRead(message)}>Mark Read</button>
            )}
          </Message>
        );
      })}
    </Container>
  )
}
```

#### Method signature changes

| v7 signature | v8+ signature |
| :- | :- |
| `fetchMessages()` | `load()` |
| New in v8+ | `setPaginationLimit(limit: number)` |
| `fetchNextPageOfMessages({ feedType: 'inbox' \| 'archive' })` | `fetchNextPageOfMessages({ datasetId: string })`  Note: `feedType` is deprecated, use `datasetId` |
| `getUnreadMessageCount()` | Replaced with `load()` (async, refresh the inbox)  and `inbox.totalUnreadCount` (sync, reads stored state) |
| `markMessageRead(messageId: string)` | `readMessage(message: InboxMessage)` |
| `markMessageUnread(messageId: string)` | `unreadMessage(message: InboxMessage)` |
| `markMessageArchived(messageId: string)` | `archiveMessage(message: InboxMessage)` |
| New in v8+ | `unarchiveMessage(message: InboxMessage)` |
| `trackClick(messageId: string, trackingId: string)` | `clickMessage(message: InboxMessage)` |
| `markMessageOpened(messageId: string)` | `openMessage(message: InboxMessage)` |
| `markAllAsRead()` | `readAllMessages()` |
| New in v8+ | `registerFeeds(feeds: CourierInboxFeed[])` |
| New in v8+ | `listenForUpdates()` |
| `inbox.messages` | `inbox.feeds[datasetId].messages`  Access messages by datasetId instead of a single array |
| `addTag(messageId: string, tag: string)` | No client-side equivalent. Set a message's tags on the send, then filter on them with `registerFeeds()` |
| `removeTag(messageId: string, tag: string)` | No client-side equivalent. A tag is fixed once the message is sent |
| `unpinMessage(messageId: string)` | Not yet supported in v8+ |

#### 4d. Feeds and tabs

v8+ adds feeds and tabs for organizing messages. A **feed** groups related **tabs**. Each tab is a filtered view of messages within its feed.

* **Feeds** group tabs into sections, such as Inbox, Archive, and Notifications.
* **Tabs** filter the messages in a feed, such as All, Unread, and Important.
* **Datasets** back each tab, identified by a unique `datasetId`.

A tab's `filter` takes `tags`, `status`, `archived`, and `from`. Set fields are AND'd together, while several `tags` match as OR. This is where v7's message tags land: send a message with its tags, then give each tag a tab. For every field, see the [tab filter reference
DOC](/docs/in-app/tabs-and-feeds#filter-a-tab).

Pass a `feeds` prop to `<CourierInbox>` to configure feeds and tabs:

```tsx App.tsx lines theme={null}
import { CourierInbox, type CourierInboxFeed } from "@trycourier/courier-react"; // [!code ++]

function App() {
  const feeds: CourierInboxFeed[] = [ // [!code ++]
    { // [!code ++]
      feedId: 'notifications', // [!code ++]
      title: 'Notifications', // [!code ++]
      tabs: [ // [!code ++]
        { // [!code ++]
          datasetId: 'all-notifications', // [!code ++]
          title: 'All', // [!code ++]
          filter: {} // [!code ++]
        }, // [!code ++]
        { // [!code ++]
          datasetId: 'unread-notifications', // [!code ++]
          title: 'Unread', // [!code ++]
          filter: { status: 'unread' } // [!code ++]
        }, // [!code ++]
        { // [!code ++]
          datasetId: 'important', // [!code ++]
          title: 'Important', // [!code ++]
          filter: { tags: ['important'] } // [!code ++]
        } // [!code ++]
      ] // [!code ++]
    } // [!code ++]
  ]; // [!code ++]

  return (
    <CourierInbox feeds={feeds} /> // [!code ++]
  );
}
```

With hooks, register feeds with `inbox.registerFeeds()` and access messages by `datasetId`:

```tsx App.tsx lines theme={null}
import { useCourier, type CourierInboxFeed } from "@trycourier/courier-react"; // [!code ++]

const MyCustomInbox = () => {
  const { inbox } = useCourier();

  useEffect(() => {
    const feeds: CourierInboxFeed[] = [ // [!code ++]
      { // [!code ++]
        feedId: 'inbox', // [!code ++]
        title: 'Inbox', // [!code ++]
        tabs: [{ datasetId: 'all_messages', title: 'All', filter: {} }] // [!code ++]
      } // [!code ++]
    ]; // [!code ++]

    // Register feeds (new in v8+) // [!code ++]
    inbox.registerFeeds(feeds); // [!code ++]

    // Set up socket listener for real-time updates (new in v8+) // [!code ++]
    await inbox.listenForUpdates(); // [!code ++]

    // Load the inbox
    await inbox.load();
  }, []);

  // Access messages by datasetId (new in v8+) // [!code ++]
  const messages = inbox.feeds['all_messages']?.messages || []; // [!code ++]

  return (
    <Container>
      {messages.map((message) => { // [!code ++]
        return (
          <Message message={message}>
            {/* ... */}
          </Message>
        );
      })}
    </Container>
  )
}
```

In v7, messages were accessed through `inbox.messages`. In v8+:

* Messages are organized by `datasetId` in `inbox.feeds[datasetId].messages`
* Use `inbox.registerFeeds()` to configure feeds and tabs
* Use `inbox.listenForUpdates()` to enable real-time updates
* Use `datasetId` (not `feedType`) when calling `fetchNextPageOfMessages()`

The [feeds and tabs reference
DOC](/docs/in-app/tabs-and-feeds) has the rest.

### 5. Upgrade Toast components

![](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/courier-toast-react-banner.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=30bb9683d4a0608b012f362d7e1bc0ce)

v8+ includes a redesigned Toast component with more customization, native theming, and dark mode. Migrating from v7 Toast means updating the component usage, its props, and the theme structure.

Replace every `<CourierProvider>` with one call to `courier.shared.signIn()`. That method lives on the singleton `useCourier()` returns.

> [!TIP]
>
> Already authenticated for Courier Inbox? Replace each `<CourierProvider>...</CourierProvider>` block with `<CourierToast>`.
>
> The Courier SDK shares authentication between components, so one call to `courier.shared.signIn` is enough.

```tsx App.tsx lines theme={null}
import { CourierProvider } from "@trycourier/react-provider"; // [!code --]
import { Toast } from "@trycourier/react-toast"; // [!code --]
import { useEffect, useState } from 'react'; // [!code ++]
import { CourierToast, useCourier } from "@trycourier/courier-react"; // [!code ++]

function App() {
  const [courierJwt, setCourierJwt] = useState<string>();
  const courier = useCourier(); // [!code ++]

  const generateCourierJwt = async () => {
    // Call your backend to generate a JWT
    setCourierJwt(result);
  };

  // When the userId in the app changes,
  // generate a new JWT to sign in to the Courier SDK
  useEffect(() => {
    generateCourierJwt();
  }, [userId]);

  // When courierJwt has been updated, call signIn
  useEffect(() => { // [!code ++]
    // Authenticate the user // [!code ++]
    courier.shared.signIn({ userId, jwt: courierJwt }); // [!code ++]
  }, [courierJwt]); // [!code ++]

  return (
    <CourierProvider // [!code --]
      authentication={courierJwt} // [!code --]
      clientKey={clientKey}> // [!code --]
      <Toast /> // [!code --]
    </CourierProvider> // [!code --]
    <CourierToast /> // [!code ++]
  );
}
```

#### 5a. Toast props

Some `<CourierToast>` props changed or moved in v8+, alongside new props for theming, custom components, and user interaction.

| v7 | v8+ | Notes |
| :- | :- | :- |
| `autoClose` | `autoDismiss` and `autoDismissTimeoutMs` | In v8+, split into two separate props. `autoDismiss` is a boolean |
| `defaultIcon` | Removed in v8+ | In v8+, configured via theme object. See [theming](#5b-theming) below |
| `hideProgressBar` | `autoDismiss` | In v8+, progress bar only displays when `autoDismiss` is enabled |
| New in v8+ | `dismissButton` | Display option for the dismiss button |
| `onClick` | `onToastItemClick` | Event signature has changed in v8+ |
| New in v8+ | `onToastItemActionClick` | Handle an action button click |
| `position` | `style` | Use React's CSS-like `style` prop on `<CourierToast>` |
| `theme` | `lightTheme` and `darkTheme` | v8+ introduces separate themes for light and dark modes |
| `transition` | Removed in v8+ | Configure custom transitions by implementing `renderToastItem` |
| `role` | Not yet supported in v8+ | |
| New in v8+ | `renderToastItemContent` | Customize the toast item content area. See [custom components](#5c-custom-components) below |
| New in v8+ | `renderToastItem` | Completely customize the toast items and stack. See [custom components](#5c-custom-components) below |

#### 5b. Theming

v8+ drops the `styled-components` package and themes natively.

The theme definition changed. Compare the [v7 theme](https://github.com/trycourier/courier-react/blob/6b5f8e93780f0caa4f47da36d3ae14a252348565/packages/react-toast/docs/4.theme.md#theme-interface) with the [v8+ theme
DOC](/docs/in-app/customize-toasts#theme) types.

```tsx App.tsx lines theme={null}
import { Toast } from "@trycourier/react-toast"; // [!code --]
import { CourierProvider } from "@trycourier/react-provider"; // [!code --]
import { CourierToast, CourierToastTheme } from "@trycourier/courier-react"; // [!code ++]

function App() {
  // `CourierToastTheme` is exposed in `@trycourier/courier-react`
  // and may provide helpful hints in your code editor.
  const theme: CourierToastTheme = {
    // Styles applied to the top-level container (ex. z-index or position)
    // In v8+ these are applied with the `style` prop on <CourierToast>
    root: { // [!code --]
      top: "10px", // [!code --]
      right: "10px", // [!code --]
    }, // [!code --]

    // Styles for toast items' outer container
    // In v8+ this is configurable under `item`
    toast: {} // [!code --]

    // Styles for message contents
    // In v8+ these are nested as values under `item`
    message: { // [!code --]
      container: { background: "white" }, // [!code --]
      title: { color: "black" } // [!code --]
    }, // [!code --]

    // Styles for the progress bar
    // In v8+ this is nested under `item.autoDismissBarColor`
    progressBar: { // [!code --]
      background: "purple" // [!code --]
    }, // [!code --]

    item: { // [!code ++]
      backgroundColor: "white", // [!code ++]
      title: { // [!code ++]
        color: "black" // [!code ++]
      }, // [!code ++]
      autoDismissBarColor: "purple" // [!code ++]
    }, // [!code ++]
  };

  return (
    <CourierProvider> // [!code --]
      <Toast theme={theme} /> // [!code --]
    </CourierProvider> // [!code --]
    <CourierToast // [!code ++]
      lightTheme={theme} // [!code ++]
      darkTheme={theme}  // [!code ++]
      style={{ top: "10px", right: "10px" }} /> // [!code ++]
  );
}
```

##### Dark mode

React Toast v8+ themes dark mode fully and switches between light and dark automatically, following system preferences.

Every field is in the [v8+ theme
DOC](/docs/in-app/customize-toasts#theme) type.

```tsx App.tsx lines theme={null}
import { Toast } from "@trycourier/react-toast"; // [!code --]
import { CourierProvider } from "@trycourier/react-provider"; // [!code --]
import { CourierToast, CourierToastTheme } from "@trycourier/courier-react"; // [!code ++]
import { appTheme } from "./theme";

function App() {
  const lightTheme: CourierToastTheme = { // [!code ++]
    ...appTheme, // [!code ++]
    // Light mode overrides... // [!code ++]
  }; // [!code ++]

  const darkTheme: CourierToastTheme = { // [!code ++]
    ...appTheme, // [!code ++]
    // Dark mode overrides... // [!code ++]
  }; // [!code ++]

  return (
    <CourierProvider> // [!code --]
      <Toast theme={darkTheme} /> // [!code --]
    </CourierProvider> // [!code --]

    // In v8+, themes can be set for both light and dark mode
    // Use the `mode` prop to force the "light", "dark", or "system" color mode
    <CourierToast lightTheme={lightTheme} darkTheme={darkTheme} mode="system" /> // [!code ++]
  );
}
```

#### 5c. Custom components

For customization beyond theming, v8+ adds two render props:

* `renderToastItemContent`: Customize the content area, keeping the default styles, animations, and dismiss behavior.
* `renderToastItem`: Replace the appearance and behavior of the toast items and stack.

See [using custom components
DOC](/docs/in-app/customize-toasts#custom-ui) and [customizing user interactions
DOC](/docs/in-app/add-toasts#handle-clicks).

#### 5d. React hooks

A custom UI holds toast state itself, with hooks.

Courier's React hooks now ship inside `@trycourier/courier-react`. Remove any dependency on `@trycourier/react-hooks`.

```json package.json lines theme={null}
{
  "dependencies": {
    "@trycourier/react-hooks": "^7.4.0", // [!code --]
    "@trycourier/courier-react": "^8.0.28" // [!code ++]
  }
}
```

Change `useToast()` to `useCourier()` and update the changed method signatures. The [full set of updated hooks](#method-signature-changes-1) follows.

```tsx App.tsx lines theme={null}
import { useToast } from "@trycourier/react-hooks"; // [!code --]
import { useCourier } from "@trycourier/courier-react"; // [!code ++]

const MyCustomToast = () => {
  const [toast] = useToast(); // [!code --]
  const { toast } = useCourier(); // [!code ++]

  useEffect(() => {
    toast({ // [!code --]
    toast.addMessage({ // [!code ++]
      title: "Hello, world!", // [!code ++]
      preview: "This is a toast." // [!code ++]
    }); // [!code ++]
  }, [])

  return (
    <CourierToast
      onToastItemClick={({ message }) => { // [!code ++]
        // New in v8+ // [!code ++]
        toast.removeMessage(message); // [!code ++]
      }}
    />
  );
}
```

#### Method signature changes

| v7 signature | v8+ signature |
| :- | :- |
| `toast(message)` | `toast.addMessage(message: InboxMessage)` |
| New in v8+ | `toast.removeMessage(message: InboxMessage)` |

> [!NOTE]
>
> `config` and `clientKey` info are removed from hooks in v8+.

### 6. Upgrade Preferences components

v8+ replaces the v7 `<PreferencesV4>` component, from `@trycourier/react-preferences`, with `<CourierPreferences>`. It shares the redesigned UI, native theming, and dark mode of the other v8+ components.

As with Inbox and Toast, replace `<CourierProvider>` with one call to `courier.shared.signIn()`. Already authenticated for another v8+ component? No second sign-in is needed. The SDK shares authentication across components.

> [!TIP]
>
> Preferences requires a JWT with the `read:preferences` and `write:preferences` scopes.

```tsx App.tsx lines theme={null}
import { CourierProvider } from "@trycourier/react-provider"; // [!code --]
import { PreferencesV4 } from "@trycourier/react-preferences"; // [!code --]
import { useEffect, useState } from 'react'; // [!code ++]
import { CourierPreferences, useCourier } from "@trycourier/courier-react"; // [!code ++]

function App() {
  const [courierJwt, setCourierJwt] = useState<string>();
  const courier = useCourier(); // [!code ++]

  // When courierJwt has been updated, call signIn
  useEffect(() => { // [!code ++]
    courier.shared.signIn({ userId, jwt: courierJwt }); // [!code ++]
  }, [courierJwt]); // [!code ++]

  return (
    <CourierProvider // [!code --]
      authentication={courierJwt} // [!code --]
      clientKey={clientKey}> // [!code --]
      <PreferencesV4 /> // [!code --]
    </CourierProvider> // [!code --]
    <CourierPreferences /> // [!code ++]
  );
}
```

#### 6a. Preferences props

The v7 `<PreferencesV4>` component accepted only two props, `tenantId` and `draft`. It had no theming props. Its colors came from the brand configured on the fetched preference page. Three things change in v8+:

* Tenant scoping moves to `signIn`. There is no per-component prop.
* Draft-preview isn't yet available.
* `<CourierPreferences>` adds native client-side theming and other options.

| v7 | v8+ | Notes |
| :- | :- | :- |
| `tenantId` | Set via `signIn` | Tenant scoping is set once at authentication with `courier.shared.signIn({ userId, jwt, tenantId })` rather than per component. It applies to both `<CourierPreferences>` and the headless `useCourier().preferences` hooks |
| `draft` | Not yet available | Draft-preview isn't yet supported by `<CourierPreferences>` in v8+. If you depend on it, remain on v7 for now |
| New in v8+ | `lightTheme` / `darkTheme` | Native theming for light and dark modes (see [Theming](#6b-theming)) |
| New in v8+ | `mode` | Force the `"light"`, `"dark"`, or `"system"` color mode |
| New in v8+ | `brandId` | Render preferences using a specific brand's styling |
| New in v8+ | `channelLabels` | Rename how delivery channels appear in the UI |
| New in v8+ | `onError` | Callback invoked when the component encounters an error |

> [!TIP]
>
> Set `tenantId` once on `signIn`. It scopes both `<CourierPreferences>` and the headless `useCourier().preferences` hooks automatically.

#### 6b. Theming

Like Inbox and Toast, v8+ Preferences drops `styled-components` and themes natively through the `lightTheme` and `darkTheme` props. The fields are in [`CourierPreferencesTheme`
DOC](/docs/in-app/customize-preferences#theme).

#### 6c. React hooks

A custom Preferences UI using the v7 `usePreferences()` hook from `@trycourier/react-hooks` should move to `useCourier().preferences`.

Courier's React hooks now ship inside `@trycourier/courier-react`. Remove any dependency on `@trycourier/react-hooks`.

```tsx App.tsx lines theme={null}
import { usePreferences } from "@trycourier/react-hooks"; // [!code --]
import { useCourier } from "@trycourier/courier-react"; // [!code ++]

const MyCustomPreferences = () => {
  const preferences = usePreferences(); // [!code --]
  const { preferences } = useCourier(); // [!code ++]

  useEffect(() => {
    preferences.fetchRecipientPreferences(); // [!code --]
    load(); // [!code ++]
  }, []);

  async function load() { // [!code ++]
    const prefs = await preferences.getUserPreferences(); // [!code ++]
    // prefs.items is the list of preference topics // [!code ++]
    setTopics(prefs.items); // [!code ++]
  } // [!code ++]

  return null;
}
```

#### Method signature changes

| v7 signature | v8+ signature |
| :- | :- |
| `preferences.fetchRecipientPreferences(tenantId?)` (result on `preferences.recipientPreferences`) | `preferences.getUserPreferences(props?: { paginationCursor?: string })` returns `Promise<CourierUserPreferences>` |
| `preferences.updateRecipientPreferences(payload)` | `preferences.putUserPreferenceTopic({ topicId, status, hasCustomRouting, customRouting, digestSchedule? })` |
| `preferences.fetchPreferencePage(tenantId?, draft?)` | Scope the tenant via `signIn`. Draft-preview isn't yet available in v8+ |
| New in v8+ | `preferences.getUserPreferenceTopic({ topicId })` |
| New in v8+ | `preferences.getDigestSchedules({ topicId })` |

> [!NOTE]
>
> `config` and `clientKey` info are removed from hooks in v8+. Tenant scoping moves from a per-call `tenantId` argument to `signIn`.

[Preferences methods
DOC](/docs/in-app/customize-preferences#methods-behind-the-component) has the full signatures and a working example.

## SDK documentation

* [Courier React
  DOC](/docs/sdk-libraries/courier-react-web)
* [Courier JS, for Web Components
  DOC](/docs/sdk-libraries/courier-js-web)
* [Add an inbox
  DOC](/docs/in-app/add-an-inbox?lang=Web%20Components)

## Markdown rendering

Courier React 1.13.0 through 7.x.x render Markdown-formatted messages automatically, such as those produced when **Markdown Rendering** is enabled for the Courier Inbox provider.

v8+ has no built-in Markdown rendering. Add it with custom Inbox components, as below with [`markdown-to-jsx`](https://www.npmjs.com/package/markdown-to-jsx).

```json package.json lines theme={null}
{
  "dependencies": {
    "@trycourier/courier-react": "^8.0.28",
    "markdown-to-jsx": "^7.7.13", // [!code ++]
    "react": "^19.1.1",
    "react-dom": "^19.1.1"
  }
}
```

```tsx App.tsx lines theme={null}
import {
  CourierInbox,
  type CourierInboxListItemFactoryProps
} from '@trycourier/courier-react';
import Markdown from "markdown-to-jsx"; // [!code ++]

export default function App() {
  return (
    <CourierInbox
      renderListItem={(props: CourierInboxListItemFactoryProps) => {
        return (
          <Markdown>{ props.message.preview || "Empty message" }</Markdown> // [!code ++]
        );
      }}
    />
  );
}
```

## Troubleshooting

**Migrate Inbox and Toast together.** The v8+ SDK depends on a newer major version of `@trycourier/courier-js` than v7 does. Two versions on one page isn't supported.

**No requests to Courier after upgrading?** Two versions of a `@trycourier/` package are probably installed at once. Run `npm dedupe`, `yarn dedupe`, or your package manager's equivalent.

Still stuck? Open an issue on [GitHub](https://github.com/trycourier/courier-web/issues) or [contact Courier Support](https://support.courier.com).


# Courier React SDK
Source: https://www.courier.com/docs/sdk-libraries/courier-react-web

Inbox, toast, and preferences components for React, plus the useCourier hook.

The React SDK wraps Courier's in-app components as React components, plus one hook that exposes the client behind them.

* `<CourierInbox />` and `<CourierInboxPopupMenu />`, an inbox as a panel or a popup
* `<CourierToast />`, toasts for messages that arrive while the app is open
* `<CourierPreferences />`, a preference center for topic subscriptions
* `useCourier()`, the client, for custom UIs and for driving the components from outside

**The components behave identically on every web framework, so this page doesn't repeat their reference.** Install and sign in here, then follow [In-App
DOC](/docs/in-app/overview) for what each component does. Every code sample there has a React tab.

> [!TIP]
>
> See these components in the [interactive Inbox demo](https://www.courier.com/inbox-demo). No setup required.

## Installation

Available on
[ GitHub](https://github.com/trycourier/courier-web/tree/main/%40trycourier/courier-react)
and [ npm](https://www.npmjs.com/package/@trycourier/courier-react).

Courier publishes two React packages: `@trycourier/courier-react` for React 18+ and `@trycourier/courier-react-17` for React 17.

```bash React 18+ theme={null}
npm install @trycourier/courier-react
```

```bash React 17 theme={null}
npm install @trycourier/courier-react-17
```

> [!TIP]
>
> This is the latest version of the Courier React SDK, recommended for new and existing apps.
>
> Coming from an earlier version? The
> [v8 migration guide
> DOC](/docs/sdk-libraries/courier-react-v8-migration-guide) covers what changed,
> how to upgrade, and docs for past versions.

> [!NOTE]
>
> Not using React? Use the
> [Web Components SDK
> DOC](/docs/sdk-libraries/courier-web-components) instead. Its elements work in any JavaScript project.

## Authentication

Courier authenticates with a **JWT** that your backend mints with your Courier API key, never in client code. [Authenticate users
DOC](/docs/in-app/authenticate-users?lang=React) is the full guide: the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See [EU setup
DOC](/docs/in-app/authenticate-users?lang=React#connect-to-the-eu-datacenter).

```tsx theme={null}
const { auth } = useCourier();

auth.signIn({ userId, jwt });  // also accepts tenantId, apiUrls, showLogs
auth.signOut();
auth.userId;                   // undefined when signed out
```

## Quick start

Add the inbox component to your app.

```jsx React 18+ lines theme={null}
import { useEffect } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    // Generate a JWT for your user on your backend server
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

    // Authenticate the user
    courier.shared.signIn({
      userId: "user_123",
      jwt: jwt,
    });
  }, []);

  return <CourierInbox />;
}
```

```jsx React 17 lines theme={null}
import { useEffect } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react-17";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    // Generate a JWT for your user on your backend server
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

    // Authenticate the user
    courier.shared.signIn({
      userId: "user_123",
      jwt: jwt,
    });
  }, []);

  return <CourierInbox />;
}
```

Scope requests to one [tenant
DOC](/docs/tenants/overview) by passing its ID to `signIn`:

```js theme={null}
courier.shared.signIn({ userId: "user_123", jwt, tenantId: "my-tenant-id" });
```

## Component reference

Each component's props, theme, callbacks, and custom-render surface live with the feature. These links open on the React tab.

| To do this | Go here |
| - | - |
| Embed the inbox, or render it as a popup | [Add an inbox&#xA;DOC](/docs/in-app/add-an-inbox?lang=React) |
| Theme it, handle clicks, replace parts of it | [Customize the inbox&#xA;DOC](/docs/in-app/customize-the-inbox?lang=React) |
| Split it into filtered tabs and feeds | [Tabs and feeds&#xA;DOC](/docs/in-app/tabs-and-feeds?lang=React) |
| Add toasts, and set auto-dismiss | [Add toasts&#xA;DOC](/docs/in-app/add-toasts?lang=React) |
| Theme a toast or replace it | [Customize toasts&#xA;DOC](/docs/in-app/customize-toasts?lang=React) |
| Add a preference center | [Add a preference center&#xA;DOC](/docs/in-app/add-a-preference-center?lang=React) |
| Theme preferences, or build your own | [Customize preferences&#xA;DOC](/docs/in-app/customize-preferences?lang=React) |
| Send a message that reaches the inbox | [Send to the inbox&#xA;DOC](/docs/in-app/send-to-the-inbox) |

The `CourierInboxTheme`, `CourierToastTheme`, and `CourierPreferencesTheme` objects are the same on React, Vue, Angular, and the Web Components, so each is documented once: [inbox theme
DOC](/docs/in-app/customize-the-inbox#courierinboxtheme-reference), [toast theme
DOC](/docs/in-app/customize-toasts#theme), [preferences theme
DOC](/docs/in-app/customize-preferences#theme).

## useCourier hook

`useCourier()` returns the Courier client and the three component surfaces. Use it to build your own UI, or to drive a prebuilt component from outside it.

```tsx theme={null}
const { shared, auth, inbox, toast, preferences } = useCourier();
```

| Key | What it holds | Reference |
| - | - | - |
| `shared` | The `Courier` client itself, for anything the keys below don't cover. | [Courier JS&#xA;DOC](/docs/sdk-libraries/courier-js-web#courierclient-options) |
| `auth` | `signIn`, `signOut`, and `userId`. | [Authenticate users&#xA;DOC](/docs/in-app/authenticate-users?lang=React) |
| `inbox` | `feeds`, `totalUnreadCount`, `error`, and every message action. | [Data and actions&#xA;DOC](/docs/in-app/build-a-custom-inbox?lang=React#data-and-actions) |
| `toast` | `addMessage` and `removeMessage`, to push a toast yourself. | [Add toasts&#xA;DOC](/docs/in-app/add-toasts?lang=React) |
| `preferences` | Read and write a user's topics, routing, and digest schedule. | [Preferences methods&#xA;DOC](/docs/in-app/customize-preferences#methods-behind-the-component) |

Components and the hook aren't a choice between two integrations. The components call the same client the hook returns, so a page can render `<CourierInbox />` and read `inbox.totalUnreadCount` for a badge elsewhere in the same tree.

**Call `inbox.listenForUpdates()` after you authenticate.** It opens the realtime connection, which nothing else in a custom UI calls for you. Without it, the inbox loads once and doesn't update again.

```tsx theme={null}
await auth.signIn({ userId, jwt });
inbox.registerFeeds(feeds);
await inbox.listenForUpdates();
await inbox.load();
```

## Advanced

### Next.js and SSR

Courier Inbox and Toast support Next.js but render client-side only. In Next.js 13+, add [`'use client'`](https://nextjs.org/docs/app/api-reference/directives/use-client) to the top of any file using Courier components.

```jsx theme={null}
"use client"

import { CourierInbox } from "@trycourier/courier-react";

export default function Page() {
  // Authentication code...
  return <CourierInbox />;
}
```

### Troubleshooting

> **Inbox not updating in real-time**
>
> Call `inbox.listenForUpdates()` after authentication. It opens the WebSocket connection required for real-time updates.
>
> ```jsx theme={null}
> await auth.signIn({ userId, jwt });
> inbox.registerFeeds(defaultFeeds());
> await inbox.listenForUpdates(); // Required for real-time
> await inbox.load();
> ```

> **Messages not loading**
>
> **Possible causes:**
>
> 1. Not authenticated: call `signIn()`
> 2. Feeds not registered: call `registerFeeds()` before `load()`
> 3. Network errors: check `inbox.error` for details
> 4. JWT expired: generate a new token

> **Authentication errors**
>
> * **Invalid JWT**: generate the JWT correctly on your backend
> * **Expired JWT**: JWTs expire. Generate a new one
> * **Missing scopes**: include `inbox:read:messages` and `inbox:write:events` in the JWT
> * **Wrong user ID**: the `userId` must match the user the JWT was issued for

> **Two tabs show identical messages**
>
> Two tabs sharing a `datasetId` collapse into one dataset. Every `datasetId` has to be unique across all feeds, not only within one. See [Tabs and feeds
> DOC](/docs/in-app/tabs-and-feeds).

> **TypeScript errors**
>
> Import types directly from the package:
>
> ```tsx theme={null}
> import { useCourier, type InboxMessage, type CourierInboxFeed } from '@trycourier/courier-react';
> ```

> **React 17 vs React 18 package mismatch**
>
> Use the correct package:
>
> * React 18+: `@trycourier/courier-react`
> * React 17: `@trycourier/courier-react-17`

### Best practices

* **JWT security**: always generate JWTs server-side. Cache on the client, refresh before expiration (standard: `'1d'`), and include only the scopes you need.
* **Performance**: `canUseCache: true` (default) serves cached data. Use `datasetIds` to load only the datasets you need, and set a suitable `setPaginationLimit()`. The hook's reactive state updates on its own, so avoid unnecessary re-renders.
* **Testing**: mock `useCourier()` in tests to return test data:

```jsx theme={null}
jest.mock('@trycourier/courier-react', () => ({
  useCourier: () => ({
    inbox: {
      feeds: { 'all_messages': { messages: mockMessages } },
      totalUnreadCount: 5
    }
  })
}));
```

## TypeScript types

**type InboxMessage**

```typescript theme={null}
type InboxMessage = {
  messageId: string;
  title?: string;
  body?: string;
  read?: string;     // ISO timestamp
  opened?: string;   // ISO timestamp
  archived?: string; // ISO timestamp
  tags?: string[];
  trackingIds?: { clickTrackingId?: string; openTrackingId?: string; };
  actions?: InboxAction[];
  data?: Record<string, unknown>;
}
```

**type InboxDataSet**

```typescript theme={null}
type InboxDataSet = {
  id: string;
  messages: InboxMessage[];
  unreadCount: number;
  canPaginate: boolean;
  paginationCursor: string | null;
}
```

**type CourierInboxFeed**

```typescript theme={null}
type CourierInboxFeed = {
  feedId: string;
  title: string;
  iconSVG?: string;
  tabs: CourierInboxTab[];
}
```

**type CourierInboxTab**

```typescript theme={null}
type CourierInboxTab = {
  datasetId: string;
  title: string;
  filter: CourierInboxDatasetFilter;
}
```

**type CourierInboxDatasetFilter**

```typescript theme={null}
type CourierInboxDatasetFilter = {
  tags?: string[];
  archived?: boolean;
  status?: 'read' | 'unread';
  from?: string;   // ISO 8601, lower bound on creation time
}
```

Set fields are AND'd together, while several `tags` match as OR. `{ tags: ['important'], status: 'unread' }` shows unread messages tagged `important`. [Filter a tab
DOC](/docs/in-app/tabs-and-feeds#filter-a-tab) has each field.

**type CourierToastItemFactoryProps**

```typescript theme={null}
type CourierToastItemFactoryProps = {
  message: InboxMessage;
  autoDismiss: boolean;
  autoDismissTimeoutMs: number;
  dismiss: () => void;
}
```


# Courier Vue SDK
Source: https://www.courier.com/docs/sdk-libraries/courier-vue-web

Inbox, toast, and preferences components for Vue, plus the useCourier composable.

The Vue SDK wraps Courier's in-app components as Vue components, plus one composable that exposes the client behind them.

* `<CourierInbox />`: inbox for displaying and managing messages
* `<CourierInboxPopupMenu />`: popup menu version of the inbox
* `<CourierToast />`: toast notifications for time-sensitive alerts
* `<CourierPreferences />`: preference center for topic subscriptions and delivery
* `useCourier()`: composable for custom UIs

> [!TIP]
>
> See these components in the [interactive Inbox demo](https://www.courier.com/inbox-demo). No setup required.

## Installation

Available on
[ GitHub](https://github.com/trycourier/courier-web/tree/main/%40trycourier/courier-vue)
and [ npm](https://www.npmjs.com/package/@trycourier/courier-vue).

```bash theme={null}
npm install @trycourier/courier-vue
```

`vue` (>= 3.3) is a peer dependency.

> [!NOTE]
>
> Not using Vue? Use the
> [Web Components SDK
> DOC](/docs/sdk-libraries/courier-web-components) instead. Its elements work in any JavaScript project.

## Authentication

Courier authenticates with a **JWT** that your backend mints with your Courier API key, never in client code. [Authenticate users
DOC](/docs/in-app/authenticate-users?lang=Vue) is the full guide: the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See [EU setup
DOC](/docs/in-app/authenticate-users?lang=Vue#connect-to-the-eu-datacenter).

```ts theme={null}
const courier = useCourier();

courier.auth.signIn({ userId, jwt });  // also accepts tenantId, apiUrls, showLogs
courier.auth.signOut();
courier.auth.userId;                   // undefined when signed out
```

## Quick start

Add the inbox component to your app. Courier components are normal Vue components. Import them and use them in your template.

```vue theme={null}
<script setup lang="ts">
import { onMounted } from "vue";
import { CourierInbox, useCourier } from "@trycourier/courier-vue";

const courier = useCourier();

onMounted(() => {
  // Generate a JWT for your user on your backend server
  const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

  // Authenticate the user
  courier.shared.signIn({
    userId: "user_123",
    jwt: jwt,
  });
});
</script>

<template>
  <CourierInbox />
</template>
```

> [!TIP]
>
> Follow the [inbox guide
> DOC](/docs/in-app/add-an-inbox?lang=Vue) for step-by-step guidance, including backend JWT generation.

## Component reference

Each component's props, theme, callbacks, and custom-render surface live with the feature. These links open on the Vue tab.

| To do this | Go here |
| - | - |
| Embed the inbox, or render it as a popup | [Add an inbox&#xA;DOC](/docs/in-app/add-an-inbox?lang=Vue) |
| Theme it, handle clicks, replace parts of it | [Customize the inbox&#xA;DOC](/docs/in-app/customize-the-inbox?lang=Vue) |
| Split it into filtered tabs and feeds | [Tabs and feeds&#xA;DOC](/docs/in-app/tabs-and-feeds?lang=Vue) |
| Add toasts, and set auto-dismiss | [Add toasts&#xA;DOC](/docs/in-app/add-toasts?lang=Vue) |
| Theme a toast or replace it | [Customize toasts&#xA;DOC](/docs/in-app/customize-toasts?lang=Vue) |
| Add a preference center | [Add a preference center&#xA;DOC](/docs/in-app/add-a-preference-center?lang=Vue) |
| Theme preferences, or build your own | [Customize preferences&#xA;DOC](/docs/in-app/customize-preferences?lang=Vue) |
| Send a message that reaches the inbox | [Send to the inbox&#xA;DOC](/docs/in-app/send-to-the-inbox) |

**Bind a render prop in kebab-case.** Vue lowercases attribute names, so `:render-list-item` reaches the component and `:renderListItem` doesn't. A custom render must also return a Vue node built with `h()`, not a string of markup. A string renders nothing.

The `CourierInboxTheme`, `CourierToastTheme`, and `CourierPreferencesTheme` objects are the same on React, Vue, Angular, and the Web Components, so each is documented once: [inbox theme
DOC](/docs/in-app/customize-the-inbox#courierinboxtheme-reference), [toast theme
DOC](/docs/in-app/customize-toasts#theme), [preferences theme
DOC](/docs/in-app/customize-preferences#theme).

## useCourier composable

The `useCourier()` composable gives you programmatic access to Courier. Use it to build custom UIs. It returns the same shape as the React hook, but `auth`, `inbox`, and `toast` are Vue [`shallowRef`s](https://vuejs.org/api/reactivity-advanced.html#shallowref). Access them with `.value` in `<script setup>`. They auto-unwrap in templates.

### When to use the composable vs components

* **Components** (`<CourierInbox />`, `<CourierToast />`): quick integration with the default UI
* **Composable** (`useCourier()`): custom UIs, programmatic control, state management
* **Both together**: the composable manages state, components render

### Composable return value

```ts theme={null}
const { shared, auth, inbox, toast, preferences } = useCourier();

// In <script setup>, reactive slices need .value:
auth.value.signIn({ userId, jwt });
inbox.value.registerFeeds(defaultFeeds());
await inbox.value.listenForUpdates();
await inbox.value.load();
console.log(inbox.value.totalUnreadCount);

// `shared` and `preferences` are plain (no .value):
const prefs = await preferences.getUserPreferences();
```

**Call `inbox.value.listenForUpdates()` after authentication to open the realtime connection.** Without it, the inbox loads once from the initial fetch and doesn't update again.

**Complete example**: authentication, inbox setup, real-time updates, and displaying messages. Templates auto-unwrap the refs (`inbox.totalUnreadCount`, `inbox.feeds[...]`):

```vue theme={null}
<script setup lang="ts">
import { onMounted } from "vue";
import { useCourier, defaultFeeds } from "@trycourier/courier-vue";

const { auth, inbox } = useCourier();

onMounted(async () => {
  auth.value.signIn({
    userId: "user_123",
    jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  });
  inbox.value.registerFeeds(defaultFeeds());
  await inbox.value.listenForUpdates();
  await inbox.value.load();
});
</script>

<template>
  <div>
    <div>Total Unread: {{ inbox.totalUnreadCount ?? 0 }}</div>
    <ul>
      <li
        v-for="message in inbox.feeds['all_messages']?.messages ?? []"
        :key="message.messageId"
        :style="{ backgroundColor: message.read ? 'transparent' : '#fee2e2', padding: '8px', marginBottom: '4px' }"
      >
        {{ message.title }}
      </li>
    </ul>
  </div>
</template>
```

Every method and reactive value the `inbox` slice exposes is in [Data and actions
DOC](/docs/in-app/build-a-custom-inbox?lang=Vue#data-and-actions). Read them off `inbox.value` in `<script setup>`, and off `inbox` in a template.

## Advanced

### Server-side rendering

Courier Inbox and Toast render client-side only. They mount in `onMounted`, which never runs during SSR. They work with Nuxt and other SSR setups without extra configuration, rendering once on the client.

### Troubleshooting

> **Inbox not updating in real-time**
>
> Call `inbox.value.listenForUpdates()` after authentication. It opens the WebSocket connection required for real-time updates.
>
> ```ts theme={null}
> auth.value.signIn({ userId, jwt });
> inbox.value.registerFeeds(defaultFeeds());
> await inbox.value.listenForUpdates(); // Required for real-time
> await inbox.value.load();
> ```

> **Messages not loading**
>
> **Possible causes:**
>
> 1. Not authenticated: call `signIn()`
> 2. Feeds not registered: call `registerFeeds()` before `load()`
> 3. Network errors: check `inbox.value.error` for details
> 4. JWT expired: generate a new token

> **Authentication errors**
>
> * **Invalid JWT**: generate the JWT correctly on your backend
> * **Expired JWT**: JWTs expire. Generate a new one
> * **Missing scopes**: include `inbox:read:messages` and `inbox:write:events` in the JWT
> * **Wrong user ID**: the `userId` must match the user the JWT was issued for

> **Custom slots not rendering**
>
> Custom render props must return a Vue node built with `h()` (imported from `vue`), not a raw string of markup. Bind the render prop with `:render-list-item="..."` (kebab-case) on the component.

> **TypeScript errors**
>
> Import types directly from the package:
>
> ```ts theme={null}
> import { useCourier, type InboxMessage, type CourierInboxFeed } from "@trycourier/courier-vue";
> ```

### Best practices

* **JWT security**: always generate JWTs server-side. Cache on the client, refresh before expiration (standard: `'1d'`), and include only the scopes you need.
* **Performance**: `canUseCache: true` (default) serves cached data. Set a suitable `setPaginationLimit()`. The composable's `shallowRef`s update on their own, so avoid unnecessary re-renders.
* **Testing**: mock `useCourier()` in tests to return test data:

```ts theme={null}
import { ref } from "vue";

vi.mock("@trycourier/courier-vue", () => ({
  useCourier: () => ({
    inbox: ref({ feeds: { all_messages: { messages: mockMessages } }, totalUnreadCount: 5 }),
  }),
}));
```

## TypeScript types

**type InboxMessage**

```typescript theme={null}
type InboxMessage = {
  messageId: string;
  title?: string;
  body?: string;
  read?: string;     // ISO timestamp
  opened?: string;   // ISO timestamp
  archived?: string; // ISO timestamp
  tags?: string[];
  trackingIds?: { clickTrackingId?: string; openTrackingId?: string; };
  actions?: InboxAction[];
  data?: Record<string, unknown>;
}
```

**type InboxDataSet**

```typescript theme={null}
type InboxDataSet = {
  id: string;
  messages: InboxMessage[];
  unreadCount: number;
  canPaginate: boolean;
  paginationCursor: string | null;
}
```

**type CourierInboxFeed**

```typescript theme={null}
type CourierInboxFeed = {
  feedId: string;
  title: string;
  iconSVG?: string;
  tabs: CourierInboxTab[];
}
```

**type CourierInboxTab**

```typescript theme={null}
type CourierInboxTab = {
  datasetId: string;
  title: string;
  filter: CourierInboxDatasetFilter;
}
```

**type CourierInboxDatasetFilter**

```typescript theme={null}
type CourierInboxDatasetFilter = {
  tags?: string[];
  archived?: boolean;
  status?: 'read' | 'unread';
}
```

All filter properties are AND'd together. `{ tags: ['important'], status: 'unread' }` shows unread messages tagged 'important'.

**type CourierToastItemFactoryProps**

```typescript theme={null}
type CourierToastItemFactoryProps = {
  message: InboxMessage;
  autoDismiss: boolean;
  autoDismissTimeoutMs: number;
  dismiss: () => void;
}
```


# Courier Web Components SDK
Source: https://www.courier.com/docs/sdk-libraries/courier-web-components

Inbox, toast, and preferences as custom elements for any web app, with or without a framework.

The Web Components SDK ships Courier's in-app components as standard custom elements, so they work in plain HTML or alongside any framework.

* `<courier-inbox>`: inbox for displaying and managing messages
* `<courier-inbox-popup-menu>`: popup menu version of the inbox
* `<courier-toast>`: toast notifications for time-sensitive alerts
* `<courier-preferences>`: preference center for topic subscriptions and delivery
* `CourierInboxDatastore` and `CourierToastDatastore`: the data layer, for custom UIs

> [!TIP]
>
> See these components in the [interactive Inbox demo](https://www.courier.com/inbox-demo). No setup required.

## Installation

The inbox, toast, and preferences are separate packages, so install only the ones you render.

```bash theme={null}
npm install @trycourier/courier-ui-inbox
npm install @trycourier/courier-ui-toast
npm install @trycourier/courier-ui-preferences
```

Available on GitHub and npm:
[ Inbox](https://github.com/trycourier/courier-web/tree/main/%40trycourier/courier-ui-inbox) ·
[ Inbox](https://www.npmjs.com/package/@trycourier/courier-ui-inbox) ·
[ Toast](https://github.com/trycourier/courier-web/tree/main/%40trycourier/courier-ui-toast) ·
[ Toast](https://www.npmjs.com/package/@trycourier/courier-ui-toast) ·
[ Preferences](https://github.com/trycourier/courier-web/tree/main/%40trycourier/courier-ui-preferences) ·
[ Preferences](https://www.npmjs.com/package/@trycourier/courier-ui-preferences)

The packages have no peer dependencies and need no build configuration.

> [!NOTE]
>
> Using React, Vue, or Angular? The [React
> DOC](/docs/sdk-libraries/courier-react-web), [Vue
> DOC](/docs/sdk-libraries/courier-vue-web), and [Angular
> DOC](/docs/sdk-libraries/courier-angular-web) SDKs wrap these same elements as native components, with props and bindings in that framework's idiom.

## Authentication

Courier authenticates with a **JWT** that your backend mints with your Courier API key, never in client code. [Authenticate users
DOC](/docs/in-app/authenticate-users?lang=Web%20Components) is the full guide: the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See [EU setup
DOC](/docs/in-app/authenticate-users?lang=Web%20Components#connect-to-the-eu-datacenter).

```ts theme={null}
import { Courier } from "@trycourier/courier-ui-inbox";

Courier.shared.signIn({ userId, jwt });  // also accepts tenantId, apiUrls, showLogs
Courier.shared.signOut();
Courier.shared.addAuthenticationListener(({ userId }) => { /* ... */ });
```

All three packages re-export the same `Courier` from `@trycourier/courier-js`. Import it from any one of them and sign in once, and every Courier element on the page uses that session and its real-time connection.

## Quick start

Importing a package registers its elements, so the tag renders as soon as the module loads. Sign the user in and the inbox fills.

```html theme={null}
<body>
  <courier-inbox id="inbox"></courier-inbox>

  <script type="module">
    import { Courier } from "@trycourier/courier-ui-inbox";

    // Generate a JWT for your user on your backend server
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

    // Authenticate the user
    Courier.shared.signIn({
      userId: "user_123",
      jwt: jwt,
    });
  </script>
</body>
```

> [!TIP]
>
> Follow the [inbox guide
> DOC](/docs/in-app/add-an-inbox?lang=Web%20Components) for step-by-step guidance, including backend JWT generation. The [Web Components example app](https://github.com/trycourier/courier-web/tree/main/examples/web-js) wires up every element.

## Component reference

Each component's options, theme, callbacks, and custom-render surface live with the feature. These links open on the Web Components tab.

| To do this | Go here |
| - | - |
| Embed the inbox, or render it as a popup | [Add an inbox&#xA;DOC](/docs/in-app/add-an-inbox?lang=Web%20Components) |
| Theme it, handle clicks, set its actions | [Customize the inbox&#xA;DOC](/docs/in-app/customize-the-inbox?lang=Web%20Components) |
| Replace parts of it, or build your own | [Build a custom inbox&#xA;DOC](/docs/in-app/build-a-custom-inbox?lang=Web%20Components) |
| Split it into filtered tabs and feeds | [Tabs and feeds&#xA;DOC](/docs/in-app/tabs-and-feeds?lang=Web%20Components) |
| Add toasts, and set auto-dismiss | [Add toasts&#xA;DOC](/docs/in-app/add-toasts?lang=Web%20Components) |
| Theme a toast or replace it | [Customize toasts&#xA;DOC](/docs/in-app/customize-toasts?lang=Web%20Components) |
| Add a preference center | [Add a preference center&#xA;DOC](/docs/in-app/add-a-preference-center?lang=Web%20Components) |
| Theme preferences, or build your own | [Customize preferences&#xA;DOC](/docs/in-app/customize-preferences?lang=Web%20Components) |
| Send a message that reaches the inbox | [Send to the inbox&#xA;DOC](/docs/in-app/send-to-the-inbox) |

The `CourierInboxTheme`, `CourierToastTheme`, and `CourierPreferencesTheme` objects are the same on React, Vue, Angular, and the Web Components, so each is documented once: [inbox theme
DOC](/docs/in-app/customize-the-inbox#courierinboxtheme-reference), [toast theme
DOC](/docs/in-app/customize-toasts#theme), [preferences theme
DOC](/docs/in-app/customize-preferences#theme).

## Attributes and methods

Every option is an HTML attribute, a method on the element, or both. Attributes suit static setup written in markup. Methods suit anything that changes at runtime or takes a function, and they are what the framework SDKs call under the hood.

```html theme={null}
<!-- Attributes take strings, so a theme or feed list is a JSON string -->
<courier-inbox
  mode="light"
  light-theme='{"inbox": {"header": {"backgroundColor": "#FFFFFF"}}}'>
</courier-inbox>

<!-- Methods take objects and functions -->
<courier-inbox id="inbox"></courier-inbox>
<script type="module">
  const inbox = document.getElementById("inbox");

  inbox.setMode("light");
  inbox.setLightTheme({ inbox: { header: { backgroundColor: "#FFFFFF" } } });
</script>
```

| Element | Attributes |
| - | - |
| `<courier-inbox>` | `height`, `feeds`, `mode`, `light-theme`, `dark-theme`, `message-click`, `message-action-click`, `message-long-press` |
| `<courier-inbox-popup-menu>` | `popup-alignment`, `popup-width`, `popup-height`, `top`, `right`, `bottom`, `left`, `feeds`, `mode`, `light-theme`, `dark-theme` |
| `<courier-toast>` | `auto-dismiss`, `auto-dismiss-timeout-ms`, `dismiss-button`, `mode`, `light-theme`, `dark-theme` |
| `<courier-preferences>` | `title`, `subtitle`, `brand-id`, `draft`, `mode`, `light-theme`, `dark-theme` |

The inbox, the popup menu, and the preferences element also take `preview`, which renders injected data with no sign-in. Pair it with `setPreviewData()`.

Render slots such as `setListItem()`, `selectFeed()`, `refresh()`, and the toast's `onToastItemClick()` exist only as methods. Each one is documented on the In-App page for its feature.

**A theme attribute must be valid JSON.** A malformed `light-theme` or `dark-theme` isn't applied, and the inbox and toast throw a parse error to the console. Build the string with `JSON.stringify()`, or call `setLightTheme()` with the object instead.

**`auto-dismiss` turns off only when set to `"false"`.** Any other value, including an empty attribute, turns it on, and removing the attribute leaves it on. Call `disableAutoDismiss()` to turn it off from code.

## Events

Besides its `onMessage*` methods, `<courier-inbox>` dispatches a DOM event for each interaction. The `detail` carries the same payload the method's handler receives.

| Event | `detail` |
| - | - |
| `message-click` | `{ message, index }` |
| `message-action-click` | `{ message, action, index }` |
| `message-long-press` | `{ message, index }` |

```js theme={null}
document.addEventListener("message-click", (event) => {
  openInApp(event.detail.message);
});
```

The events bubble out of the element's shadow DOM, so you can listen on the element, on `<courier-inbox-popup-menu>`, or on `document`. That suits a host that delegates events from one place, or that loads the element before its own code runs.

The `message-click`, `message-action-click`, and `message-long-press` attributes take a function body as a string, the way `onclick` does, and run it with `props` in scope. The element compiles it with `new Function`, so a Content Security Policy without `'unsafe-eval'` blocks it. Use the event or the method under a strict CSP.

## Typing the elements

Each package exports its element class, so a TypeScript host can type the element it queries and get the methods autocompleted.

```ts theme={null}
import { CourierInbox } from "@trycourier/courier-ui-inbox";
import type { CourierToast } from "@trycourier/courier-ui-toast";
import type { CourierPreferences } from "@trycourier/courier-ui-preferences";

const inbox = document.getElementById("inbox") as CourierInbox;
inbox.setFeeds(CourierInbox.defaultFeeds());
```

## Advanced

### Server-side rendering

Importing a package on the server is safe. The elements register only when `window` exists, so the import is a no-op under Node, and the tags render once the module runs in the browser. In Next.js, import the package from a client component.

### Troubleshooting

> **The element renders nothing**
>
> The package isn't imported on that page, so the browser treats the tag as an unknown element. Import the package (`@trycourier/courier-ui-inbox` for the inbox) in a module that runs on that page.

> **A method call throws 'is not a function'**
>
> The script ran before the element was registered. Import the package first, or wait with `await customElements.whenDefined("courier-inbox")` before calling methods.

> **Messages not loading**
>
> **Possible causes:**
>
> 1. Not authenticated: call `Courier.shared.signIn()`
> 2. JWT expired: generate a new token
> 3. Missing scopes: include `inbox:read:messages` and `inbox:write:events` in the JWT
> 4. Wrong user ID: the `userId` must match the user the JWT was issued for


# Courier C# SDK
Source: https://www.courier.com/docs/sdk-libraries/csharp

Typed access to the Courier API from C# with async methods throughout.

The Courier C# SDK gives typed access to the [Courier REST API
DOC](/docs/reference/api-overview) from C#.

It targets .NET Standard 2.0, uses async/await throughout, and returns typed response objects.

Available on
[ NuGet](https://www.nuget.org/packages/TryCourier) and
[ GitHub](https://github.com/trycourier/courier-csharp).

## Installation

Install the package from [NuGet](https://www.nuget.org/packages/TryCourier):

```bash theme={null}
dotnet add package TryCourier
```

Requires .NET Standard 2.0 or later.

## Quick start

```csharp theme={null}
using System.Text.Json;
using TryCourier;
using TryCourier.Models;
using TryCourier.Models.Send;

CourierClient client = new();

var response = await client.Send.Message(new SendMessageParams
{
    Message = new()
    {
        To = new UserRecipient { UserId = "user_123" },
        Template = "welcome-email",
        Data = new Dictionary<string, JsonElement>
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
    },
});

Console.WriteLine(response.RequestID);
```

> [!TIP]
>
> The client reads `COURIER_API_KEY` from your environment. You can also set it explicitly: `new CourierClient { ApiKey = "YOUR_COURIER_API_KEY" }`.

## Authentication

Get your API key from [Settings > API Keys](https://app.courier.com/settings/api-keys). Set it as an environment variable:

```bash theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
```

Or pass it to the client:

```csharp theme={null}
CourierClient client = new() { ApiKey = "YOUR_COURIER_API_KEY" };
```

| Property | Environment variable | Default |
| - | - | - |
| `ApiKey` | `COURIER_API_KEY` | -- |
| `BaseUrl` | `COURIER_BASE_URL` | `https://api.courier.com` |

## Sending notifications

Design your notification in [Design Studio
DOC](/docs/design/templates/design-studio), then reference it by ID:

```csharp theme={null}
var response = await client.Send.Message(new SendMessageParams
{
    Message = new()
    {
        To = new UserRecipient { UserId = "user_123" },
        Template = "my-template-id",
        Data = new Dictionary<string, JsonElement>
        {
            { "order_id", JsonSerializer.SerializeToElement("10042") },
        },
    },
});
```

## Available resources

The SDK covers the full Courier API. Every method is async and returns typed models.

| Resource | Namespace | Description |
| - | - | - |
| Send | `client.Send` | Send messages to one or more recipients |
| Messages | `client.Messages` | Retrieve status, history, and content of sent messages |
| Profiles | `client.Profiles` | Create, update, and retrieve user profiles |
| Users | `client.Users` | Manage preferences, tenants, and push tokens per user |
| Auth | `client.Auth` | Issue JWT tokens for client-side SDK authentication |
| Lists | `client.Lists` | Manage subscription lists and their subscribers |
| Audiences | `client.Audiences` | Define and query audience segments |
| Tenants | `client.Tenants` | Manage tenants for multi-tenant setups |
| Journeys | `client.Journeys` | Invoke and cancel runs. Create, list, publish, and archive [journeys&#xA;DOC](/docs/journeys/overview) |
| Brands | `client.Brands` | Manage brand settings (logos, colors, templates) |
| Notifications | `client.Notifications` | List and inspect notification templates |
| Translations | `client.Translations` | Workspace `.po` strings for the `{{t}}` helper |

## Common operations

### Checking message status

```csharp theme={null}
var message = await client.Messages.Retrieve("your-message-id");
Console.WriteLine(message.Status);
Console.WriteLine(message.Delivered);
```

### Managing user profiles

```csharp theme={null}
await client.Profiles.Create("user_123", new ProfileCreateParams
{
    Profile = new Dictionary<string, JsonElement>
    {
        { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
        { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
    },
});

var profile = await client.Profiles.Retrieve("user_123");
```

### Issuing JWT tokens

Courier's [client-side SDKs
DOC](/docs/sdk-libraries/sdks-overview) (React, JavaScript, mobile) authenticate users with a JWT your backend issues. [Authenticate users
DOC](/docs/in-app/authenticate-users) covers the token flow, the scope strings, and token refresh. Use `client.Auth.IssueToken`:

```csharp theme={null}
var result = await client.Auth.IssueToken(new AuthIssueTokenParams
{
    Scope = "user_id:user_123 inbox:read:messages inbox:write:events",
    ExpiresIn = "2 days",
});

Console.WriteLine(result.Token);
```

| Scope | Permission |
| - | - |
| `user_id:<id>` | Which user the token is for (required) |
| `inbox:read:messages` | Read inbox messages |
| `inbox:write:events` | Mark messages as read/archived |
| `read:preferences` | Read notification preferences |
| `write:preferences` | Update notification preferences |
| `write:user-tokens` | Register push notification tokens |

## Configuration

### Error handling

When the API returns a non-success status code, the SDK throws a `CourierApiException`:

```csharp theme={null}
try
{
    await client.Send.Message(parameters);
}
catch (CourierApiException e)
{
    Console.WriteLine(e.StatusCode);
    Console.WriteLine(e.Message);
}
```

### Retries and timeouts

The SDK retries failed requests up to 2 times with exponential backoff. Use `WithOptions` to configure per-request:

```csharp theme={null}
var response = await client
    .WithOptions(options => options with
    {
        Timeout = TimeSpan.FromSeconds(20),
        MaxRetries = 0,
    })
    .Send.Message(parameters);
```

`WithOptions` returns a new client instance. The original is unchanged.

## Journeys

[Journeys
DOC](/docs/journeys/overview) are multi-step workflows: send, delay, branch, throttle, digest, and more. Invoke one by ID or alias to start a run. Cancel runs by ID, or by a shared cancelation token.

```csharp theme={null}
// Start a run (by journey ID or alias); the response includes RunID
var response = await client.Journeys.Invoke("your-journey-id", new JourneyInvokeParams
{
    UserID = "user_123",
});
Console.WriteLine(response.RunID);
```

> [!NOTE]
>
> `client.Journeys.Cancel(...)` takes exactly one of `run_id` or `cancelation_token` (spelled with one "l"). Build and manage journeys from code with `Create`, `List`, `Publish`, and `Archive`. See [Build journeys via API
> DOC](/docs/journeys/build).

## More operations

A few more resources from the full [Courier REST API
DOC](/docs/reference/api-overview):

| Resource | Method | Use case |
| - | - | - |
| User preferences | `client.Users.Preferences.Retrieve(userId)` | Fetch a user's notification preferences for your [preference center&#xA;DOC](/docs/recipients/preferences/overview) |
| Cancel a message | `client.Messages.Cancel(messageId)` | Cancel a delayed or queued message before delivery |
| Push tokens | `client.Users.Tokens.AddSingle(token, params)` | Register a device push token for [iOS&#xA;DOC](/docs/sdk-libraries/ios), [Android&#xA;DOC](/docs/sdk-libraries/android), [React Native&#xA;DOC](/docs/sdk-libraries/react-native), or [Flutter&#xA;DOC](/docs/sdk-libraries/flutter) |

> **[API Reference](/docs/reference/api-overview)**
>
> Full REST API docs with request/response examples.

> **[Send API](/docs/send/overview)**
>
> Learn about the Send endpoint, routing, and message options.

> **[Quickstart](/docs/get-started/send-a-message)**
>
> Send your first notification in under two minutes.

> **[GitHub](https://github.com/trycourier/courier-csharp)**
>
> Source code, issues, and changelog.

## Idempotent sends

Pass an idempotency key and Courier replays the first response for that key instead of sending again. The SDK sets the `Idempotency-Key` header for you. [Idempotency
DOC](/docs/reference/api-overview#idempotency) covers the scoping rule and the replay window.

```csharp theme={null}
SendMessageParams parameters = new()
{
    Message = new() { To = new UserRecipient { UserId = "user_123" }, Template = "nt_01kx4h2jdafq8bk9aftxak4b40" },
    IdempotencyKey = "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
};
var response = await client.Send.Message(parameters);
```


# Courier Flutter SDK
Source: https://www.courier.com/docs/sdk-libraries/flutter

Prebuilt inbox and preferences widgets, push token sync, and Dart APIs for Flutter.

The Courier Flutter SDK gives you prebuilt widgets and Dart APIs. It handles authentication, token management, and real-time delivery on iOS and Android.

This page is the Flutter reference: what to install, how to configure both native projects, and the Dart API surface. Each flow is written once and applies to every platform.

| To do this | Read |
| :- | :- |
| Render the inbox | [Add an inbox&#xA;DOC](/docs/in-app/add-an-inbox?lang=Flutter) |
| Theme it, handle taps, or build your own UI | [Customize the inbox&#xA;DOC](/docs/in-app/customize-the-inbox?lang=Flutter) |
| Set up push, from provider to device | [Set up push notifications&#xA;GUIDE](/docs/guides/set-up-mobile-push) |
| Add the preference center | [Add a preference center&#xA;DOC](/docs/in-app/add-a-preference-center?lang=Flutter) |
| Mint the JWT you sign in with | [Authenticate users&#xA;DOC](/docs/in-app/authenticate-users?lang=Flutter) |

Available on
[ GitHub](https://github.com/trycourier/courier-flutter)
and [ pub.dev](https://pub.dev/packages/courier_flutter).

| Requirement | Value |
| - | - |
| Min Dart SDK | 3.3.0 |
| Min Flutter | 3.13.6 |
| Min iOS version | 15.0 |
| Min Android SDK | 23 |
| Gradle | 8.4+ |

> [!NOTE]
>
> The SDK's `intl` dependency (`>=0.19.0 <1.0.0`) is incompatible with Flutter 3.32+ (Dart 3.7+), which ships `intl` 1.0. On dependency resolution errors, pin `intl: ^0.19.0` in your `pubspec.yaml` or wait for an SDK update that widens the constraint.

## Installation

```bash theme={null}
flutter pub add courier_flutter
```

### iOS setup

Update your deployment target to iOS 15+, then install the CocoaPod:

```bash theme={null}
cd ios && pod install
```

In `ios/Runner/AppDelegate.swift`, inherit from `CourierFlutterDelegate`. It is what carries the APNs token and the push callbacks into Dart.

```swift theme={null}
import Flutter
import courier_flutter

@main
@objc class AppDelegate: CourierFlutterDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}
```

### Android setup

**1. Add the Jitpack repository**

In your `android/build.gradle`:

```gradle theme={null}
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
```

**2. Set minimum SDK version**

In your `app/build.gradle`:

```gradle theme={null}
minSdkVersion 23
targetSdkVersion 33
compileSdkVersion 33
```

Your app must support at least Gradle 8.4.

**3. Extend CourierFlutterActivity**

In `MainActivity`. This is what lets the SDK persist user state across app sessions.

```kotlin theme={null}
import com.courier.courier_flutter.CourierFlutterActivity

class MainActivity : CourierFlutterActivity() {
    // ...
}
```

## Authentication

Courier authenticates with a **JWT** that your backend mints with your Courier API key, never in client code. [Authenticate users
DOC](/docs/in-app/authenticate-users?lang=Flutter) covers the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See [EU setup
DOC](/docs/in-app/authenticate-users?lang=Flutter#connect-to-the-eu-datacenter).

Credentials persist across app sessions, so you sign in once per user rather than on every launch.

```dart theme={null}
await Courier.shared.signIn(userId: "your_user_id", accessToken: jwt);
await Courier.shared.signOut();
```

## Inbox

[Add an inbox
DOC](/docs/in-app/add-an-inbox?lang=Flutter) is the setup flow. These are the types it uses on Flutter.

| Type | What it is |
| :- | :- |
| `CourierInbox` | The prebuilt inbox widget |
| `CourierInboxTheme` | Fonts, colors, unread indicators, swipe actions, tab and button styles |
| `addInboxListener` | Raw message data and events, for a UI you render yourself |

Every callback and action these expose is documented per platform in [Data and actions
DOC](/docs/in-app/build-a-custom-inbox?lang=Flutter#data-and-actions).

![Custom Inbox list item rendering](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/flutter-inbox-custom.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=84e592bc00dd3ab8b3df7e7772110c4b)

A list item rendered by the app instead of the prebuilt widget

### Inbox theme

With no `CourierInboxTheme`, the widget takes its styling from your app's Flutter `Theme`:

* Button style from `Theme.of(context).elevatedButtonTheme.style`
* Loading and unread indicator color from `Theme.of(context).primaryColor`
* Text styles from `Theme.of(context).textTheme`

Pass a theme to override those. Light and dark themes are separate.

```dart theme={null}
final theme = CourierInboxTheme(
    loadingIndicatorColor: Color(0xFF9747FF),
    tabIndicatorColor: Color(0xFF9747FF),
    unreadIndicatorStyle: CourierInboxUnreadIndicatorStyle(
        indicator: CourierInboxUnreadIndicator.dot,
        color: Color(0xFF9747FF),
    ),
    // ... additional style properties
);

CourierInbox(
  canSwipePages: true,
  lightTheme: theme,
  darkTheme: theme,
)
```

![Default Inbox on iOS](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/flutter-inbox-default-ios.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=52513145c60eeb78af2413f6946b71da)

![Default Inbox on Android](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/flutter-inbox-default-android.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=e2fa6a8aa9ac9b58e154f70bf529857e)

Default Inbox on iOS and Android

![Styled Inbox on iOS](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/flutter-inbox-styled-ios.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=e6f2b72880921d7f17da56bb19e14577)

![Styled Inbox on Android](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/flutter-inbox-styled-android.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=dc928e6d0d986d461b830d88f1853d93)

Styled Inbox on iOS and Android

Branding from [Courier Studio](https://app.courier.com/designer/brands) also applies. The SDK reads primary color and footer visibility from your brand settings.

## Push notifications

[Set up push notifications
GUIDE](/docs/guides/set-up-mobile-push) is the setup flow, from connecting APNs and FCM to a device that receives push. It covers the native wiring above, `setTokenForProvider`, permission, and reading the payload on tap.

> [!NOTE]
>
> Push notifications require a physical device. Simulators and emulators don't reliably support push token registration or notification delivery.

| Feature | iOS | Android |
| - | - | - |
| Automatic token management | Yes | Yes |
| Notification tracking | Yes | Yes |
| Permission requests | Yes | No |

On iOS, add a [Notification Service Extension
DOC](/docs/sdk-libraries/ios#notification-service-extension) to track delivery while your app is closed.

## Preferences

[Add a preference center
DOC](/docs/in-app/add-a-preference-center?lang=Flutter) is the setup flow. These are the types it uses on Flutter.

| Type | What it is |
| :- | :- |
| `CourierPreferences` | The prebuilt preference center widget |
| `mode` | `TopicMode()` or `ChannelsMode(channels: [push, sms, email])` |
| `CourierPreferencesTheme` | Fonts, colors, toggle styles, section headers |

> [!NOTE]
>
> Topics and sections are configured in the [Preferences Editor
> GUIDE](/docs/guides/build-a-preference-center#configure-the-topics). See [Preferences Overview
> DOC](/docs/recipients/preferences/overview) for how preference enforcement works at send time.

### Preferences theme

Light and dark themes are separate, and [Courier Studio branding](https://app.courier.com/designer/brands) applies automatically when you supply a `brandId`.

```dart theme={null}
final theme = CourierPreferencesTheme(
    brandId: "YOUR_BRAND_ID",
    sectionTitleStyle: TextStyle(fontWeight: FontWeight.bold, fontSize: 20),
    topicTitleStyle: TextStyle(fontSize: 18),
    // ... additional style properties
);

CourierPreferences(
  mode: TopicMode(),
  lightTheme: theme,
  darkTheme: theme,
)
```

<video aria-label="Default Preferences on Flutter" />

<video aria-label="Styled Preferences on Flutter" />

Default and styled Preferences on Flutter

## CourierClient

For advanced use cases, `CourierClient` is a low-level wrapper around the Courier API. Each client holds its own credentials, so you can spin up as many as you need.

### Initialization

```dart theme={null}
final client = CourierClient(
  jwt:          "...",          // Optional. Required for most authenticated calls
  userId:       "your_user_id",
  connectionId: "...",          // Optional. Used for the inbox websocket
  tenantId:     "...",          // Optional. Scopes the client to a tenant
  apiUrls:      CourierApiUrls.eu, // Optional. Use for EU users
  showLogs:     true,           // Optional. Defaults to kDebugMode
);

final options = client.options;
```

### Token management

```dart theme={null}
final device = CourierDevice(
  appId:        "APP_ID",
  adId:         "AD_ID",
  deviceId:     "DEVICE_ID",
  platform:     "ios",
  manufacturer: "Apple",
  model:        "iPhone 15",
);

await client.tokens.putUserToken(
  token: "...",
  provider: "firebase-fcm",
  device: device, // Optional
);

await client.tokens.deleteUserToken(token: "...");
```

### Inbox

```dart theme={null}
final feed = await client.inbox.getMessages(
  paginationLimit: 25,
  startCursor: null,
);

final archived = await client.inbox.getArchivedMessages(
  paginationLimit: 25,
  startCursor: null,
);

final unreadCount = await client.inbox.getUnreadMessageCount();

await client.inbox.open(messageId: "...");
await client.inbox.click(messageId: "...", trackingId: "tracking_id");
await client.inbox.read(messageId: "...");
await client.inbox.unread(messageId: "...");
await client.inbox.archive(messageId: "...");
await client.inbox.readAll();
```

### Preferences

```dart theme={null}
final prefs = await client.preferences.getUserPreferences(
  paginationCursor: null,
);

final topic = await client.preferences.getUserPreferenceTopic(
  topicId: "...",
);

await client.preferences.putUserPreferenceTopic(
  topicId: "...",
  status: CourierUserPreferencesStatus.optedIn,
  hasCustomRouting: true,
  customRouting: [CourierUserPreferencesChannel.push],
);
```

### Branding

```dart theme={null}
final brand = await client.brands.getBrand(brandId: "...");
```

### URL tracking

Pass any tracking URL found inside a push notification payload or inbox message:

```dart theme={null}
// Available events: clicked, delivered, opened, read, unread
await client.tracking.postTrackingUrl(
  url: trackingUrl,
  event: CourierTrackingEvent.delivered,
);
```

See the full Courier API reference at [courier.com/docs/reference
DOC](/docs/reference/api-overview).


# Courier Go SDK
Source: https://www.courier.com/docs/sdk-libraries/go

Typed access to the Courier API from Go with request structs.

The Courier Go SDK gives typed access to the [Courier REST API
DOC](/docs/reference/api-overview) from Go.

It uses strongly typed request structs with `omitzero` semantics and returns parsed response types.

Available on
[ GitHub](https://github.com/trycourier/courier-go)
and [ pkg.go.dev](https://pkg.go.dev/github.com/trycourier/courier-go/v4).

## Installation

```go theme={null}
import (
	"github.com/trycourier/courier-go/v4" // imported as courier
)
```

Or pin a specific version:

```bash theme={null}
go get -u 'github.com/trycourier/courier-go/v4'
```

Requires Go 1.22+.

## Quick start

```go theme={null}
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/trycourier/courier-go/v4"
	"github.com/trycourier/courier-go/v4/option"
	"github.com/trycourier/courier-go/v4/shared"
)

func main() {
	client := courier.NewClient(
		option.WithAPIKey(os.Getenv("COURIER_API_KEY")),
	)
	response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
		Message: courier.SendMessageParamsMessage{
			To: courier.SendMessageParamsMessageToUnion{
				OfUserRecipient: &shared.UserRecipientParam{
					UserID: courier.String("your_user_id"),
				},
			},
			Template: courier.String("your_template_id"),
			Data: map[string]any{
				"foo": "bar",
			},
		},
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.RequestID)
}
```

> [!TIP]
>
> The client reads `COURIER_API_KEY` from your environment. Pass it explicitly with `option.WithAPIKey("YOUR_COURIER_API_KEY")`.

## Authentication

Get your API key from [Settings > API Keys](https://app.courier.com/settings/api-keys) in the Courier dashboard. Set it as an environment variable:

```bash theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
```

The SDK reads it by default. To pass the key explicitly:

```go theme={null}
client := courier.NewClient(
	option.WithAPIKey("YOUR_COURIER_API_KEY"),
)
```

## Sending notifications

Design your notification in [Design Studio
DOC](/docs/design/templates/design-studio), then reference it by ID:

```go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("my-template-id"),
		Data: map[string]any{
			"order_id": "10042",
		},
	},
})
```

## Available resources

The SDK covers the full Courier API. Every method is typed and carries Go docstrings.

| Resource | Namespace | Description |
| - | - | - |
| Send | `client.Send` | Send messages to one or more recipients |
| Messages | `client.Messages` | Retrieve status, history, and content of sent messages |
| Profiles | `client.Profiles` | Create, update, and retrieve user profiles |
| Users | `client.Users` | Manage preferences, tenants, and push tokens per user |
| Auth | `client.Auth` | Issue JWT tokens for client-side SDK authentication |
| Lists | `client.Lists` | Manage subscription lists and their subscribers |
| Audiences | `client.Audiences` | Define and query audience segments |
| Tenants | `client.Tenants` | Manage tenants for multi-tenant setups |
| Journeys | `client.Journeys` | Invoke and cancel runs. Create, list, publish, and archive [journeys&#xA;DOC](/docs/journeys/overview) |
| Brands | `client.Brands` | Manage brand settings (logos, colors, templates) |
| Notifications | `client.Notifications` | List and inspect notification templates |
| Translations | `client.Translations` | Workspace `.po` strings for the `{{t}}` helper |

## Common operations

### Checking message status

```go theme={null}
message, err := client.Messages.Get(context.TODO(), "your-message-id")
fmt.Println(message.Status)
fmt.Println(message.Delivered) // Unix ms timestamp; 0 until delivered
```

### Managing user profiles

```go theme={null}
_, err := client.Profiles.New(context.TODO(), "user_123", courier.ProfileNewParams{
	Profile: map[string]any{
		"email": "sarah@acme-corp.com",
		"name":  "Sarah Bennett",
	},
})

profile, err := client.Profiles.Get(context.TODO(), "user_123")
```

### Issuing JWT tokens

Courier's [client-side SDKs
DOC](/docs/sdk-libraries/sdks-overview) (React, JavaScript, mobile) authenticate users with a JWT your backend issues. [Authenticate users
DOC](/docs/in-app/authenticate-users) covers the token flow, the scope strings, and token refresh. Use `client.Auth.IssueToken`:

```go theme={null}
result, err := client.Auth.IssueToken(context.TODO(), courier.AuthIssueTokenParams{
	Scope:     "user_id:user_123 inbox:read:messages inbox:write:events",
	ExpiresIn: "2 days",
})
fmt.Println(result.Token)
```

| Scope | Permission |
| - | - |
| `user_id:<id>` | Which user the token is for (required) |
| `inbox:read:messages` | Read inbox messages |
| `inbox:write:events` | Mark messages as read/archived |
| `read:preferences` | Read notification preferences |
| `write:preferences` | Update notification preferences |
| `write:user-tokens` | Register push notification tokens |

## Configuration

### Error handling

When the API returns a non-success status code, the SDK returns an error that can be unwrapped to access status and details:

```go theme={null}
response, err := client.Send.Message(context.TODO(), params)
if err != nil {
	var apiErr *courier.Error
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode)
		fmt.Println(apiErr.Error())
	}
}
```

### Retries

The SDK retries failed requests up to 2 times with exponential backoff. Configure globally or per-request:

```go theme={null}
client := courier.NewClient(
	option.WithMaxRetries(0), // disable retries
)
```

### Timeouts

The SDK sets no request timeout by default. Add one with a context deadline (or the `option.WithRequestTimeout` client option):

```go theme={null}
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()

response, err := client.Send.Message(ctx, params)
```

## Journeys

[Journeys
DOC](/docs/journeys/overview) are multi-step workflows: send, delay, branch, throttle, digest, and more. Invoke one by ID or alias to start a run. Cancel runs by ID, or by a shared cancelation token.

```go theme={null}
// Start a run (by journey ID or alias); the response includes a RunID
response, err := client.Journeys.Invoke(context.TODO(), "your-journey-id", courier.JourneyInvokeParams{
    JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
        UserID: courier.String("user_123"),
        Data:   map[string]any{"order_id": "A-1042"},
    },
})

// Cancel one run, or every run sharing a cancelation token
_, err = client.Journeys.Cancel(context.TODO(), courier.JourneyCancelParams{
    CancelJourneyRequest: courier.CancelJourneyRequestParamOfByRunID(response.RunID),
})
```

> [!NOTE]
>
> `cancel` takes exactly one of `run_id` or `cancelation_token` (spelled with one "l"). Build and manage journeys from code with create, list, publish, and archive. See [Build journeys via API
> DOC](/docs/journeys/build).

## More operations

A few more resources from the full [Courier REST API
DOC](/docs/reference/api-overview):

| Resource | Method | Use case |
| - | - | - |
| User preferences | `client.Users.Preferences.Get(ctx, userId, courier.UserPreferenceGetParams{})` | Fetch a user's notification preferences for your [preference center&#xA;DOC](/docs/recipients/preferences/overview) |
| Cancel a message | `client.Messages.Cancel(ctx, messageId)` | Cancel a delayed or queued message before delivery |
| Push tokens | `client.Users.Tokens.AddSingle(ctx, token, params)` | Register a device push token for [iOS&#xA;DOC](/docs/sdk-libraries/ios), [Android&#xA;DOC](/docs/sdk-libraries/android), [React Native&#xA;DOC](/docs/sdk-libraries/react-native), or [Flutter&#xA;DOC](/docs/sdk-libraries/flutter) |

> **[API Reference](/docs/reference/api-overview)**
>
> Full REST API docs with request/response examples.

> **[Send API](/docs/send/overview)**
>
> Learn about the Send endpoint, routing, and message options.

> **[Quickstart](/docs/get-started/send-a-message)**
>
> Send your first notification in under two minutes.

> **[GitHub](https://github.com/trycourier/courier-go)**
>
> Source code, issues, and changelog.

## Idempotent sends

Pass an idempotency key and Courier replays the first response for that key instead of sending again. The SDK sets the `Idempotency-Key` header for you. [Idempotency
DOC](/docs/reference/api-overview#idempotency) covers the scoping rule and the replay window.

```go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
	IdempotencyKey: courier.String("6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91"),
})
```


# Courier iOS SDK
Source: https://www.courier.com/docs/sdk-libraries/ios

Prebuilt inbox and preferences UI, push token sync, and Swift APIs for UIKit and SwiftUI.

The Courier iOS SDK gives you prebuilt UI components and Swift APIs. It handles authentication, token management, and real-time message delivery.

This page is the iOS reference: what to install, how to configure Xcode, and the Swift API surface. Each flow is written once and applies to every platform.

| To do this | Read |
| :- | :- |
| Render the inbox | [Add an inbox&#xA;DOC](/docs/in-app/add-an-inbox?lang=iOS) |
| Theme it, handle taps, or build your own UI | [Customize the inbox&#xA;DOC](/docs/in-app/customize-the-inbox?lang=iOS) |
| Set up push, from provider to device | [Set up push notifications&#xA;GUIDE](/docs/guides/set-up-mobile-push) |
| Add the preference center | [Add a preference center&#xA;DOC](/docs/in-app/add-a-preference-center?lang=iOS) |
| Mint the JWT you sign in with | [Authenticate users&#xA;DOC](/docs/in-app/authenticate-users?lang=iOS) |

Available on
[ GitHub](https://github.com/trycourier/courier-ios).

| Requirement | Value |
| - | - |
| Min iOS version | 15.0 |
| Package managers | Swift Package Manager, CocoaPods |

## Installation

```text Swift Package Manager theme={null}
1. In Xcode, go to File > Add Packages
2. Paste: https://github.com/trycourier/courier-ios
3. Select the version and add to your target
```

```ruby CocoaPods theme={null}
platform :ios, '15.0'

target 'YourApp' do
  pod 'Courier_iOS'
end
```

If using CocoaPods, run `pod install` from your project's `ios/` directory after updating the Podfile.

## Authentication

Courier authenticates with a **JWT** that your backend mints with your Courier API key, never in client code. [Authenticate users
DOC](/docs/in-app/authenticate-users?lang=iOS) is the full guide: the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See [EU setup
DOC](/docs/in-app/authenticate-users?lang=iOS#connect-to-the-eu-datacenter).

Credentials persist across app sessions, so you sign in once per user rather than on every launch.

```swift theme={null}
Task {
  await Courier.shared.signIn(userId: "your_user_id", accessToken: jwt)
  await Courier.shared.signOut()
}
```

## Inbox

[Add an inbox
DOC](/docs/in-app/add-an-inbox?lang=iOS) is the setup flow. These are the types it uses on iOS.

| Type | What it is |
| :- | :- |
| `CourierInboxView` | The prebuilt inbox as a SwiftUI view |
| `CourierInbox` | The same inbox as a UIKit view |
| `CourierInboxTheme` | Fonts, colors, unread indicators, swipe actions, button styles |
| `addInboxListener` | Raw message data and events, for a UI you render yourself |

Every callback and action these expose is documented per platform in [Data and actions
DOC](/docs/in-app/build-a-custom-inbox?lang=iOS#data-and-actions).

### Inbox theme

`CourierInboxTheme` is a constructor argument, and light and dark themes are separate.

```swift theme={null}
CourierInboxView(
    canSwipePages: true,
    lightTheme: yourLightTheme,
    darkTheme: yourDarkTheme,
    ...
)
```

![Default Inbox](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/ios-inbox-default.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=5905813f276b28f4c8697809caa5657d)

![Styled Inbox](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/ios-inbox-styled.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=b9964741c06b9e61a53232592f5e2034)

Default and styled Inbox on iOS

Branding from [Courier Studio](https://app.courier.com/designer/brands) also applies. The SDK reads primary color and footer visibility from your brand settings.

## Push notifications

[Set up push notifications
GUIDE](/docs/guides/set-up-mobile-push) is the setup flow, from connecting APNs to a device that receives push. It covers the `CourierDelegate` wiring, `setAPNSToken` and `setToken`, permission, and reading the payload on tap.

> [!NOTE]
>
> Push notifications require a physical device. Simulators don't reliably support push token registration or notification delivery.

The one piece of configuration that lives here is the extension target.

### Notification Service Extension

iOS only wakes your app for a push while it is running, so delivery goes untracked when the app is closed. A Notification Service Extension runs instead, and reports the delivery for you.

**1. Download the template**

Download [`CourierNotificationServiceTemplate.zip`](https://github.com/trycourier/courier-notification-service-extension-template/archive/refs/heads/main.zip) and run `sh make_template.sh`. Watch the [video walkthrough on GitHub](https://github.com/trycourier/courier-ios/blob/master/Docs/3_PushNotifications.md#4-add-the-notification-service-extension-optional-but-recommended) for a step-by-step guide.

**2. Add the extension target**

In Xcode: File > New > Target > select "Courier Service" > Finish.

**3. Link the Courier SDK**

Add the Courier package to the new target via SPM or CocoaPods.

> [!NOTE]
>
> **Attach Mutable Content** must be on for the [APNs provider
> DOC](/docs/integrations/push/apple-push-notification), or the extension never runs. It is on by default.

## Preferences

[Add a preference center
DOC](/docs/in-app/add-a-preference-center?lang=iOS) is the setup flow. These are the types it uses on iOS.

| Type | What it is |
| :- | :- |
| `CourierPreferencesView` | The prebuilt preference center as a SwiftUI view |
| `CourierPreferences` | The same view for UIKit |
| `mode` | `.topic` or `.channels([.push, .sms, .email])` |
| `CourierPreferencesTheme` | Fonts, colors, toggle styles, section headers |

> [!NOTE]
>
> Topics and sections are configured in the [Preferences Editor
> GUIDE](/docs/guides/build-a-preference-center#configure-the-topics). See [Preferences Overview
> DOC](/docs/recipients/preferences/overview) for how preference enforcement works at send time.

### Preferences theme

Light and dark themes are separate, and [Courier Studio branding](https://app.courier.com/designer/brands) applies automatically when you supply a `brandId`.

<video aria-label="Default Preferences" />

<video aria-label="Styled Preferences" />

Default and styled Preferences on iOS

## CourierClient

For advanced use cases, `CourierClient` is a low-level wrapper around the Courier API. Each client holds its own credentials, so you can spin up as many as you need.

### Initialization

```swift theme={null}
let client = CourierClient(
    jwt:           "...",          // Optional. Required for most authenticated calls
    userId:        "your_user_id",
    connectionId:  "...",          // Optional. Used for the inbox websocket
    tenantId:      "...",          // Optional. Scopes the client to a tenant
    apiUrls:       .eu,            // Optional. Use for EU users
    showLogs:      true            // Optional. Defaults to your build configuration
)

// Inspect or log via the client
let options = client.options
client.log("...")
client.warn("...")
client.error("...")
```

### Token management

```swift theme={null}
try await client.tokens.putUserToken(
    token: "...",
    provider: "firebase-fcm"
)

// Customize device metadata stored alongside the token
let device = CourierDevice(
    appId:         "APP_ID",
    adId:          "AD_ID",
    deviceId:      "DEVICE_ID",
    platform:      "ios",
    manufacturer:  "Apple",
    model:         "iPhone 15"
)

try await client.tokens.putUserToken(
    token: "...",
    provider: "firebase-fcm",
    device: device
)

try await client.tokens.deleteUserToken(token: "...")
```

### Inbox

```swift theme={null}
let messages = try await client.inbox.getMessages(
    paginationLimit: 25,
    startCursor: nil
)

let archived = try await client.inbox.getArchivedMessages(
    paginationLimit: 25,
    startCursor: nil
)

let unreadCount = try await client.inbox.getUnreadMessageCount()

try await client.inbox.open(messageId: "...")
try await client.inbox.read(messageId: "...")
try await client.inbox.unread(messageId: "...")
try await client.inbox.archive(messageId: "...")
try await client.inbox.readAll()
```

### Inbox websocket

Receive real-time updates across devices:

```swift theme={null}
let socket = client.inbox.socket

try await socket.connect(
    receivedMessage: { message in
        print(message)
    },
    receivedMessageEvent: { event in
        // Fires only when the event comes from a different connectionId
        // Available events: .read, .unread, .markAllRead, .opened, .archive
        print(event)
    }
)

try await socket.sendSubscribe()

await socket.disconnect()
```

### Preferences

```swift theme={null}
let prefs = try await client.preferences.getUserPreferences(paginationCursor: nil)

let topic = try await client.preferences.getUserPreferenceTopic(topicId: "...")

try await client.preferences.putUserPreferenceTopic(
    topicId: "...",
    status: .optedIn,
    hasCustomRouting: true,
    customRouting: [.push]
)
```

### Branding

```swift theme={null}
let brand = try await client.brands.getBrand(brandId: "...")
```

### URL tracking

Pass any tracking URL found inside a push notification payload or inbox message:

```swift theme={null}
// Available events: .clicked, .delivered, .opened, .read, .unread
try await client.tracking.postTrackingUrl(
    url: "courier_tracking_url",
    event: .delivered
)
```

See the full Courier API reference at [courier.com/docs/reference
DOC](/docs/reference/api-overview).


# Courier Java SDK
Source: https://www.courier.com/docs/sdk-libraries/java

Typed access to the Courier API from Java 8+ with builder-pattern requests.

The Courier Java SDK gives typed access to the [Courier REST API
DOC](/docs/reference/api-overview) from Java 8+.

It uses builder-pattern request construction, OkHttp for transport, and returns strongly typed response objects.

Available on
[ GitHub](https://github.com/trycourier/courier-java)
and [ Maven Central](https://central.sonatype.com/artifact/com.courier/courier-java).

## Installation

```kotlin Gradle theme={null}
implementation("com.courier:courier-java:LATEST_VERSION")
```

```xml Maven theme={null}
<dependency>
  <groupId>com.courier</groupId>
  <artifactId>courier-java</artifactId>
  <version>LATEST_VERSION</version>
</dependency>
```

Replace `LATEST_VERSION` with the current version from [Maven Central](https://central.sonatype.com/artifact/com.courier/courier-java). Requires Java 8+.

## Quick start

```java theme={null}
import com.courier.client.CourierClient;
import com.courier.client.okhttp.CourierOkHttpClient;
import com.courier.core.JsonValue;
import com.courier.models.UserRecipient;
import com.courier.models.send.SendMessageParams;

CourierClient client = CourierOkHttpClient.fromEnv();

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("your_user_id").build())
        .template("your_template_id")
        .data(SendMessageParams.Message.Data.builder()
            .putAdditionalProperty("foo", JsonValue.from("bar"))
            .build())
        .build())
    .build();

var response = client.send().message(params);
System.out.println(response.requestId());
```

> [!TIP]
>
> `CourierOkHttpClient.fromEnv()` reads `COURIER_API_KEY` from your environment, or the `courier.apiKey` system property. The builder also takes it: `.apiKey("YOUR_COURIER_API_KEY")`.

## Authentication

Get your API key from [Settings > API Keys](https://app.courier.com/settings/api-keys) in the Courier dashboard. Set it as an environment variable:

```bash theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
```

Or pass it via the builder:

```java theme={null}
CourierClient client = CourierOkHttpClient.builder()
    .apiKey("YOUR_COURIER_API_KEY")
    .build();
```

| Setter | System property | Environment variable | Default |
| - | - | - | - |
| `apiKey` | `courier.apiKey` | `COURIER_API_KEY` | -- |
| `baseUrl` | `courier.baseUrl` | `COURIER_BASE_URL` | `https://api.courier.com` |

## Sending notifications

Design your notification in [Design Studio
DOC](/docs/design/templates/design-studio), then reference it by ID:

```java theme={null}
var params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(SendMessageParams.Message.Data.builder()
            .putAdditionalProperty("order_id", JsonValue.from("10042"))
            .build())
        .build())
    .build();

var response = client.send().message(params);
```

## Available resources

The SDK covers the full Courier API. Every method returns strongly typed response objects.

| Resource | Namespace | Description |
| - | - | - |
| Send | `client.send()` | Send messages to one or more recipients |
| Messages | `client.messages()` | Retrieve status, history, and content of sent messages |
| Profiles | `client.profiles()` | Create, update, and retrieve user profiles |
| Users | `client.users()` | Manage preferences, tenants, and push tokens per user |
| Auth | `client.auth()` | Issue JWT tokens for client-side SDK authentication |
| Lists | `client.lists()` | Manage subscription lists and their subscribers |
| Audiences | `client.audiences()` | Define and query audience segments |
| Tenants | `client.tenants()` | Manage tenants for multi-tenant setups |
| Journeys | `client.journeys()` | Invoke and cancel runs. Create, list, publish, and archive [journeys&#xA;DOC](/docs/journeys/overview) |
| Brands | `client.brands()` | Manage brand settings (logos, colors, templates) |
| Notifications | `client.notifications()` | List and inspect notification templates |
| Translations | `client.translations()` | Workspace `.po` strings for the `{{t}}` helper |

## Common operations

### Checking message status

```java theme={null}
var message = client.messages().retrieve("your-message-id");
System.out.println(message.status());
System.out.println(message.delivered());
```

### Managing user profiles

```java theme={null}
client.profiles().create("user_123", ProfileCreateParams.builder()
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .putAdditionalProperty("name", JsonValue.from("Sarah Bennett"))
        .build())
    .build());

var profile = client.profiles().retrieve("user_123");
```

### Issuing JWT tokens

Courier's [client-side SDKs
DOC](/docs/sdk-libraries/sdks-overview) (React, JavaScript, mobile) authenticate users with a JWT your backend issues. [Authenticate users
DOC](/docs/in-app/authenticate-users) covers the token flow, the scope strings, and token refresh. Use `client.auth().issueToken`:

```java theme={null}
var result = client.auth().issueToken(AuthIssueTokenParams.builder()
    .scope("user_id:user_123 inbox:read:messages inbox:write:events")
    .expiresIn("2 days")
    .build());

System.out.println(result.token());
```

| Scope | Permission |
| - | - |
| `user_id:<id>` | Which user the token is for (required) |
| `inbox:read:messages` | Read inbox messages |
| `inbox:write:events` | Mark messages as read/archived |
| `read:preferences` | Read notification preferences |
| `write:preferences` | Update notification preferences |
| `write:user-tokens` | Register push notification tokens |

## Configuration

### Error handling

When the API returns a non-success status code, the SDK throws a `CourierServiceException`:

```java theme={null}
try {
    client.send().message(params);
} catch (CourierServiceException e) {
    System.out.println(e.statusCode());
    System.out.println(e.getMessage());
}
```

### Retries

The SDK retries failed requests up to 2 times with exponential backoff. Configure globally:

```java theme={null}
CourierClient client = CourierOkHttpClient.builder()
    .maxRetries(0)
    .build();
```

### Timeouts

Requests time out after 60 seconds by default. Configure globally:

```java theme={null}
CourierClient client = CourierOkHttpClient.builder()
    .timeout(Duration.ofSeconds(20))
    .build();
```

Or override per-request using `withOptions`:

```java theme={null}
client.withOptions(options -> options.timeout(Duration.ofSeconds(5)))
    .send().message(params);
```

## Journeys

[Journeys
DOC](/docs/journeys/overview) are multi-step workflows: send, delay, branch, throttle, digest, and more. Invoke one by ID or alias to start a run. Cancel runs by ID, or by a shared cancelation token.

```java theme={null}
// Start a run (by journey ID or alias); the response includes a runId
JourneysInvokeResponse response = client.journeys().invoke(
    "your-journey-id",
    JourneyInvokeParams.builder()
        .journeysInvokeRequest(JourneysInvokeRequest.builder()
            .userId("user_123")
            .build())
        .build());
System.out.println(response.runId());
```

> [!NOTE]
>
> Cancel a run with `client.journeys().cancel(...)`, passing exactly one of `run_id` or `cancelation_token` (spelled with one "l"). Build and manage journeys from code with create, list, publish, and archive. See [Build journeys via API
> DOC](/docs/journeys/build).

## More operations

A few more resources from the full [Courier REST API
DOC](/docs/reference/api-overview):

| Resource | Method | Use case |
| - | - | - |
| User preferences | `client.users().preferences().retrieve(userId)` | Fetch a user's notification preferences for your [preference center&#xA;DOC](/docs/recipients/preferences/overview) |
| Cancel a message | `client.messages().cancel(messageId)` | Cancel a delayed or queued message before delivery |
| Push tokens | `client.users().tokens().addSingle(token, params)` | Register a device push token for [iOS&#xA;DOC](/docs/sdk-libraries/ios), [Android&#xA;DOC](/docs/sdk-libraries/android), [React Native&#xA;DOC](/docs/sdk-libraries/react-native), or [Flutter&#xA;DOC](/docs/sdk-libraries/flutter) |

> **[API Reference](/docs/reference/api-overview)**
>
> Full REST API docs with request/response examples.

> **[Send API](/docs/send/overview)**
>
> Learn about the Send endpoint, routing, and message options.

> **[Quickstart](/docs/get-started/send-a-message)**
>
> Send your first notification in under two minutes.

> **[GitHub](https://github.com/trycourier/courier-java)**
>
> Source code, issues, and changelog.

## Idempotent sends

Pass an idempotency key and Courier replays the first response for that key instead of sending again. The SDK sets the `Idempotency-Key` header for you. [Idempotency
DOC](/docs/reference/api-overview#idempotency) covers the scoping rule and the replay window.

```java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .idempotencyKey("6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91")
    .build();
SendMessageResponse response = client.send().message(params);
```


# Courier Node.js SDK
Source: https://www.courier.com/docs/sdk-libraries/node

Typed access to the Courier API from TypeScript or JavaScript: install, authenticate, send.

The Courier Node.js SDK gives typed, server-side access to the [Courier REST API
DOC](/docs/reference/api-overview) from TypeScript or JavaScript.

Available on
[ GitHub](https://github.com/trycourier/courier-node)
and [ npm](https://www.npmjs.com/package/@trycourier/courier).

## Installation

```bash npm theme={null}
npm install @trycourier/courier
```

```bash yarn theme={null}
yarn add @trycourier/courier
```

```bash pnpm theme={null}
pnpm add @trycourier/courier
```

Requires Node.js 20+ (LTS), TypeScript 4.9+. Also works in Deno 1.28+, Bun 1.0+, Cloudflare Workers, and Vercel Edge Runtime.

## Quick start

```ts theme={null}
import Courier from '@trycourier/courier';

const client = new Courier();

const response = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { name: 'Sarah Bennett' },
  },
});

console.log(response.requestId);
```

> [!TIP]
>
> The client reads `COURIER_API_KEY` from your environment.

## Authentication

Get your API key from [Settings > API Keys](https://app.courier.com/settings/api-keys) in the Courier dashboard. Set it as an environment variable:

```bash theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
```

The SDK reads it by default. To pass the key explicitly:

```ts theme={null}
const client = new Courier({
  apiKey: 'YOUR_COURIER_API_KEY',
});
```

## Sending notifications

### With a template

Design your notification in [Design Studio
DOC](/docs/design/templates/design-studio), then reference it by ID:

```ts theme={null}
const response = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { order_id: '10042', item_name: 'Courier Hoodie' },
  },
});
```

### To multiple recipients

Send to several recipients in one call:

```ts theme={null}
const response = await client.send.message({
  message: {
    to: [
      { user_id: 'user_123' },
      { user_id: 'user_123' },
      { email: 'sarah@acme-corp.com' },
    ],
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
  },
});
```

## Available resources

The SDK covers the full Courier API.

| Resource | Namespace | Description |
| - | - | - |
| Send | `client.send` | Send messages to one or more recipients |
| Messages | `client.messages` | Retrieve status, history, and content of sent messages |
| Profiles | `client.profiles` | Create, update, and retrieve user profiles |
| Users | `client.users` | Manage preferences, tenants, and push tokens per user |
| Auth | `client.auth` | Issue JWT tokens for client-side SDK authentication |
| Lists | `client.lists` | Manage subscription lists and their subscribers |
| Audiences | `client.audiences` | Define and query audience segments |
| Tenants | `client.tenants` | Manage tenants for multi-tenant setups |
| Journeys | `client.journeys` | Invoke and cancel runs. Create, list, publish, and archive [journeys&#xA;DOC](/docs/journeys/overview) |
| Brands | `client.brands` | Manage brand settings (logos, colors, templates) |
| Notifications | `client.notifications` | List and inspect notification templates |
| Translations | `client.translations` | Workspace `.po` strings for the `{{t}}` helper |

## Common operations

### Checking message status

After sending, use the `requestId` to check delivery status or get the full event timeline:

```ts theme={null}
const message = await client.messages.retrieve('your-message-id');
console.log(message.status);    // e.g. 'DELIVERED'
console.log(message.delivered);  // delivery timestamp (ms)

const history = await client.messages.history('your-message-id');
for (const event of history.results) {
  console.log(event.type, event.event);
}
```

List recent messages with optional filters:

```ts theme={null}
const recent = await client.messages.list({ status: ['DELIVERED'] });
```

### Managing user profiles

Profiles store the recipient data Courier delivers to: email, phone, and custom fields. Create the profile before sending to a `user_id`.

```ts theme={null}
// Create or merge into a profile
await client.profiles.create('user_123', {
  profile: {
    email: 'sarah@acme-corp.com',
    phone_number: '+15551234567',
    name: 'Sarah Bennett',
  },
});

// Retrieve a profile
const profile = await client.profiles.retrieve('user_123');
console.log(profile.profile.email);

// Partial update (JSON Patch)
await client.profiles.update('user_123', {
  patch: [{ op: 'replace', path: '/name', value: 'Jane Smith' }],
});
```

> [!NOTE]
>
> `create` merges with any existing profile. `replace` overwrites it and drops any field you leave out.

### Issuing JWT tokens

Courier's [client-side SDKs
DOC](/docs/sdk-libraries/sdks-overview) (React, JavaScript, mobile) authenticate users with a JWT your backend issues. [Authenticate users
DOC](/docs/in-app/authenticate-users) covers the token flow, the scope strings, and token refresh. Use `auth.issueToken`:

```ts theme={null}
const { token } = await client.auth.issueToken({
  scope: 'user_id:user_123 inbox:read:messages inbox:write:events read:preferences write:preferences',
  expires_in: '2 days',
});

// Return this token to your frontend
```

The `scope` string controls what the token can access. Common scopes:

| Scope | Permission |
| - | - |
| `user_id:<id>` | Which user the token is for (required) |
| `inbox:read:messages` | Read inbox messages |
| `inbox:write:events` | Mark messages as read/archived |
| `read:preferences` | Read notification preferences |
| `write:preferences` | Update notification preferences |
| `write:user-tokens` | Register push notification tokens |

## TypeScript types

Every request and response has a TypeScript definition. Import them directly:

```ts theme={null}
import Courier from '@trycourier/courier';

const params: Courier.SendMessageParams = {
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { foo: 'bar' },
  },
};

const response: Courier.SendMessageResponse = await client.send.message(params);
```

Methods, parameters, and response fields carry docstrings that show on hover in VS Code and other editors.

## Configuration

### Error handling

The SDK throws typed errors for API failures. All errors extend `Courier.APIError`:

```ts theme={null}
try {
  await client.send.message({ message: { to: { user_id: 'user_123' }, template: 'nt_01kx4h2jdafq8bk9aftxak4b40' } });
} catch (err) {
  if (err instanceof Courier.APIError) {
    console.log(err.status);  // e.g. 400
    console.log(err.constructor.name);  // e.g. 'BadRequestError'
    console.log(err.message);
  }
}
```

| Status Code | Error Type |
| - | - |
| 400 | `BadRequestError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 409 | `ConflictError` |
| 422 | `UnprocessableEntityError` |
| 429 | `RateLimitError` |
| >=500 | `InternalServerError` |
| N/A | `APIConnectionError` |

### Retries

The SDK retries failed requests up to 2 times with exponential backoff. It retries connection failures, 408, 409, 429, and 5xx responses.

```ts theme={null}
// Disable retries
const client = new Courier({ maxRetries: 0 });

// Or override per-request
await client.send.message(
  { message: { to: { user_id: 'user_123' }, template: 'nt_01kx4h2jdafq8bk9aftxak4b40' } },
  { maxRetries: 5 },
);
```

### Timeouts

Requests time out after 60 seconds by default. Configure globally or per-request:

```ts theme={null}
const client = new Courier({
  timeout: 20 * 1000, // 20 seconds
});

// Override per-request
await client.send.message(
  { message: { to: { user_id: 'user_123' }, template: 'nt_01kx4h2jdafq8bk9aftxak4b40' } },
  { timeout: 5 * 1000 },
);
```

A timeout throws `APIConnectionTimeoutError`. The SDK retries timed-out requests by default.

### Logging

Enable debug logging with the `COURIER_LOG` environment variable or the `logLevel` client option:

```ts theme={null}
const client = new Courier({
  logLevel: 'debug', // 'debug' | 'info' | 'warn' | 'error' | 'off'
});
```

At `debug` level the SDK logs every HTTP request and response, headers and bodies included. You can also pass a custom logger (pino, winston, etc.):

```ts theme={null}
import pino from 'pino';

const client = new Courier({
  logger: pino().child({ name: 'Courier' }),
  logLevel: 'debug',
});
```

### Raw response access

Access HTTP headers or the underlying `Response` object:

```ts theme={null}
// Headers only (does not consume body)
const raw = await client.send.message({
  message: { to: { user_id: 'user_123' }, template: 'nt_01kx4h2jdafq8bk9aftxak4b40' },
}).asResponse();
console.log(raw.headers.get('x-request-id'));

// Parsed data + raw response
const { data, response } = await client.send.message({
  message: { to: { user_id: 'user_123' }, template: 'nt_01kx4h2jdafq8bk9aftxak4b40' },
}).withResponse();
console.log(data.requestId);
```

## Journeys

[Journeys
DOC](/docs/journeys/overview) are multi-step workflows: send, delay, branch, throttle, digest, and more. Invoke one by ID or alias to start a run. Cancel runs by ID, or by a shared cancelation token.

```ts theme={null}
// Start a run (by journey ID or alias); the response includes a runId
const { runId } = await client.journeys.invoke('your-journey-id', {
  user_id: 'user_123',
  data: { order_id: 'A-1042' },
});

// Cancel one run, or every run sharing a cancelation token
await client.journeys.cancel({ run_id: runId });
// await client.journeys.cancel({ cancelation_token: 'order-A-1042' });
```

> [!NOTE]
>
> `cancel` takes exactly one of `run_id` or `cancelation_token` (spelled with one "l"). Build and manage journeys from code with `client.journeys.create`, `list`, `publish`, and `archive`. See [Build journeys via API
> DOC](/docs/journeys/build).

## More operations

A few more resources from the full [Courier REST API
DOC](/docs/reference/api-overview):

| Resource | Method | Use case |
| - | - | - |
| User preferences | `client.users.preferences.retrieve(userId)` | Fetch a user's notification preferences for your [preference center&#xA;DOC](/docs/recipients/preferences/overview) |
| Cancel a message | `client.messages.cancel(messageId)` | Cancel a delayed or queued message before delivery (returns 409 if already delivered) |
| Push tokens | `client.users.tokens.addSingle(token, { user_id, provider_key: 'firebase-fcm' })` | Register a device push token for [iOS&#xA;DOC](/docs/sdk-libraries/ios), [Android&#xA;DOC](/docs/sdk-libraries/android), [React Native&#xA;DOC](/docs/sdk-libraries/react-native), or [Flutter&#xA;DOC](/docs/sdk-libraries/flutter) |

> **[API Reference](/docs/reference/api-overview)**
>
> Full REST API docs with request/response examples.

> **[Send API](/docs/send/overview)**
>
> Learn about the Send endpoint, routing, and message options.

> **[Quickstart](/docs/get-started/send-a-message)**
>
> Send your first notification in under two minutes.

> **[GitHub](https://github.com/trycourier/courier-node)**
>
> Source code, issues, and changelog.

## Idempotent sends

Pass an idempotency key and Courier replays the first response for that key instead of sending again. The SDK sets the `Idempotency-Key` header for you. [Idempotency
DOC](/docs/reference/api-overview#idempotency) covers the scoping rule and the replay window.

```ts theme={null}
const response = await client.send.message({
  message: { to: { user_id: "user_123" }, template: "nt_01kx4h2jdafq8bk9aftxak4b40" },
  "Idempotency-Key": "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
});
```


# Courier PHP SDK
Source: https://www.courier.com/docs/sdk-libraries/php

Typed access to the Courier API from PHP 8.1+ with named parameters.

The Courier PHP SDK gives typed access to the [Courier REST API
DOC](/docs/reference/api-overview) from any PHP 8.1+ application.

It takes optional arguments as named parameters and returns typed response objects.

Available on
[ GitHub](https://github.com/trycourier/courier-php).

> [!NOTE]
>
> The PHP SDK is in beta. APIs may change between releases. [Share feedback or report issues on GitHub.](https://github.com/trycourier/courier-php/issues/new)

## Installation

Install from Packagist with Composer:

```bash theme={null}
composer require trycourier/courier
```

Requires PHP 8.1+. Latest version on [Packagist](https://packagist.org/packages/trycourier/courier).

## Quick start

```php theme={null}
<?php

use Courier\Client;

$client = new Client(apiKey: getenv('COURIER_API_KEY'));

$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['name' => 'Sarah Bennett'],
  ],
);

var_dump($response->requestID);
```

> [!TIP]
>
> Pass your API key in the `COURIER_API_KEY` environment variable, or to the constructor: `new Client(apiKey: 'YOUR_COURIER_API_KEY')`.

## Authentication

Get your API key from [Settings > API Keys](https://app.courier.com/settings/api-keys). Set it as an environment variable:

```bash theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
```

Or pass it to the client constructor:

```php theme={null}
$client = new Client(apiKey: 'YOUR_COURIER_API_KEY');
```

## Sending notifications

Design your notification in [Design Studio
DOC](/docs/design/templates/design-studio), then reference it by ID:

```php theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['order_id' => '10042', 'item_name' => 'Courier Hoodie'],
  ],
);
```

## Available resources

The SDK covers the full Courier API.

| Resource | Namespace | Description |
| - | - | - |
| Send | `$client->send` | Send messages to one or more recipients |
| Messages | `$client->messages` | Retrieve status, history, and content of sent messages |
| Profiles | `$client->profiles` | Create, update, and retrieve user profiles |
| Users | `$client->users` | Manage preferences, tenants, and push tokens per user |
| Auth | `$client->auth` | Issue JWT tokens for client-side SDK authentication |
| Bulk | `$client->bulk` | Send messages to large recipient lists via jobs |
| Lists | `$client->lists` | Manage subscription lists and their subscribers |
| Audiences | `$client->audiences` | Define and query audience segments |
| Tenants | `$client->tenants` | Manage tenants for multi-tenant setups |
| Journeys | `$client->journeys` | Invoke and cancel runs. Create, list, publish, and archive [journeys&#xA;DOC](/docs/journeys/overview) |
| Brands | `$client->brands` | Manage brand settings (logos, colors, templates) |
| Notifications | `$client->notifications` | List and inspect notification templates |
| Translations | `$client->translations` | Workspace `.po` strings for the `{{t}}` helper |

## Common operations

### Checking message status

```php theme={null}
$message = $client->messages->retrieve('your-message-id');
echo $message->status;
echo $message->delivered;
```

### Managing user profiles

```php theme={null}
$client->profiles->create('user_123', profile: [
    'email' => 'sarah@acme-corp.com',
    'phone_number' => '+15551234567',
    'name' => 'Sarah Bennett',
]);

$profile = $client->profiles->retrieve('user_123');
```

### Issuing JWT tokens

Courier's [client-side SDKs
DOC](/docs/sdk-libraries/sdks-overview) (React, JavaScript, mobile) authenticate users with a JWT your backend issues. [Authenticate users
DOC](/docs/in-app/authenticate-users) covers the token flow, the scope strings, and token refresh. Use `$client->auth->issueToken`:

```php theme={null}
$result = $client->auth->issueToken(
  scope: 'user_id:user_123 inbox:read:messages inbox:write:events',
  expiresIn: '2 days',
);

echo $result->token;
```

| Scope | Permission |
| - | - |
| `user_id:<id>` | Which user the token is for (required) |
| `inbox:read:messages` | Read inbox messages |
| `inbox:write:events` | Mark messages as read/archived |
| `read:preferences` | Read notification preferences |
| `write:preferences` | Update notification preferences |
| `write:user-tokens` | Register push notification tokens |

## Configuration

### Error handling

The SDK throws typed exceptions for API failures. All extend `Courier\Core\Exceptions\APIException`:

```php theme={null}
use Courier\Core\Exceptions\APIConnectionException;
use Courier\Core\Exceptions\RateLimitException;
use Courier\Core\Exceptions\APIStatusException;

try {
  $client->send->message(message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ]);
} catch (APIConnectionException $e) {
  echo "The server could not be reached\n";
} catch (RateLimitException $e) {
  echo "Rate limited; back off a bit.\n";
} catch (APIStatusException $e) {
  echo "API error: " . $e->getMessage() . "\n";
}
```

### Retries

The SDK retries failed requests up to 2 times with exponential backoff.

```php theme={null}
// Disable retries
$client = new Client(requestOptions: ['maxRetries' => 0]);

// Or per-request
$client->send->message(
  message: ['to' => ['user_id' => 'user_123'], 'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40'],
  requestOptions: ['maxRetries' => 5],
);
```

## Journeys

[Journeys
DOC](/docs/journeys/overview) are multi-step workflows: send, delay, branch, throttle, digest, and more. Invoke one by ID or alias to start a run. Cancel runs by ID, or by a shared cancelation token.

```php theme={null}
// Start a run (by journey ID or alias); the response includes runID
$response = $client->journeys->invoke(
  templateID: 'your-journey-id',
  userID: 'user_123',
  data: ['order_id' => 'A-1042'],
);
echo $response->runID;
```

> [!NOTE]
>
> `cancel` takes exactly one of `run_id` or `cancelation_token` (spelled with one "l"). Build and manage journeys from code with `create`, `list`, `publish`, and `archive`. See [Build journeys via API
> DOC](/docs/journeys/build).

## More operations

A few more resources from the full [Courier REST API
DOC](/docs/reference/api-overview):

| Resource | Method | Use case |
| - | - | - |
| User preferences | `$client->users->preferences->retrieve($userId)` | Fetch a user's notification preferences for your [preference center&#xA;DOC](/docs/recipients/preferences/overview) |
| Cancel a message | `$client->messages->cancel($messageId)` | Cancel a delayed or queued message before delivery |
| Push tokens | `$client->users->tokens->addSingle($token, userID: $userId, providerKey: 'firebase-fcm')` | Register a device push token for [iOS&#xA;DOC](/docs/sdk-libraries/ios), [Android&#xA;DOC](/docs/sdk-libraries/android), [React Native&#xA;DOC](/docs/sdk-libraries/react-native), or [Flutter&#xA;DOC](/docs/sdk-libraries/flutter) |

> **[API Reference](/docs/reference/api-overview)**
>
> Full REST API docs with request/response examples.

> **[Send API](/docs/send/overview)**
>
> Learn about the Send endpoint, routing, and message options.

> **[Quickstart](/docs/get-started/send-a-message)**
>
> Send your first notification in under two minutes.

> **[GitHub](https://github.com/trycourier/courier-php)**
>
> Source code, issues, and changelog.

## Idempotent sends

Pass an idempotency key and Courier replays the first response for that key instead of sending again. The SDK sets the `Idempotency-Key` header for you. [Idempotency
DOC](/docs/reference/api-overview#idempotency) covers the scoping rule and the replay window.

```php theme={null}
$response = $client->send->message(
  message: ['to' => ['user_id' => 'user_123'], 'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40'],
  idempotencyKey: '6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91',
);
```


# Courier Python SDK
Source: https://www.courier.com/docs/sdk-libraries/python

Typed access to the Courier API from Python with sync and async clients.

The Courier Python SDK gives you typed access to the [Courier REST API
DOC](/docs/reference/api-overview).

It includes sync and async clients, Pydantic response models, and TypedDict request params.

Available on
[ GitHub](https://github.com/trycourier/courier-python)
and [ PyPI](https://pypi.org/project/trycourier/).

## Installation

```bash pip theme={null}
pip install trycourier
```

```bash poetry theme={null}
poetry add trycourier
```

```bash pipenv theme={null}
pipenv install trycourier
```

Requires Python 3.9+.

## Quick start

```python theme={null}
from courier import Courier

client = Courier()

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"name": "Sarah Bennett"},
    },
)

print(response.request_id)
```

> [!TIP]
>
> The client reads `COURIER_API_KEY` from your environment automatically. You can also pass it explicitly: `Courier(api_key='YOUR_COURIER_API_KEY')`.

## Authentication

Get your API key from [Settings > API Keys](https://app.courier.com/settings/api-keys) in the Courier dashboard. Set it as an environment variable:

```bash theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
```

The SDK picks this up by default. To pass it explicitly:

```python theme={null}
client = Courier(api_key="YOUR_COURIER_API_KEY")
```

> [!NOTE]
>
> Use a `.env` file with [python-dotenv](https://pypi.org/project/python-dotenv/) to keep your API key out of source control.

## Sending notifications

### With a template

Design your notification in [Design Studio
DOC](/docs/design/templates/design-studio), then reference it by ID:

```python theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"order_id": "10042", "item_name": "Courier Hoodie"},
    },
)
```

### To multiple recipients

Send to a list of users in a single call:

```python theme={null}
response = client.send.message(
    message={
        "to": [
            {"user_id": "user_123"},
            {"user_id": "user_123"},
            {"email": "sarah@acme-corp.com"},
        ],
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

## Async usage

### Basic async client

Import `AsyncCourier` instead of `Courier` and use `await`:

```python theme={null}
import asyncio
from courier import AsyncCourier

client = AsyncCourier()

async def main():
    response = await client.send.message(
        message={
            "to": {"user_id": "user_123"},
            "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
            "data": {"name": "Sarah Bennett"},
        },
    )
    print(response.request_id)

asyncio.run(main())
```

The async client has the same API as the sync client. Every method returns an awaitable.

### Using aiohttp instead of httpx

For better concurrency, swap the HTTP backend to `aiohttp`:

```bash theme={null}
pip install trycourier[aiohttp]
```

```python theme={null}
import asyncio
from courier import AsyncCourier, DefaultAioHttpClient

async def main():
    async with AsyncCourier(http_client=DefaultAioHttpClient()) as client:
        response = await client.send.message(
            message={
                "to": {"user_id": "user_123"},
                "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
            },
        )
        print(response.request_id)

asyncio.run(main())
```

## Available resources

The SDK covers the full Courier API. Every method is typed and documented with docstrings.

| Resource | Namespace | Description |
| - | - | - |
| Send | `client.send` | Send messages to one or more recipients |
| Messages | `client.messages` | Retrieve status, history, and content of sent messages |
| Profiles | `client.profiles` | Create, update, and retrieve user profiles |
| Users | `client.users` | Manage preferences, tenants, and push tokens per user |
| Auth | `client.auth` | Issue JWT tokens for client-side SDK authentication |
| Lists | `client.lists` | Manage subscription lists and their subscribers |
| Audiences | `client.audiences` | Define and query audience segments |
| Tenants | `client.tenants` | Manage tenants for multi-tenant setups |
| Journeys | `client.journeys` | Invoke and cancel runs. Create, list, publish, and archive [journeys&#xA;DOC](/docs/journeys/overview) |
| Brands | `client.brands` | Manage brand settings (logos, colors, templates) |
| Notifications | `client.notifications` | List and inspect notification templates |
| Translations | `client.translations` | Workspace `.po` strings for the `{{t}}` helper |

## Common operations

### Checking message status

After sending, use the `request_id` to check delivery status or get the full event timeline:

```python theme={null}
message = client.messages.retrieve("your-message-id")
print(message.status)    # e.g. 'DELIVERED'
print(message.delivered)  # delivery timestamp (ms)

history = client.messages.history("your-message-id")
for event in history.results:
    print(event["type"], event["event"])
```

List recent messages with optional filters:

```python theme={null}
recent = client.messages.list(status=["DELIVERED"])
```

### Managing user profiles

Profiles store recipient data (email, phone, custom fields) that Courier uses for delivery. You need a profile before you can send to a `user_id`.

```python theme={null}
# Create or merge into a profile
client.profiles.create("user_123", profile={
    "email": "sarah@acme-corp.com",
    "phone_number": "+15551234567",
    "name": "Sarah Bennett",
})

# Retrieve a profile
profile = client.profiles.retrieve("user_123")
print(profile.profile["email"])

# Partial update (merge)
client.profiles.update("user_123", patch=[{"op": "replace", "path": "/name", "value": "Jane Smith"}])
```

> [!NOTE]
>
> `create` merges with any existing profile. Use `replace` for a full overwrite (any fields not included will be removed).

### Issuing JWT tokens

Courier's [client-side SDKs
DOC](/docs/sdk-libraries/sdks-overview) (React, JavaScript, mobile) authenticate users with a JWT your backend issues. [Authenticate users
DOC](/docs/in-app/authenticate-users) covers the token flow, the scope strings, and token refresh. Use `auth.issue_token`:

```python theme={null}
result = client.auth.issue_token(
    scope="user_id:user_123 inbox:read:messages inbox:write:events read:preferences write:preferences",
    expires_in="2 days",
)

# Return result.token to your frontend
print(result.token)
```

The `scope` string controls what the token can access. Common scopes:

| Scope | Permission |
| - | - |
| `user_id:<id>` | Which user the token is for (required) |
| `inbox:read:messages` | Read inbox messages |
| `inbox:write:events` | Mark messages as read/archived |
| `read:preferences` | Read notification preferences |
| `write:preferences` | Update notification preferences |
| `write:user-tokens` | Register push notification tokens |

## Type safety

Request parameters are TypedDicts, and responses are Pydantic models. You get autocomplete and inline docs in your editor.

```python theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"foo": "bar"},
    },
)

# Response is a Pydantic model
print(response.request_id)
print(response.to_dict())
print(response.to_json())
```

> [!TIP]
>
> For VS Code type checking, set `python.analysis.typeCheckingMode` to `basic` in your settings.

## Configuration

### Error handling

The SDK throws typed errors for API failures. All errors extend `courier.APIError`:

```python theme={null}
import courier
from courier import Courier

client = Courier()

try:
    client.send.message(
        message={
            "to": {"user_id": "user_123"},
            "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        },
    )
except courier.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)
except courier.RateLimitError as e:
    print("Rate limited; back off a bit.")
except courier.APIStatusError as e:
    print(f"API error: {e.status_code}")
    print(e.response)
```

| Status Code | Error Type |
| - | - |
| 400 | `BadRequestError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 422 | `UnprocessableEntityError` |
| 429 | `RateLimitError` |
| >=500 | `InternalServerError` |
| N/A | `APIConnectionError` |

### Retries

The SDK retries failed requests up to 2 times with exponential backoff. Retried errors include connection failures, timeouts, 408, 409, 429, and 5xx responses.

Only network errors are retried. Any other exception raised while a request is in flight reaches your code unchanged. That includes a Celery or RQ time limit that fires while the SDK waits for Courier, so your task's cleanup runs and the SDK doesn't send the request again.

A retry after a timeout can still repeat a send that Courier already received. To stop a retried send from going out twice, pass an [idempotency key](#idempotent-sends).

```python theme={null}
# Disable retries
client = Courier(max_retries=0)

# Override per-request
client.with_options(max_retries=5).send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

### Timeouts

Requests time out after 60 seconds by default. Configure globally or per-request:

```python theme={null}
import httpx
from courier import Courier

# Simple timeout
client = Courier(timeout=20.0)  # 20 seconds

# Granular control
client = Courier(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# Override per-request
client.with_options(timeout=5.0).send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
```

A timeout raises `APITimeoutError`. Timed-out requests are retried by default.

### Logging

Enable debug logging with the `COURIER_LOG` environment variable:

```bash theme={null}
export COURIER_LOG=info   # or 'debug' for full request/response logging
```

The SDK uses Python's standard `logging` module, so it works with your existing setup.

### Raw response access

Access HTTP headers or stream the response body:

```python theme={null}
from courier import Courier

client = Courier()

# Get headers + parsed data
response = client.send.with_raw_response.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
print(response.headers.get("x-request-id"))
send_result = response.parse()

# Stream the response
with client.send.with_streaming_response.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
) as response:
    for line in response.iter_lines():
        print(line)
```

### Custom HTTP client

Override the default [httpx client](https://www.python-httpx.org/api/#client) for proxies or custom transports:

```python theme={null}
import httpx
from courier import Courier, DefaultHttpxClient

client = Courier(
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)
```

## Journeys

[Journeys
DOC](/docs/journeys/overview) are multi-step workflows (send, delay, branch, throttle, digest, and more). Invoke one by ID or alias to start a run, then cancel runs by ID or a shared cancelation token.

```python theme={null}
# Start a run (by journey ID or alias); the response includes run_id
response = client.journeys.invoke(
    "your-journey-id",
    user_id="user_123",
    data={"order_id": "A-1042"},
)

# Cancel one run, or every run sharing a cancelation token
client.journeys.cancel(run_id=response.run_id)
# client.journeys.cancel(cancelation_token="order-A-1042")
```

> [!NOTE]
>
> `cancel` takes exactly one of `run_id` or `cancelation_token` (spelled with one "l"). You can also build and manage journeys from code with `client.journeys.create`, `list`, `publish`, and `archive`. See [Build journeys via API
> DOC](/docs/journeys/build).

## More operations

A few more resources from the full [Courier REST API
DOC](/docs/reference/api-overview):

| Resource | Method | Use case |
| - | - | - |
| User preferences | `client.users.preferences.retrieve(user_id)` | Fetch a user's notification preferences for your [preference center&#xA;DOC](/docs/recipients/preferences/overview) |
| Cancel a message | `client.messages.cancel(message_id)` | Cancel a delayed or queued message before delivery (returns 409 if already delivered) |
| Push tokens | `client.users.tokens.add_single(token, user_id=user_id, provider_key="firebase-fcm")` | Register a device push token for [iOS&#xA;DOC](/docs/sdk-libraries/ios), [Android&#xA;DOC](/docs/sdk-libraries/android), [React Native&#xA;DOC](/docs/sdk-libraries/react-native), or [Flutter&#xA;DOC](/docs/sdk-libraries/flutter) |

> **[API Reference](/docs/reference/api-overview)**
>
> Full REST API docs with request/response examples.

> **[Send API](/docs/send/overview)**
>
> Learn about the Send endpoint, routing, and message options.

> **[Quickstart](/docs/get-started/send-a-message)**
>
> Send your first notification in under two minutes.

> **[GitHub](https://github.com/trycourier/courier-python)**
>
> Source code, issues, and changelog.

## Idempotent sends

Pass an idempotency key and Courier replays the first response for that key instead of sending again. The SDK sets the `Idempotency-Key` header for you. [Idempotency
DOC](/docs/reference/api-overview#idempotency) covers the scoping rule and the replay window.

```python theme={null}
response = client.send.message(
    message={"to": {"user_id": "user_123"}, "template": "nt_01kx4h2jdafq8bk9aftxak4b40"},
    idempotency_key="6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
)
```


# Courier React Native SDK
Source: https://www.courier.com/docs/sdk-libraries/react-native

Prebuilt inbox and preferences UI, push token sync, and TypeScript APIs for React Native.

The Courier React Native SDK gives you prebuilt components and TypeScript APIs. It handles authentication, token management, and real-time delivery on iOS and Android.

This page is the React Native reference: what to install, how to configure both native projects, and the TypeScript API surface. Each flow is written once and applies to every platform.

| To do this | Read |
| :- | :- |
| Render the inbox | [Add an inbox&#xA;DOC](/docs/in-app/add-an-inbox?lang=React%20Native) |
| Theme it, handle taps, or build your own UI | [Customize the inbox&#xA;DOC](/docs/in-app/customize-the-inbox?lang=React%20Native) |
| Set up push, from provider to device | [Set up push notifications&#xA;GUIDE](/docs/guides/set-up-mobile-push) |
| Add the preference center | [Add a preference center&#xA;DOC](/docs/in-app/add-a-preference-center?lang=React%20Native) |
| Mint the JWT you sign in with | [Authenticate users&#xA;DOC](/docs/in-app/authenticate-users?lang=React%20Native) |

Available on
[ GitHub](https://github.com/trycourier/courier-react-native)
and [ npm](https://www.npmjs.com/package/@trycourier/courier-react-native).

| Requirement | Value |
| - | - |
| Min iOS version | 15.0 |
| Min Android SDK | 23 |
| Gradle | 8.4+ |

## Installation

```bash npm theme={null}
npm install @trycourier/courier-react-native
```

```bash yarn theme={null}
yarn add @trycourier/courier-react-native
```

### iOS setup

**1. Set iOS deployment target to 15.0+**

Update your Podfile:

```ruby theme={null}
platform :ios, '15.0'
```

**2. Install CocoaPods**

```bash theme={null}
cd ios && pod install
```

**3. Forward the APNs callbacks**

In your Swift `AppDelegate`, hold a `CourierDelegate` and forward the registration callbacks to it. This is what syncs the token.

```swift theme={null}
private let courierDelegate = CourierDelegate()

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    courierDelegate.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    courierDelegate.application(application, didFailToRegisterForRemoteNotificationsWithError: error)
}
```

An older app with an Objective-C `AppDelegate` inherits from `CourierReactNativeDelegate` instead. On Expo, see [Expo](#expo) below.

```objective-c theme={null}
#import <courier-react-native/CourierReactNativeDelegate.h>

@interface AppDelegate : CourierReactNativeDelegate
@end
```

### Android setup

**1. Add the Jitpack repository**

In your `android/build.gradle`:

```gradle theme={null}
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://www.jitpack.io' }
    }
}
```

**2. Set minimum SDK version**

In your `android/build.gradle`:

```gradle theme={null}
ext {
    minSdkVersion = 23
    compileSdkVersion = 33
    targetSdkVersion = 33
}
```

**3. Extend CourierReactNativeActivity**

Update your `MainActivity` to extend `CourierReactNativeActivity`. This lets the SDK manage user state across app sessions.

```kotlin Kotlin theme={null}
import com.courierreactnative.CourierReactNativeActivity

class MainActivity : CourierReactNativeActivity() {
    // ...
}
```

```java Java theme={null}
import com.courierreactnative.CourierReactNativeActivity;

public class MainActivity extends CourierReactNativeActivity {
    // ...
}
```

**4. Use a Material theme**

The prebuilt inbox and preference center only render correctly when your app theme extends `Theme.MaterialComponents`. Set it in `res/values/styles.xml`.

## Authentication

Courier authenticates with a **JWT** that your backend mints with your Courier API key, never in client code. [Authenticate users
DOC](/docs/in-app/authenticate-users?lang=React%20Native) covers the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See [EU setup
DOC](/docs/in-app/authenticate-users?lang=React%20Native#connect-to-the-eu-datacenter).

Credentials persist across app sessions, so you sign in once per user rather than on every launch.

```typescript theme={null}
import Courier from "@trycourier/courier-react-native";

await Courier.shared.signIn({ userId: "your_user_id", accessToken: jwt });
await Courier.shared.signOut();
```

## Inbox

[Add an inbox
DOC](/docs/in-app/add-an-inbox?lang=React%20Native) is the setup flow. These are the types it uses on React Native.

| Type | What it is |
| :- | :- |
| `CourierInboxView` | The prebuilt inbox component |
| `lightTheme` / `darkTheme` | Theme props, each split into `iOS` and `android` styles |
| `addInboxListener` | Raw message data and events, for a UI you render yourself |

Every callback and action these expose is documented per platform in [Data and actions
DOC](/docs/in-app/build-a-custom-inbox?lang=React%20Native#data-and-actions).

### Inbox theme

The theme is a prop, and the two platforms take separate style objects. Fonts resolve differently on each: a family name on iOS, an asset path on Android.

```typescript theme={null}
<CourierInboxView
  lightTheme={{
    iOS: {
      unreadIndicatorStyle: { indicator: "dot", color: "#9747FF" },
      titleStyle: { unread: { font: { family: "Avenir", size: 18 } } },
      // ... additional iOS styles
    },
    android: {
      unreadIndicatorStyle: { indicator: "dot", color: "#9747FF" },
      titleStyle: { unread: { font: { family: "fonts/poppins.otf", size: 18 } } },
      // ... additional Android styles
    },
  }}
/>
```

![Default Inbox on iOS](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/ios-inbox-default.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=5905813f276b28f4c8697809caa5657d)

![Default Inbox on Android](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/android-inbox-default.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=817cf39df7f5c01b47a61a6d267257fb)

Default Inbox on iOS and Android

![Styled Inbox on iOS](https://mintcdn.com/courier-4f1f25dc/9rcgucLA9fBnJt_U/assets/ios-inbox-styled.webp?fit=max\&auto=format\&n=9rcgucLA9fBnJt_U\&q=85\&s=b9964741c06b9e61a53232592f5e2034)

![Styled Inbox on Android](https://mintcdn.com/courier-4f1f25dc/A-IH_41Pkuff3UAy/assets/android-inbox-styled.webp?fit=max\&auto=format\&n=A-IH_41Pkuff3UAy\&q=85\&s=3c22892996909ce834922f4b4434f391)

Styled Inbox on iOS and Android

Branding from [Courier Studio](https://app.courier.com/designer/brands) also applies. The SDK reads primary color and footer visibility from your brand settings.

## Push notifications

[Set up push notifications
GUIDE](/docs/guides/set-up-mobile-push) is the setup flow, from connecting APNs and FCM to a device that receives push. It covers the native wiring above, `setTokenForProvider`, permission, and reading the payload on tap.

> [!NOTE]
>
> Push notifications require a physical device. Simulators and emulators don't reliably support push token registration or notification delivery.

| Feature | iOS | Android |
| - | - | - |
| Automatic token management | Yes | Yes |
| Notification tracking | Yes | Yes |
| Permission requests | Yes | Yes |

Two things live only here. On Android, forward both `FirebaseMessagingService` callbacks to `Courier.Companion.onMessageReceived` and `Courier.Companion.onNewToken`. On iOS, add a [Notification Service Extension
DOC](/docs/sdk-libraries/ios#notification-service-extension) to track delivery while your app is closed.

### Expo

Expo manages `AppDelegate` (iOS) and `MainActivity` (Android) itself, so the subclassing above doesn't apply. Follow the [Expo setup guide on GitHub](https://github.com/trycourier/courier-react-native/blob/master/Docs/6_Expo.md), which wires Courier into `ExpoAppDelegate`.

## Preferences

[Add a preference center
DOC](/docs/in-app/add-a-preference-center?lang=React%20Native) is the setup flow. These are the types it uses on React Native.

| Type | What it is |
| :- | :- |
| `CourierPreferencesView` | The prebuilt preference center component |
| `mode` | `{ type: "topic" }` or `{ type: "channels", channels: [...] }` |
| `lightTheme` / `darkTheme` | Theme props, each split into `iOS` and `android` styles |

> [!NOTE]
>
> Topics and sections are configured in the [Preferences Editor
> GUIDE](/docs/guides/build-a-preference-center#configure-the-topics). See [Preferences Overview
> DOC](/docs/recipients/preferences/overview) for how preference enforcement works at send time.

### Preferences theme

The theme takes platform-specific style objects, the same shape as the inbox theme above. [Courier Studio branding](https://app.courier.com/designer/brands) applies automatically when you supply a `brandId`.

<video aria-label="Default Preferences on iOS" />

<video aria-label="Default Preferences on Android" />

Default Preferences on iOS and Android

<video aria-label="Styled Preferences on iOS" />

<video aria-label="Styled Preferences on Android" />

Styled Preferences on iOS and Android

## CourierClient

For advanced use cases, `CourierClient` is a low-level wrapper around the Courier API. Each client holds its own credentials, so you can spin up as many as you need.

### Initialization

```typescript theme={null}
import { CourierClient, getCourierApiUrlsForRegion } from "@trycourier/courier-react-native";

const client = new CourierClient({
    jwt:          "...",          // Optional. Required for most authenticated calls
    userId:       "your_user_id",
    connectionId: "...",          // Optional. Used for the inbox websocket
    tenantId:     "...",          // Optional. Scopes the client to a tenant
    apiUrls:      getCourierApiUrlsForRegion("eu"), // Optional. Use for EU users
    showLogs:     true            // Optional. Defaults to your build configuration
});

const options = client.options;

// Tear the client down when you no longer need it
client.remove();
```

### Token management

```typescript theme={null}
const device = {
    appId:        "APP_ID",
    adId:         "AD_ID",
    deviceId:     "DEVICE_ID",
    platform:     "ios",
    manufacturer: "Apple",
    model:        "iPhone 15"
};

await client.tokens.putUserToken({
    token: "...",
    provider: "firebase-fcm",
    device // Optional
});

await client.tokens.deleteUserToken({ token: "..." });
```

### Inbox

```typescript theme={null}
const messages = await client.inbox.getMessages({
    paginationLimit: 25,
    startCursor: undefined
});

const archived = await client.inbox.getArchivedMessages({
    paginationLimit: 25,
    startCursor: undefined
});

const unreadCount = await client.inbox.getUnreadMessageCount();

await client.inbox.open({ messageId: "..." });
await client.inbox.read({ messageId: "..." });
await client.inbox.unread({ messageId: "..." });
await client.inbox.archive({ messageId: "..." });
await client.inbox.readAll();
```

### Preferences

```typescript theme={null}
const prefs = await client.preferences.getUserPreferences({
    paginationCursor: undefined
});

const topic = await client.preferences.getUserPreferenceTopic({
    topicId: "..."
});

await client.preferences.putUserPreferenceTopic({
    topicId: "...",
    status: CourierUserPreferencesStatus.OptedIn,
    hasCustomRouting: true,
    customRouting: [CourierUserPreferencesChannel.Push]
});
```

### Branding

```typescript theme={null}
const brand = await client.brands.getBrand({ brandId: "..." });
```

### URL tracking

Pass any tracking URL found inside a push notification payload or inbox message:

```typescript theme={null}
// Available events: Clicked, Delivered, Opened, Read, Unread
await client.tracking.postTrackingUrl({
    url: "courier_tracking_url",
    event: CourierTrackingEvent.Delivered
});
```

See the full Courier API reference at [courier.com/docs/reference
DOC](/docs/reference/api-overview).


# Courier Ruby SDK
Source: https://www.courier.com/docs/sdk-libraries/ruby

Typed access to the Courier API from Ruby 3.2+, with Sorbet definitions.

The Courier Ruby SDK gives typed access to the [Courier REST API
DOC](/docs/reference/api-overview) from any Ruby 3.2+ application.

It ships with Yard docstrings, RBS and RBI type definitions for Sorbet, and uses `net/http` with connection pooling.

Available on
[ GitHub](https://github.com/trycourier/courier-ruby)
and [ RubyGems](https://rubygems.org/gems/trycourier).

## Installation

Add to your `Gemfile`:

```ruby theme={null}
gem "trycourier"
```

Then run `bundle install`. Requires Ruby 3.2+. See [RubyGems](https://rubygems.org/gems/trycourier) for the latest version.

## Quick start

```ruby theme={null}
require "bundler/setup"
require "courier"

client = Courier::Client.new

response = client.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" }
  }
)

puts response.request_id
```

> [!TIP]
>
> The client reads `COURIER_API_KEY` from your environment. Pass it explicitly: `Courier::Client.new(api_key: "YOUR_COURIER_API_KEY")`.

> [!NOTE]
>
> The method is `send_` (with a trailing underscore) because `send` is a reserved method in Ruby.

## Authentication

Get your API key from [Settings > API Keys](https://app.courier.com/settings/api-keys) in the Courier dashboard. Set it as an environment variable:

```bash theme={null}
export COURIER_API_KEY="YOUR_COURIER_API_KEY"
```

The SDK reads it by default. To pass the key explicitly:

```ruby theme={null}
client = Courier::Client.new(api_key: "YOUR_COURIER_API_KEY")
```

## Sending notifications

Design your notification in [Design Studio
DOC](/docs/design/templates/design-studio), then reference it by ID:

```ruby theme={null}
response = client.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { order_id: "10042", item_name: "Courier Hoodie" }
  }
)
```

## Available resources

The SDK covers the full Courier API. Every method carries Yard docstrings.

| Resource | Namespace | Description |
| - | - | - |
| Send | `client.send_` | Send messages to one or more recipients |
| Messages | `client.messages` | Retrieve status, history, and content of sent messages |
| Profiles | `client.profiles` | Create, update, and retrieve user profiles |
| Users | `client.users` | Manage preferences, tenants, and push tokens per user |
| Auth | `client.auth` | Issue JWT tokens for client-side SDK authentication |
| Lists | `client.lists` | Manage subscription lists and their subscribers |
| Audiences | `client.audiences` | Define and query audience segments |
| Tenants | `client.tenants` | Manage tenants for multi-tenant setups |
| Journeys | `client.journeys` | Invoke and cancel runs. Create, list, publish, and archive [journeys&#xA;DOC](/docs/journeys/overview) |
| Brands | `client.brands` | Manage brand settings (logos, colors, templates) |
| Notifications | `client.notifications` | List and inspect notification templates |
| Translations | `client.translations` | Workspace `.po` strings for the `{{t}}` helper |

## Common operations

### Checking message status

```ruby theme={null}
message = client.messages.retrieve("your-message-id")
puts message.status
puts message.delivered

history = client.messages.history("your-message-id")
```

### Managing user profiles

```ruby theme={null}
client.profiles.create("user_123", profile: {
  email: "sarah@acme-corp.com",
  phone_number: "+15551234567",
  name: "Sarah Bennett"
})

profile = client.profiles.retrieve("user_123")
```

### Issuing JWT tokens

Courier's [client-side SDKs
DOC](/docs/sdk-libraries/sdks-overview) (React, JavaScript, mobile) authenticate users with a JWT your backend issues. [Authenticate users
DOC](/docs/in-app/authenticate-users) covers the token flow, the scope strings, and token refresh. Use `client.auth.issue_token`:

```ruby theme={null}
result = client.auth.issue_token(
  scope: "user_id:user_123 inbox:read:messages inbox:write:events",
  expires_in: "2 days"
)

puts result.token
```

| Scope | Permission |
| - | - |
| `user_id:<id>` | Which user the token is for (required) |
| `inbox:read:messages` | Read inbox messages |
| `inbox:write:events` | Mark messages as read/archived |
| `read:preferences` | Read notification preferences |
| `write:preferences` | Update notification preferences |
| `write:user-tokens` | Register push notification tokens |

## Configuration

### Error handling

The SDK throws typed errors for API failures. All errors extend `Courier::Errors::APIError`:

```ruby theme={null}
begin
  client.send_.message(message: { to: { user_id: "user_123" }, template: "nt_01kx4h2jdafq8bk9aftxak4b40" })
rescue Courier::Errors::APIConnectionError => e
  puts "The server could not be reached"
rescue Courier::Errors::RateLimitError => e
  puts "Rate limited; back off a bit."
rescue Courier::Errors::APIStatusError => e
  puts "API error: #{e.status}"
end
```

### Retries

The SDK retries failed requests up to 2 times with exponential backoff.

```ruby theme={null}
client = Courier::Client.new(max_retries: 0)

# Or per-request
client.send_.message(
  message: { to: { user_id: "user_123" }, template: "nt_01kx4h2jdafq8bk9aftxak4b40" },
  request_options: { max_retries: 5 }
)
```

### Timeouts

Requests time out after 60 seconds by default. Configure globally or per-request:

```ruby theme={null}
client = Courier::Client.new(timeout: 20)

client.send_.message(
  message: { to: { user_id: "user_123" }, template: "nt_01kx4h2jdafq8bk9aftxak4b40" },
  request_options: { timeout: 5 }
)
```

## Journeys

[Journeys
DOC](/docs/journeys/overview) are multi-step workflows: send, delay, branch, throttle, digest, and more. Invoke one by ID or alias to start a run. Cancel runs by ID, or by a shared cancelation token.

```ruby theme={null}
# Start a run (by journey ID or alias); the response includes run_id
response = client.journeys.invoke(
  "your-journey-id",
  user_id: "user_123",
  data: { order_id: "A-1042" }
)

# Cancel one run, or every run sharing a cancelation token
client.journeys.cancel(cancel_journey_request: { run_id: response.run_id })
# client.journeys.cancel(cancel_journey_request: { cancelation_token: "order-A-1042" })
```

> [!NOTE]
>
> `cancel` takes exactly one of `run_id` or `cancelation_token` (spelled with one "l"). Build and manage journeys from code with create, list, publish, and archive. See [Build journeys via API
> DOC](/docs/journeys/build).

## More operations

A few more resources from the full [Courier REST API
DOC](/docs/reference/api-overview):

| Resource | Method | Use case |
| - | - | - |
| User preferences | `client.users.preferences.retrieve(user_id)` | Fetch a user's notification preferences for your [preference center&#xA;DOC](/docs/recipients/preferences/overview) |
| Cancel a message | `client.messages.cancel(message_id)` | Cancel a delayed or queued message before delivery |
| Push tokens | `client.users.tokens.add_single(token, user_id:, provider_key: :"firebase-fcm")` | Register a device push token for [iOS&#xA;DOC](/docs/sdk-libraries/ios), [Android&#xA;DOC](/docs/sdk-libraries/android), [React Native&#xA;DOC](/docs/sdk-libraries/react-native), or [Flutter&#xA;DOC](/docs/sdk-libraries/flutter) |

> **[API Reference](/docs/reference/api-overview)**
>
> Full REST API docs with request/response examples.

> **[Send API](/docs/send/overview)**
>
> Learn about the Send endpoint, routing, and message options.

> **[Quickstart](/docs/get-started/send-a-message)**
>
> Send your first notification in under two minutes.

> **[GitHub](https://github.com/trycourier/courier-ruby)**
>
> Source code, issues, and changelog.

## Idempotent sends

Pass an idempotency key and Courier replays the first response for that key instead of sending again. The SDK sets the `Idempotency-Key` header for you. [Idempotency
DOC](/docs/reference/api-overview#idempotency) covers the scoping rule and the replay window.

```ruby theme={null}
response = courier.send_.message(
  message: { to: { user_id: "user_123" }, template: "nt_01kx4h2jdafq8bk9aftxak4b40" },
  idempotency_key: "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91"
)
```


# Courier SDKs
Source: https://www.courier.com/docs/sdk-libraries/sdks-overview

Server SDKs that wrap the REST API and client SDKs that render in-app UI, for every platform.

Server SDKs wrap the [REST API
DOC](/docs/reference/api-overview). Client SDKs render in-app UI.

## Server

Send notifications, manage Profiles and Lists, and configure Templates from your backend. Each authenticates with a workspace API key from [Settings → API Keys](https://app.courier.com/settings/api-keys), scoped to one [environment
DOC](/docs/workspaces/environments).

> **[Node.js](/docs/sdk-libraries/node)**

> **[Python](/docs/sdk-libraries/python)**

> **[Ruby](/docs/sdk-libraries/ruby)**

> **[Go](/docs/sdk-libraries/go)**

> **[Java](/docs/sdk-libraries/java)**

> **[PHP](/docs/sdk-libraries/php)**

> **[C# / .NET](/docs/sdk-libraries/csharp)**

## Client

Build the Inbox, Toasts, and Preferences into your app. [In-App
DOC](/docs/in-app/overview) holds those flows, and [Set up push notifications
GUIDE](/docs/guides/set-up-mobile-push) holds mobile push. Each SDK page is the reference for its platform.

> **[React](/docs/sdk-libraries/courier-react-web)**

> **[Vue](/docs/sdk-libraries/courier-vue-web)**

> **[Angular](/docs/sdk-libraries/courier-angular-web)**

> **[Web Components](/docs/sdk-libraries/courier-web-components)**

> **[JavaScript](/docs/sdk-libraries/courier-js-web)**

> **[React Native](/docs/sdk-libraries/react-native)**

> **[iOS](/docs/sdk-libraries/ios)**

> **[Android](/docs/sdk-libraries/android)**

> **[Flutter](/docs/sdk-libraries/flutter)**

Upgrading from React v7? See the [migration guide
DOC](/docs/sdk-libraries/courier-react-v8-migration-guide).


# Delay and schedule a send
Source: https://www.courier.com/docs/send/delay-and-schedule

Delay a send by a duration, until a timestamp, or into a delivery window in the user's timezone.

The `delay` object holds a message for later. Choose a duration, an exact timestamp, or a recurring window in the recipient's timezone.

## Pick a delay

Add `delay` to the message on any send. Courier holds the message until the time you set, then sends it. Each option is one field:

| To | Set | Example |
| :- | :- | :- |
| Wait a fixed amount of time | `delay.duration`, in milliseconds | `3600000` (one hour) |
| Schedule for a specific time | `delay.until`, as an ISO 8601 timestamp | `2026-01-01T09:00:00-05:00` |
| Send inside a recurring window | `delay.until`, as opening hours | `Mo-Fr 09:00-17:00` |

Set one option per send. If a send has both, `delay.duration` wins. A delay can run up to 31 days. A window is the only option that uses the recipient's timezone, so one send can reach each person at 9 AM their time.

## Delay a send

**1. Delay by a duration**

Set `delay.duration` in milliseconds to hold the message that long from now. Courier sends after exactly that interval (3600000 ms is one hour).

```javascript Node.js highlight={5} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    delay: { duration: 3600000 },
  },
});
```

```python Python highlight={5} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "delay": {"duration": 3600000},
    },
)
```

```bash cURL highlight={8} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "delay": { "duration": 3600000 }
    }
  }'
```

```ruby Ruby highlight={5} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    delay: { duration: 3600000 }
  }
)
```

```go Go highlight={10} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Delay: courier.SendMessageParamsMessageDelay{
			Duration: courier.Int(3600000),
		},
	},
})
```

```java Java highlight={5} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .delay(JsonValue.from(java.util.Map.of("duration", 3600000)))
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={5} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'delay' => ['duration' => 3600000],
  ],
);
```

```csharp C# highlight={7} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Delay = new() { Duration = 3600000 },
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","delay":{"duration":3600000}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 in one hour.
```

**2. Schedule for a specific time**

Set `delay.until` to an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp to send at an exact moment. A date alone (`2026-01-01`) is midnight UTC. Include a time and offset for precision (`2026-01-01T09:00:00-05:00`).

```javascript Node.js highlight={5} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    delay: { until: '2026-01-01T09:00:00Z' },
  },
});
```

```python Python highlight={5} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "delay": {"until": "2026-01-01T09:00:00Z"},
    },
)
```

```bash cURL highlight={8} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "delay": { "until": "2026-01-01T09:00:00Z" }
    }
  }'
```

```ruby Ruby highlight={5} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    delay: { until: "2026-01-01T09:00:00Z" }
  }
)
```

```go Go highlight={10} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Delay: courier.SendMessageParamsMessageDelay{
			Until: courier.String("2026-01-01T09:00:00Z"),
		},
	},
})
```

```java Java highlight={5} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .delay(JsonValue.from(java.util.Map.of("until", "2026-01-01T09:00:00Z")))
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={5} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'delay' => ['until' => '2026-01-01T09:00:00Z'],
  ],
);
```

```csharp C# highlight={7} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Delay = new() { Until = "2026-01-01T09:00:00Z" },
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","delay":{"until":"2026-01-01T09:00:00Z"}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on January 1 at 9am UTC.
```

**3. Send within a delivery window**

Set `delay.until` to a recurring window (opening-hours syntax) and Courier holds the message until the next time inside it. This is how you deliver during business hours or at a good local time.

It is also how you enforce **quiet hours**, because a window is the inverse of a do-not-disturb period. A 9am to 9pm window in the recipient's timezone says "never between 9pm and 9am". A message arriving outside it waits rather than waking anyone.

```javascript Node.js highlight={9} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
      timezone: "America/New_York",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    delay: {
      until: "Mo-Fr 09:00-17:00",
    },
  },
});
```

```python Python highlight={9} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
            "timezone": "America/New_York",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "delay": {
            "until": "Mo-Fr 09:00-17:00",
        },
    },
)
```

```bash cURL highlight={12} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123",
        "timezone": "America/New_York"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "delay": {
        "until": "Mo-Fr 09:00-17:00"
      }
    }
  }'
```

```ruby Ruby highlight={9} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123",
      timezone: "America/New_York"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    delay: {
      until: "Mo-Fr 09:00-17:00"
    }
  }
)
```

```go Go highlight={12} theme={null}
// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "user_id": "user_123",
  "timezone": "America/New_York"
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		// delay: {"until": "Mo-Fr 09:00-17:00"}
	},
})
```

```java Java highlight={10} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .userId("user_123")
            .putAdditionalProperty("timezone", JsonValue.from("America/New_York"))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .delay(JsonValue.from(java.util.Map.of("until", "Mo-Fr 09:00-17:00")))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
      'timezone' => 'America/New_York',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'delay' => [
      'until' => 'Mo-Fr 09:00-17:00',
    ],
  ],
);
```

```csharp C# highlight={18} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "user_id": "user_123",
                  "timezone": "America/New_York"
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Delay = new() { Until = "Mo-Fr 09:00-17:00" },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123", "timezone": "America/New_York"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.delay '{"until": "Mo-Fr 09:00-17:00"}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 during business hours in their timezone.
```

Courier resolves the timezone in this order: `delay.timezone` (highest), then `to.timezone` or the profile's `zoneinfo`, then the profile's `timezone`, then UTC. Send an array of recipients with different timezones and each one's window is computed independently, so a single call delivers at 9 AM local for everyone. Windows accept patterns like `Mo-Fr 09:00-17:00`, `Sa-Su 00:00-23:59`, and split schedules (`Mo-Fr 09:00-12:00,14:00-18:00`).

> [!NOTE]
>
> **`delay.timezone` only applies to a window.**\\
>
> For an ISO `until` timestamp, the timezone is already in the timestamp. `delay.timezone` matters only when `until` is an opening-hours expression.

**4. Check the logs**

Send with a `delay`, then open the message in [Logs](https://app.courier.com/logs). A `Request Delayed` event shows the computed delivery time.


# Channel settings and overrides
Source: https://www.courier.com/docs/send/overrides

Set a template's email fields and channel conditions, and change channel or provider payloads on a single send.

Channel settings control how each channel behaves within a template, and send-time overrides let you adjust a single message.

## How overrides work

An override changes part of a message at send time, without editing the template. Courier applies it just before handing the message to the provider, so it works with template-based sends and with any [Elemental
DOC](/docs/design/elemental/overview) content the template renders.

There are two levels:

| Level | Where you set it | Applies to |
| :- | :- | :- |
| **Channel override** | `message.channels.<channel>.override` | Every provider configured for that channel |
| **Provider override** | `message.providers.<key>.override` | One provider, passing fields from that provider's own API |

Use both on the same send if you need to. When the two set the same field, **the provider override wins**.

> [!NOTE]
>
> Courier applies overrides **after** the render step. The Rendered tab in the logs won't show them, only the pre-override output. To see the final payload, look at the provider request in the Raw tab.

The fields each channel accepts live with that channel: [email
DOC](/docs/integrations/email/overview#channel-overrides), [SMS
DOC](/docs/integrations/sms/overview#channel-overrides), [push
DOC](/docs/integrations/push/overview#channel-overrides), and [chat
DOC](/docs/integrations/direct-message/overview#channel-overrides). Each provider page documents its own provider-specific schema.

## Prerequisites

* A template with more than one channel
* A connected provider for each of those channels

## Configure channels

**1. Set email address fields**

Email channels carry sender and recipient fields you set in the channel settings, with variables allowed for dynamic values:

* **From**: `"Sarah Bennett <notify@acme-corp.com>"`. The `Name <email>` form carries the display name, and it is the only way to set one when a provider's integration has no From Name field.
* **Reply-To**: where replies go.
* **CC / BCC**: additional recipients, often driven by a variable.

The sender resolves at three levels, and the first one set wins:

1. `message.channels.email.override.from` on the send, for one message.
2. The **From** field here, for every send of this template.
3. **From Address** on the provider integration, for every email through that provider.

With none of the three set, the send fails at the provider rather than falling back to a Courier address. [Send from your own domain
GUIDE](/docs/guides/send-from-your-domain) walks the whole setup.

> [!NOTE]
>
> Gmail is the exception. It always sends as the authorized inbox, so a **From** value here has no effect on it. Set the display name with the integration's From Name instead.

**2. Add per-channel conditions**

A channel condition skips only that channel, while the rest of the notification still delivers (a template condition, by contrast, stops the whole send). Set them in the channel's **Conditions** tab, or over the API with `message.channels.<channel>.if`, where each value is an expression evaluated against `data` and `profile`:

```javascript Node.js highlight={9} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    channels: {
      sms: {
        if: "data.priority === 'high'",
      },
    },
  },
});
```

```python Python highlight={9} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "channels": {
            "sms": {
                "if": "data.priority === 'high'",
            },
        },
    },
)
```

```bash cURL highlight={12} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "channels": {
        "sms": {
          "if": "data.priority === '\''high'\''"
        }
      }
    }
  }'
```

```ruby Ruby highlight={9} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    channels: {
      sms: {
        if: "data.priority === 'high'"
      }
    }
  }
)
```

```go Go highlight={10} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Channels: shared.MessageChannelsParam{
			"sms": shared.ChannelParam{If: courier.String("data.priority === 'high'")},
		},
	},
})
```

```java Java highlight={7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .channels(MessageChannels.builder()
            .putAdditionalProperty("sms", JsonValue.from(
                java.util.Map.of("if", "data.priority === 'high'")))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'channels' => [
      'sms' => [
        'if' => 'data.priority === \'high\'',
      ],
    ],
  ],
);
```

```csharp C# highlight={9} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Channels = new Dictionary<string, Channel>
        {
            { "sms", new Channel { If = "data.priority === 'high'" } },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.channels '{"sms": {"if": "data.priority === '\''high'\''"}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 and only use SMS when the priority is high.
```

> [!NOTE]
>
> Setting `routing` on a send drops the template's default routing conditions, so include any channel conditions you want in `message.channels`.

User preferences take precedence over channel conditions. When a user sets custom channel routing, conditions run only within their selected channels.

**3. Override a provider at send time**

Adjust how a specific provider sends this one message with `providers.<provider>.override`, without changing the template. For example, filter push tokens or set a provider-specific field:

```javascript Node.js highlight={17-18} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "all",
      channels: [
        "push",
      ],
    },
    providers: {
      "firebase-fcm": {
        override: {
          config: {
            filterByBundleId: true,
            bundleId: "com.acme.app",
          },
        },
      },
    },
  },
});
```

```python Python highlight={17-18} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "all",
            "channels": [
                "push",
            ],
        },
        "providers": {
            "firebase-fcm": {
                "override": {
                    "config": {
                        "filterByBundleId": True,
                        "bundleId": "com.acme.app",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={20-21} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "all",
        "channels": [
          "push"
        ]
      },
      "providers": {
        "firebase-fcm": {
          "override": {
            "config": {
              "filterByBundleId": true,
              "bundleId": "com.acme.app"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={17-18} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "all",
      channels: [
        "push"
      ]
    },
    providers: {
      "firebase-fcm": {
        override: {
          config: {
            filterByBundleId: true,
            bundleId: "com.acme.app"
          }
        }
      }
    }
  }
)
```

```go Go highlight={19-20} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
			},
			Method: "all",
		},
		Providers: shared.MessageProvidersParam{
			"firebase-fcm": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"filterByBundleId": true,
						"bundleId": "com.acme.app",
					},
				},
			},
		},
	},
})
```

```java Java highlight={12-13} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("push")
            .method(SendMessageParams.Message.Routing.Method.ALL)
            .build())
        .providers(MessageProviders.builder()
            .putAdditionalProperty("firebase-fcm", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "filterByBundleId", true,
                        "bundleId", "com.acme.app"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={17-18} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'all',
      'channels' => [
        'push',
      ],
    ],
    'providers' => [
      'firebase-fcm' => [
        'override' => [
          'config' => [
            'filterByBundleId' => true,
            'bundleId' => 'com.acme.app',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={18-19} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["push"], Method = Send::Method.All },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "firebase-fcm",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "filterByBundleId": true,
                            "bundleId": "com.acme.app"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "all", "channels": ["push"]}' \
  --message.providers '{"firebase-fcm": {"override": {"config": {"filterByBundleId": true, "bundleId": "com.acme.app"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with a provider-specific override.
```

See [Push providers
DOC](/docs/integrations/push/overview#channel-overrides) for the push override fields, and each [provider integration
DOC](/docs/integrations/overview) for its override options.

**4. Check the logs**

Send with your settings and open the message in [Logs](https://app.courier.com/logs). Confirm the channels that sent, and that each channel condition behaved as expected.


# Send a message
Source: https://www.courier.com/docs/send/overview

Send a message with one API call, and choose between a template, a broadcast, or a journey.

A send is one API call. Name who it goes to and what it says. Courier renders it, applies preferences, routes, and delivers.

```javascript Node.js theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { name: 'Sarah Bennett' },
  },
});
```

```python Python theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"name": "Sarah Bennett"},
    },
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "name": "Sarah Bennett" }
    }
  }'
```

```ruby Ruby theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" }
  }
)
```

```go Go theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("name", "Sarah Bennett")))
        .build())
    .build();
client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['name' => 'Sarah Bennett'],
  ],
);
```

```csharp C# theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
    },
};

await client.Send.Message(parameters);
```

```bash CLI theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"name":"Sarah Bennett"}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with their name.
```

The response returns a `requestId`, not a delivery result. Find it in [Logs](https://app.courier.com/logs) to confirm the message rendered and delivered.

## Prerequisites

* [A Courier API key](https://app.courier.com/settings/api-keys), and [the SDK for your language
  DOC](/docs/sdk-libraries/sdks-overview) or curl
* [A template
  DOC](/docs/design/templates/overview), for the `nt_` id in the call above
* [A saved user
  DOC](/docs/recipients/overview), or their contact details inline in `to`
* [A connected provider
  DOC](/docs/integrations/overview) for the channel it goes out on. Test email and the [inbox
  DOC](/docs/in-app/overview) need none.

## Three ways to send

All three send the same content: a [template
DOC](/docs/design/templates/overview) you design once. What differs is what starts the send.

### 1. Templates

**Use a template when your application triggers the send.** A receipt, a password reset, an alert. Your app calls the API with a recipient and a template, like the example above. The template holds what the message says on every channel, plus its routing and brand settings. Your app supplies `data`, and the template's [variables
DOC](/docs/design/templates/variables) render each recipient's own version.

That split keeps a send small. Content changes ship by publishing the template, with no deploy.

> **[Design a Template](/docs/design/templates/overview)**
>
> Build it in the visual editor, or manage it as JSON over the Templates API.

### 2. Broadcasts

**Use a broadcast when you choose the moment.** One message to a whole [list or audience
DOC](/docs/recipients/lists-and-audiences/overview), sent now or on a schedule. You pick the group, and Courier fans it out.

> **[Send a Broadcast](/docs/broadcasts/overview)**
>
> Reach a saved list or audience in one send.

### 3. Journeys

**Use a journey when the send happens later, or depends on what the user does.** A multi-step flow that runs per user, with delays, branching, and enrichment between steps. A user event or an API call starts it, and the journey decides what comes next.

> **[Build a Journey](/docs/journeys/overview)**
>
> Lay out steps, delays, and branches in the visual builder.

| | Templates | Broadcasts | Journeys |
| - | - | - | - |
| Shape | One message | One message to a group | Multi-step flow, per user |
| Started by | Your API call | You, now or scheduled | A user event or API call |
| Timing | Immediate, or a delay | Now or scheduled | Delays and waits between steps |
| Logic | In your code | None | Built-in branching |
| Best for | Transactional messages | Newsletters, announcements | Onboarding, digests, re-engagement |

## How it works

Every send is one `message` object posted to [Send a message](/docs/api-reference/send/send-a-message), whichever SDK you call it from. It has four parts:

```json theme={null}
{
  "message": {
    "to": { ... },
    "template": "...",
    "data": { ... },
    "routing": { ... }
  }
}
```

| Part | What it does | Example |
| - | - | - |
| `to` | Who gets it: a `user_id` for a stored [profile&#xA;DOC](/docs/recipients/overview), or contact details inline | `{ "user_id": "user_123" }` |
| `template` | What it says: a [template&#xA;DOC](/docs/design/templates/overview) by its `nt_` ID, or an [alias&#xA;DOC](/docs/design/templates/overview#send-it-by-id-or-alias) you assign | `"nt_01kx4h2jdafq8bk9aftxak4b40"` |
| `data` | The [variables&#xA;DOC](/docs/design/templates/variables) it fills in | `{ "name": "Sarah Bennett" }` |
| `routing` | Where it goes. Leave it out and the template's own [routing&#xA;DOC](/docs/send/routing) applies | `{ "method": "single" }` |

Pass an array in `to` to reach several recipients, or contact details inline for a one-off: `{ "email": "sarah@acme-corp.com" }`.

A message with no reusable design can carry its `content` inline instead of a `template`. That content is [Elemental
DOC](/docs/design/elemental/overview), the same format a template renders.

Courier enforces each recipient's [preferences
DOC](/docs/recipients/preferences/overview) at send time. Opt-outs and channel choices apply without extra logic in your code.

### The pipeline

```mermaid theme={null}
flowchart LR
    A["Your app"] --> B["Courier API"]
    B --> C["Provider"]
    C --> D["Your user"]
```

Courier records every step, so you can follow a message from request to delivery in [message logs
DOC](/docs/monitor/overview). Transient provider errors retry, and an unavailable provider or channel fails over to the next one.

### Idempotency

Send an `Idempotency-Key` header to make a retry safe. A repeated request with the same key returns the original response instead of sending again. A retry after a network failure can't duplicate the send.

> [!TIP]
>
> Add `routing` to pin the channels for this request, or `channels` and `providers` to adjust delivery settings. See [channel settings & overrides
> DOC](/docs/send/overrides) and [how routing & failover work
> DOC](/docs/send/routing).

## FAQ

> **Can I send to multiple users at once?**
>
> Pass an array of recipients in `to`, or send to a [list or audience
> DOC](/docs/recipients/lists-and-audiences/overview). For a large group, a list or audience send fans out for you (see [Send to lists & audiences
> GUIDE](/docs/guides/announce-to-a-list)).

> **Does the API tell me if delivery succeeded?**
>
> The API returns a `requestId`, not a delivery result, since the send runs asynchronously. Check delivery in [message logs
> DOC](/docs/monitor/overview) or receive a `message:updated` [webhook
> DOC](/docs/monitor/webhooks/outbound).

> **How do I prevent duplicate sends?**
>
> Send an `Idempotency-Key` header. A second request with the same key returns the original result without sending again.


# Push payloads
Source: https://www.courier.com/docs/send/push/custom-data

Attach custom data to a push and read it on iOS, Android, React Native, and Flutter.

A push carries more than a title and body. The `data` object rides alongside the alert, and your app reads it on arrival or tap.

Put your fields in a `data` object on the message. One `data` object covers FCM, APNs, and Expo, so you describe the payload once.

Send your push template with a `data` object using [Send a message](/docs/api-reference/send/send-a-message):

```javascript Node.js highlight={6-10} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    routing: { method: 'all', channels: ['push'] },
    data: {
      order_id: 'ord_4821',
      screen: 'order-detail',
      carrier: 'UPS',
    },
  },
});
```

```python Python highlight={6-10} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {"method": "all", "channels": ["push"]},
        "data": {
            "order_id": "ord_4821",
            "screen": "order-detail",
            "carrier": "UPS",
        },
    },
)
```

```bash cURL highlight={9-13} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": { "method": "all", "channels": ["push"] },
      "data": {
        "order_id": "ord_4821",
        "screen": "order-detail",
        "carrier": "UPS"
      }
    }
  }'
```

```ruby Ruby highlight={6-10} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "all", channels: ["push"] },
    data: {
      order_id: "ord_4821",
      screen: "order-detail",
      carrier: "UPS"
    }
  }
)
```

```go Go highlight={11-15} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodAll),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("push")}},
		},
		Data: map[string]any{
			"order_id": "ord_4821",
			"screen":  "order-detail",
			"carrier": "UPS",
		},
	},
})
```

```java Java highlight={8-11} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(JsonValue.from(java.util.Map.of(
            "method", "all",
            "channels", java.util.List.of("push"))))
        .data(JsonValue.from(java.util.Map.of(
            "order_id", "ord_4821",
            "screen", "order-detail",
            "carrier", "UPS")))
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={6-10} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => ['method' => 'all', 'channels' => ['push']],
    'data' => [
      'order_id' => 'ord_4821',
      'screen' => 'order-detail',
      'carrier' => 'UPS',
    ],
  ],
);
```

```csharp C# highlight={8-13} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new Routing { Method = Method.All, Channels = ["push"] },
        Data = new Dictionary<string, JsonElement>()
        {
            { "order_id", JsonSerializer.SerializeToElement("ord_4821") },
            { "screen", JsonSerializer.SerializeToElement("order-detail") },
            { "carrier", JsonSerializer.SerializeToElement("UPS") },
        },
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","routing":{"method":"all","channels":["push"]},"data":{"order_id":"ord_4821","screen":"order-detail","carrier":"UPS"}}'
```

```text MCP theme={null}
With Courier MCP, send the order-shipped push to user_123 with the order id and deep link in the data.
```

> [!NOTE]
>
> **Older templates need a route for `data`.**\\
>
> New templates map `data` into the FCM and APNs payload by default, and a send with inline `content` needs no mapping at all. Having trouble getting your fields through on an older template? [Data mapping
> DOC](/docs/design/templates/data-mapping) covers it. Expo forwards `data` either way.

Courier adds one key of its own to the same object, `trackingUrl`, for delivery and click tracking. Treat that name as reserved.

## How the data arrives per provider

Each provider has its own payload rules, so the same `data` object lands in a different shape.

| Provider | Where it lands | Nested values | Override key |
| :- | :- | :- | :- |
| [FCM&#xA;DOC](/docs/integrations/push/firebase-fcm) | The `data` block of the FCM message | Flattened to strings. An object or array becomes a JSON string. | `override.body.data` |
| [APNs&#xA;DOC](/docs/integrations/push/apple-push-notification) | The top level of the APNs payload, next to `aps` | Preserved as real JSON. | `override.body.payload` |
| [Expo&#xA;DOC](/docs/integrations/push/expo) | The `data` field of the Expo push message | Preserved as real JSON. | `override` (merged at the top level) |

**FCM flattens everything to strings.** FCM only accepts string values in `data`, so Courier converts anything else with `JSON.stringify`. Send `{ "nested": { "carrier": "UPS" } }` and the device receives `nested` as the string `{"carrier":"UPS"}`, which your app has to parse. Numbers arrive as strings too: `badgeCount: 3` arrives as `"3"`.

**Expo forwards `data` on every send.** The Expo handler copies the request's `data` straight into the payload, so it arrives with no data mapping.

### The same send, side by side

Sending this `data` object, with the template's push channel mapping it through:

```json theme={null}
{
  "order_id": "ord_4821",
  "screen": "order-detail",
  "badgeCount": 3,
  "isPriority": true,
  "nested": {
    "carrier": "UPS",
    "eta": "2026-07-30"
  },
  "tags": ["shipped", "priority"]
}
```

produces two different payloads on the device:

```json APNs theme={null}
{
  "aps": {
    "alert": { "title": "Order #4821 shipped", "body": "Arriving Thursday." },
    "sound": "ping.aiff",
    "mutable-content": 1
  },
  "order_id": "ord_4821",
  "screen": "order-detail",
  "badgeCount": 3,
  "isPriority": true,
  "nested": { "carrier": "UPS", "eta": "2026-07-30" },
  "tags": ["shipped", "priority"],
  "trackingUrl": "https://<tenant>.ct0.app/t/<token>"
}
```

```json FCM theme={null}
{
  "title": "Order #4821 shipped",
  "body": "Arriving Thursday.",
  "order_id": "ord_4821",
  "screen": "order-detail",
  "badgeCount": "3",
  "isPriority": "true",
  "nested": "{\"carrier\":\"UPS\",\"eta\":\"2026-07-30\"}",
  "tags": "[\"shipped\",\"priority\"]",
  "trackingUrl": "https://<tenant>.ct0.app/t/<token>",
  "gcm.message_id": "1785281856917263",
  "google.c.sender.id": "313914309026"
}
```

On APNs your keys are siblings of `aps` and keep their JSON types. On FCM they live in the `data` block and are all strings.

Both payloads reflect Courier's **default** provider settings, tuned for the mobile SDKs:

* **FCM: Apply Recommended Courier Mobile SDK Formatting** (`remapData`), on by default. It ships the message as `data` instead of `notification`, which improves delivery and lets you style the notification yourself. It also attaches an APNs override so iOS delivery tracking stays accurate. That is why `title` and `body` appear in the `data` block above. Turn it off and they arrive in a separate `notification` block.
* **APNs: Attach Mutable Content** (`mutableContent`), on by default. It adds `"mutable-content": 1`, which lets a [Notification Service Extension
  DOC](/docs/sdk-libraries/ios#notification-service-extension) see the message before it reaches the user and record the delivery. Turn it off and messages still arrive, but delivery metrics get less accurate.

An iOS device receiving through FCM also gets the `aps` block and the `google.c.*` keys shown above. An Android device doesn't.

> [!TIP]
>
> Flat, already-stringified `data` values avoid parsing on Android. One level of string keys and string values behaves identically on FCM, APNs, and Expo.

## Read the data on the device

The Courier mobile SDKs hand you the full payload on delivery and on tap. Read your keys from it and route.

```swift iOS theme={null}
class AppDelegate: CourierDelegate {

    override func pushNotificationDeliveredInForeground(
        message: [AnyHashable: Any]
    ) -> UNNotificationPresentationOptions {
        let order_id = message["order_id"] as? String
        print("Delivered for order: \(order_id ?? "none")")
        return [.sound, .list, .banner, .badge]
    }

    override func pushNotificationClicked(message: [AnyHashable: Any]) {
        if let screen = message["screen"] as? String {
            router.navigate(to: screen)
        }
    }
}
```

```kotlin Android theme={null}
class MainActivity : CourierActivity() {

    // The payload is a Map<String, String>: every FCM data value is a string
    override fun onPushNotificationClicked(pushNotification: Map<String, String>) {
        val screen = pushNotification["screen"]
        val order_id = pushNotification["order_id"]

        // A nested object arrives as a JSON string, so parse it
        val carrier = pushNotification["nested"]?.let { JSONObject(it).getString("carrier") }

        screen?.let { router.navigate(it) }
    }

    override fun onPushNotificationDelivered(pushNotification: Map<String, String>) {
        Log.d("Courier", "Delivered: $pushNotification")
    }
}
```

```dart Flutter theme={null}
Courier.shared.addPushListener(
  onPushClicked: (push) {
    final screen = push['screen'];
    if (screen != null) {
      router.navigate(screen);
    }
  },
  onPushDelivered: (push) {
    debugPrint('Delivered: $push');
  },
);
```

```typescript React Native theme={null}
Courier.shared.addPushNotificationListener({
  onPushNotificationClicked: (push) => {
    if (push.screen) {
      router.navigate(push.screen);
    }
  },
  onPushNotificationDelivered: (push) => {
    console.log("Delivered:", push);
  },
});
```

On iOS and Android the handler is a method on a class you already own, so it lives as long as
your app does. Flutter and React Native return a listener instead, and it holds a reference
until you drop it. Call `remove()` on teardown, such as inside Flutter's `dispose()`.

## Deep-link on tap

Send the destination under your own key in `data`, then read it in your tap handler and route. The example at the top of this page uses `screen`. Any URL works there: a custom scheme like `acme://orders/ord_4821`, or a universal link like `https://acme.com/orders/ord_4821`.

Universal links are set up on the platform, not in Courier. Courier carries the string, and the operating system decides whether it opens your app:

* [Apple's Universal Links guide](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content)
* [Android's App Links guide](https://developer.android.com/training/app-links)
* [Expo's deep linking guide](https://docs.expo.dev/linking/into-your-app/)

The tap handler is the one in [Read the data on the device](#read-the-data-on-the-device) above.

## Send data with no visible alert

A silent push shows the user nothing. Use it to move the app icon badge, or to wake your app in the background and sync.

`providers.apn.override.silent` keeps the alert off the payload, so nothing appears on the lock screen. Pair it with `badge` and APNs moves the number itself, with no code running in your app:

```javascript Node.js highlight={10,12} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      apn: {
        override: {
          silent: true,
          body: {
            badge: 3,
          },
        },
      },
    },
  },
});
```

```python Python highlight={10,12} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "apn": {
                "override": {
                    "silent": True,
                    "body": {
                        "badge": 3,
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={13,15} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "providers": {
        "apn": {
          "override": {
            "silent": true,
            "body": {
              "badge": 3
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={10,12} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      apn: {
        override: {
          silent: true,
          body: {
            badge: 3
          }
        }
      }
    }
  }
)
```

```go Go highlight={12,14} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"apn": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"silent": true,
					"body": map[string]any{
						"badge": 3,
					},
				},
			},
		},
	},
})
```

```java Java highlight={7-8} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("apn", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "silent", true,
                    "body", java.util.Map.of("badge", 3)
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={10,12} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'providers' => [
      'apn' => [
        'override' => [
          'silent' => true,
          'body' => [
            'badge' => 3,
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={16,18} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "apn",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "silent": true,
                          "body": {
                            "badge": 3
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"apn": {"override": {"silent": true, "body": {"badge": 3}}}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 as a silent iOS push that sets the badge to 3.
```

To wake your app in the background as well, add `"content-available": 1` to the same `body`. iOS then launches your app to handle the payload, which is what you want for syncing content before the user opens it. A badge on its own doesn't need it.

On FCM, the message already ships as data with no `notification` block, because **Apply Recommended Courier Mobile SDK Formatting** (`remapData`) is on by default. Courier moves `title`, `body`, and `image` into the `data` block alongside your own keys. Your app reads all of it as data and decides what to display.

If that setting is off on your integration, switch it back on for a single send:

```javascript Node.js highlight={11} theme={null}
const { requestId } = await client.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "firebase-fcm": {
        override: {
          config: {
            remapData: true,
          },
        },
      },
    },
  },
});
```

```python Python highlight={11} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "firebase-fcm": {
                "override": {
                    "config": {
                        "remapData": True,
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={14} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "providers": {
        "firebase-fcm": {
          "override": {
            "config": {
              "remapData": true
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={11} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "firebase-fcm": {
        override: {
          config: {
            remapData: true
          }
        }
      }
    }
  }
)
```

```go Go highlight={13} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"firebase-fcm": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"remapData": true,
					},
				},
			},
		},
	},
})
```

```java Java highlight={7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("firebase-fcm", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of("remapData", true)
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={11} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'providers' => [
      'firebase-fcm' => [
        'override' => [
          'config' => [
            'remapData' => true,
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={17} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "firebase-fcm",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "remapData": true
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"firebase-fcm": {"override": {"config": {"remapData": true}}}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with FCM data remapping turned on for this send.
```

Your app needs background delivery configured either way: **Background Modes → Remote notifications** on iOS, and a `FirebaseMessagingService` that handles `onMessageReceived` on Android.

## Verify the payload

**1. Send to a real device**

Send the request above to a `user_id` with a registered token. Simulators don't receive push.

**2. Confirm the payload on the device**

Log the full message in your delivery or tap handler and check your keys are present. On Android, every value is a string.

**3. Check the log if a key is missing**

Open [Logs](https://app.courier.com/logs) and open the message. The provider request shows the exact payload Courier sent, including the `data` block. Fields missing there were dropped by the send, not the device. The usual cause is a template send with no data mapping.

## FAQ

> **Why is my data missing from the push payload?**
>
> Check the template's age. New templates map `data` through by default, but one created before that default uses `data` for variable substitution only. [Data mapping
> DOC](/docs/design/templates/data-mapping) shows how to turn it on, or set the fields in a [provider override
> DOC](/docs/send/overrides#how-overrides-work). Expo forwards `data` either way.

> **Why did my number arrive as a string on Android?**
>
> FCM only permits string values in its `data` block, so Courier stringifies everything else. `3` becomes `"3"` and `{ "a": "b" }` becomes `"{\"a\":\"b\"}"`. Parse on the device, or send flat strings to begin with.

> **Can I send different data to iOS and Android?**
>
> Send the shared fields in the top-level `data` object, then add per-platform fields in each provider's override (`firebase-fcm` under `override.body.data`, `apn` under `override.body.payload`).

> **Is there a size limit on the data payload?**
>
> The provider sets it, not Courier. APNs allows 4KB for a normal push, and FCM allows 4KB for the data block. The provider rejects anything over the limit and the message goes `UNDELIVERABLE`. Send IDs and let the app fetch the rest.

> **Which provider keys does Courier use for push?**
>
> `firebase-fcm`, `apn`, `expo`, `onesignal`, and `pusher-beams`. Use these keys to register a token and to override a provider on a send.


# Push notifications
Source: https://www.courier.com/docs/send/push/overview

How device tokens are stored on the user, synced by the SDK, and used to send push.

A push reaches a device through a token, and that token belongs to a signed-in user.

The Courier mobile SDKs register and refresh those tokens for you. How much they do depends on the native hook you wired up, so it is per provider, not per platform.

| Provider | Key | iOS | Android |
| :- | :- | :- | :- |
| APNs | `apn` | Automatic via `CourierDelegate` | Not applicable |
| Firebase Cloud Messaging | `firebase-fcm` | Manual | Automatic via `FirebaseMessagingService` |
| Expo | `expo` | Manual | Manual |
| OneSignal | `onesignal` | Manual | Manual |
| Pusher Beams | `pusher-beams` | Manual | Manual |

Anything marked Manual you register yourself, and the rest of this page is how.

## Hand the SDK a token

`setToken` is for a provider the SDK can't fetch from, one marked Manual in the table above. You supply the string, and everything after that is still the SDK's job.

**It writes to the same place the API does.** `setToken` calls [Add a token to a user](/docs/api-reference/device-tokens/add-a-token-to-a-user) against the signed-in user, with the device record attached, so tokens from the SDK and the API live in the same place.

It first deletes whichever token it last cached for that provider, so a device doesn't leave stale rows behind. That delete is best effort, and a failure is logged rather than thrown.

Call it before anyone signs in and the token is only held on the device. `signIn` writes every held token to that user, and `signOut` deletes them again, so a shared device stops receiving the previous user's pushes.

> [!NOTE]
>
> The device rotates its token on reinstall, on restore, and when app data is cleared. Call `setToken` again from that provider's own refresh callback, or the stale one fails at the provider rather than in your code.

```swift iOS theme={null}
Task {
    // APNs token
    try await Courier.shared.setAPNSToken(deviceToken)

    // FCM or another provider
    try await Courier.shared.setToken(for: .firebaseFcm, token: fcmToken)
}
```

```kotlin Android theme={null}
lifecycleScope.launch {
    Courier.shared.setToken(
        provider = "firebase-fcm",
        token = "your_messaging_token"
    )
}
```

```dart Flutter theme={null}
await Courier.shared.setTokenForProvider(
  token: fcmToken,
  provider: CourierPushProvider.firebaseFcm,
);

await Courier.shared.setToken(token: 'token_value', provider: 'YOUR_PROVIDER');
```

```typescript React Native theme={null}
import { CourierPushProvider } from "@trycourier/courier-react-native";

await Courier.shared.setTokenForProvider({
    provider: CourierPushProvider.FIREBASE_FCM,
    token: "your_messaging_token"
});

await Courier.shared.setToken({ key: "your-provider-key", token: "your_messaging_token" });
```

## Manage tokens yourself

`setToken` still leaves the lifecycle to the SDK. To do the CRUD yourself, address the same user through one of two APIs.

From a backend, or an app with no Courier SDK, use the Token Management API:

* Store one with [Add a token to a user](/docs/api-reference/device-tokens/add-a-token-to-a-user)
* Read what a user has with [List tokens](/docs/api-reference/device-tokens/list-tokens)
* Remove one on logout with [Delete user token](/docs/api-reference/device-tokens/delete-user-token)

Calling all three is then your job, on every device. Nothing cleans up on sign-out, and nothing re-registers a rotated token.

From inside the app, without signing anyone in, construct a `CourierClient` and go through its token client. It reaches the same two endpoints, authenticating with the JWT the way `signIn` does, and it writes nothing to `Courier.shared`.

```swift iOS theme={null}
let client = CourierClient(jwt: jwt, userId: "user_123")

try await client.tokens.putUserToken(
    token: fcmToken,
    provider: "firebase-fcm"
)

try await client.tokens.deleteUserToken(token: fcmToken)
```

```kotlin Android theme={null}
val client = CourierClient(jwt = jwt, userId = "user_123")

client.tokens.putUserToken(
    token = fcmToken,
    provider = "firebase-fcm",
    device = CourierDevice.current(context)
)

client.tokens.deleteUserToken(token = fcmToken)
```

```dart Flutter theme={null}
final client = CourierClient(jwt: jwt, userId: 'user_123');

await client.tokens.putUserToken(
  token: fcmToken,
  provider: 'firebase-fcm',
);

await client.tokens.deleteUserToken(token: fcmToken);
```

```typescript React Native theme={null}
const client = new CourierClient({ userId: "user_123", jwt: jwt });

await client.tokens.putUserToken({
  token: fcmToken,
  provider: "firebase-fcm",
});

await client.tokens.deleteUserToken({ token: fcmToken });
```

> [!NOTE]
>
> The client covers writing and deleting only. Listing a user's tokens is REST, so [List tokens](/docs/api-reference/device-tokens/list-tokens) has no client equivalent. On Android `device` is required, and `CourierDevice.current(context)` fills it.

## Read the tokens the SDK is holding

Useful when a push doesn't arrive and you need to confirm the device actually registered.

```swift iOS theme={null}
let apns = await Courier.shared.apnsToken            // Data?
let fcm = await Courier.shared.getToken(for: .firebaseFcm)
let all = await Courier.shared.tokens                // [String: String]
```

```kotlin Android theme={null}
val fcm = Courier.shared.fcmToken

// Force Firebase to hand the SDK a fresh token
lifecycleScope.launch {
    Courier.shared.refreshFcmToken()
    val token = Courier.shared.getToken(provider = "your-provider-key")
}
```

```dart Flutter theme={null}
final fcm = await Courier.shared.getTokenForProvider(
  provider: CourierPushProvider.firebaseFcm,
);
final other = await Courier.shared.getToken(provider: 'YOUR_PROVIDER');
```

```typescript React Native theme={null}
const forKey = await Courier.shared.getToken({ key: "your-provider-key" });
const forProvider = await Courier.shared.getTokenForProvider({
  provider: CourierPushProvider.EXPO,
});
const all = await Courier.shared.getAllTokens();
```

## Notification permissions

Each SDK wraps the platform permission calls, so you prompt, read the status, and recover from a denial without touching the native APIs.

| Function | Does |
| :- | :- |
| `requestNotificationPermission` | Shows the system dialog. The setup steps above call this once. |
| `getNotificationPermissionStatus` | Reads the status without prompting. Android calls it `isPushPermissionGranted`. |
| `openSettingsForApp` | Opens your app's settings page, the only route back after a denial. |

```swift iOS theme={null}
// Prompts once, then returns the resulting UNAuthorizationStatus
let status = try await Courier.requestNotificationPermission()

// Reads the status without prompting
let current = try await Courier.getNotificationPermissionStatus()

// Send the user here after they deny the dialog
Courier.openSettingsForApp()
```

```kotlin Android theme={null}
// Prompts on Android 13 and later, a no-op below API 33
Courier.shared.requestNotificationPermission(activity)

// Reads the status without prompting
val isGranted = Courier.shared.isPushPermissionGranted(context)
```

```dart Flutter theme={null}
final status = await Courier.requestNotificationPermission();

final current = await Courier.getNotificationPermissionStatus();

await Courier.openSettingsApp();
```

```typescript React Native theme={null}
const status = await Courier.requestNotificationPermission();

const current = await Courier.getNotificationPermissionStatus();

Courier.openSettingsForApp();
```

The system dialog appears once. After that only the user can change the setting, so read the status on launch and offer your own prompt into settings when it is denied.

> [!NOTE]
>
> Android has no `openSettingsForApp`, and Flutter names it `openSettingsApp`. iOS returns a `UNAuthorizationStatus`, Flutter and React Native return a string, and Android's check returns a `Boolean`.

## Control how iOS presents a foreground push

By default iOS suppresses the system banner while your app is open. Set the presentation options to change that.

```swift iOS theme={null}
// Returned from your CourierDelegate override
override func pushNotificationDeliveredInForeground(
    message: [AnyHashable: Any]
) -> UNNotificationPresentationOptions {
    return [.sound, .list, .banner, .badge]
}
```

```dart Flutter theme={null}
Courier.setIOSForegroundPresentationOptions(options: [
  iOSNotificationPresentationOption.banner,
  iOSNotificationPresentationOption.sound,
  iOSNotificationPresentationOption.list,
  iOSNotificationPresentationOption.badge,
]);
```

```typescript React Native theme={null}
Courier.setIOSForegroundPresentationOptions({
  options: ["sound", "badge", "list", "banner"],
});
```


# Message routing and failover
Source: https://www.courier.com/docs/send/routing

How Courier picks the channels and providers for each message, falls back when one can't deliver, and where you set routing: a strategy or the send.

Routing decides which channels a message goes out on and which provider delivers each one. When an option can't deliver, Courier moves to the next, so a user without a push token still gets the email.

## Two decisions: channel, then provider

Courier routes every message in two steps. It picks channels from the routing object's `channels` list, then picks providers inside each channel in priority order. Each step has its own method:

| Decision | Set with | `single` | `all` |
| :- | :- | :- | :- |
| Which channels | `routing.method` | Tries channels in order and stops at the first that delivers | Sends on every channel in the list |
| Which providers | The channel's `routing_method` | Tries providers in order and stops at the first that delivers (the default) | Sends through every provider on the channel |

Failover happens at both levels. Under `single`, everything after the first option is its backup.

## Where routing is set

Most templates carry their routing in a routing strategy: a saved set of channels, fallback order, and providers, attached to the template by ID. Build one in Design Studio or with the API, and every template that uses it picks up your edits on its next send. See [Routing strategies
DOC](/docs/send/routing-strategies).

To change routing for one message, pass a `routing` object on the send:

```javascript Node.js highlight={5-8} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: ["push", "email"],
    },
  },
});
```

```python Python highlight={5-8} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": ["push", "email"],
        },
    },
)
```

```bash cURL highlight={8-11} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": ["push", "email"]
      }
    }
  }'
```

```ruby Ruby highlight={5-8} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: ["push", "email"]
    }
  }
)
```

```go Go highlight={7-13} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Method: string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
				{OfString: courier.String("email")},
			},
		},
	},
})
```

```java Java highlight={5-9} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .addChannel("push")
            .addChannel("email")
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={5-8} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => ['push', 'email'],
    ],
  ],
);
```

```csharp C# highlight={4-8} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new Routing { Method = Method.Single, Channels = ["push", "email"] },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push", "email"]}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123, trying push first and falling back to email.
```

An inline `routing` object replaces the strategy's channel list and method for that message. The strategy's provider order and channel conditions still apply to the channels you list. With neither, Courier uses the workspace's default routing, which is `{ "method": "single", "channels": ["email"] }` unless your workspace has saved its own.

The recipient's [preferences
DOC](/docs/recipients/preferences/overview) apply on top of routing. An opted-out topic blocks the send, and a user who picked their own channels for a topic gets those channels instead.

## Common patterns

Each pattern is a `routing` object. Pass it on a send, or save the same shape as a strategy.

### Fall back to another channel

Courier tries push, then email, then SMS, and stops at the first that delivers. A user with no push token gets the email, and SMS goes out only if email fails too:

```json theme={null}
{ "method": "single", "channels": ["push", "email", "sms"] }
```

### Send on every channel

Email and Inbox both go out. Each channel fails over among its own providers, so a failed email doesn't stop the Inbox message:

```json theme={null}
{ "method": "all", "channels": ["email", "inbox"] }
```

### Always send one channel, fall back across the rest

An entry in `channels` can be a nested routing object with its own `method`. Here the Inbox message always goes out, and the user also gets push, or email if push can't deliver:

```json theme={null}
{
  "method": "all",
  "channels": [
    "inbox",
    { "method": "single", "channels": ["push", "email"] }
  ]
}
```

Design Studio's **Advanced** routing scheme saves this shape.

### Reach every device on push

APNs and FCM are two providers inside the one `push` channel, and a channel's `routing_method` defaults to `single`. Courier delivers through the first provider that works and stops, so a user with both an iPhone and an Android tablet gets the notification on one device.

Set the push channel's `routing_method` to `all`. It goes in `message.channels`, keyed by channel name, not in the `routing` object:

```javascript Node.js highlight={7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "single", channels: ["push"] },
    channels: {
      push: { routing_method: "all" },
    },
  },
});
```

```python Python highlight={7} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {"method": "single", "channels": ["push"]},
        "channels": {
            "push": {"routing_method": "all"},
        },
    },
)
```

```bash cURL highlight={10} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": { "method": "single", "channels": ["push"] },
      "channels": {
        "push": { "routing_method": "all" }
      }
    }
  }'
```

```ruby Ruby highlight={7} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "single", channels: ["push"] },
    channels: {
      push: { routing_method: "all" }
    }
  }
)
```

```go Go highlight={13} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("push")}},
		},
		Channels: shared.MessageChannelsParam{
			"push": shared.ChannelParam{
				RoutingMethod: shared.ChannelRoutingMethodAll,
			},
		},
	},
})
```

```java Java highlight={11} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .addChannel("push")
            .build())
        .channels(MessageChannels.builder()
            .putAdditionalProperty("push", JsonValue.from(java.util.Map.of(
                "routing_method", "all")))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={7} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => ['method' => 'single', 'channels' => ['push']],
    'channels' => [
      'push' => ['routing_method' => 'all'],
    ],
  ],
);
```

```csharp C# highlight={10} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new Routing { Method = Method.Single, Channels = ["push"] },
        Channels = new Dictionary<string, Channel>()
        {
            { "push", new() { RoutingMethod = RoutingMethod.All } },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push"]}' \
  --message.channels '{"push": {"routing_method": "all"}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on push, reaching every device rather than stopping at the first.
```

A user with only an iPhone gets the same result either way, because Courier skips FCM when the user has no FCM token.

> [!NOTE]
>
> **Both providers have to be installed.**\\
>
> `routing_method` decides how many of the push channel's providers Courier uses. Install APNs and Firebase FCM under [Integrations](https://app.courier.com/integrations), and Courier includes both.

### Send through one provider

Put a provider key such as `twilio` in `channels` instead of a channel name, and Courier sends through that provider alone. See [Send to a provider
DOC](/docs/send/send-to-a-provider).

## Channel priority

Inside a channel, Courier tries providers in this order:

1. The providers listed for that channel in the strategy, in the order you set.
2. Any other provider you've configured for the channel.

Courier skips a provider that can't reach the recipient, such as an SMS provider for a user with no `phone_number`, or whose `if` condition is false. A condition on the channel skips the whole channel. [Channel overrides
DOC](/docs/send/overrides) covers writing conditions.

To change the provider order for one send, list the providers in `message.channels`:

```json theme={null}
{
  "channels": {
    "email": { "providers": ["ses", "sendgrid"] }
  }
}
```

## Failover

Courier moves to the next provider in a channel when one can't take the message or returns an error. It retries transient errors, such as a rate limit or a dropped connection, before moving on. A channel fails when every provider on it has failed or the recipient has no address for it, and a `single` route then moves to the next channel. If every option in the route fails, the message fails.

Every attempt shows in the message's [log
DOC](/docs/monitor/logs).

## Timeouts

Courier retries provider errors for about 24 hours, roughly 104 attempts. `message.timeout.message` sets the message's overall timeout in milliseconds. It defaults to 72 hours, which is also the cap. A shorter timeout ends retries sooner.

On an Enterprise plan, Courier also moves past a slow provider or channel. It gives each provider 5 minutes and each channel 30 minutes, and you can change both per send. On other plans, a send that sets channel or provider timeouts returns `402`.

## FAQ

> **What is the difference between single and all?**
>
> `single` sends through the first channel that delivers and keeps the rest as failover. `all` sends through every channel in the list at once. A channel's own `routing_method` makes the same choice between the providers inside it.

> **Does a routing object on the send replace the template's routing strategy?**
>
> An inline `routing` object replaces the strategy's channel list and method for that one message. The strategy's provider order and channel conditions still apply, so you can reorder channels on a send without losing the rest of the configuration.

> **How do I send one push to both iOS and Android?**
>
> Set the push channel's `routing_method` to `all` in `message.channels`, and install both APNs and Firebase FCM under Integrations. See [reach every device on push](#reach-every-device-on-push).

> **Is failover available on every plan?**
>
> Failover on errors works on every plan: Courier moves to the next provider or channel when one can't deliver. Moving past a provider or channel that is slow, rather than failed, requires an Enterprise plan.


# Routing strategies
Source: https://www.courier.com/docs/send/routing-strategies

Save channel order, fallback, and provider priority as a routing strategy, attach it to templates, and change delivery for all of them in one edit.

A routing strategy is a saved routing setup: the channels a template sends on, their fallback order, and the providers behind each one. Templates point at a strategy by ID, so one edit changes delivery for every template that uses it.

![A routing strategy in Design Studio: email always sends, then SMS, Slack, MS Teams, In-App, and push as fallbacks, with a flowchart of the route](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-advanced-routing-modal.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=863fb1e12cb89cb16d4f4920e798e080)

## What a strategy holds

A strategy carries the same `routing` object you'd pass on a send, plus the per-channel and per-provider settings around it. Its ID starts with `rs_`.

| Field | What it sets |
| :- | :- |
| `name` | The label in the routing selector |
| `routing` | The channel list and `method`, as described in [How routing works&#xA;DOC](/docs/send/routing#two-decisions-channel-then-provider) |
| `channels` | Per channel: `providers` in priority order, `routing_method`, an `if` condition, and an `override` |
| `providers` | Per provider: an `if` condition and an `override` that apply on every channel |
| `description`, `tags` | Your own labels for finding the strategy later |

## Build a strategy in Design Studio

Open a template and click the **routing selector** in the toolbar. It lists the workspace's strategies, with a pencil icon to edit each one and **Add new routing** to create one. Picking a strategy attaches it to the template.

![The routing selector open in the Design Studio toolbar, listing three strategies with edit icons and an Add new routing option](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-routing-selector.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=12df464d297c11f459c5c6fb53eb72b6)

Give the strategy a **Routing name**, then pick a **Routing scheme**:

* **Basic** sends on every channel you switch on, at the same time.
* **Advanced** splits channels into two lists. Everything under **Always send to the following channels (min. 1)** sends. If the last of those fails, Courier tries the channels under **If the last above fails, send to the first successful one below**, in order, until one delivers.

Drag channels to change their order. The flowchart beside the lists draws the route as you build it.

To set the provider order for a channel, click the pencil icon next to it. Under **Routing scheme**, **To the best of** tries providers in the order you drag them into, and **To all** sends through every one. **Add more integrations** puts another provider on the channel. The **Conditions** tab sets when the channel is used, on every template that shares the strategy.

Click **Create routing strategy** to save a new one, or **Save and close** after an edit. **Delete** stays disabled while any template uses the strategy, so move those templates to another strategy first.

## Manage strategies with the API

### Create a strategy

[Create Routing Strategy](/docs/api-reference/routing-strategies/create-routing-strategy) takes a `name` and a `routing` object. This strategy tries email, then SMS, and sends email through SendGrid with SES as the backup:

```javascript Node.js highlight={5} theme={null}
const strategy = await courier.routingStrategies.create({
  name: "Email with SMS fallback",
  routing: { method: "single", channels: ["email", "sms"] },
  channels: {
    email: { providers: ["sendgrid", "ses"] },
  },
  tags: ["production"],
});
```

```python Python highlight={5} theme={null}
strategy = client.routing_strategies.create(
    name="Email with SMS fallback",
    routing={"method": "single", "channels": ["email", "sms"]},
    channels={
        "email": {"providers": ["sendgrid", "ses"]},
    },
    tags=["production"],
)
```

```bash cURL highlight={8} theme={null}
curl -X POST https://api.courier.com/routing-strategies \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email with SMS fallback",
    "routing": { "method": "single", "channels": ["email", "sms"] },
    "channels": {
      "email": { "providers": ["sendgrid", "ses"] }
    },
    "tags": ["production"]
  }'
```

```ruby Ruby highlight={5} theme={null}
strategy = courier.routing_strategies.create(
  name: "Email with SMS fallback",
  routing: {method: :single, channels: ["email", "sms"]},
  channels: {
    email: {providers: ["sendgrid", "ses"]}
  },
  tags: ["production"]
)
```

```go Go highlight={12} theme={null}
strategy, err := client.RoutingStrategies.New(context.TODO(), courier.RoutingStrategyNewParams{
	RoutingStrategyCreateRequest: courier.RoutingStrategyCreateRequestParam{
		Name: "Email with SMS fallback",
		Routing: shared.MessageRoutingParam{
			Method: shared.MessageRoutingMethodSingle,
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("email")},
				{OfString: courier.String("sms")},
			},
		},
		Channels: shared.MessageChannelsParam{
			"email": shared.ChannelParam{Providers: []string{"sendgrid", "ses"}},
		},
		Tags: []string{"production"},
	},
})
```

```java Java highlight={11} theme={null}
RoutingStrategyGetResponse strategy = client.routingStrategies().create(
    RoutingStrategyCreateRequest.builder()
        .name("Email with SMS fallback")
        .routing(MessageRouting.builder()
            .method(MessageRouting.Method.SINGLE)
            .addChannel("email")
            .addChannel("sms")
            .build())
        .channels(MessageChannels.builder()
            .putAdditionalProperty("email", JsonValue.from(java.util.Map.of(
                "providers", java.util.List.of("sendgrid", "ses"))))
            .build())
        .addTag("production")
        .build());
```

```php PHP highlight={5} theme={null}
$strategy = $client->routingStrategies->create(
  name: 'Email with SMS fallback',
  routing: ['method' => 'single', 'channels' => ['email', 'sms']],
  channels: [
    'email' => ['providers' => ['sendgrid', 'ses']],
  ],
  tags: ['production'],
);
```

```csharp C# highlight={7} theme={null}
RoutingStrategyCreateParams parameters = new()
{
    Name = "Email with SMS fallback",
    Routing = new() { Method = Method.Single, Channels = ["email", "sms"] },
    Channels = new Dictionary<string, Channel>()
    {
        { "email", new() { Providers = ["sendgrid", "ses"] } },
    },
    Tags = ["production"],
};

var strategy = await client.RoutingStrategies.Create(parameters);
```

```bash CLI highlight={5} theme={null}
courier routing-strategies create \
  --api-key "$COURIER_API_KEY" \
  --name "Email with SMS fallback" \
  --routing '{"method": "single", "channels": ["email", "sms"]}' \
  --channels '{"email": {"providers": ["sendgrid", "ses"]}}' \
  --tag production
```

```text MCP theme={null}
With Courier MCP, create a routing strategy named "Email with SMS fallback" that tries email first, then SMS, and sends email through SendGrid with SES as the backup.
```

The response carries the new strategy's `id`. Set it as `routing.strategy_id` when you create or replace a template, as shown in [Manage templates with the API
DOC](/docs/design/templates/api).

### Switch providers on every template at once

Every template that uses a strategy picks up a change on its next send, so one edit moves all of them to a new provider. Courier reads the strategy at send time, so no template needs republishing. To see which templates a change reaches, call [List notifications for a Routing Strategy](/docs/api-reference/routing-strategies/list-notifications-for-a-routing-strategy) first.

[Replace Routing Strategy](/docs/api-reference/routing-strategies/replace-routing-strategy) takes the complete strategy and clears any field you leave out, so send every field you want to keep. This puts SES ahead of SendGrid:

```javascript Node.js highlight={5} theme={null}
const strategy = await courier.routingStrategies.replace("rs_01kx4h2jdafq8bk9amzvy6hbv0", {
  name: "Email with SMS fallback",
  routing: { method: "single", channels: ["email", "sms"] },
  channels: {
    email: { providers: ["ses", "sendgrid"] },
  },
  tags: ["production"],
});
```

```python Python highlight={6} theme={null}
strategy = client.routing_strategies.replace(
    id="rs_01kx4h2jdafq8bk9amzvy6hbv0",
    name="Email with SMS fallback",
    routing={"method": "single", "channels": ["email", "sms"]},
    channels={
        "email": {"providers": ["ses", "sendgrid"]},
    },
    tags=["production"],
)
```

```bash cURL highlight={8} theme={null}
curl -X PUT https://api.courier.com/routing-strategies/rs_01kx4h2jdafq8bk9amzvy6hbv0 \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email with SMS fallback",
    "routing": { "method": "single", "channels": ["email", "sms"] },
    "channels": {
      "email": { "providers": ["ses", "sendgrid"] }
    },
    "tags": ["production"]
  }'
```

```ruby Ruby highlight={6} theme={null}
strategy = courier.routing_strategies.replace(
  "rs_01kx4h2jdafq8bk9amzvy6hbv0",
  name: "Email with SMS fallback",
  routing: {method: :single, channels: ["email", "sms"]},
  channels: {
    email: {providers: ["ses", "sendgrid"]}
  },
  tags: ["production"]
)
```

```go Go highlight={15} theme={null}
strategy, err := client.RoutingStrategies.Replace(
	context.TODO(),
	"rs_01kx4h2jdafq8bk9amzvy6hbv0",
	courier.RoutingStrategyReplaceParams{
		RoutingStrategyReplaceRequest: courier.RoutingStrategyReplaceRequestParam{
			Name: "Email with SMS fallback",
			Routing: shared.MessageRoutingParam{
				Method: shared.MessageRoutingMethodSingle,
				Channels: []shared.MessageRoutingChannelUnionParam{
					{OfString: courier.String("email")},
					{OfString: courier.String("sms")},
				},
			},
			Channels: shared.MessageChannelsParam{
				"email": shared.ChannelParam{Providers: []string{"ses", "sendgrid"}},
			},
			Tags: []string{"production"},
		},
	},
)
```

```java Java highlight={13} theme={null}
RoutingStrategyGetResponse strategy = client.routingStrategies().replace(
    RoutingStrategyReplaceParams.builder()
        .id("rs_01kx4h2jdafq8bk9amzvy6hbv0")
        .routingStrategyReplaceRequest(RoutingStrategyReplaceRequest.builder()
            .name("Email with SMS fallback")
            .routing(MessageRouting.builder()
                .method(MessageRouting.Method.SINGLE)
                .addChannel("email")
                .addChannel("sms")
                .build())
            .channels(MessageChannels.builder()
                .putAdditionalProperty("email", JsonValue.from(java.util.Map.of(
                    "providers", java.util.List.of("ses", "sendgrid"))))
                .build())
            .addTag("production")
            .build())
        .build());
```

```php PHP highlight={6} theme={null}
$strategy = $client->routingStrategies->replace(
  'rs_01kx4h2jdafq8bk9amzvy6hbv0',
  name: 'Email with SMS fallback',
  routing: ['method' => 'single', 'channels' => ['email', 'sms']],
  channels: [
    'email' => ['providers' => ['ses', 'sendgrid']],
  ],
  tags: ['production'],
);
```

```csharp C# highlight={8} theme={null}
RoutingStrategyReplaceParams parameters = new()
{
    ID = "rs_01kx4h2jdafq8bk9amzvy6hbv0",
    Name = "Email with SMS fallback",
    Routing = new() { Method = Method.Single, Channels = ["email", "sms"] },
    Channels = new Dictionary<string, Channel>()
    {
        { "email", new() { Providers = ["ses", "sendgrid"] } },
    },
    Tags = ["production"],
};

var strategy = await client.RoutingStrategies.Replace(parameters);
```

```bash CLI highlight={6} theme={null}
courier routing-strategies replace \
  --api-key "$COURIER_API_KEY" \
  --id rs_01kx4h2jdafq8bk9amzvy6hbv0 \
  --name "Email with SMS fallback" \
  --routing '{"method": "single", "channels": ["email", "sms"]}' \
  --channels '{"email": {"providers": ["ses", "sendgrid"]}}' \
  --tag production
```

```text MCP theme={null}
With Courier MCP, update routing strategy rs_01kx4h2jdafq8bk9amzvy6hbv0 so email sends through SES first and SendGrid second, keeping everything else the same.
```

### List and archive strategies

[List Routing Strategies](/docs/api-reference/routing-strategies/list-routing-strategies) returns each strategy's name and tags. [Get Routing Strategy](/docs/api-reference/routing-strategies/get-routing-strategy) returns its full configuration. [Archive Routing Strategy](/docs/api-reference/routing-strategies/archive-routing-strategy) returns `409` while any template still uses the strategy.

## FAQ

> **Do I need to republish templates after editing a routing strategy?**
>
> Templates don't need republishing after a strategy edit. A template stores only the strategy's ID, and Courier reads the strategy on every send, so the next message uses the new configuration.

> **Can one send use different routing from its template's strategy?**
>
> A send can pass its own `routing` object, which replaces the strategy's channel list and method for that message. The strategy's provider order and channel conditions still apply. See [where routing is set
> DOC](/docs/send/routing#where-routing-is-set).


# Send to a provider
Source: https://www.courier.com/docs/send/send-to-a-provider

Send through one specific provider by naming it in routing instead of a channel.

Courier recommends routing to a channel. Naming a provider key in `routing.channels` instead is supported, and sends through that one provider.

```javascript Node.js highlight={10} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "some-provider-key",
      ],
    },
  },
});
```

```python Python highlight={10} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": [
                "some-provider-key",
            ],
        },
    },
)
```

```bash cURL highlight={13} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": [
          "some-provider-key"
        ]
      }
    }
  }'
```

```ruby Ruby highlight={10} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "some-provider-key"
      ]
    }
  }
)
```

```go Go highlight={11} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("some-provider-key")},
			},
			Method: "single",
		},
	},
})
```

```java Java highlight={6} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("some-provider-key")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={10} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => [
        'some-provider-key',
      ],
    ],
  ],
);
```

```csharp C# highlight={7} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["some-provider-key"], Method = Send::Method.Single },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["some-provider-key"]}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 through some-provider-key only.
```

## Route to the channel first

Routing to a channel is what Courier recommends. Attach your providers to it, address the recipient, and route to the channel by name.

Courier then tries that channel's providers in [priority order
DOC](/docs/send/routing#channel-priority) and moves to the next one when a send fails. A provider you connect later joins the order without a code change.

Pin a provider only for the cases below.

## When to pin one

* Smoke-testing a provider you just connected, before it carries real traffic.
* Reproducing one provider's behavior while you debug a delivery.
* Splitting traffic across two providers on the same channel, such as a transactional sender and a bulk sender.

## What pinning costs

| You give up | Because |
| :- | :- |
| **Failover** | The list holds one provider, so there is nothing to fall back to. |
| **Channel priority** | The channel's provider order no longer decides anything. |
| **Providers added later** | The key names one provider, and a new one never becomes a candidate. |

> [!NOTE]
>
> **A provider key selects, it doesn't install.** Connect the provider under [Integrations](https://app.courier.com/integrations), then add it to the channel in the template's routing selector. A channel delivers only through the providers attached to it.

## Overrides need no pin

A [provider override
DOC](/docs/send/overrides#how-overrides-work) is keyed by provider, and Courier applies it when that provider runs. Route to the channel and the override still lands.

```javascript Node.js highlight={10} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push",
      ],
    },
    providers: {
      apn: {
        override: {
          body: {
            badge: 99,
          },
        },
      },
    },
  },
});
```

```python Python highlight={10} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": [
                "push",
            ],
        },
        "providers": {
            "apn": {
                "override": {
                    "body": {
                        "badge": 99,
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={13} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": [
          "push"
        ]
      },
      "providers": {
        "apn": {
          "override": {
            "body": {
              "badge": 99
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={10} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: [
        "push"
      ]
    },
    providers: {
      apn: {
        override: {
          body: {
            badge: 99
          }
        }
      }
    }
  }
)
```

```go Go highlight={11} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
			},
			Method: "single",
		},
		Providers: shared.MessageProvidersParam{
			"apn": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"badge": 99,
					},
				},
			},
		},
	},
})
```

```java Java highlight={6} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("push")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .providers(MessageProviders.builder()
            .putAdditionalProperty("apn", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of("badge", 99)
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={10} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => [
        'push',
      ],
    ],
    'providers' => [
      'apn' => [
        'override' => [
          'body' => [
            'badge' => 99,
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={7} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["push"], Method = Send::Method.Single },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "apn",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """{"body": {"badge": 99}}"""
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push"]}' \
  --message.providers '{"apn": {"override": {"body": {"badge": 99}}}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on push with a badge count of 99.
```

APNs gets the badge. Firebase FCM, on the same channel, is untouched.

## Find a provider key

Every provider page ends with a **Provider key** section carrying the exact string, and [Integrations
DOC](/docs/integrations/overview) lists them all. The key also names each attempt in [Logs](https://app.courier.com/logs).


# Message statuses and errors
Source: https://www.courier.com/docs/send/statuses

Every status a message can have, what each one means, and why a send fails.

A send is asynchronous. The API returns a `requestId`, and the message moves through a status lifecycle you track in the logs.

## How it works

### The status lifecycle

A message's status only advances, never backward. Two independent systems drive it. **Provider confirmation** produces `DELIVERED`. **Courier tracking** produces `OPENED` and `CLICKED`, so engagement can arrive before or without a delivery confirmation.

| Category | Statuses | Meaning |
| - | - | - |
| Intermediate | `ENQUEUED`, `ROUTED`, `SENT` | Still processing or awaiting provider confirmation. `SENT` isn't terminal. |
| Terminal (delivery) | `DELIVERED`, `UNDELIVERABLE` | Provider accepted, or rejected/failed. |
| Terminal (engagement) | `OPENED`, `CLICKED` | The recipient interacted. |
| Terminal (routing) | `UNROUTABLE`, `CANCELED`, `FILTERED`, `UNMAPPED` | The message never reached a provider. |
| Processing | `DELAYED`, `DIGESTED`, `THROTTLED` | Held for later, batched into a digest, or rate-limited. |

Open a message in the [logs
DOC](/docs/monitor/overview) to see its provider response.

### Send API responses

A successful send returns a `requestId` you use to track the message:

```json theme={null}
{ "requestId": "87e7c05b-4f46-fda24e356e23" }
```

A failed request returns an HTTP error with a `message` and a `type`:

| Type | Status | Meaning |
| - | - | - |
| `invalid_request_error` | 400, 404, 409, 413 | Malformed request or a missing resource. Fix it before retrying. |
| `authentication_error` | 401 | The API key is missing, invalid, or for the wrong environment. |
| `authorization_error` | 403 | The key is valid but lacks permission. |
| `rate_limit_error` | 429 | A rate limit was exceeded. Back off and retry. |
| `api_error` | 500, 503 | A Courier-side error. Retry with exponential backoff. |

The most common `400` on `/send` is `Either 'content' or 'template' must be defined`. Send one, not both. Next most common are a missing `to`, or a `list_id`/`audience_id` that doesn't exist. A `413` means the request exceeded the **6 MB** payload limit. Host attachments externally and pass URLs in `data` rather than base64.

### Limits

[Send a message](/docs/api-reference/send/send-a-message) is **not rate-limited by request count**, so you can send at volume. Its request body caps at **6 MB**, as does [Invoke an ad hoc Automation](/docs/api-reference/automations/invoke-an-ad-hoc-automation). Every other endpoint caps at 1 MB.

A few management endpoints are rate-limited per workspace. Their responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining` so you can pace requests. Exceeding a limit returns `429 Too Many Requests`:

| Endpoint | Limit |
| - | - |
| [Update a List](/docs/api-reference/lists/update-a-list) | 60 requests / minute |
| `POST` or [Replace user Preferences in bulk](/docs/api-reference/user-preferences/replace-user-preferences-in-bulk) | 50 requests / second |
| [Resend message](/docs/api-reference/messages/resend-message) | 1 request / 2 seconds, per message |

Endpoints not listed here aren't request-count limited today.

### Send limits

**Send limits** cap how many messages a user, topic, or tenant receives in a window. They are a separate feature from API rate limits. A message blocked by one shows as `THROTTLED` in the log instead of delivering. A [send rate limit
DOC](/docs/integrations/send-rate-limits) on a provider queues sends above the rate instead of blocking them.

The Developer plan's 10,000-sends-per-period cap produces the same `THROTTLED` status. It applies after the API returns `202`, so the status shows up in the message log rather than the response. A `THROTTLED` message you didn't set a limit for usually means the plan cap.

### Why a message is UNROUTABLE

`UNROUTABLE` is one status with several causes. Open the message in [Logs](https://app.courier.com/logs) and read its `reason`:

| `reason` | Cause | Fix |
| - | - | - |
| `NO_PROVIDERS` | No provider is configured for the routed channel in this environment, or none of the configured ones is allowed by the send's channel list. | Configure a provider for the channel in [Integrations](https://app.courier.com/integrations), or drop the channel from `routing`. |
| `NO_CHANNELS` | No channel resolved for the send. | Add a channel to `routing`, or to the template's routing strategy. |
| `UNPUBLISHED` | The template has never been published. | Publish it. |
| `OPT_IN_REQUIRED` | The topic needs an opt-in the recipient hasn't given. | See [preference resolution&#xA;DOC](/docs/recipients/preferences/overview#status-precedence). |
| `UNSUBSCRIBED` | The recipient opted out of the topic. | Expected. Opt-outs are per tenant, so check the tenant context too. |
| `FILTERED` | A channel or provider condition evaluated false. | Check the `if` conditions on the channel and provider. |

The timeline then shows one attempt per provider, each with its own `reason` for being skipped:

| Provider `reason` | Meaning |
| - | - |
| `MISSING_CONFIGURATION` | The provider is named on the send or template but isn't configured in this environment. |
| `MISSING_PROVIDER_SUPPORT` | The provider doesn't serve that channel. |
| `INCOMPLETE_PROFILE_DATA` | The recipient's profile has no address this provider can use (no `email`, no `phone_number`, no device token). |
| `FILTERED_AT_PROVIDER` | The provider's own `if` condition evaluated false. |

To audit in bulk, list the failures over the API:

```javascript Node.js highlight={1} theme={null}
const messages = await client.messages.list({ status: ['UNROUTABLE'] });

for (const message of messages.results) {
  console.log(message.messageId, message.reason);
}
```

```python Python highlight={1} theme={null}
messages = client.messages.list(status=["UNROUTABLE"])

for message in messages.results:
    print(message.message_id, message.reason)
```

```bash cURL theme={null}
curl "https://api.courier.com/messages?status=UNROUTABLE" \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby highlight={1} theme={null}
messages = courier.messages.list(status: ["UNROUTABLE"])

messages.results.each do |message|
  puts "#{message.message_id} #{message.reason}"
end
```

```go Go highlight={2} theme={null}
messages, err := client.Messages.List(context.TODO(), courier.MessageListParams{
	Status: []string{"UNROUTABLE"},
})
if err != nil {
	panic(err)
}

for _, message := range messages.Results {
	fmt.Println(message.MessageID, message.Reason)
}
```

```java Java highlight={2} theme={null}
MessageListResponse messages =
    client.messages().list(MessageListParams.builder().addStatus("UNROUTABLE").build());

messages.results().forEach(message ->
    System.out.println(message.messageId() + " " + message.reason()));
```

```php PHP highlight={1} theme={null}
$messages = $client->messages->list(status: ['UNROUTABLE']);

foreach ($messages->results as $message) {
  echo $message->messageId . ' ' . $message->reason . PHP_EOL;
}
```

```csharp C# highlight={1} theme={null}
var messages = await client.Messages.List(new() { Status = ["UNROUTABLE"] });

foreach (var message in messages.Results)
{
    Console.WriteLine($"{message.MessageID} {message.Reason}");
}
```

```bash CLI highlight={3} theme={null}
courier messages list \
  --api-key "$COURIER_API_KEY" \
  --status UNROUTABLE
```

```text MCP theme={null}
With Courier MCP, list my messages with the UNROUTABLE status.
```

### Debug other statuses

* **Stuck at `SENT`**: delivery tracking isn't configured for that channel, not a failure. See [delivery tracking](#delivery-tracking-is-per-provider).
* **`FILTERED`**: preferences, send conditions, or routing removed the message. Check the recipient's [preferences
  DOC](/docs/recipients/preferences/overview).
* **`UNDELIVERABLE`**: the provider rejected it. The timeline shows the provider's error.

For real-time status without polling, receive the `message:updated` [outbound webhook
DOC](/docs/monitor/webhooks/outbound).

### Delivery tracking is per provider

`DELIVERED` only appears when the provider tells Courier the message landed. That reporting is **off until you set it up, per provider**. Until then a healthy send stops at `SENT`. This is the most common reason a working integration looks broken.

A provider reports in one of four ways:

| How it reports | What you do | Providers |
| - | - | - |
| **Webhook** | Paste Courier's webhook URL into the provider, and it pushes status in real time. | [SendGrid&#xA;DOC](/docs/integrations/email/sendgrid#delivery-tracking), [AWS SES&#xA;DOC](/docs/integrations/email/aws-ses#delivery-tracking), [Mailgun&#xA;DOC](/docs/integrations/email/mailgun), [Resend&#xA;DOC](/docs/integrations/email/resend), [Sinch Engage&#xA;DOC](/docs/integrations/sms/sinch-engage) |
| **Polling** | Turn the toggle on in the integration's settings. Courier then asks the provider's API on a schedule. | SendGrid, Mailgun, [Twilio&#xA;DOC](/docs/integrations/sms/twilio), [Postmark&#xA;DOC](/docs/integrations/email/postmark), [Mandrill&#xA;DOC](/docs/integrations/email/mandrill), [Plivo&#xA;DOC](/docs/integrations/sms/plivo) |
| **Immediate** | Nothing. The provider acknowledges synchronously, so Courier marks the message `DELIVERED` on accept. | [Slack&#xA;DOC](/docs/integrations/direct-message/slack), [Microsoft Teams&#xA;DOC](/docs/integrations/direct-message/microsoft-teams), [Discord&#xA;DOC](/docs/integrations/direct-message/discord), [Stream Chat&#xA;DOC](/docs/integrations/direct-message/stream-chat), [Viber&#xA;DOC](/docs/integrations/direct-message/viber), [PagerDuty&#xA;DOC](/docs/integrations/other/pagerduty), [Webhook&#xA;DOC](/docs/integrations/other/webhook-integration) |
| **Reported by your app** | Use a Courier mobile SDK, or `POST` the `trackingUrl` from the payload yourself. | [APNs, FCM, Expo, OneSignal&#xA;DOC](/docs/integrations/push/overview#tracking) |

Providers absent from this table send no delivery confirmation, so their messages stop at `SENT` by design. Where both a webhook and polling are offered, prefer the webhook. It is real time and needs no extra provider permissions.

## FAQ

> **What does UNROUTABLE mean?**
>
> Courier found no valid route: the recipient had no address for the routed channel, or no channel was configured for the send. Check the recipient's profile and the send's routing.

> **My message is stuck at SENT. Did it fail?**
>
> Usually not. `SENT` means Courier handed it to the provider and got no delivery confirmation back. That usually means delivery tracking isn't set up for that channel.

> **Is the Send API rate-limited?**
>
> Not by request count. You can send at volume. A few management endpoints are limited (see the table above). Send limits (per user, topic, or tenant) govern message volume and mark blocked messages `THROTTLED`.

> **Why did I get a 413?**
>
> The request exceeded the body-size cap: 6 MB on `/send` and `/automations/invoke`, 1 MB on every other endpoint. Host attachments externally and pass their URLs in `data`. Base64 inflates size by about a third.


# Tenant context
Source: https://www.courier.com/docs/tenants/context

How a tenant's brand, preferences, templates, and properties apply when a send names it.

Naming a tenant on a send is the whole of the API you write. Courier loads the tenant merged with its parent chain, then picks the brand, resolves preferences, and selects tenant-specific content.

## How it works

### The tenant object

A tenant stores the defaults for its members. Its fields are an `id` you choose (like `acme-corp`), a `name`, an optional `parent_tenant_id`, a `brand_id`, `default_preferences`, free-form `properties`, and a `user_profile` that merges into recipients.

Tenants hold no channels, providers, or API keys of their own. Those are workspace-and-environment concepts every tenant shares.

```json theme={null}
{
  "id": "acme-corp",
  "name": "Acme Corp",
  "parent_tenant_id": null,
  "brand_id": "bnd_acmecorp",
  "default_preferences": { "items": [] },
  "properties": { "plan": "enterprise" },
  "user_profile": {}
}
```

A send selects that tenant with `context.tenant_id`. Courier loads the object above, merged with its parents, and applies the brand, preferences, and templates it names:

```javascript Node.js highlight={11} theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const { requestId } = await client.send.message({
  message: {
    to: {
      user_id: 'user_123',
      context: { tenant_id: 'acme-corp' },
    },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { first_name: 'Sarah' },
    routing: { method: 'single', channels: ['inbox'] },
  },
});

console.log(requestId);
```

```python Python highlight={11} theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
            "context": {"tenant_id": "acme-corp"},
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"first_name": "Sarah"},
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)
print(response.request_id)
```

```bash cURL highlight={6} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123", "context": { "tenant_id": "acme-corp" } },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "first_name": "Sarah" },
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'
```

```ruby Ruby highlight={9} theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123",
      context: { tenant_id: "acme-corp" }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { first_name: "Sarah" },
    routing: { method: "single", channels: ["inbox"] }
  }
)

puts(response)
```

```go Go highlight={6} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID:  courier.String("user_123"),
				Context: shared.MessageContextParam{TenantID: courier.String("acme-corp")},
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"first_name": "Sarah",
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("inbox")}},
		},
	},
})
```

```java Java highlight={5} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of(
            "user_id", "user_123",
            "context", java.util.Map.of("tenant_id", "acme-corp"))))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("first_name", "Sarah")))
        .routing(JsonValue.from(java.util.Map.of(
            "method", "single",
            "channels", java.util.List.of("inbox"))))
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={5} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'userID' => 'user_123',
      'context' => ['tenantID' => 'acme-corp'],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['first_name' => 'Sarah'],
    'routing' => ['method' => 'single', 'channels' => ['inbox']],
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123", Context = new MessageContext { TenantID = "acme-corp" } },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "first_name", JsonSerializer.SerializeToElement("Sarah") },
        },
        Routing = new Routing { Method = Method.Single, Channels = ["inbox"] },
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123","context":{"tenant_id":"acme-corp"}},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"first_name":"Sarah"},"routing":{"method":"single","channels":["inbox"]}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with acme-corp as their tenant context.
```

The highlighted line is the whole of it. Nothing else in the request changes, and no field repeats what the tenant already stores. [Send with tenants
DOC](/docs/tenants/send) covers the other targeting shapes.

### Hierarchy and inheritance

Customers often have structure of their own: environments, regions, sites, business units. Set `parent_tenant_id` to nest one tenant inside another and Courier walks the chain when it builds a message. You still send a single `tenant_id`, the deepest one.

The merge walks top-down, parent first, and **child values override parent values** on conflicting keys. A child starts from everything its ancestors define and overrides only what it needs, so a Slack token set once at the top serves every tenant beneath it.

```text theme={null}
acme                     brand, default preferences, properties
└── acme-eu              inherits all three, overrides brand_id
    └── acme-eu-checkout inherits the EU brand and Acme's defaults
```

**Keep the tree to four levels.** Courier loads tenant context as a four-layer sliding window. It starts at most three ancestors up rather than at the root, so in a five-deep tree, the top tenant's settings don't apply to a leaf send.

What inherits down the chain: `brand_id`, `default_preferences`, tenant templates, `properties`, and `user_profile` (deep-merged key by key).

### What inherits, and what doesn't

Channels, providers, and API keys do **not** inherit, because they aren't tenant fields. You configure a provider (SendGrid, a Slack integration) once per environment, and every tenant there uses it. A parent tenant can't hold an access token for its children to inherit.

`user_profile` is where a customer's own provider details go. Sends that name the tenant route through their Slack workspace instead of yours, or reach their Microsoft Teams organization through your bot with `ms_teams` fields such as `tenant_id` and `service_url`. You store them once per organization rather than once per user.

```json theme={null}
{ "user_profile": { "slack": { "access_token": "xoxb-..." } } }
```

The recipient profile is itself a merge, in this precedence (later wins):

1. The tenant context (parent chain merged, child over parent).
2. The user's stored Courier profile.
3. The `to` profile on the send request.

### How a send picks a brand

Courier picks the brand in this order, highest first:

1. `brand_id` on the send request.
2. The **tenant's `brand_id`**, the "auto-infer" behavior: set a brand on the tenant and Courier applies it automatically.
3. The template's assigned default brand.
4. The workspace's default (primary) brand.

To brand messages per customer, set `brand_id` on the tenant and send in that tenant's context. Courier falls back to the primary brand only when no higher layer names one. For template sends, the template must have its brand enabled.

### Tenant templates

A tenant template is a tenant's own version of a template, stored separately and linked to the tenant. Courier merges its content over the message at send time, then routes normally. Reference one with `template: "tenant/<template_id>"`, where `tenant` is the literal word and the tenant comes from the context. Tenant templates are API-only. See [Create & manage tenant templates
DOC](/docs/tenants/templates).

### Setting tenant context on a send

Courier resolves which tenant a send uses in this order:

1. A recipient's `context.tenant_id`.
2. The message-level `context.tenant_id`.
3. A `tenant_id` recipient (fan-out to members).

A tenant loads its context (brand, preferences, templates) and scopes preference lookups to that tenant. It doesn't change channel or provider routing, which stays workspace-and-environment scoped. [Send with tenants
DOC](/docs/tenants/send) covers every targeting shape.

### Auto-infer tenant context

If a send names no tenant and the user belongs to exactly one, Courier loads that tenant's context. This helps console, list, and audience sends where brand or provider data lives on the tenant. A user with two or more memberships must have the tenant specified, or the send returns `Tenant Context Not Found`. Turn auto-infer off in workspace settings.

### Tenant-scoped inbox

The [in-app inbox
DOC](/docs/in-app/overview) scopes to a tenant only when you pass a `tenantId` at `signIn`. That applies to every inbox read and the live socket for the session. Sign in **without** a `tenantId` and the inbox shows only messages sent without a tenant. Auto-infer doesn't apply to the inbox client. See [Scope the inbox to a tenant
DOC](/docs/in-app/send-to-the-inbox#scope-the-inbox-to-a-tenant).

## Troubleshooting

* **A send fails with `Tenant Context Not Found`.** The user belongs to more than one tenant and the send didn't specify one. Set `context.tenant_id`.
* **The wrong brand renders.** An explicit `brand_id` on the send, or the tenant's own `brand_id`, overrides the workspace primary brand. To use the tenant's brand, set `brand_id` on the tenant and confirm the template has its brand enabled.
* **A message sent without a tenant doesn't appear in the inbox.** The client signed in with a `tenantId`, so it shows only that tenant's messages. Sign in without a `tenantId` to see messages sent without one.
* **A user doesn't see a tenant message in their inbox.** The message went to a tenant the client isn't signed in with. The send `tenant_id` and the sign-in `tenantId` must match.

## FAQ

> **Does a child tenant inherit its parent's brand and preferences?**
>
> Courier merges a tenant with its parent chain (up to four levels), child over parent. Brand, default preferences, tenant templates, properties, and user profile inherit. Channels, providers, and API keys don't, because they are workspace-and-environment scoped, not tenant fields.

> **Why does Courier use the primary brand instead of my tenant's brand?**
>
> Courier falls back to the workspace primary brand only when the send, the tenant, and the template all name none. Set `brand_id` on the tenant, send in that tenant's context, and confirm the template has its brand enabled.

> **Why don't my tenant templates show in the console?**
>
> Tenant templates are managed through the API, not the console. No screen creates, lists, or deletes them. Use the tenant templates endpoints. See [Create & manage tenant templates
> DOC](/docs/tenants/templates).


# Tenants
Source: https://www.courier.com/docs/tenants/overview

Model each customer organization with its own brand, defaults, templates, and properties.

A tenant is one of your customer organizations: the company, account, or workspace that a group of your users belongs to. If you sell to businesses, you already have this object in your own database, under one of those names.

```json theme={null}
{
  "message": {
    "to": { "user_id": "user_123" },
    "context": { "tenant_id": "acme-corp" },
    ...
  }
}
```

One field on the send names the organization. Courier applies that tenant's brand, defaults, and content, so one template goes out looking like it came from each of your customers.

## What tenants are for

> **White-label the notifications each customer receives**
>
> Every customer sees their own logo, colors, and sender identity. Attach a [brand
> DOC](/docs/design/brands) to the tenant and Courier applies it whenever you send to a user in that tenant, with no change to the template.

> **Let each customer set their own notification defaults**
>
> A tenant carries default [preferences
> DOC](/docs/tenants/preferences) for its topics. One customer starts opted out of product announcements, another makes billing alerts required. Their users can still change their own.

> **Give one customer a different version of a message**
>
> A [tenant template
> DOC](/docs/tenants/templates) overrides the workspace template for that tenant only. Use it when a customer needs different wording, an extra legal line, or their own layout.

> **Notify everyone in a customer's organization**
>
> Send to a `tenant_id` instead of a user and Courier fans out to its members. Tenants can nest through `parent_tenant_id`, so a send can walk the hierarchy up or down. See [Send with Tenants
> DOC](/docs/tenants/send).

> **Model teams, projects, or workspaces inside your product**
>
> A tenant doesn't have to be a company. It maps to whatever unit your product bills or brands: a team, a project, a store, a region.

## What you store on a tenant

Anything that is true about a customer organization rather than about a particular notification.

| What you store | Where it goes |
| - | - |
| Their logo, colors, and email chrome | `brand_id`, referencing a [brand&#xA;DOC](/docs/design/brands) |
| What is switched on or off for everyone at that company | `default_preferences`, plus [per-topic overrides&#xA;DOC](/docs/tenants/preferences) |
| Their plan, region, support address, account manager | `properties`, readable from template content |
| Their own edited version of one of your emails | A [tenant template&#xA;DOC](/docs/tenants/templates) |
| Their connected Slack workspace, or their Microsoft Teams bot details in `ms_teams` | `user_profile` |
| Their position under a parent organization | `parent_tenant_id` |

Without a tenant, all of that gets looked up and assembled in front of every send. With one, you pass an id and Courier resolves the rest.

Put event-specific values in `data`. Put customer-level values in the tenant's `properties`. A support address that arrives in `data` on every send is one that belongs in `properties` once.

## What a tenant isn't

**A tenant isn't a way to group recipients.** If what you want is "send this to these people", use a [list or an audience
DOC](/docs/recipients/lists-and-audiences/overview). A tenant scopes branding and settings to one customer. To send to a group of users, use a list or an audience.

**A tenant isn't an environment.** Use [environments
DOC](/docs/workspaces/environments) to separate test traffic from production. Tenants divide your customers, not your pipeline.

**Tenant membership isn't permissions.** Being in a tenant decides which context Courier builds a message from, and nothing about what that user may do. Authorization stays in your application.

## How it works

You address a user, and name the tenant that user is acting in. See [how tenant context works
DOC](/docs/tenants/context) for the resolution order.

```mermaid theme={null}
flowchart LR
    A["One send"] --> B{"Which tenant?"}
    B -->|acme-corp| C["Acme brand"]
    B -->|beta-inc| D["Beta brand"]
    B -->|None named| E["Workspace default"]
```

Anything the tenant doesn't define falls through to the workspace default, so you only configure the differences.

A user can belong to as many tenants as you need, and each membership is independent. Someone who works with two of your customers can have alerts on at Acme and off at Beta. They see Acme's branding in one email and Beta's in the next, with a separate inbox feed on each side.

## How tenant context resolves

**Courier can apply a tenant you didn't name.** If a user belongs to exactly one tenant and your send doesn't specify one, Courier loads that tenant's context anyway. This is a workspace setting, useful for console, list, and audience sends where the tenant isn't explicit in the request. See [auto-infer
DOC](/docs/tenants/context#auto-infer-tenant-context).

**A tenant-scoped inbox message appears only to a client signed in with that tenant.** A message sent with `tenant_id: "acme-corp"` shows up once the client calls `signIn` with the same `tenantId`. Signing in without it shows only messages sent without a tenant, so this one stays hidden even though the send succeeded.

**Tenant hierarchy merges up to four levels.** Courier loads tenant context as a four-layer sliding window, starting at the tenant you sent to rather than the root. In a five-deep tree, the top tenant's settings don't apply to a leaf send.

## Limits & behavior

**Channels, providers, and API keys are shared across tenants.** Configure a provider such as SendGrid once, and every tenant uses it. A customer's own Slack token, or their Microsoft Teams bot details such as `ms_teams.tenant_id` and `ms_teams.service_url`, can still live in the tenant's `user_profile`, which merges into the recipient at send time.

## FAQ

> **Do I need tenants for a single-customer app?**
>
> Tenants serve multiple customer organizations from one account, as in B2B SaaS or white-label products. A single-customer app needs one workspace and no tenants.

> **Does a tenant need its own template for every notification?**
>
> A tenant inherits every workspace template by default. Create a [tenant template
> DOC](/docs/tenants/templates) only for the messages that customer needs to differ.

> **Can a user belong to more than one tenant?**
>
> If the user belongs to exactly one tenant, Courier infers it. With two or more memberships you must set `context.tenant_id`, or the send fails with `Tenant Context Not Found`. See [tenant context
> DOC](/docs/tenants/context).

> **Where do I put the tenant on a send?**
>
> Either `to.tenant_id` on the recipient or `message.context.tenant_id`. Both behave identically, so pick one and put it behind a shared helper. [Notify across tenants
> GUIDE](/docs/guides/notify-across-tenants) uses the context form throughout.


# Tenant default preferences
Source: https://www.courier.com/docs/tenants/preferences

Set default topic statuses per tenant that apply before a user makes their own choice.

> [!NOTE]
>
> [How preferences resolve
> DOC](/docs/recipients/preferences/overview) and [how tenant context works
> DOC](/docs/tenants/context) cover the concepts behind this page.

Preferences are usually the first reason people reach for tenants. A customer's admin wants a category of notification switched off across their whole company, and that has to hold for users who never open a preference center.

A tenant default sets a topic's starting state for everyone in that organization. It overrides the workspace default for any send that names the tenant, and each user can still change their own from there.

**A tenant default isn't a way to force a setting.** A user who opts out stays opted out, because their own preference sits below the tenant's in the [merge order
DOC](/docs/recipients/preferences/overview#status-precedence). Mark a topic `REQUIRED` when it is transactional and nobody should be able to switch it off, which is the only status that ignores what the user chose.

> [!NOTE]
>
> A tenant default sets a topic's **status** and nothing else. Channel routing is read from each user's own preference record. A tenant's `has_custom_routing` and `custom_routing` have no effect at send time, even though the API accepts and returns them, so a tenant that looks correctly configured can route nothing. To route a topic to specific channels, set it on the [user's preferences
> DOC](/docs/recipients/preferences/api).

## Prerequisites

* [A tenant under Directory → Tenants](https://app.courier.com/directory/tenants)
* [The tenant model
  DOC](/docs/tenants/overview)
* [Your subscription topics under Platform → Preferences](https://app.courier.com/~/test/platform/preferences)
* [The status precedence rules
  DOC](/docs/recipients/preferences/overview#status-precedence)

## Set tenant defaults

**1. Set defaults in the console**

In the console, a tenant stores its defaults as a single `default_preferences` JSON object that you edit directly. Go to the tenant in the [console](https://app.courier.com/directory/tenants) (**Directory → Tenants**) and open its **Details** tab. In the **Default Preferences** section, paste a JSON object whose `items` array holds one entry per topic. Each entry takes the `topic_id` as `id` and a `status` of `OPTED_IN`, `OPTED_OUT`, or `REQUIRED`. Save.

![A tenant's Details tab with the Default Preferences JSON editor holding three topic entries and reporting Valid JSON](https://mintcdn.com/courier-4f1f25dc/rYENcCCTyPPrDtw0/assets/tenant-default-preferences.webp?fit=max\&auto=format\&n=rYENcCCTyPPrDtw0\&q=85\&s=275ba127bd82e12171112f9077d377cc)

The Default Preferences JSON editor on a tenant's Details tab in the console.

This example opts one topic in, makes a second impossible to turn off, and opts out of a third. Topics you leave out keep their workspace default:

```json theme={null}
{
  "items": [
    {
      "id": "pt_01kx4h2jdafq8bk996nn92357r",
      "status": "OPTED_IN"
    },
    {
      "id": "pt_01kx4h9m2rdvc7yq5tb8n30k4e",
      "status": "REQUIRED"
    },
    {
      "id": "pt_01kx4hb7t8fzs2mp6wc4j91xgd",
      "status": "OPTED_OUT"
    }
  ]
}
```

**2. Set a default with the API**

[Create or replace default Preferences for Topic](/docs/api-reference/tenants/create-or-replace-default-preferences-for-topic) sets tenant defaults one topic at a time from your backend. Only the topics you include override the workspace default. Topics you leave out fall back to their workspace default state. The same `default_preferences` object shown above is what you send when you create or replace the tenant through the [Tenants API](/docs/api-reference/tenants/create-or-replace-a-tenant). Set one topic's default with a body shaped like a topic, carrying its `status`.

```javascript Node.js highlight={9} theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

await client.tenants.preferences.items.update('pt_01kx4h2jdafq8bk996nn92357r', {
  tenant_id: 'acme-corp',
  status: 'OPTED_IN',
});
```

```python Python highlight={10} theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
client.tenants.preferences.items.update(
    topic_id="pt_01kx4h2jdafq8bk996nn92357r",
    tenant_id="acme-corp",
    status="OPTED_IN",
)
```

```bash cURL highlight={4} theme={null}
curl -X PUT https://api.courier.com/tenants/acme-corp/default_preferences/items/pt_01kx4h2jdafq8bk996nn92357r \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "OPTED_IN" }'
```

```ruby Ruby highlight={5} theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

result = courier.tenants.preferences.items.update("pt_01kx4h2jdafq8bk996nn92357r", tenant_id: "acme-corp", status: :OPTED_IN)

puts(result)
```

```go Go highlight={7} theme={null}
err := client.Tenants.Preferences.Items.Update(
	context.TODO(),
	"pt_01kx4h2jdafq8bk996nn92357r",
	courier.TenantPreferenceItemUpdateParams{
		TenantID: "acme-corp",
		SubscriptionTopicNew: courier.SubscriptionTopicNewParam{
			Status: courier.SubscriptionTopicNewStatusOptedIn,
		},
	},
)
```

```java Java highlight={5} theme={null}
ItemUpdateParams params = ItemUpdateParams.builder()
    .tenantId("acme-corp")
    .topicId("pt_01kx4h2jdafq8bk996nn92357r")
    .subscriptionTopicNew(SubscriptionTopicNew.builder()
        .status(SubscriptionTopicNew.Status.OPTED_IN)
        .build())
    .build();
client.tenants().preferences().items().update(params);
```

```php PHP highlight={4} theme={null}
$result = $client->tenants->preferences->items->update(
  'pt_01kx4h2jdafq8bk996nn92357r',
  tenantID: 'acme-corp',
  status: 'OPTED_IN',
);
```

```csharp C# highlight={5} theme={null}
ItemUpdateParams parameters = new()
{
    TenantID = "acme-corp",
    TopicID = "pt_01kx4h2jdafq8bk996nn92357r",
    Status = Status.OptedIn,
};

await client.Tenants.Preferences.Items.Update(parameters);
```

```bash CLI highlight={5} theme={null}
courier tenants:preferences:items update \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --topic-id pt_01kx4h2jdafq8bk996nn92357r \
  --status OPTED_IN
```

```text MCP theme={null}
With Courier MCP, opt acme-corp into that topic by default.
```

**3. Remove a tenant default**

[Remove default Preferences for Topic](/docs/api-reference/tenants/remove-default-preferences-for-topic) removes a tenant default for a topic, reverting it to the workspace default:

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

await client.tenants.preferences.items.delete('pt_01kx4h2jdafq8bk996nn92357r', { tenant_id: 'acme-corp' });
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
client.tenants.preferences.items.delete(
    topic_id="pt_01kx4h2jdafq8bk996nn92357r",
    tenant_id="acme-corp",
)
```

```bash cURL theme={null}
curl -X DELETE https://api.courier.com/tenants/acme-corp/default_preferences/items/pt_01kx4h2jdafq8bk996nn92357r \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

result = courier.tenants.preferences.items.delete("pt_01kx4h2jdafq8bk996nn92357r", tenant_id: "acme-corp")

puts(result)
```

```go Go theme={null}
err := client.Tenants.Preferences.Items.Delete(
	context.TODO(),
	"pt_01kx4h2jdafq8bk996nn92357r",
	courier.TenantPreferenceItemDeleteParams{
		TenantID: "acme-corp",
	},
)
```

```java Java theme={null}
ItemDeleteParams params = ItemDeleteParams.builder()
    .tenantId("acme-corp")
    .topicId("pt_01kx4h2jdafq8bk996nn92357r")
    .build();
client.tenants().preferences().items().delete(params);
```

```php PHP theme={null}
$result = $client->tenants->preferences->items->delete(
  'pt_01kx4h2jdafq8bk996nn92357r', tenantID: 'acme-corp'
);
```

```csharp C# theme={null}
ItemDeleteParams parameters = new()
{
    TenantID = "acme-corp",
    TopicID = "pt_01kx4h2jdafq8bk996nn92357r",
};

await client.Tenants.Preferences.Items.Delete(parameters);
```

```bash CLI theme={null}
courier tenants:preferences:items delete \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --topic-id pt_01kx4h2jdafq8bk996nn92357r
```

```text MCP theme={null}
With Courier MCP, remove acme-corp's default for that topic.
```

**4. Read the defaults back**

Read the tenant back to confirm its defaults. The `default_preferences` field on the returned tenant holds the topics you set. Call the [get tenant endpoint](/docs/api-reference/tenants/get-a-tenant):

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const tenant = await client.tenants.retrieve('acme-corp');

console.log(tenant.default_preferences);
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
tenant = client.tenants.retrieve("acme-corp")
print(tenant.default_preferences)
```

```bash cURL theme={null}
curl -X GET https://api.courier.com/tenants/acme-corp \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

tenant = courier.tenants.retrieve("acme-corp")

puts(tenant.default_preferences)
```

```go Go theme={null}
tenant, err := client.Tenants.Get(context.TODO(), "acme-corp")
```

```java Java theme={null}
Tenant tenant = client.tenants().retrieve("acme-corp");
```

```php PHP theme={null}
$tenant = $client->tenants->retrieve('acme-corp');
```

```csharp C# theme={null}
TenantRetrieveParams parameters = new() { TenantID = "acme-corp" };

var tenant = await client.Tenants.Retrieve(parameters);
```

```bash CLI theme={null}
courier tenants retrieve \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp
```

```text MCP theme={null}
With Courier MCP, show me acme-corp's tenant settings and default preferences.
```

**5. Verify the tenant default**

Pick a user with no preference set for the Topic. Send them a message mapped to it in the Tenant's context, including `tenant_id`. Confirm delivery follows the Tenant default, not the workspace default.

## How tenant defaults apply

* **A user's preference read shows the topic default, not the tenant's.** The call returns the topic-level `default_status` even when [scoped to the tenant
  DOC](/docs/recipients/preferences/api#scope-to-a-tenant). Read the tenant itself for its defaults, and use a test send to confirm what a user receives.
* **A tenant default applies to sends that carry the tenant.** A send without `tenant_id` uses the workspace default, unless auto-infer resolves the tenant for you.


# Send with a tenant
Source: https://www.courier.com/docs/tenants/send

Send to a user or a whole tenant with tenant_id, and handle users in several tenants.

> [!NOTE]
>
> [How tenant context works
> DOC](/docs/tenants/context) covers the concepts behind this page.

The user determines who receives the message. The tenant determines which of that user's contexts Courier builds it from: whose brand, whose defaults, whose content.

You can target a single user in a tenant's context, fan out to every member of a tenant, or walk a tenant hierarchy up or down.

**The tenant goes in one of two places, and both behave identically.** Put it on the recipient as `to.tenant_id`, or on the message as `context.tenant_id`. Pick one and put it behind a shared helper, because tracking down a message that rendered with the wrong brand is a great deal harder when two call sites disagree about where the tenant lives.

## Prerequisites

* [A tenant with member users
  DOC](/docs/tenants/overview)
* [A Courier API key](https://app.courier.com/settings/api-keys)

## Send to a user with tenant context

Set `context.tenant_id` on a recipient to attach the tenant's metadata, preferences, and branding to their message. User-level preferences and profile data take precedence over the tenant's.

The template holds the content. Pass the variables it expects in `data`, and reference tenant values like `{$.tenant.name}` from inside the template, where the tenant context resolves them.

```javascript Node.js highlight={14} theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const { requestId } = await client.send.message({
  message: {
    to: {
      user_id: 'user_123',
      context: { tenant_id: 'acme-corp' },
    },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { first_name: 'Sarah' },
    routing: { method: 'single', channels: ['inbox'] },
  },
});

console.log(requestId);
```

```python Python highlight={14} theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
            "context": {"tenant_id": "acme-corp"},
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"first_name": "Sarah"},
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)
print(response.request_id)
```

```bash cURL highlight={8} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123", "context": { "tenant_id": "acme-corp" } },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "first_name": "Sarah" },
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'
```

```ruby Ruby highlight={12} theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123",
      context: { tenant_id: "acme-corp" }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { first_name: "Sarah" },
    routing: { method: "single", channels: ["inbox"] }
  }
)

puts(response)
```

```go Go highlight={10} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID:  courier.String("user_123"),
				Context: shared.MessageContextParam{TenantID: courier.String("acme-corp")},
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"first_name": "Sarah",
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("inbox")}},
		},
	},
})
```

```java Java highlight={7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of(
            "user_id", "user_123",
            "context", java.util.Map.of("tenant_id", "acme-corp"))))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("first_name", "Sarah")))
        .routing(JsonValue.from(java.util.Map.of(
            "method", "single",
            "channels", java.util.List.of("inbox"))))
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={8} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'userID' => 'user_123',
      'context' => ['tenantID' => 'acme-corp'],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['first_name' => 'Sarah'],
    'routing' => ['method' => 'single', 'channels' => ['inbox']],
  ],
);
```

```csharp C# highlight={7} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123", Context = new MessageContext { TenantID = "acme-corp" } },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "first_name", JsonSerializer.SerializeToElement("Sarah") },
        },
        Routing = new Routing { Method = Method.Single, Channels = ["inbox"] },
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123","context":{"tenant_id":"acme-corp"}},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"first_name":"Sarah"},"routing":{"method":"single","channels":["inbox"]}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with acme-corp as their tenant context.
```

A user doesn't need to be a member of the tenant to receive a message in its context. This is useful when the tenant holds branding or credentials but you aren't fanning out to members.

## Send to every member of a tenant

Put a `tenant_id` in `to` and Courier looks up the tenant's members and sends to each one.

```javascript Node.js highlight={9} theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const { requestId } = await client.send.message({
  message: {
    to: { tenant_id: 'acme-corp' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { first_name: 'Sarah' },
    routing: { method: 'single', channels: ['inbox'] },
  },
});

console.log(requestId);
```

```python Python highlight={9} theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "to": {"tenant_id": "acme-corp"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"first_name": "Sarah"},
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)
print(response.request_id)
```

```bash cURL highlight={6} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "tenant_id": "acme-corp" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "first_name": "Sarah" },
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'
```

```ruby Ruby highlight={7} theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    to: { tenant_id: "acme-corp" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { first_name: "Sarah" },
    routing: { method: "single", channels: ["inbox"] }
  }
)

puts(response)
```

```go Go highlight={5} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				TenantID: courier.String("acme-corp"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"first_name": "Sarah",
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("inbox")}},
		},
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("tenant_id", "acme-corp")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("first_name", "Sarah")))
        .routing(JsonValue.from(java.util.Map.of(
            "method", "single",
            "channels", java.util.List.of("inbox"))))
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={3} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['tenantID' => 'acme-corp'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['first_name' => 'Sarah'],
    'routing' => ['method' => 'single', 'channels' => ['inbox']],
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { TenantID = "acme-corp" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "first_name", JsonSerializer.SerializeToElement("Sarah") },
        },
        Routing = new Routing { Method = Method.Single, Channels = ["inbox"] },
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"tenant_id":"acme-corp"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"first_name":"Sarah"},"routing":{"method":"single","channels":["inbox"]}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to every member of acme-corp.
```

## Send to multiple users with shared context

When sending to an array of users, set a shared tenant at the message level with `message.context.tenant_id`. Every recipient inherits it. Override it for a specific recipient by setting `context.tenant_id` on that entry, which takes precedence over the message-level context.

```javascript Node.js highlight={10,14} theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const { requestId } = await client.send.message({
  message: {
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    context: { tenant_id: 'acme-corp' },
    to: [
      { user_id: 'user_123' },
      { user_id: 'user_456' },
      { user_id: 'user_456', context: { tenant_id: 'beta-inc' } },
    ],
  },
});

console.log(requestId);
```

```python Python highlight={10,14} theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "context": {"tenant_id": "acme-corp"},
        "to": [
            {"user_id": "user_123"},
            {"user_id": "user_456"},
            {"user_id": "user_456", "context": {"tenant_id": "beta-inc"}},
        ],
    },
)
print(response.request_id)
```

```bash cURL highlight={7,11} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "context": { "tenant_id": "acme-corp" },
      "to": [
        { "user_id": "user_123" },
        { "user_id": "user_456" },
        { "user_id": "user_456", "context": { "tenant_id": "beta-inc" } }
      ]
    }
  }'
```

```ruby Ruby highlight={8,12} theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    context: { tenant_id: "acme-corp" },
    to: [
      { user_id: "user_123" },
      { user_id: "user_456" },
      { user_id: "user_456", context: { tenant_id: "beta-inc" } }
    ]
  }
)

puts(response)
```

```go Go highlight={4,11} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Context:  shared.MessageContextParam{TenantID: courier.String("acme-corp")},
		To: courier.SendMessageParamsMessageToUnion{
			OfSendMessagesMessageToArray: []courier.SendMessageParamsMessageToArrayItemUnion{
				{OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")}},
				{OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_456")}},
				{OfUserRecipient: &shared.UserRecipientParam{
					UserID:  courier.String("user_456"),
					Context: shared.MessageContextParam{TenantID: courier.String("beta-inc")},
				}},
			},
		},
	},
})
```

```java Java highlight={4,8} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .context(JsonValue.from(java.util.Map.of("tenant_id", "acme-corp")))
        .to(JsonValue.from(java.util.List.of(
            java.util.Map.of("user_id", "user_123"),
            java.util.Map.of("user_id", "user_456"),
            java.util.Map.of("user_id", "user_456", "context", java.util.Map.of("tenant_id", "beta-inc")))))
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={4,8} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'context' => ['tenantID' => 'acme-corp'],
    'to' => [
      ['userID' => 'user_123'],
      ['userID' => 'user_456'],
      ['userID' => 'user_456', 'context' => ['tenantID' => 'beta-inc']],
    ],
  ],
);
```

```csharp C# highlight={6,11} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Context = new MessageContext { TenantID = "acme-corp" },
        To = new List<Recipient>
        {
            new UserRecipient { UserID = "user_123" },
            new UserRecipient { UserID = "user_456" },
            new UserRecipient { UserID = "user_456", Context = new MessageContext { TenantID = "beta-inc" } },
        },
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"template":"nt_01kx4h2jdafq8bk9aftxak4b40","context":{"tenant_id":"acme-corp"},"to":[{"user_id":"user_123"},{"user_id":"user_456"},{"user_id":"user_456","context":{"tenant_id":"beta-inc"}}]}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 and user_456 in acme-corp, and user_456 in beta-inc.
```

Here `user_123` and `user_456` get Acme Corp's context, while `user_456` gets Beta Inc's.

## Handle users in multiple tenants

Courier infers the tenant for a user who belongs to exactly one tenant, so specifying it is optional for them. A user with two or more memberships must have `context.tenant_id` set, or the send returns `Tenant Context Not Found`.

> [!NOTE]
>
> In the `tenant/<template_id>` format, `tenant` is the literal word rather than your tenant ID, which goes in `context.tenant_id`. [Create & manage tenant templates
> DOC](/docs/tenants/templates) has the full format.

## Fan out across a hierarchy

Set `include_children: true` to also send to users in a tenant's descendant tenants, or `include_parent: true` to walk upward through its ancestors.

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const { requestId } = await client.send.message({
  message: {
    to: { tenant_id: 'acme-corp', include_children: true },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    routing: { method: 'single', channels: ['inbox'] },
  },
});

console.log(requestId);
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "to": {"tenant_id": "acme-corp", "include_children": True},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)
print(response.request_id)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "tenant_id": "acme-corp", "include_children": true },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    to: { tenant_id: "acme-corp", include_children: true },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "single", channels: ["inbox"] }
  }
)

puts(response)
```

```go Go theme={null}
// include_children isn't in the typed recipient model, so set it as an extra field.
to := shared.UserRecipientParam{}
to.SetExtraFields(map[string]any{
	"tenant_id":        "acme-corp",
	"include_children": true,
})

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To:       courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("inbox")}},
		},
	},
})
```

```java Java theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of(
            "tenant_id", "acme-corp",
            "include_children", true)))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(JsonValue.from(java.util.Map.of(
            "method", "single",
            "channels", java.util.List.of("inbox"))))
        .build())
    .build();
client.send().message(params);
```

```php PHP theme={null}
$response = $client->send->message(
  message: [
    'to' => ['tenantID' => 'acme-corp', 'include_children' => true],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => ['method' => 'single', 'channels' => ['inbox']],
  ],
);
```

```csharp C# theme={null}
// include_children isn't in the typed recipient model, so build `to` from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = UserRecipient.FromRawUnchecked(new Dictionary<string, JsonElement>
        {
            ["tenant_id"] = JsonSerializer.SerializeToElement("acme-corp"),
            ["include_children"] = JsonSerializer.SerializeToElement(true),
        }),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new Routing { Method = Method.Single, Channels = ["inbox"] },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"tenant_id":"acme-corp","include_children":true},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","routing":{"method":"single","channels":["inbox"]}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to acme-corp and all of its child tenants.
```

Courier traverses up to four levels of the hierarchy in either direction.

> [!NOTE]
>
> On Go and C#, `include_children` and `include_parent` aren't in the typed recipient models yet, so the tabs above set them as extra fields on the recipient. Every other operation on this page has a fully typed Go and C# form.

## Segment delivery data by customer

Courier records the tenant on the message at `providers[].reference.tenantId`, so you can group logs and delivery data by customer after the fact. Read it from the [message record
DOC](/docs/monitor/overview) or from a [delivery webhook
DOC](/docs/monitor/webhooks/outbound).

A send that never named a tenant carries no reference, which is one more reason to route every multi-tenant send through the same helper.

## How tenant context resolves

* **Courier can apply a tenant you didn't name.** If the user belongs to exactly one tenant and the send specifies none, Courier loads that tenant's context anyway. See [auto-infer
  DOC](/docs/tenants/context#auto-infer-tenant-context), and turn it off in workspace settings if you would rather send unscoped.
* **A tenant-scoped inbox message appears only to a client signed in with that tenant.** Signing in without it shows only messages sent without a tenant, so this one stays hidden even though the send reports success. Pass the same `tenantId` to `signIn` that your sends carry.
* **Hierarchy traversal stops at four levels.** The window starts at the tenant you sent to rather than at the root, so a fifth ancestor's settings don't apply to the message.

## Verify

**1. Send with a branded tenant**

Send with a tenant that has a `brand_id` set, and confirm the message renders with that tenant's brand (see [brand selection
DOC](/docs/tenants/context#how-a-send-picks-a-brand)).

**2. Check the message log**

Confirm the send used the tenant's preferences, not the workspace defaults.

**3. Confirm fan-out delivery**

For a fan-out send, confirm each expected member received a copy.


# Tenant templates
Source: https://www.courier.com/docs/tenants/templates

Give one customer its own version of a template without changing how you send.

> [!NOTE]
>
> [How tenant context works
> DOC](/docs/tenants/context) covers the concepts behind this page.

A tenant template overrides one of your templates for a single customer, keyed by an id you choose. Their admin can rewrite the copy in their own voice, and only their users see it. Everyone else keeps the default.

You create, publish, and delete tenant templates through the API, then reference them in a send with the `tenant/<template_id>` format.

**A tenant template isn't a separate template you have to route to.** Your send logic doesn't branch on which customer it is for. It names the same id every time, and Courier merges the tenant's version over the message when one exists.

**Leave the `tenant/` prefix off and the send succeeds with the wrong content.** Courier reads `template: "welcome"` as your workspace template and renders that, because a template id that resolves isn't an error. The customer's edits aren't in the message.

> [!NOTE]
>
> Tenant templates have no console UI, so create, list, and delete them through the API, as every step below does. To hand the editing to your customer instead, [embed the designer
> GUIDE](/docs/guides/let-customers-edit-notifications) in your own app.

## Prerequisites

* [A tenant
  DOC](/docs/tenants/overview)
* [A Courier API key](https://app.courier.com/settings/api-keys)

## Manage tenant templates

**1. Create or update a tenant template**

Create or replace a tenant's template with the [create-or-update endpoint](/docs/api-reference/tenant-templates/create-or-update-a-tenant-template). The `template_id` is an ID you choose for this tenant's template. Every element sits inside a `channel` block, the same rule [workspace templates
DOC](/docs/design/templates/api#content-needs-a-channel-to-live-in) follow.

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const response = await client.tenants.templates.replace('welcome', {
  tenant_id: 'acme-corp',
  template: {
    content: {
      version: '2022-01-01',
      elements: [
        {
          type: 'channel',
          channel: 'email',
          elements: [{ type: 'text', content: 'Welcome to Acme Corp!' }],
        },
      ],
    },
  },
});

console.log(response.id);
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.tenants.templates.replace(
    template_id="welcome",
    tenant_id="acme-corp",
    template={
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "channel",
                    "channel": "email",
                    "elements": [{"type": "text", "content": "Welcome to Acme Corp!"}],
                }
            ],
        }
    },
)
print(response.id)
```

```bash cURL wrap theme={null}
curl -X PUT https://api.courier.com/tenants/acme-corp/templates/welcome \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "channel",
            "channel": "email",
            "elements": [{ "type": "text", "content": "Welcome to Acme Corp!" }]
          }
        ]
      }
    }
  }'
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.tenants.templates.replace(
  "welcome",
  tenant_id: "acme-corp",
  template: {
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "channel",
          channel: "email",
          elements: [{ type: "text", content: "Welcome to Acme Corp!" }]
        }
      ]
    }
  }
)

puts(response)
```

```go Go theme={null}
// The typed elemental model has no field for a channel's child elements, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [{ "type": "text", "content": "Welcome to Acme Corp!" }]
    }
  ]
}`))

response, err := client.Tenants.Templates.Replace(
	context.TODO(),
	"welcome",
	courier.TenantTemplateReplaceParams{
		TenantID: "acme-corp",
		PutTenantTemplateRequest: courier.PutTenantTemplateRequestParam{
			Template: courier.TenantTemplateInputParam{Content: content},
		},
	},
)
```

```java Java theme={null}
TemplateReplaceParams params = TemplateReplaceParams.builder()
    .tenantId("acme-corp")
    .templateId("welcome")
    .putTenantTemplateRequest(PutTenantTemplateRequest.builder()
        .template(TenantTemplateInput.builder()
            .content(ElementalContent.builder()
                // The channel builder has no addElement, so its children go in as an additional property.
                .addElement(ElementalChannelNodeWithType.builder()
                    .type(ElementalChannelNodeWithType.Type.CHANNEL)
                    .channel("email")
                    .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                        java.util.Map.of("type", "text", "content", "Welcome to Acme Corp!"))))
                    .build())
                .version("2022-01-01")
                .build())
            .build())
        .build())
    .build();
client.tenants().templates().replace(params);
```

```php PHP theme={null}
$response = $client->tenants->templates->replace(
  'welcome',
  tenantID: 'acme-corp',
  template: [
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'channel',
          'channel' => 'email',
          'elements' => [['type' => 'text', 'content' => 'Welcome to Acme Corp!']],
        ],
      ],
    ],
  ],
);
```

```csharp C# theme={null}
TemplateReplaceParams parameters = new()
{
    TenantID = "acme-corp",
    TemplateID = "welcome",
    Template = new()
    {
        Content = new()
        {
            Version = "2022-01-01",
            Elements =
            [
                // Elemental nodes expose no typed content property, so build the node from raw JSON.
                ElementalChannelNodeWithType.FromRawUnchecked(
                    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                    {
                      "type": "channel",
                      "channel": "email",
                      "elements": [{ "type": "text", "content": "Welcome to Acme Corp!" }]
                    }
                    """)),
            ],
        },
    },
};

await client.Tenants.Templates.Replace(parameters);
```

```bash CLI theme={null}
courier tenants:templates replace \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --template-id welcome \
  --template '{"content":{"version":"2022-01-01","elements":[{"type":"channel","channel":"email","elements":[{"type":"text","content":"Welcome to Acme Corp!"}]}]}}'
```

```text MCP theme={null}
With Courier MCP, create a welcome template for acme-corp that greets their users.
```

**2. Publish the template**

Changes take effect once published. [Publish the current draft](/docs/api-reference/tenant-templates/publish-a-tenant-template) to make it live.

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const response = await client.tenants.templates.publish('welcome', {
  tenant_id: 'acme-corp',
});

console.log(response.id);
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.tenants.templates.publish(
    template_id="welcome",
    tenant_id="acme-corp",
)
print(response.id)
```

```bash cURL wrap theme={null}
curl -X POST https://api.courier.com/tenants/acme-corp/templates/welcome/publish \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.tenants.templates.publish("welcome", tenant_id: "acme-corp")

puts(response)
```

```go Go theme={null}
response, err := client.Tenants.Templates.Publish(
	context.TODO(),
	"welcome",
	courier.TenantTemplatePublishParams{
		TenantID: "acme-corp",
	},
)
```

```java Java theme={null}
TemplatePublishParams params = TemplatePublishParams.builder()
    .tenantId("acme-corp")
    .templateId("welcome")
    .build();
client.tenants().templates().publish(params);
```

```php PHP theme={null}
$response = $client->tenants->templates->publish(
  'welcome', tenantID: 'acme-corp'
);
```

```csharp C# theme={null}
TemplatePublishParams parameters = new()
{
    TenantID = "acme-corp",
    TemplateID = "welcome",
};

await client.Tenants.Templates.Publish(parameters);
```

```bash CLI theme={null}
courier tenants:templates publish \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --template-id welcome
```

```text MCP theme={null}
With Courier MCP, publish acme-corp's welcome template.
```

**3. List and read templates**

[List a tenant's templates](/docs/api-reference/tenant-templates/list-templates-in-tenant), [read one](/docs/api-reference/tenant-templates/get-a-template-in-tenant), or read a [specific version](/docs/api-reference/tenant-templates/get-a-template-version).

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const templates = await client.tenants.templates.list('acme-corp');

console.log(templates.has_more);
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
templates = client.tenants.templates.list(
    tenant_id="acme-corp",
)
print(templates.has_more)
```

```bash cURL wrap theme={null}
curl -X GET https://api.courier.com/tenants/acme-corp/templates \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

templates = courier.tenants.templates.list("acme-corp")

puts(templates)
```

```go Go theme={null}
templates, err := client.Tenants.Templates.List(
	context.TODO(),
	"acme-corp",
	courier.TenantTemplateListParams{},
)
```

```java Java theme={null}
TemplateListResponse templates = client.tenants().templates().list("acme-corp");
```

```php PHP theme={null}
$templates = $client->tenants->templates->list('acme-corp');
```

```csharp C# theme={null}
TemplateListParams parameters = new() { TenantID = "acme-corp" };

var templates = await client.Tenants.Templates.List(parameters);
```

```bash CLI theme={null}
courier tenants:templates list \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp
```

```text MCP theme={null}
With Courier MCP, list acme-corp's templates.
```

**4. Delete a template**

[Deleting a tenant template](/docs/api-reference/tenant-templates/delete-a-tenant-template) removes it. Tenant templates are managed through the API, so this is how you remove one.

```javascript Node.js theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

await client.tenants.templates.delete('welcome', { tenant_id: 'acme-corp' });
```

```python Python theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
client.tenants.templates.delete(
    template_id="welcome",
    tenant_id="acme-corp",
)
```

```bash cURL wrap theme={null}
curl -X DELETE https://api.courier.com/tenants/acme-corp/templates/welcome \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

result = courier.tenants.templates.delete("welcome", tenant_id: "acme-corp")

puts(result)
```

```go Go theme={null}
err := client.Tenants.Templates.Delete(
	context.TODO(),
	"welcome",
	courier.TenantTemplateDeleteParams{
		TenantID: "acme-corp",
	},
)
```

```java Java theme={null}
TemplateDeleteParams params = TemplateDeleteParams.builder()
    .tenantId("acme-corp")
    .templateId("welcome")
    .build();
client.tenants().templates().delete(params);
```

```php PHP theme={null}
$result = $client->tenants->templates->delete(
  'welcome', tenantID: 'acme-corp'
);
```

```csharp C# theme={null}
TemplateDeleteParams parameters = new()
{
    TenantID = "acme-corp",
    TemplateID = "welcome",
};

await client.Tenants.Templates.Delete(parameters);
```

```bash CLI theme={null}
courier tenants:templates delete \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --template-id welcome
```

```text MCP theme={null}
With Courier MCP, delete acme-corp's welcome template.
```

**5. Send with the tenant template**

Reference the tenant template in a send with `template: "tenant/<template_id>"`, and set the tenant in the context. The word `tenant` is literal. Your tenant ID goes in `context.tenant_id`.

```javascript Node.js highlight={9} theme={null}
import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const { requestId } = await client.send.message({
  message: {
    template: 'tenant/welcome',
    context: { tenant_id: 'acme-corp' },
    to: { user_id: 'user_123' },
  },
});

console.log(requestId);
```

```python Python highlight={9} theme={null}
import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "template": "tenant/welcome",
        "context": {"tenant_id": "acme-corp"},
        "to": {"user_id": "user_123"},
    },
)
print(response.request_id)
```

```bash cURL highlight={6} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "tenant/welcome",
      "context": { "tenant_id": "acme-corp" },
      "to": { "user_id": "user_123" }
    }
  }'
```

```ruby Ruby highlight={7} theme={null}
require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    template: "tenant/welcome",
    context: { tenant_id: "acme-corp" },
    to: { user_id: "user_123" }
  }
)

puts(response)
```

```go Go highlight={3} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		Template: courier.String("tenant/welcome"),
		Context:  shared.MessageContextParam{TenantID: courier.String("acme-corp")},
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
	},
})
```

```java Java highlight={3} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .template("tenant/welcome")
        .context(JsonValue.from(java.util.Map.of("tenant_id", "acme-corp")))
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .build())
    .build();
client.send().message(params);
```

```php PHP highlight={3} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'tenant/welcome',
    'context' => ['tenantID' => 'acme-corp'],
    'to' => ['userID' => 'user_123'],
  ],
);
```

```csharp C# highlight={5} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        Template = "tenant/welcome",
        Context = new MessageContext { TenantID = "acme-corp" },
        To = new UserRecipient { UserID = "user_123" },
    },
};

await client.Send.Message(parameters);
```

```bash CLI highlight={3} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"template":"tenant/welcome","context":{"tenant_id":"acme-corp"},"to":{"user_id":"user_123"}}'
```

```text MCP theme={null}
With Courier MCP, send acme-corp's welcome template to user_123.
```

At send time, Courier merges the tenant template's content over the message and routes it normally.

**6. Verify the template**

After publishing, [read the template back](/docs/api-reference/tenant-templates/get-a-template-in-tenant) and confirm the content is what you sent. Then send with `template: "tenant/<template_id>"` in the tenant's context and check the message log to confirm the tenant's content rendered.

## Limits & behavior

* **Publish to make a change live.** Creating or replacing a tenant template writes a draft. Sends keep rendering the last published version until you publish.
* **The tenant ID sits in a different place per method.** `list` takes it positionally, while `retrieve`, `replace`, and `publish` take it in the body. Your SDK's `resources/tenants/` types have the exact signatures.


# Audit trail
Source: https://www.courier.com/docs/workspaces/audit-trail

A log of API key rotations, role changes, publishes, and integration edits, with who and when.

Courier records every API key rotation, role change, publish, and integration edit.

Use it for compliance and security review, in the console or through the Audit Events API.

## How it works

### What it records

The audit trail captures configuration and access changes across the workspace:

* **API keys**: created, deleted, rotated.
* **Users**: invited, role changed, deleted, logged out.
* **Workspace settings**: name, discoverability, SSO-required, tracking toggles, guard rails.
* **Templates**: published, deleted, duplicated, draft created, rolled back, topic changed.
* **Brands**: created, updated, published, deleted, default changed.
* **Automations**: template published or deleted.
* **Preferences**: page published, topic/section created or deleted, channels changed, default status changed.
* **Outbound integrations**: Segment, Rudderstack, Datadog, and New Relic source changes.

Each event records the actor, the target that changed, the source, a timestamp, and the event type. It records workspace changes, not message delivery. For delivery history see [logs
DOC](/docs/monitor/overview).

### Reading the audit trail

Review events in the console under **Settings**, or pull them over the API. [List Audit Events](/docs/api-reference/audit-events/list-audit-events) is cursor-paginated, and [Get an Audit Event](/docs/api-reference/audit-events/get-an-audit-event) reads one. Use the API to forward events to a SIEM, an external log store, or a compliance dashboard.

```javascript Node.js theme={null}
const auditEvents = await client.auditEvents.list();

for (const event of auditEvents.results) {
  console.log(event.type, event.actor.email, event.timestamp);
}
```

```python Python theme={null}
audit_events = client.audit_events.list()

for event in audit_events.results:
    print(event.type, event.actor.email, event.timestamp)
```

```bash cURL theme={null}
curl https://api.courier.com/audit-events \
  -H "Authorization: Bearer $COURIER_API_KEY"
```

```ruby Ruby theme={null}
audit_events = courier.audit_events.list

audit_events.results.each do |event|
  puts "#{event.type} #{event.actor.email} #{event.timestamp}"
end
```

```go Go theme={null}
auditEvents, err := client.AuditEvents.List(context.TODO(), courier.AuditEventListParams{})
if err != nil {
	panic(err)
}

for _, event := range auditEvents.Results {
	fmt.Println(event.Type, event.Timestamp)
}
```

```java Java theme={null}
AuditEventListResponse auditEvents =
    client.auditEvents().list(AuditEventListParams.builder().build());

auditEvents.results().forEach(event ->
    System.out.println(event.type() + " " + event.timestamp()));
```

```php PHP theme={null}
$auditEvents = $client->auditEvents->list();

foreach ($auditEvents->results as $event) {
  echo $event->type . ' ' . $event->timestamp . PHP_EOL;
}
```

```csharp C# theme={null}
var auditEvents = await client.AuditEvents.List(new());

foreach (var auditEvent in auditEvents.Results)
{
    Console.WriteLine($"{auditEvent.Type} {auditEvent.Timestamp}");
}
```

```bash CLI theme={null}
courier audit-events list \
  --api-key "$COURIER_API_KEY"
```

```text MCP theme={null}
With Courier MCP, list this workspace's audit events.
```

The audit trail requires the **Enterprise** plan. [Contact Courier](https://www.courier.com/request-demo) to enable it for your workspace.

## FAQ

> **Can I pull audit events into my own system?**
>
> Use [List Audit Events](/docs/api-reference/audit-events/list-audit-events) to page through events and forward them to a SIEM, log store, or dashboard. Each event includes the actor, target, source, type, and timestamp.

> **Does the audit trail show message deliveries?**
>
> The audit trail records workspace and access changes. For delivery history, use [message logs
> DOC](/docs/monitor/overview).


# Billing: sends, AI credits, and device previews
Source: https://www.courier.com/docs/workspaces/billing

What Courier bills for: message sends, AI credits, and the Device Preview add-on. Plan pricing, how each one is counted, and common billing questions.

Your Courier bill has up to three parts, each metered separately:

| What | How it's counted | How you pay |
| :- | :- | :- |
| Message sends | One unit per template send, per recipient | Per send, set by your plan |
| AI credits | Per AI journey node run or AI Translation request | Credit packs, 100 credits per \$1 |
| Device previews | One preview per device in a run | Monthly add-on, plus overage |

## Message sends

Your plan sets the price per send:

| Plan | Price |
| :- | :- |
| Developer | Free for 10,000 sends a month |
| Business | \$0.005 for every send, with a credit card on file |
| Enterprise | Custom volume pricing below \$0.005 per send |

Adding a credit card to a Developer workspace moves it to Business. [Courier pricing](https://www.courier.com/pricing) has the current plans.

### How sends are counted

One send is one template sent to one recipient. **A multi-channel template counts as one send**, even when it delivers separate messages over email, SMS, and push:

| Scenario | Units |
| - | - |
| One email to Sarah Bennett | 1 |
| Email, push, and Slack to Sarah Bennett via one profile | 1 |
| One send to a list of 100 users | 100 |
| One send to three recipients by email address | 3 |

A send counts whether or not the provider delivers it. Undeliverable messages and messages blocked by preferences count too. Sends from every [environment
DOC](/docs/workspaces/environments) count, including Test and custom environments.

The per-send price covers every channel, including Courier Inbox, which has no fee of its own. The providers you connect, such as SendGrid or Twilio, bill you separately under their own pricing.

## AI credits

AI credits pay for [AI journey nodes
DOC](/docs/journeys/nodes/ai) and [AI Translation
DOC](/docs/design/elemental/locales#translate-in-design-studio), and both draw from one balance. Credits cost \$1 per 100, and you buy them in packs in the console on the Business or Enterprise plan. They're billed separately from your sends.

* AI journey nodes cost a set number of credits per run for the model you pick, plus overage past 3,072 input tokens or 1,000 output tokens. A journey test run that reaches an AI node costs the same as a real one. The per-model costs are in [AI node billing
  DOC](/docs/journeys/nodes/ai#billing).
* AI Translation costs 2.5 credits per translation request, plus token overages. A long template can take more than one request per locale.

Auto top-up buys another pack when your balance falls below a threshold, 100 credits by default.

## Device previews

[Device Preview
DOC](/docs/design/templates/device-preview) is a paid monthly add-on, so it needs a credit card on file. Enable it in [Settings → Billing](https://app.courier.com/settings/billing).

Each device in a run counts as one preview. The add-on comes in three tiers, each with a set number of previews a month. Each preview past that bills as overage:

| Monthly price | Previews included | Overage per preview |
| -: | -: | -: |
| \$20 | 100 | \$0.20 |
| \$50 | 400 | \$0.15 |
| \$100 | 1,000 | \$0.12 |

Included previews reset monthly and don't roll over. A run request that Courier rejects isn't billed.

## FAQ

### Plans and send pricing

> **How much does Courier cost?**
>
> Courier has three plans. Developer is free for 10,000 sends a month. Business is pay-as-you-go at $0.005 for every send. Enterprise has custom volume pricing below $0.005 per send. Pricing is based on sends, not on seats or channels.

> **Does Courier have a free plan?**
>
> The Developer plan is free and includes 10,000 sends a month, journeys, broadcasts, the MCP server, the CLI, and the SDKs.

> **How do I estimate my monthly bill on the Business plan?**
>
> Your send cost on Business is `monthly sends × $0.005`, counting every send. For example, 50,000 sends a month costs $250, 200,000 costs $1,000, and 1,000,000 costs \$5,000. AI credits and the Device Preview add-on bill on top of that.

> **What happens when I go over 10,000 sends a month?**
>
> Sending more than 10,000 a month takes the Business plan, which you get by adding a credit card. Business charges \$0.005 for every send, including the first 10,000, with no seat or channel fees.

> **How do I upgrade to the Business plan?**
>
> Add a credit card in [Settings → Billing](https://app.courier.com/settings/billing). A workspace with a card on file is on the Business plan, which also unlocks AI credits and the Device Preview add-on.

> **Does Courier offer volume discounts?**
>
> The Enterprise plan has custom volume pricing below \$0.005 per send, quoted by Courier's sales team based on your volume. It also adds role-based access control, observability integrations, a dedicated Slack channel, and an enterprise SLA.

> **Does Courier charge per seat or per channel?**
>
> Courier charges per send only, so adding teammates or channels doesn't change your bill.

> **Does Courier's price include provider fees, such as SMS or email provider charges?**
>
> Courier's per-send price covers Courier. Every provider you connect, for email, SMS, push, or chat, bills you its own fees, such as per SMS segment. Courier Inbox, the in-app channel, has no fee beyond the per-send price.

> **Does it cost extra to send from an AI agent?**
>
> Sending from an AI agent costs the same as any other send. Agents use Courier's MCP server, CLI, or SDKs, all included on the free Developer plan, and there's no per-agent fee.

> **Why is my new workspace on the Developer plan?**
>
> A new workspace isn't attached to an existing Enterprise contract or plan. If your contract covers multiple workspaces, contact your Courier account team or [support](mailto:support@courier.com) to add the new workspace to your plan.

> **Who can change the plan or payment method?**
>
> Administrators manage billing, including the plan and payment method. The Manager role doesn't include billing. With [custom roles
> DOC](/docs/workspaces/team-access#custom-role-scopes), the `billing` scope grants `ViewBilling`, `UpdatePaymentMethod`, and `UpdatePlan`.

### Counting sends

> **What counts as a send?**
>
> A send is one template sent to one recipient. A multi-channel template counts as one send, even when it delivers separate messages over email, SMS, push, Slack, and Inbox.

> **Do test sends count toward my bill?**
>
> Sends made with a Test key count the same as Production sends, and so do sends from custom environments.

> **Do undelivered messages count?**
>
> A send counts whether or not the provider delivers it, so bounced and undeliverable messages count.

> **How are sends to a list or audience counted?**
>
> A send to a list or audience counts once per recipient. A send to a list of 100 users is 100 sends.

> **How can I reduce my send count?**
>
> [Digests
> DOC](/docs/journeys/nodes/digest) and [batching
> DOC](/docs/journeys/nodes/batch) combine several events into one notification, so a user gets one send instead of many. That lowers your Courier bill and your provider costs.

### AI credit costs

> **What do AI credits cost?**
>
> AI credits cost \$1 per 100 credits. You buy them as packs in the console, billed separately from your sends.

> **Which plans can use AI credits?**
>
> AI credits are available on the Business and Enterprise plans. On the Developer plan, credit packs can't be bought and AI journey nodes can't be placed on the canvas.

> **What uses AI credits?**
>
> AI journey nodes and AI Translation both use AI credits, and they draw from the same balance.

> **How many credits does an AI journey node use?**
>
> An AI journey node uses a fixed number of credits per run for the model you pick, plus overage when the input passes 3,072 tokens or the output passes 1,000 tokens. Web search on Anthropic models adds 2 credits per run. [AI node billing
> DOC](/docs/journeys/nodes/ai#billing) lists the cost of every model.

> **How much does AI Translation cost?**
>
> AI Translation costs 2.5 credits per translation request, plus token overages. A long template can take more than one request per locale.

> **Do journey test runs use AI credits?**
>
> A journey test run that reaches an AI node uses the same credits as a real run, because it calls the same model.

> **Does a skipped AI node use credits?**
>
> An AI node whose conditions aren't met is skipped and uses no credits.

> **How does auto top-up work?**
>
> Auto top-up charges your card for another credit pack when your balance falls below a threshold. The default threshold is 100 credits.

### Device preview costs

> **How much does Device Preview cost?**
>
> Device Preview is a monthly add-on in three tiers. $20 a month includes 100 previews, then $0.20 each. $50 includes 400, then $0.15 each. $100 includes 1,000, then $0.12 each.

> **What counts as one preview?**
>
> Each device in a run is one preview. A run across 12 email clients uses 12 previews.

> **Do unused previews roll over?**
>
> Included previews reset each month and don't roll over.

> **Am I billed for a rejected preview run?**
>
> Courier checks a run request before the run exists, so a rejected request isn't billed.

> **How do I turn on Device Preview?**
>
> Enable the Device Preview add-on in [Settings → Billing](https://app.courier.com/settings/billing). It needs a credit card on file.


# Compliance: SOC 2, HIPAA, GDPR, and data requests
Source: https://www.courier.com/docs/workspaces/compliance

Courier's SOC 2 Type II, HIPAA, PCI DSS, GDPR, and CCPA programs, where to get the reports, and how to answer data access and deletion requests.

Courier maintains SOC 2 Type II, HIPAA, and PCI DSS programs, and supports your GDPR and CCPA obligations.

| Document | Where to get it |
| - | - |
| SOC 2 Type II report, HIPAA report, penetration test | [Courier Security Portal](https://security.courier.com/) |
| Data Processing Addendum (DPA) | [Courier's DPA](https://www.courier.com/data-processing-addendum) |
| Subprocessors and their regions | [Courier's subprocessor list](https://www.courier.com/subprocessors) |
| HIPAA Business Associate Agreement (BAA) | [Courier sales](https://www.courier.com/request-demo) |

For EU data residency, see [Regional datacenters
DOC](/docs/workspaces/datacenters). For how Courier protects your data, see [Security
DOC](/docs/workspaces/security).

## Personal data in logs

Message logs show the data you send, such as a recipient's email address or phone number. [Roles
DOC](/docs/workspaces/team-access#roles-and-permissions) control which teammates can see it, and [Logs
DOC](/docs/monitor/logs) lists how long each plan keeps it.

**Never send PHI in your notifications.** Keep protected health information out of message content and the data you pass to Courier.

## Data access and deletion requests

Handle data-subject requests through the API. Run them in each datacenter you've sent the user notifications through, because each datacenter keeps its own data.

**Export a user's data.** [Get a Profile](/docs/api-reference/user-profiles/get-a-profile) returns their stored profile.

**Delete a user's data.** Deleting the profile also removes their contact details and tenant memberships. List subscriptions and device tokens have their own delete calls:

| What it holds | Call |
| :- | :- |
| Profile, contact details, tenant memberships | [Delete a Profile](/docs/api-reference/user-profiles/delete-a-profile) |
| List subscriptions | [Delete List subscriptions](/docs/api-reference/user-profiles/delete-list-subscriptions) |
| A device token | [Delete user token](/docs/api-reference/device-tokens/delete-user-token) |

To delete device tokens, list them with [List tokens](/docs/api-reference/device-tokens/list-tokens), then delete each one.

Preferences have no delete call. To clear them, replace them with an empty set using [Replace user Preferences in bulk](/docs/api-reference/user-preferences/replace-user-preferences-in-bulk).


# Regional datacenters: US and EU
Source: https://www.courier.com/docs/workspaces/datacenters

Courier runs separate US and EU datacenters. Send EU users' notifications through the EU datacenter to keep their data in Europe for data residency.

Courier has two datacenters: US and EU (Ireland). All data in the two datacenters is separate, and none of it is shared. Each keeps its own templates, brands, users, logs, and API keys. Your team signs in to both with the same email address.

| | US | EU |
| - | - | - |
| Console | `https://app.courier.com` | `https://app.eu.courier.com` |
| API | `https://api.courier.com` | `https://api.eu.courier.com` |
| Inbox | `https://inbox.courier.com` | `https://inbox.eu.courier.io` |
| Inbox real-time | `wss://realtime.courier.io` | `wss://realtime.eu.courier.io` |

Every SDK and the CLI use the US unless you point them at the EU. For certifications and subprocessors, see [Compliance
DOC](/docs/workspaces/compliance).

## Set up the EU datacenter

The EU datacenter is available on every paid plan: Business and Enterprise.

**1. Create your account**

Sign up at [app.courier.com](https://app.courier.com) if you don't have an account yet.

**2. Sign in to the EU console**

Sign in at [app.eu.courier.com](https://app.eu.courier.com) with the same email address, and open your workspace.

**3. Set up your EU workspace**

Set it up the way you set up your US workspace: copy its API keys, connect your providers, and add your templates and brands. Then send through the [EU API](#send-through-the-eu) and [connect your inbox to the EU](#connect-your-inbox-to-the-eu).

## Send through the EU

Every server SDK and the CLI read `COURIER_BASE_URL`. Set it to the EU API, and use an API key from your EU workspace:

```bash theme={null}
export COURIER_BASE_URL="https://api.eu.courier.com"
export COURIER_API_KEY="YOUR_COURIER_API_KEY"   # an API key from app.eu.courier.com
```

To set it in code instead, pass the base URL when you create the client:

| SDK | Option |
| - | - |
| Node.js | `baseURL` |
| Python | `base_url` |
| Ruby | `base_url:` |
| Go | `option.WithBaseURL(...)` |
| Java | `.baseUrl(...)` |
| PHP | `baseUrl:` |
| C# | `BaseUrl` |
| CLI | `--base-url` |

The [hosted MCP server
DOC](/docs/resources/mcp) works with your EU API key too.

## Connect your inbox to the EU

1. Your backend creates each user's inbox token with your EU API key, through `https://api.eu.courier.com`.
2. Your app signs the inbox in with the EU URLs.

[Connect to the EU datacenter
DOC](/docs/in-app/authenticate-users#connect-to-the-eu-datacenter) has the code for every SDK.

## FAQ

> **Can I move my data from the US to the EU?**
>
> Data you've already sent through the US stays in the US. [Set up your EU workspace](#set-up-the-eu-datacenter), then send new notifications through `https://api.eu.courier.com`.


# Environments and API keys
Source: https://www.courier.com/docs/workspaces/environments

Production, Test, and custom environments with separate API keys, templates, and logs, and how to migrate templates between them.

An environment is a separate copy of your Courier setup inside one workspace, the same way you run separate development, staging, and production deployments. The API key on each request decides which environment it reads from and writes to.

| Separate in each environment | Shared across the workspace |
| :- | :- |
| Templates, brands, and tags | Team members, and the [roles&#xA;DOC](/docs/workspaces/team-access) that set their access in each environment |
| Journeys and subscription topics | [Open and click tracking&#xA;DOC](/docs/monitor/tracking) settings |
| Provider integrations and their credentials | [Billing&#xA;DOC](/docs/workspaces/billing), which counts sends from every environment |
| API keys | |
| Logs and metrics | |

A change in one environment doesn't reach another until you [migrate
DOC](/docs/workspaces/environments#migrate-assets-between-environments) it.

## API keys

Every API key belongs to one environment, and the key you call Courier with decides where the request lands. Courier has no separate test mode: a Test key is what puts you in the Test environment. The prefix tells you what the key can do:

| Key | Prefix | What it does |
| :- | :- | :- |
| Published | `pk_…` | Sends with the latest published version of each template, through that environment's integrations |
| Draft | `dk_…` | Renders unpublished template changes against real payloads, so you catch a rendering bug before publishing |

Create a separate key for each service so you can rotate or revoke one without breaking the others. Use API keys only in server-side code, and use Test keys during development. A browser or mobile app signs in with a JWT that your backend mints, as [Authenticate users
DOC](/docs/in-app/authenticate-users) shows.

Create and rotate keys in [Settings → API Keys](https://app.courier.com/settings/api-keys).

## Production, Test, and custom environments

Every workspace starts with **Production** and **Test**. A workspace can have up to 20 environments, so you can add up to 18 custom ones, such as Staging or QA. Archived environments don't count toward the limit. To create one, open the environment dropdown at the top of the console and select **New Environment**. You can rename any environment except Production.

Switch environments from the same dropdown. Switching changes only your view, never live notifications.

### Email in the Test environment

A new workspace's Test environment comes with a testing email provider already configured, so you can send before connecting anything of your own.

That provider **only delivers to the address you signed up with**. You can develop against real sends with no chance of reaching a customer, which also makes a Test key the right one to hand an [AI agent
GUIDE](/docs/guides/send-from-an-ai-agent).

To reach other addresses from Test, connect your own email provider to that environment, such as a sandbox SendGrid key. Integrations are per environment, so this doesn't change Production.

## Migrate assets between environments

To copy a template to another environment, open the ellipsis menu on the template in the templates page and choose **Migrate assets**. Courier copies the template with its dependencies: brands, tags, subscription topics, test events, and event maps. On later migrations, you choose whether to overwrite each copied dependency or keep the one already there. To copy to another workspace, pick it as the destination.

**Provider integrations stay in their own environment and aren't copied.** Before you send from a migrated template, configure its providers in the destination environment. The destination can use different credentials from the source.

## Logs and metrics by environment

Logs and metrics belong to the environment of the key that made the send. A Test-key send appears only in the Test environment's logs, and a Production-key send only in Production's.

## FAQ

> **Should I use separate workspaces or environments for staging?**
>
> Environments are the right fit for staging. Create a custom Staging environment in the same workspace. Separate workspaces are for separate billing, not for staging.

> **Why does a migrated template render but not deliver?**
>
> Provider integrations are per environment and aren't migrated. Configure the provider in the destination environment so the template has a channel to send through.


# Workspaces
Source: https://www.courier.com/docs/workspaces/overview

A workspace is the top-level container for brands, providers, templates, API keys, and users, and when to run more than one.

A workspace is the top-level container for everything in Courier.

It holds brands, providers, templates, API keys, user profiles, and analytics, and shares none of them with other workspaces. Environments inside a workspace separate release stages, so you build and test without touching live traffic.

## Workspace, environment, or tenant

Courier has three isolation layers, and they stack: a workspace contains environments, and within an environment you send to tenants. Pick the layer whose boundary you need. Choosing a workspace where you needed a tenant means maintaining two of every template.

| Layer | What it isolates | Use it when | ID |
| - | - | - | - |
| **Workspace** | Everything: brands, providers, templates, API keys, users, analytics | You need separate billing | `wrk_` |
| **Environment** | Config and data within a workspace (templates, integrations, keys, logs) | You want test and production (or staging) separated in one workspace | `env_` |
| **Tenant** | A recipient segment's brand, default preferences, and templates | You serve multiple customer organizations (B2B SaaS, white-label) from one account | a string you choose |

[Tenants
DOC](/docs/tenants/overview) covers when and how to use them.

## Environments and API keys

Every workspace starts with Production and Test environments, and you can add up to 18 custom ones, for 20 in total. Each API key belongs to one environment. [Environments and API keys
DOC](/docs/workspaces/environments) covers which key to use and how to move templates between environments.

## US and EU workspaces

If you use both the US and EU datacenters, you have a separate workspace in each. Each one keeps its own data in its own datacenter, and nothing is shared between them. See [Regional datacenters
DOC](/docs/workspaces/datacenters).

[Billing
DOC](/docs/workspaces/billing) covers what Courier bills for, including how a new workspace joins your plan.

## FAQ

> **Can I copy templates between workspaces?**
>
> The **Migrate assets** flow copies a template and its dependencies to another environment or another workspace in the same datacenter. Provider integrations aren't copied, so configure them in the destination. [Migrate assets
> DOC](/docs/workspaces/environments#migrate-assets-between-environments) has the details.
>
> To copy a template between your US and EU workspaces, use the [Templates API or the CLI
> DOC](/docs/design/templates/api#manage-templates-as-code). Read it with a key from one workspace, then create it with a key from the other.


# Security: how Courier protects your data
Source: https://www.courier.com/docs/workspaces/security

How Courier protects your notification data, and the controls you use to secure your workspace: SSO, roles, audit trail, API keys, and signed webhooks.

The [Courier Security Portal](https://security.courier.com/) has Courier's security practices in detail and the current reports. For certifications and data requests, see [Compliance
DOC](/docs/workspaces/compliance).

## How Courier protects your data

| Area | What Courier does |
| - | - |
| Infrastructure | Runs on AWS across multiple availability zones, inside a private network with firewalls and intrusion detection. |
| Encryption | Encrypts customer data at rest. The API accepts HTTPS only. |
| Backups | Backs up data daily. |
| Staff access | Staff use multi-factor authentication on internal systems, and access to customer data is restricted. |
| Testing | An independent firm runs a penetration test every year, and Courier manages vulnerabilities and patches. |
| Data location | Your data stays in the [datacenter&#xA;DOC](/docs/workspaces/datacenters) you send it through, US or EU. |

## Secure your workspace

| Control | What it does |
| - | - |
| [SSO and SCIM&#xA;DOC](/docs/workspaces/team-access#single-sign-on) | Teammates sign in through Google, GitHub, or Okta. SCIM creates, updates, and deactivates them from your directory. |
| [Roles&#xA;DOC](/docs/workspaces/team-access#roles-and-permissions) | Limit what each teammate can change and how much of a message log they see. |
| [Audit trail&#xA;DOC](/docs/workspaces/audit-trail) | Records API key rotations, role changes, publishes, and integration edits, with who and when. |
| [API keys&#xA;DOC](/docs/workspaces/environments#api-keys) | Each key is scoped to one environment and one permission level. |
| [Webhook signatures&#xA;DOC](/docs/monitor/webhooks/security) | Prove an outbound webhook came from Courier before you act on it. |
| [Inbox tokens&#xA;DOC](/docs/in-app/authenticate-users) | Your backend mints a JWT for each user, so the browser never holds your API key. |

## FAQ

> **Can I self-host Courier?**
>
> Courier is a managed cloud platform, with no self-hosted or on-premise option. To keep notification data in Europe, send through the [EU datacenter
> DOC](/docs/workspaces/datacenters).

> **How do I report a security issue?**
>
> Report it through Courier's [responsible disclosure policy](https://www.courier.com/responsible-disclosure-policy).

> **Where can I check Courier's uptime?**
>
> The [Courier status page](https://status.courier.com/) shows current incidents and uptime.


# Team access, roles, and SSO
Source: https://www.courier.com/docs/workspaces/team-access

Invite teammates, assign built-in or custom roles, and set up SSO and SCIM.

Team access controls who belongs to a workspace and what each person can do.

## How it works

### Roles and permissions

Courier has six built-in roles. Each sets read/write access and log visibility. Level 1 shows a message summary. Level 2 adds status detail and the request data, including PII. Full also renders the message.

| Role | Best for | Access |
| - | - | - |
| **Administrator** | Owners and admins | Full read/write, account management, edit API keys. |
| **Manager** | A team lead without billing/user duties | Full read/write, view API keys. |
| **Developer** | Engineers working the API and Designer | Read-only in Production, full in Test. Level 2 logs in Production, Full in Test. |
| **Designer** | Template and brand editors | Full read/write for Designer, Brands, Metrics. Read-only integrations and Lists. Level 1 logs. |
| **Support Specialist** | Support staff | Read-only Designer/Brands/Integrations. Full Lists and Metrics. Full logs. |
| **Analyst** | Read-only users | Read-only Designer/Brands/Integrations/Lists. Full Metrics. Level 2 logs. |

Administrators assign roles from **Settings → Team**. When no built-in role fits, define **custom roles** from granular scopes (`template:WriteItem`, `message:ReadEventDetails`, `brand:WriteItem`, and so on).

> [!NOTE]
>
> **Any role other than Administrator, and any custom role, requires the Enterprise plan.**\\
>
> On the Developer and Business plans, every teammate is an Administrator. An invite or API call that sets any other role is rejected.

### Custom role scopes

A custom role is a set of scopes. Each scope is a resource and an action, `template:WriteItem`.
A `resource:*` wildcard grants every action on that resource, so `template:*` covers listing,
reading, and writing Templates.

**Platform scopes** cover the notification product itself.

| Resource | Actions |
| - | - |
| `analytics` | `View` |
| `asset` | `ListItems`, `ReadItem`, `WriteItem` |
| `brand` | `ListItems`, `ReadItem`, `WriteItem` |
| `category` | `ListItems`, `ReadItem`, `WriteItem` |
| `integration` | `ListItems`, `ReadItem`, `WriteItem` |
| `list` | `ListItems`, `ReadItem`, `WriteItem` |
| `message` | `ListItems`, `ReadItem`, `ReadEventDetails`, `RequeueItem`, `WriteItem` |
| `metrics` | `GetMetrics` |
| `recipient` | `ListItems`, `ReadItem`, `WriteItem` |
| `shared-content` | `ListItems`, `ReadItem`, `WriteItem` |
| `template` | `ListItems`, `ReadItem`, `WriteItem` |
| `tenant` | `ListItems`, `ReadItem`, `WriteItem` |
| `webhook` | `ListItems`, `ReadItem`, `WriteItem` |

**Account-management scopes** cover the workspace rather than what it sends.

| Resource | Actions |
| - | - |
| `apikey` | `ListItems`, `ReadItem`, `WriteItem`, `RotateKey` |
| `billing` | `ViewBilling`, `UpdatePaymentMethod`, `UpdatePlan` |
| `environment` | `ListItems`, `ReadItem`, `WriteItem` |
| `security` | `WriteSettings` |
| `tracking` | `WriteSettings` |
| `user` | `ListItems`, `ReadItem`, `WriteItem`, `InviteUser` |

**`message:ReadEventDetails` is the one to grant deliberately.** It exposes the request data
on a message, which includes whatever PII the send carried, and it is what separates a Level
2 log view from Level 1.

### Inviting and removing members

Invite teammates from **Settings → Team**: click **Invite User**, enter their email, and pick a role. Remove a member from the dropdown next to their email. Members can also join through workspace discoverability (below) instead of an invite. The Developer plan caps pending invites at 10. Accept or revoke one before sending more. Business and Enterprise have no cap.

### Single sign-on

**Google SSO**, **GitHub SSO**, and **Okta SSO** let your team authenticate through your identity provider. Require SSO to disable password login. **SCIM directory provisioning** creates, updates, and deactivates users from your directory.

* **Google and GitHub SSO**: available on every plan, including **Developer**. Require login from your configured domains under **Settings → Team**.
* **Okta SSO and SCIM**: connect Courier as an app in Okta for sign-in and directory sync. Both are commercial features. Contact [Courier](https://www.courier.com/request-demo) to enable them for your workspace.

### Workspace discoverability

Let people who sign up with an approved email domain request access, instead of inviting each one. Under **Settings → Team**, confirm your domain is in the approved list, then choose a level:

* **Request access**: an approved-domain user requests, an admin approves.
* **Join directly**: an approved-domain user joins without approval.
* **IT admin only**: members are added manually, used with Okta provisioning.

## FAQ

> **Can I add roles other than Administrator?**
>
> On the Enterprise plan, yes: assign any of the six built-in roles or define custom roles. On Developer and Business, every member is an Administrator.

> **Do you support Okta and SCIM?**
>
> Courier supports Okta SSO and SCIM directory provisioning. Both are enabled commercially rather than by a plan toggle, so contact Courier to turn them on.

> **What can each role see in logs?**
>
> Log access has three levels: Level 1 (message summary), Level 2 (status detail plus request data including PII), and Full (also renders the message). Each role maps to one level, per the table above.