The Courier connector lets your AI agent act in each user's Courier account. Each user connects their own Courier access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 58 tools.
- Tools
- 58
- What they doRead · write · destructive
- 24 · 24 · 1024 read24 write10 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Courier connection
In AgentKit > Connections, create a Courier connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'courier'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Courier:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'courier_audiences_list',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "courier"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Courier:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="courier_audiences_list",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Courier credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolcourier_audience_getReturn one audience with its name, description, and the filter and AND or OR operator that decide which users belong to it.Read-onlyGet an Audience
Return one audience with its name, description, and the filter and AND or OR operator that decide which users belong to it. Returns an object with id, name, description, operator, filter, created_at, updated_at. Use this when you have the ID. Use courier_audiences_list to find one. Needs audience_id from courier_audiences_list.
Inputs
audience_idstringrequired- A unique identifier representing the audience_id. Example: vip-customers
courier_audience_members_listReturn the users currently matching an audience filter, with paging.Read-onlyList Audience members
Return the users currently matching an audience filter, with paging. Returns items, an array of items with added_at, audience_id, audience_version, member_id, reason, plus paging. Needs audience_id from courier_audiences_list.
Inputs
audience_idstringrequired- A unique identifier representing the audience id. Example: vip-customers
cursorstring- A unique identifier that allows for fetching the next set of members. Example: eyJpZCI6IjEyMyJ9
courier_audiences_listReturn the audiences in the workspace with paging.Read-onlyList all Audiences
Return the audiences in the workspace with paging. Returns items, an array of items with id, name, description, operator, filter, created_at, updated_at, plus paging. Use this to browse. Use courier_audience_get when you already have the ID.
Inputs
cursorstring- A unique identifier that allows for fetching the next set of audiences. Example: eyJpZCI6IjEyMyJ9
courier_automation_run_steps_listList the per-step state of one Automation run, in full — this endpoint is not paginated.Read-onlyList steps for an Automation run
List the per-step state of one Automation run, in full — this endpoint is not paginated. Returns an object with steps. Needs id from courier_automation_runs_list.
Inputs
idstringrequired- A unique identifier representing the Automation run. Example: user-123
courier_automation_runs_listList runs of the workspace's v2 Automations, newest first, filtered by status, Template, or date range and paged by cursor.Read-onlyList Automation runs
List runs of the workspace's v2 Automations, newest first, filtered by status, Template, or date range and paged by cursor. Returns an object with runs, next_cursor.
Inputs
cursorstring- A cursor token for pagination. Use the `next_cursor` from the previous response to fetch the next page of results. Treat it as opaque. Example: eyJpZCI6IjEyMyJ9
end_datestring- An inclusive upper bound on `created_at`, in the same format as `start_date`. Example: 2026-01-31T23:59:59Z
limitstring- The number of runs to return per page, between `1` and `50`. Defaults to `20`. Values outside the range are clamped, and a non-numeric value falls back to `20`. Example: 20
start_datestring- An inclusive lower bound on `created_at`, as an ISO 8601 date or timestamp (e.g. `2026-08-18` or `2026-08-18T20:06:36.259Z`). Any other format returns `400`. Example: 2026-01-01T00:00:00Z
statusstring- A comma-separated list of run statuses to filter on, e.g. `PROCESSED,ERROR`. Example: active
template_idstring- A comma-separated list of Automation Template ids to filter on. Example: user-123
courier_automations_listList the workspace's saved automation templates, each with its id and a cursor for paging to the next page of results.Read-onlyList Automations
List the workspace's saved automation templates, each with its id and a cursor for paging to the next page of results. Returns templates, an array of items with name, id, version, createdAt, updatedAt, plus cursor.
Inputs
cursorstring- A cursor token for pagination. Use the cursor from the previous response to fetch the next page of results. Example: eyJpZCI6IjEyMyJ9
versionstring- The version of templates to retrieve. Accepted values are published (for published templates) or draft (for draft templates). Defaults to published. Example: publishedone of
publisheddraft
courier_brand_getReturn one brand by id, including its colors, logo and styling settings, Handlebars snippets, and published version.Read-onlyGet a Brand
Return one brand by id, including its colors, logo and styling settings, Handlebars snippets, and published version. Returns an object with id, name, published, created, updated, settings, snippets, version. Use this when you have the ID. Use courier_brands_list to find one. Needs brand_id from courier_brands_list.
Inputs
brand_idstringrequired- A unique identifier associated with the brand you wish to retrieve. Example: user-123
courier_brands_listList the workspace's brands.Read-onlyList Brands
List the workspace's brands. Every entry carries its name, styling settings, snippets, and published version. Returns results, an array of items with id, name, published, created, updated, settings, snippets, version, plus paging. Use this to browse. Use courier_brand_get when you already have the ID.
Inputs
cursorstring- A unique identifier that allows for fetching the next set of brands. Example: eyJpZCI6IjEyMyJ9
courier_list_getReturn one list by id with its name and created and updated timestamps.Read-onlyGet a List
Return one list by id with its name and created and updated timestamps. Returns an object with id, name, created, updated. Use this when you have the ID. Use courier_lists_list to find one. Needs list_id from courier_lists_list.
Inputs
list_idstringrequired- A unique identifier representing the list you wish to retrieve. Example: weekly-digest
courier_list_subscriptions_listReturn the users subscribed to a list with paging, each with the preferences recorded for that subscription.Read-onlyList List Subscribers
Return the users subscribed to a list with paging, each with the preferences recorded for that subscription. Returns items, an array of items with recipientId, created, preferences, plus paging. Needs list_id from courier_lists_list.
Inputs
list_idstringrequired- A unique identifier representing the list you wish to retrieve. Example: weekly-digest
cursorstring- A unique identifier that allows for fetching the next set of list subscriptions. Example: eyJpZCI6IjEyMyJ9
courier_lists_listReturn the workspace's lists, filterable by a pattern to fetch a subset such as every regional list.Read-onlyList Lists
Return the workspace's lists, filterable by a pattern to fetch a subset such as every regional list. Returns items, an array of items with id, name, created, updated, plus paging. Use this to browse. Use courier_list_get when you already have the ID.
Inputs
cursorstring- A unique identifier that allows for fetching the next page of lists. Example: eyJpZCI6IjEyMyJ9
patternstring- "A pattern used to filter the list items returned. Pattern types supported: exact match on `list_id` or a pattern of one or more pattern parts. you may replace a part with either: `*` to match all parts in that position, or `` to signify a wildcard `endsWith` pattern match.". Example: newsletter.*
courier_message_content_getReturn the rendered content Courier delivered for a message, broken out per channel, to confirm what the recipient received.Read-onlyGet Message Content
Return the rendered content Courier delivered for a message, broken out per channel, to confirm what the recipient received. Returns results, an array of items with channel, channel_id, content. Needs message_id from courier_messages_list.
Inputs
message_idstringrequired- A unique identifier associated with the message you wish to retrieve (results from a send). Example: 1-65f1c2b3-4a5b6c7d8e9f0a1b2c3d4e5f
courier_message_getReturn a sent message's status, recipient, event, and per-provider delivery detail, with timestamps for enqueued, sent, delivered, opened, and clicked.Read-onlyGet message
Return a sent message's status, recipient, event, and per-provider delivery detail, with timestamps for enqueued, sent, delivered, opened, and clicked. Returns an object with providers, id, status, enqueued, sent, delivered, opened, clicked, recipient, event, notification, error and more. Use this when you have the ID. Use courier_messages_list to find one. Needs message_id from courier_messages_list.
Inputs
message_idstringrequired- A unique identifier associated with the message you wish to retrieve (results from a send). Example: 1-65f1c2b3-4a5b6c7d8e9f0a1b2c3d4e5f
courier_message_history_getReturn the ordered event history for a sent message, one entry per status transition with its timestamp.Read-onlyGet Message History
Return the ordered event history for a sent message, one entry per status transition with its timestamp. Returns results, an array of items. Needs message_id from courier_messages_list.
Inputs
message_idstringrequired- A unique identifier representing the message ID. Example: 1-65f1c2b3-4a5b6c7d8e9f0a1b2c3d4e5f
typestring- A supported Message History type that will filter the events returned. Example: email
courier_messages_listReturn previously sent messages, most recent first, each carrying its status, recipient, channel, and provider.Read-onlyList messages
Return previously sent messages, most recent first, each carrying its status, recipient, channel, and provider. Returns results, an array of items with id, status, enqueued, sent, delivered, opened, clicked, recipient, event, notification, plus paging. Use this to browse. Use courier_message_get when you already have the ID.
Inputs
archivedboolean- A boolean value that indicates whether archived messages should be included in the response. Example: false
cursorstring- A unique identifier that allows for fetching the next set of messages. Example: eyJpZCI6IjEyMyJ9
enqueued_afterstring- The enqueued datetime of a message to filter out messages received before. Example: eyJpZCI6IjEyMyJ9
eventstring- A unique identifier representing the event that was used to send the event. Example: order-shipped
liststring- A unique identifier representing the list the message was sent to. Example: weekly-digest
messageIdstring- A unique identifier representing the message_id returned from either /send or /send/list. Example: user-123
notificationstring- A unique identifier representing the notification that was used to send the event. Example: nt_01abc23def
providerarray- The key assocated to the provider you want to filter on. E.g., sendgrid, inbox, twilio, slack, msteams, etc. Allows multiple values to be set in query parameters. Example: ["sendgrid"]
recipientstring- A unique identifier representing the recipient associated with the requested profile. Example: user-123
statusarray- An indicator of the current status of the message. Allows multiple values to be set in query parameters. Example: ["DELIVERED"]
tagarray- A tag placed in the metadata.tags during a notification send. Allows multiple values to be set in query parameters. Example: ["onboarding"]
tagsstring- A comma delimited list of 'tags'. Messages will be returned if they match any of the tags passed in. Example: onboarding
tenant_idstring- Messages sent with the context of a Tenant. Example: user-123
traceIdstring- The unique identifier used to trace the requests. Example: user-123
courier_profile_getReturn a user's stored profile and preferences, including the email address, phone number, and push tokens Courier can reach them on.Read-onlyGet a Profile
Return a user's stored profile and preferences, including the email address, phone number, and push tokens Courier can reach them on. Returns an object with profile, preferences.
Inputs
user_idstringrequired- A unique identifier representing the user associated with the requested profile. Example: user-123
courier_profile_lists_getReturn the lists a user is subscribed to, with paging.Read-onlyGet Profile List Subscriptions
Return the lists a user is subscribed to, with paging. Returns results, an array of items with id, name, created, updated, preferences, plus paging.
Inputs
user_idstringrequired- A unique identifier representing the user associated with the requested user profile. Example: user-123
cursorstring- A unique identifier that allows for fetching the next set of message statuses. Example: eyJpZCI6IjEyMyJ9
courier_template_content_getReturn a template's content and checksum.Read-onlyGet Notification Template Content
Return a template's content and checksum. V2 templates return Elemental elements, while V1 templates return blocks and channels instead. Returns channels, an array of items with id, type, content, locales, checksum, plus version, elements, blocks, checksum. Needs id from courier_templates_list.
Inputs
idstringrequired- Notification template ID (`nt_` prefix). Example: user-123
versionstring- Accepts `draft`, `published`, or a version string (e.g., `v001`). Defaults to `published`. Example: v3
courier_template_getRetrieve a notification template by ID.Read-onlyGet Notification Template
Retrieve a notification template by ID. Returns the published version by default. Returns an object with name, tags, brand, subscription, routing, content, email, alias, id, state, created, creator and more. Use this when you have the ID. Use courier_templates_list to find one. Needs id from courier_templates_list.
Inputs
idstringrequired- Template ID (nt_ prefix). Example: user-123
versionstring- Version to retrieve. One of "draft", "published", or a version string like "v001". Defaults to "published". Example: draft
courier_template_versions_listReturn a notification template's published versions, most recent first, for comparison or rollback.Read-onlyList Notification Template Versions
Return a notification template's published versions, most recent first, for comparison or rollback. Returns an object with versions, paging. Needs id from courier_templates_list.
Inputs
idstringrequired- Template ID (nt_ prefix). Example: user-123
cursorstring- Opaque pagination cursor from a previous response. Omit for the first page. Example: eyJpZCI6IjEyMyJ9
limitinteger- Maximum number of versions to return per page. Default 10, max 10. Example: 20
courier_templates_listList the workspace's notification templates.Read-onlyList Notification Templates
List the workspace's notification templates. Each carries a name, tags, brand, routing, and its draft or published state. Returns results, an array of items with created_at, updated_at, id, routing, tags, title, topic_id, note, event_ids, name, plus paging. Use this to browse. Use courier_template_get when you already have the ID.
Inputs
cursorstring- Opaque pagination cursor from a previous response. Omit for the first page. Example: eyJpZCI6IjEyMyJ9
event_idstring- Filter to templates linked to this event map ID. Example: user-123
notesboolean- Include template notes in the response. Only applies to legacy templates. Example: false
tagsstring- Comma-delimited list of tag names. Only templates carrying all of the listed tags are returned. Matching is case-insensitive. Filtering is applied before pagination. Example: onboarding
courier_user_preference_getReturn a user's opt-in status and channel choices for one subscription topic, or the effective default if they have set no override.Read-onlyGet user Subscription Topic
Return a user's opt-in status and channel choices for one subscription topic, or the effective default if they have set no override. Returns an object with topic. Use this when you have the ID. Use courier_user_preferences_list to find one. Needs topic_id from courier_user_preferences_list.
Inputs
topic_idstringrequired- A unique identifier associated with a subscription topic. Example: 74Q4QGFBEX481DP6JRPMV751H4XT
user_idstringrequired- A unique identifier associated with the user whose preferences you wish to retrieve. Example: user-123
tenant_idstring- Query the preferences of a user for this specific tenant context. Example: user-123
courier_user_preferences_listReturn a user's preference overrides with paging, one entry per subscription topic they have set a choice for.Read-onlyGet user's Preferences
Return a user's preference overrides with paging, one entry per subscription topic they have set a choice for. Returns items, an array of items with custom_routing, default_status, has_custom_routing, section_id, section_name, status, topic_id, topic_name, digest_schedule_id, plus paging. Use this to browse. Use courier_user_preference_get when you already have the ID.
Inputs
user_idstringrequired- A unique identifier associated with the user whose preferences you wish to retrieve. Example: user-123
tenant_idstring- Query the preferences of a user for this specific tenant context. Example: user-123
courier_user_tokens_listReturn every device token registered for a user, each with its provider key, status, and expiry date.Read-onlyList tokens
Return every device token registered for a user, each with its provider key, status, and expiry date. Returns an object with tokens.
Inputs
user_idstringrequired- The user's ID. This can be any uniquely identifiable string. Example: user-123
courier_audience_upsertCreate or replace an audience from a filter and an AND or OR operator.WriteCreate or Update Audience
Create or replace an audience from a filter and an AND or OR operator. Returns an object with audience. The request replaces the stored value with what you send. Needs audience_id from courier_audiences_list.
- Idempotent
Inputs
audience_idstringrequired- A unique identifier representing the audience id. Example: vip-customers
descriptionstring- A description of the audience. Example: Users located in the US
filterobject- Filter configuration for audience membership containing an array of filter rules. Example: {"operator": "AND", "filters": [{"operator": "EQ", "path": "profile.location", "value": "US"}]}
namestring- The name of the audience. Example: Engaged US Users
operatorstring- The logical operator (AND/OR) combining the top-level `filter.filters`. Convenience alias for `filter.operator`: if set, it is applied to the top-level filter group. Prefer setting `operator` directly inside `filter`. Example: ANDone of
ANDOR
courier_automation_invokeStart an automation run from a saved template for one recipient, with optional data and profile, and returns a runId.WriteInvoke Automation Template
Start an automation run from a saved template for one recipient, with optional data and profile, and returns a runId. Returns an object with runId. Needs templateId from courier_automations_list.
Inputs
recipientstringrequired- The user ID the automation runs for. Example: user-123
templateIdstringrequired- A unique identifier representing the automation template to be invoked. This could be the Automation Template ID or the Automation Template Alias. Example: user-123
brandstring- The brand ID that styles the messages sent. Example: brand-123
dataobject- Data passed to templates as variables. Example: {"order_id": "A-1001"}
idempotency_keystring- A unique key that makes this request idempotent. If Courier receives another request with the same `Idempotency-Key`, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry `POST` requests after network failures without risking duplicate sends. The key is scoped to this endpoint. Example: order-ORD-456-user-123
profileobject- Profile fields to merge into the recipient's Courier profile for this run, such as email and phone_number. Example: {"email": "jane@example.com"}
templatestring- The notification template ID or alias the automation steps should send. Example: nt_01abc23def
x_idempotency_expirationstring- How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year. Example: 1785312000
courier_automation_invoke_ad_hocInvoke an ad hoc Automation.WriteInvoke Ad Hoc Automation
Invoke an ad hoc Automation. Runs a series of automation steps supplied inline, without a saved template, and returns a runId. Returns an object with runId.
Inputs
automationobjectrequired- The ad hoc automation: a list of steps (send, delay, cancel and so on) and an optional cancelation_token. Example: {"steps": [{"action": "send", "template": "nt_01abc23def"}]}
brandstring- The brand ID that styles the messages sent. Example: brand-123
dataobject- Data passed to templates as variables. Example: {"order_id": "A-1001"}
idempotency_keystring- A unique key that makes this request idempotent. If Courier receives another request with the same `Idempotency-Key`, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry `POST` requests after network failures without risking duplicate sends. The key is scoped to this endpoint. Example: order-ORD-456-user-123
profileobject- Profile fields to merge into the recipient's Courier profile for this run, such as email and phone_number. Example: {"email": "jane@example.com"}
recipientstring- The user ID the automation runs for. Example: user-123
templatestring- The notification template ID or alias the automation steps should send. Example: nt_01abc23def
x_idempotency_expirationstring- How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year. Example: 1785312000
courier_brand_createCreate a brand from a name and settings, including primary and secondary colors.WriteCreate a new Brand
Create a brand from a name and settings, including primary and secondary colors. Returns an object with id, name, published, created, updated, settings, snippets, version.
Inputs
namestringrequired- Display name. Example: Acme
settingsobjectrequired- Brand settings: colors, email header and footer, and inbox styling. Example: {"colors": {"primary": "#1a73e8"}}
idstring- The brand ID to create. Leave empty to let Courier generate one. Example: brand-123
idempotency_keystring- A unique key that makes this request idempotent. If Courier receives another request with the same `Idempotency-Key`, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry `POST` requests after network failures without risking duplicate sends. The key is scoped to this endpoint. Example: order-ORD-456-user-123
snippetsobject- Reusable brand snippets (name and value pairs) that templates can reference. Example: {"items": [{"name": "footer", "value": "Acme Inc."}]}
x_idempotency_expirationstring- How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year. Example: 1785312000
courier_brand_replaceReplace a brand with the values you supply, so send the complete settings and snippets rather than only the fields you want changed.WriteReplace a Brand
Replace a brand with the values you supply, so send the complete settings and snippets rather than only the fields you want changed. Returns an object with id, name, published, created, updated, settings, snippets, version. The request replaces the stored value with what you send. Needs brand_id from courier_brands_list.
- Idempotent
Inputs
brand_idstringrequired- A unique identifier associated with the brand you wish to update. Example: user-123
namestringrequired- The name of the brand. Example: My Brand
settingsobject- Brand settings: colors, email header and footer, and inbox styling. Example: {"colors": {"primary": "#1a73e8"}}
snippetsobject- Reusable brand snippets (name and value pairs) that templates can reference. Example: {"items": [{"name": "footer", "value": "Acme Inc."}]}
courier_event_trackRecord an inbound event that can trigger a journey.WriteTrack Event
Record an inbound event that can trigger a journey. Returns an object with messageId.
Inputs
eventstringrequired- A descriptive name of the event. This name will appear as a trigger in the Courier Automation Trigger node. Example: order-shipped
messageIdstringrequired- A required unique identifier that will be used to de-duplicate requests. If not unique, will respond with 409 Conflict status. Example: 4c62c457-b329-4bea-9bfc-17bba86c393f
propertiesobjectrequired- Event properties passed to automations and templates. Example: {"order_id": "A-1001"}
typestringrequired- The event type. For inbound tracking this is track. Example: trackone of
track userIdstring- The user id associated with the track. Example: 1234
courier_list_restoreRestore a previously deleted list along with its subscribers, so a list removed by mistake can be brought back rather than rebuilt.WriteRestore a List
Restore a previously deleted list along with its subscribers, so a list removed by mistake can be brought back rather than rebuilt. Returns an empty response on success (HTTP 204). Needs list_id from courier_lists_list.
- Idempotent
Inputs
list_idstringrequired- A unique identifier representing the list you wish to retrieve. Example: weekly-digest
courier_list_subscribers_addSubscribe additional users to the list, without modifying existing subscriptions.WriteAdd Subscribers to List
Subscribe additional users to the list, without modifying existing subscriptions. Returns an empty response on success (HTTP 202). Needs list_id from courier_lists_list.
Inputs
list_idstringrequired- A unique identifier representing the list you wish to retrieve. Example: weekly-digest
recipientsarrayrequired- The users to subscribe, each with a recipientId and optional per-list preferences. Example: [{"recipientId": "user-123"}]
idempotency_keystring- A unique key that makes this request idempotent. If Courier receives another request with the same `Idempotency-Key`, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry `POST` requests after network failures without risking duplicate sends. The key is scoped to this endpoint. Example: order-ORD-456-user-123
x_idempotency_expirationstring- How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year. Example: 1785312000
courier_list_subscribers_replaceSubscribe the users to the list, overwriting existing subscriptions.WriteReplace List Subscribers
Subscribe the users to the list, overwriting existing subscriptions. Returns an empty response on success (HTTP 202). The request replaces the stored value with what you send. Needs list_id from courier_lists_list.
- Idempotent
Inputs
list_idstringrequired- A unique identifier representing the list you wish to retrieve. Example: weekly-digest
recipientsarrayrequired- The users to subscribe, each with a recipientId and optional per-list preferences. Example: [{"recipientId": "user-123"}]
courier_list_upsertCreate or replace a list from a name and preferences.WriteCreate or Update List
Create or replace a list from a name and preferences. Returns an empty response on success (HTTP 204). The request replaces the stored value with what you send. Needs list_id from courier_lists_list.
- Idempotent
Inputs
list_idstringrequired- A unique identifier representing the list you wish to retrieve. Example: weekly-digest
namestringrequired- Display name. Example: Acme
preferencesobject- Notification preferences for this list subscription, keyed by notification or category. Example: {"notifications": {}}
courier_list_user_subscribeSubscribe one user to a list, creating the list if it does not yet exist.WriteSubscribe User to List
Subscribe one user to a list, creating the list if it does not yet exist. Returns an empty response on success (HTTP 204). Needs list_id from courier_lists_list; user_id from courier_list_subscriptions_list.
- Idempotent
Inputs
list_idstringrequired- A unique identifier representing the list you wish to retrieve. Example: weekly-digest
user_idstringrequired- A unique identifier representing the recipient associated with the list. Example: user-123
preferencesobject- Notification preferences for this list subscription, keyed by notification or category. Example: {"notifications": {}}
courier_message_resendResend a previously sent message to the same recipient and content, returning a new messageId.WriteResend message
Resend a previously sent message to the same recipient and content, returning a new messageId. Returns an object with messageId. Needs message_id from courier_messages_list.
Inputs
message_idstringrequired- A unique identifier representing the message ID of the original message to resend. Example: 1-65f1c2b3-4a5b6c7d8e9f0a1b2c3d4e5f
courier_message_sendSend a message to one or more recipients (a user ID, email, phone number, list, audience or tenant) using a stored template or inline content; Courier routes it to email, SMS, push, chat or inbox by your routing rules.WriteSend Message
Send a message to one or more recipients (a user ID, email, phone number, list, audience or tenant) using a stored template or inline content; Courier routes it to email, SMS, push, chat or inbox by your routing rules. Returns requestId, which ties together every message the send produces. Use this to send now. Use courier_messages_list or courier_message_get with the requestId to check delivery, and courier_automation_invoke for multi-step flows.
Inputs
messageobjectrequired- Defines the message to be delivered. Example: {"to": {"email": "jane@example.com"}, "content": {"title": "Your order shipped", "body": "Order A-1001 is on its way."}, "routing": {"method": "single", "channels": ["email"]}}
idempotency_keystring- A unique key that makes this request idempotent. If Courier receives another request with the same `Idempotency-Key`, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry `POST` requests after network failures without risking duplicate sends. The key is scoped to this endpoint. Example: order-ORD-456-user-123
x_idempotency_expirationstring- How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year. Example: 1785312000
courier_profile_lists_subscribeSubscribe a user to one or more lists, creating any list that does not yet exist.WriteSubscribe Profile to Lists
Subscribe a user to one or more lists, creating any list that does not yet exist. Returns an object with status.
Inputs
listsarrayrequired- The lists to subscribe the profile to, each with a listId and optional preferences. Example: [{"listId": "weekly-digest"}]
user_idstringrequired- A unique identifier representing the user associated with the requested user profile. Example: user-123
idempotency_keystring- A unique key that makes this request idempotent. If Courier receives another request with the same `Idempotency-Key`, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry `POST` requests after network failures without risking duplicate sends. The key is scoped to this endpoint. Example: order-ORD-456-user-123
x_idempotency_expirationstring- How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year. Example: 1785312000
courier_profile_mergeMerge the supplied values into a user's profile, creating it if absent and leaving any key you omit untouched.WriteCreate or Merge Profile
Merge the supplied values into a user's profile, creating it if absent and leaving any key you omit untouched. Returns an object with status.
Inputs
profileobjectrequired- Profile fields to merge into the recipient's Courier profile for this run, such as email and phone_number. Example: {"email": "jane@example.com"}
user_idstringrequired- A unique identifier representing the user associated with the requested profile. Example: user-123
idempotency_keystring- A unique key that makes this request idempotent. If Courier receives another request with the same `Idempotency-Key`, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry `POST` requests after network failures without risking duplicate sends. The key is scoped to this endpoint. Example: order-ORD-456-user-123
x_idempotency_expirationstring- How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year. Example: 1785312000
courier_profile_patchApply a JSON Patch to a user profile, adding, removing, or replacing individual fields without sending the whole object.WritePatch Profile
Apply a JSON Patch to a user profile, adding, removing, or replacing individual fields without sending the whole object. Returns an empty response on success (HTTP 204). Only the fields you pass change; omitted fields keep their current values.
Inputs
patcharrayrequired- List of patch operations to apply to the profile. Example: [{"op": "replace", "path": "/email", "value": "jdoe@example.com"}]
user_idstringrequired- A unique identifier representing the user associated with the requested user profile. Example: user-123
courier_profile_replaceReplace a Profile.WriteReplace a Profile
Replace a Profile. Overwrites a user profile in full, removing any key absent from the request body. Returns an object with status. The request replaces the stored value with what you send.
- Idempotent
Inputs
profileobjectrequired- The complete profile to store for this user. It replaces the stored profile: any field you leave out, such as phone_number, is removed. To change only some fields, use courier_profile_merge or courier_profile_patch. Example: {"email": "jane@example.com", "phone_number": "+15558675309"}
user_idstringrequired- A unique identifier representing the user associated with the requested user profile. Example: user-123
courier_request_archiveArchive a send request by its request id.WriteArchive Request
Archive a send request by its request id. Use it to remove test sends or superseded requests from the message list without deleting them. Returns an empty response on success (HTTP 202).
- Idempotent
Inputs
request_idstringrequired- A unique identifier representing the request ID. Example: user-123
courier_template_content_replaceReplace all Elemental content in a template, overwriting every existing element.WriteReplace Notification Template Content
Replace all Elemental content in a template, overwriting every existing element. Returns an object with id, version, elements, state. The request replaces the stored value with what you send. Needs id from courier_templates_list.
- Idempotent
Inputs
contentobjectrequired- Elemental content payload. The server defaults `version` when omitted. Example: {"elements": [{"type": "text"}]}
idstringrequired- Notification template ID (`nt_` prefix). Example: user-123
statestring- Template state. Defaults to `DRAFT`. Example: DRAFTone of
DRAFTPUBLISHED
courier_template_createCreate a notification template.WriteCreate Notification Template
Create a notification template. Requires all fields in the notification object. Returns an object with name, tags, brand, subscription, routing, content, email, alias, id, state, created, creator and more.
Inputs
notificationobjectrequired- Template fields accepted in POST and PUT request bodies, nested under a `notification` key. Example: {"name": "Welcome Email", "tags": ["onboarding"], "brand": null, "subscription": null, "routing": null, "content": {"version": "2022-01-01", "elements": [{"type": "channel", "channel": "email", "elements": [{"type": "meta", "title": "Welcome!"}, {"type": "text", "content": "Thanks for signing up."}]}]}, "alias": "welcome"}
idempotency_keystring- A unique key that makes this request idempotent. If Courier receives another request with the same `Idempotency-Key`, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry `POST` requests after network failures without risking duplicate sends. The key is scoped to this endpoint. Example: order-ORD-456-user-123
statestring- Template state after creation. Case-insensitive input, normalized to uppercase in the response. Defaults to "DRAFT". Example: DRAFTone of
DRAFTPUBLISHED x_idempotency_expirationstring- How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year. Example: 1785312000
courier_template_publishPublish a notification template.WritePublish Notification Template
Publish a notification template. Publishes the current draft by default. Returns an empty response on success (HTTP 204). Needs id from courier_templates_list.
Inputs
idstringrequired- Template ID (nt_ prefix). Example: user-123
idempotency_keystring- A unique key that makes this request idempotent. If Courier receives another request with the same `Idempotency-Key`, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry `POST` requests after network failures without risking duplicate sends. The key is scoped to this endpoint. Example: order-ORD-456-user-123
versionstring- Historical version to publish (e.g. "v001"). Omit to publish the current draft. Example: v3
x_idempotency_expirationstring- How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year. Example: 1785312000
courier_template_replaceReplace a notification template in full, so send every field rather than only the ones you want changed.WriteReplace Notification Template
Replace a notification template in full, so send every field rather than only the ones you want changed. Returns an object with name, tags, brand, subscription, routing, content, email, alias, id, state, created, creator and more. The request replaces the stored value with what you send. Needs id from courier_templates_list.
- Idempotent
Inputs
idstringrequired- Template ID (nt_ prefix). Example: user-123
notificationobjectrequired- Template fields accepted in POST and PUT request bodies, nested under a `notification` key. Example: {"name": "Welcome Email", "tags": ["onboarding"], "brand": null, "subscription": null, "routing": null, "content": {"version": "2022-01-01", "elements": [{"type": "channel", "channel": "email", "elements": [{"type": "meta", "title": "Welcome!"}, {"type": "text", "content": "Thanks for signing up."}]}]}, "alias": "welcome"}
statestring- Template state after update. Case-insensitive input, normalized to uppercase in the response. Defaults to "DRAFT". Example: PUBLISHEDone of
DRAFTPUBLISHED
courier_user_preference_updateSet a user's opt-in status and channel choices for one subscription topic, overriding the tenant default for that topic only.WriteUpdate User Topic Preference
Set a user's opt-in status and channel choices for one subscription topic, overriding the tenant default for that topic only. Returns an object with message. The request replaces the stored value with what you send. Needs topic_id from courier_user_preferences_list.
- Idempotent
Inputs
topicobjectrequired- The preference for this subscription topic: status (OPTED_IN, OPTED_OUT or REQUIRED) and optional custom routing. Example: {"status": "OPTED_OUT"}
topic_idstringrequired- A unique identifier associated with a subscription topic. Example: 74Q4QGFBEX481DP6JRPMV751H4XT
user_idstringrequired- A unique identifier associated with the user whose preferences you wish to retrieve. Example: abc-123
tenant_idstring- Update the preferences of a user for this specific tenant context. Example: user-123
courier_user_token_addRegister one device token for a user against a provider key, overwriting the token if it already exists.WriteAdd User Device Token
Register one device token for a user against a provider key, overwriting the token if it already exists. Returns an empty response on success (HTTP 204). Needs token from courier_user_tokens_list.
- Idempotent
Inputs
provider_keystringrequired- The push provider for this token: firebase-fcm, apn, expo or onesignal. Example: firebase-fcmone of
firebase-fcmapnexpoonesignal tokenstringrequired- The full token string. Example: fcm-token-abc123
user_idstringrequired- The user's ID. This can be any uniquely identifiable string. Example: user-123
deviceobject- Information about the device the token came from. Example: {"app_id": "com.example.app"}
expiry_dateboolean- When the token expires. Accepts a date, or the boolean `false` to disable expiration entirely. ISO 8601 is recommended (for example `2026-10-25T00:00:00.000Z`). A value that cannot be parsed as a date is rejected; it is not treated as "no expiration" and does not fall back to the default. `true` is not a supported value. Omit the field to use the default, which expires a token that has not been re-registered for 60 days. Example: 2027-01-01T00:00:00Z
propertiesstring- Properties about the token. Example: {"app": "ios"}
trackingobject- Tracking information about the device the token came from. Example: {"os_version": "17.2", "ip": "203.0.113.10"}
courier_audience_deleteDelete an audience permanently, so update any caller sending to it by audience id first.DestructiveDelete an Audience
Delete an audience permanently, so update any caller sending to it by audience id first. Returns an empty response on success (HTTP 204). Needs audience_id from courier_audiences_list.
- Idempotent
Inputs
audience_idstringrequired- A unique identifier representing the audience id. Example: vip-customers
courier_brand_deleteDelete a brand by id.DestructiveDelete a Brand
Delete a brand by id. Reassign any template or tenant that references it before deleting to keep their styling intact. Returns an empty response on success (HTTP 204). Needs brand_id from courier_brands_list.
- Idempotent
Inputs
brand_idstringrequired- A unique identifier associated with the brand you wish to retrieve. Example: user-123
courier_list_deleteDelete a list, halting sends that target it.DestructiveDelete a List
Delete a list, halting sends that target it. A previously deleted list can be brought back with the companion restore endpoint. Returns an empty response on success (HTTP 204). Needs list_id from courier_lists_list.
- Idempotent
Inputs
list_idstringrequired- A unique identifier representing the list you wish to retrieve. Example: weekly-digest
courier_list_user_unsubscribeRemove one user's subscription to a list, addressed by list id and user id.DestructiveUnsubscribe User from List
Remove one user's subscription to a list, addressed by list id and user id. Returns an empty response on success (HTTP 204). Needs list_id from courier_lists_list; user_id from courier_list_subscriptions_list.
- Idempotent
Inputs
list_idstringrequired- A unique identifier representing the list you wish to retrieve. Example: weekly-digest
user_idstringrequired- A unique identifier representing the recipient associated with the list. Example: user-123
courier_message_cancelCancel a message that is still queued or delayed (for example inside a digest or a delay step) so it is not delivered.DestructiveCancel message
Cancel a message that is still queued or delayed (for example inside a digest or a delay step) so it is not delivered. Returns the message with its updated status. Use courier_messages_list to find the message_id. A message already sent cannot be recalled.
Inputs
message_idstringrequired- A unique identifier representing the message ID. Example: 1-65f1c2b3-4a5b6c7d8e9f0a1b2c3d4e5f
courier_profile_deleteDelete a user's profile and stored contact details.DestructiveDelete a Profile
Delete a user's profile and stored contact details. Returns an empty response on success (HTTP 204).
- Idempotent
Inputs
user_idstringrequired- A unique identifier representing the user associated with the requested user profile. Example: user-123
courier_profile_lists_unsubscribe_allRemove every list subscription for a user at once.DestructiveRemove Profile from All Lists
Remove every list subscription for a user at once. Returns an object with status.
- Idempotent
Inputs
user_idstringrequired- A unique identifier representing the user associated with the requested profile. Example: user-123
courier_template_archiveArchive a notification template, preventing new sends from referencing it.DestructiveArchive Notification Template
Archive a notification template, preventing new sends from referencing it. Returns an empty response on success (HTTP 204). Needs id from courier_templates_list.
- Idempotent
Inputs
idstringrequired- Template ID (nt_ prefix). Example: user-123
courier_user_preference_deleteRemove a user's override for one subscription topic, resetting it to the effective default from the tenant or workspace.DestructiveDelete User Topic Preference
Remove a user's override for one subscription topic, resetting it to the effective default from the tenant or workspace. Returns an empty response on success (HTTP 204). Needs topic_id from courier_user_preferences_list.
- Idempotent
Inputs
topic_idstringrequired- A unique identifier associated with a subscription topic. Example: 74Q4QGFBEX481DP6JRPMV751H4XT
user_idstringrequired- A unique identifier associated with the user whose preferences you wish to delete. Example: abc-123
tenant_idstring- Delete the preferences of a user for this specific tenant context. Example: user-123
courier_user_token_deleteDelete one device token for a user, addressed by the token value, so push sends no longer target that device.DestructiveDelete User Device Token
Delete one device token for a user, addressed by the token value, so push sends no longer target that device. Returns an empty response on success (HTTP 204). Needs token from courier_user_tokens_list.
- Idempotent
Inputs
tokenstringrequired- The full token string. Example: fcm-token-abc123
user_idstringrequired- The user's ID. This can be any uniquely identifiable string. Example: user-123
No tools match.