io.github.trycourier/courier

Official123 tools

by trycourier · TypeScript

Courier

Send notifications, manage templates, and configure integrations with Courier.

Send notifications and manage message templates across multiple communication channels.

Captured live from the server via tools/list.

get_audience

Get an audience by its ID, including its filter definition.

Parameters (1)

audience_idstringrequired
The audience ID

list_audience_members

List all members of an audience.

Parameters (2)

audience_idstringrequired
The audience ID
cursorstring
Pagination cursor

list_audiences

List all audiences in the workspace.

Parameters (1)

cursorstring
Pagination cursor

update_audience

Create or update an audience with a filter definition.

Parameters (4)

audience_idstringrequired
The audience ID
namestring
Display name
descriptionstring
Description
filterany
Filter definition object (operator, rules)

delete_audience

Delete an audience by its ID.

Parameters (1)

audience_idstringrequired
The audience ID to delete

get_audit_event

Get a specific audit event by its ID.

Parameters (1)

audit_event_idstringrequired
The audit event ID

list_audit_events

List audit events in the workspace. Useful for tracking API usage and changes.

Parameters (1)

cursorstring
Pagination cursor

generate_jwt_for_user

Generate a JWT authentication token for a user. Used for client-side SDK auth (Inbox, Preferences, etc.).

Parameters (3)

user_idstringrequired
The user ID to scope the token to
scopesarray
Permission scopes for the token
expires_instring
Token expiry duration (e.g. "1h", "2 days")

invoke_automation_template

Invoke an automation run from an existing automation template. Call list_automations first to get the template_id. Example: { template_id: "auto-onboarding", recipient: "user-123", data: { plan: "pro" } }.

Parameters (6)

template_idstringrequired
The automation template ID
recipientstringrequired
Recipient user ID
brandstring
Brand ID override
dataobject
Data to pass to the automation
profileobject
Profile data for the recipient
templatestring
Notification template override

invoke_ad_hoc_automation

Invoke an ad-hoc automation with inline steps. Valid step actions: send, send-list, delay, cancel, update-profile, invoke, fetch-data. To cancel a previously started automation, use the cancel_automation tool instead.

Parameters (6)

automationobjectrequired
The automation definition with typed steps
brandstring
dataobject
profileobject
recipientstring
templatestring

list_automations

List automation templates in the workspace. Always call this first to discover template_id values before calling invoke_automation_template. Optionally filter by version.

Parameters (2)

cursorstring
Pagination cursor
versionstring
Filter by version state

cancel_automation

Cancel a running automation by its cancelation_token. This invokes a second ad-hoc automation with a single cancel step. The token must match the cancelation_token set when the original automation was started. Note: spelling is "cancelation_token" (single "l").

Parameters (1)

cancelation_tokenstringrequired
The cancelation_token that was set when the automation was originally invoked

create_brand

Create a new brand. The API requires settings — omitting it returns a 400. If you do not have specific brand colors, omit settings and a safe default will be used automatically (black primary, white secondary). Example: { name: "Acme", settings: { colors: { primary: "#1a73e8", secondary: "#ffffff" } } }.

Parameters (4)

namestringrequired
Brand display name
idstring
Optional brand ID; auto-generated if omitted
settingsobject
Brand appearance settings. If omitted, defaults to { colors: { primary: "#000000", secondary: "#ffffff" } }.
snippetsobject
Brand snippets

get_brand

Get a brand by its ID.

Parameters (1)

brand_idstringrequired
The brand ID

list_brands

List all brands in the workspace.

Parameters (1)

cursorstring
Pagination cursor

update_brand

Replace an existing brand with new values.

Parameters (4)

brand_idstringrequired
The brand ID to update
namestringrequired
Brand display name
settingsobject
Brand settings (colors, email, inapp)
snippetsobject
Brand snippets

delete_brand

Delete a brand by its ID.

Parameters (1)

brand_idstringrequired
The brand ID to delete

create_bulk_job

Create a new bulk job for sending messages to multiple recipients. Workflow: create_bulk_job → add_bulk_users → run_bulk_job.

Parameters (1)

messageobjectrequired
Bulk message definition with event/template and content

add_bulk_users

Add users to an existing bulk job.

Parameters (2)

job_idstringrequired
The bulk job ID
usersarrayrequired
Array of user objects to add

run_bulk_job

Run a bulk job, triggering delivery to all added users.

Parameters (1)

job_idstringrequired
The bulk job ID to run

get_bulk_job

Get the status of a bulk job.

Parameters (1)

job_idstringrequired
The bulk job ID

list_bulk_users

List the users in a bulk job.

Parameters (2)

job_idstringrequired
The bulk job ID
cursorstring
Pagination cursor

courier_installation_guide

Get the Courier SDK installation guide for a specific platform. For client-side SDKs (React, iOS, Android, Flutter, React Native), also generates a sample JWT.

Parameters (2)

platformstringrequired
The platform to get installation guide for
user_idstring
User ID for JWT generation (client-side SDKs only). Defaults to "example_user".

track_inbound_event

Track an inbound event that can trigger automations. Requires event name, messageId (for deduplication), and properties.

Parameters (4)

eventstringrequired
The event name (appears as trigger in Automation Trigger node)
messageIdstringrequired
Unique ID for deduplication (returns 409 if not unique)
propertiesobjectrequired
Event properties payload
userIdstring
User ID associated with the event

list_lists

Get all lists. Optionally filter by pattern (e.g. 'example.list.*').

Parameters (2)

patternstring
Filter pattern (e.g. 'example.list.*')
cursorstring
Pagination cursor

get_list

Get a list by its ID.

Parameters (1)

list_idstringrequired
The list ID

get_list_subscribers

Get all subscribers of a list.

Parameters (2)

list_idstringrequired
The list ID
cursorstring
Pagination cursor

create_list

Create or update a list by list ID.

Parameters (2)

list_idstringrequired
The list ID
namestringrequired
Display name for the list

subscribe_user_to_list

Subscribe a user to a list. Creates the list if it doesn't exist.

Parameters (3)

list_idstringrequired
The list ID
user_idstringrequired
The user ID to subscribe
preferencesobject
Optional notification preferences

unsubscribe_user_from_list

Unsubscribe a user from a list.

Parameters (2)

list_idstringrequired
The list ID
user_idstringrequired
The user ID to unsubscribe

delete_list

Delete a list by its ID.

Parameters (1)

list_idstringrequired
The list ID

restore_list

Restore a previously deleted list.

Parameters (1)

list_idstringrequired
The list ID

bulk_subscribe_to_list

Replace all subscribers on a list with the given recipients.

Parameters (2)

list_idstringrequired
The list ID
recipientsarrayrequired
Recipients to set on the list

add_subscribers_to_list

Append subscribers to a list without removing existing subscribers.

Parameters (2)

list_idstringrequired
The list ID
recipientsarrayrequired
Recipients to set on the list

list_messages

List messages you've previously sent. Filter by status, recipient, notification, provider, tags, or tenant.

Parameters (14)

cursorstring
Pagination cursor for fetching the next page
eventstring
Filter by event ID
liststring
Filter by list ID
messageIdstring
Filter by message ID
notificationstring
Filter by notification ID
recipientstring
Filter by recipient user ID
statusarray
Filter by status (e.g. DELIVERED, UNDELIVERABLE)
tagarray
Filter by metadata tags
tagsstring
Comma-delimited list of tags
tenant_idstring
Filter by tenant ID
traceIdstring
Filter by trace ID
enqueued_afterstring
ISO 8601 timestamp; only return messages enqueued after this time
providerarray
Filter by provider key (e.g. sendgrid, twilio)
archivedboolean
Include archived messages

get_message

Get the full details and status of a single message by its ID.

Parameters (1)

message_idstringrequired
The message ID to retrieve

get_message_content

Get the rendered content (HTML, text, subject) of a previously sent message.

Parameters (1)

message_idstringrequired
The message ID

get_message_history

Get the event history for a message, showing each step in the delivery pipeline (enqueued, sent, delivered, etc.).

Parameters (2)

message_idstringrequired
The message ID
typestring
Filter by event type

cancel_message

Cancel a message that is currently being delivered. Returns the message details with updated status.

Parameters (1)

message_idstringrequired
The message ID to cancel

list_notifications

List notification templates. Optionally filter by cursor.

Parameters (1)

cursorstring
Pagination cursor

get_notification_content

Get the published content blocks of a notification template.

Parameters (1)

notification_idstringrequired
The notification template ID

get_notification_draft_content

Get the draft (unpublished) content blocks of a notification template.

Parameters (1)

notification_idstringrequired
The notification template ID

create_notification

Create a V2 notification template. name is required. Provide content inline or set it immediately after creation via put_notification_content. To send with this template you must publish it first via publish_notification (or pass state: 'PUBLISHED' on create). Link a routing strategy via notification.routing.strategy_id to control which channels are used. Example: { notification: { name: 'welcome-email', tags: [], brand: null, subscription: null, routing: { strategy_id: 'rs_01abc' }, content: { version: '2022-01-01', elements: [] } } }.

Parameters (2)

notificationobjectrequired
Notification template payload
statestring
Template state after creation (defaults to DRAFT)

get_notification

Retrieve a notification template by ID. Optionally request draft, published, or a version such as v001.

Parameters (2)

notification_idstringrequired
The notification template ID
versionstring
Version to retrieve: draft, published, or a string like v001

replace_notification

Replace a notification template entirely (full document PUT).

Parameters (3)

notification_idstringrequired
The notification template ID to replace
notificationobjectrequired
Full notification template payload
statestring
Template state after update (defaults to DRAFT)

archive_notification

Archive a notification template by ID.

Parameters (1)

notification_idstringrequired
The notification template ID to archive

list_notification_versions

List version history for a notification template.

Parameters (3)

notification_idstringrequired
The notification template ID
cursorstring
Pagination cursor from a previous response
limitnumber
Max versions per page (default 10, max 10)

publish_notification

Publish a notification template, making it available for sending. Must be called before send_message_template unless the template was created with state: 'PUBLISHED'. Publishes the current draft by default; pass version (e.g. 'v001') to publish a specific historical version. Returns 204 on success.

Parameters (2)

notification_idstringrequired
The notification template ID to publish
versionstring
Historical version to publish (e.g. v001); omit to publish current draft

list_notification_checks

List checks for a notification submission.

Parameters (2)

notification_idstringrequired
The notification template ID
submission_idstringrequired
The submission ID for the checks resource

update_notification_checks

Update check statuses for a notification submission.

Parameters (3)

notification_idstringrequired
The notification template ID
submission_idstringrequired
The submission ID for the checks resource
checksarrayrequired
Checks to update

put_notification_content

Replace the elemental content of a V2 notification template. Overwrites all elements. Use channel elements to target specific channels. Multi-channel example: elements: [{ type: "channel", channel: "email", elements: [{ type: "meta", title: "Hello" }, { type: "text", content: "Email body" }] }, { type: "channel", channel: "push", elements: [{ type: "meta", title: "Hello" }, { type: "text", content: "Push body" }] }, { type: "channel", channel: "inbox", elements: [{ type: "text", content: "Inbox plain text only" }] }].

Parameters (4)

notification_idstringrequired
The notification template ID (nt_ prefix)
elementsarrayrequired
Array of elemental content nodes
versionstring
Content version string
statestring
Template state after update

put_notification_element

Update a single element within a V2 notification template.

Parameters (9)

notification_idstringrequired
The notification template ID (nt_ prefix)
element_idstringrequired
The element ID to update
typestringrequired
Element type (e.g. text, action, image, divider, meta)
channelsarray
Channels this element applies to
dataobject
Element data payload
ifstring
Conditional expression for element visibility
loopstring
Loop expression for repeating elements
refstring
Reference identifier
statestring
Template state after update

put_notification_locale

Set locale-specific content overrides for a V2 notification template. Each element override must reference an existing element by its id. Example for Spanish locale: { notification_id: "nt_01abc", locale_id: "es", elements: [{ id: "elem_meta_1", title: "Restablecer contraseña" }, { id: "elem_text_1", content: "Haga clic en el enlace para restablecer su contraseña." }] }.

Parameters (4)

notification_idstringrequired
The notification template ID (nt_ prefix)
locale_idstringrequired
Locale identifier (e.g. es, fr, pt-BR)
elementsarrayrequired
Array of element overrides with id and locale-specific content
statestring
Template state after update

cancel_notification_submission

Cancel a notification template submission.

Parameters (2)

notification_idstringrequired
The notification template ID
submission_idstringrequired
The submission ID to cancel

get_user_profile_by_id

Get a user profile by their ID. Returns profile data including email, phone, and custom properties.

Parameters (1)

user_idstringrequired
The user ID to look up

create_or_merge_user

Create a new user profile or merge supplied values into an existing profile (POST). Existing fields not included are preserved.

Parameters (2)

user_idstringrequired
The user ID
profileobject
Profile data to create or merge (e.g. { email: "...", phone_number: "..." })

replace_profile

Fully replace a user profile (PUT). All existing data is overwritten; include every field you want to keep.

Parameters (2)

user_idstringrequired
The user ID
profileobjectrequired
Complete profile data to replace with

patch_profile

Partially update a user profile via JSON Patch (RFC 6902). Use add/replace/remove operations on specific profile paths.

Parameters (2)

user_idstringrequired
The user ID
patcharrayrequired
Array of JSON Patch operations to apply to the profile

delete_profile

Delete a user profile permanently.

Parameters (1)

user_idstringrequired
The user ID to delete

get_user_list_subscriptions

Get all list subscriptions for a user.

Parameters (2)

user_idstringrequired
The user ID
cursorstring
Pagination cursor

subscribe_user_to_lists

Subscribe a user to one or more lists. Creates lists that do not exist.

Parameters (2)

user_idstringrequired
The user ID
listsarrayrequired
Array of lists to subscribe to

delete_user_list_subscriptions

Delete all list subscriptions for a user.

Parameters (1)

user_idstringrequired
The user ID

send_message

Send a message to a user using inline title and body content (no template). Optionally specify routing channels.

Parameters (6)

user_idstringrequired
The recipient user ID
titlestringrequired
Message title
bodystringrequired
Message body
dataobject
Key-value data to include with the message
methodstring
Routing method: deliver to all channels or stop after first success
channelsarray
Channel names to route through (e.g. email, sms, push). Omit to use default routing.

send_message_template

Send a message to a user using a published notification template. The template must be published before sending — call publish_notification first if needed. Example: { user_id: "user-123", template: "nt_01abc123", data: { name: "Alex", resetUrl: "https://app.example.com/reset" } }.

Parameters (5)

user_idstringrequired
The recipient user ID
templatestringrequired
Template ID or notification slug
dataobject
Key-value data for template variables
methodstring
Routing method
channelsarray
Channel names to route through. Omit to use template routing config.

send_message_to_list

Send a message to all subscribers of a list using inline title and body content.

Parameters (6)

list_idstringrequired
The list ID to send to
titlestringrequired
Message title
bodystringrequired
Message body
dataobject
Key-value data to include
methodstring
Routing method
channelsarray
Channel names to route through. Omit to use default routing.

send_message_to_list_template

Send a message to all subscribers of a list using a notification template.

Parameters (5)

list_idstringrequired
The list ID to send to
templatestringrequired
Template ID or notification slug
dataobject
Key-value data for template variables
methodstring
Routing method
channelsarray
Channel names to route through. Omit to use template routing config.

get_tenant

Get a tenant by its ID.

Parameters (1)

tenant_idstringrequired
The tenant ID

create_or_update_tenant

Create or replace a tenant. Tenants represent organizations or groups that users belong to.

Parameters (7)

tenant_idstringrequired
The tenant ID
namestringrequired
Display name for the tenant
parent_tenant_idstring
Parent tenant ID for hierarchical tenants
default_preferencesany
Default notification preferences for users in this tenant
propertiesobject
Custom properties for the tenant
user_profileobject
Default profile data for users in this tenant
brand_idstring
Brand ID to associate with this tenant

list_tenants

List all tenants in the workspace.

Parameters (2)

cursorstring
Pagination cursor
limitnumber
Max results per page

delete_tenant

Delete a tenant by its ID.

Parameters (1)

tenant_idstringrequired
The tenant ID to delete

list_tenant_users

List users associated with a tenant.

Parameters (3)

tenant_idstringrequired
The tenant ID
cursorstring
Pagination cursor
limitnumber
Max results per page (default 20, max 100)

update_tenant_preference

Set the default notification preference for a subscription topic on a tenant. This controls tenant-level defaults — it does NOT set per-user preferences (use the user preferences API for that). The topic_id must already exist as a subscription topic in the workspace; a 404 means the topic has not been created yet. Example: { tenant_id: "acme", topic_id: "marketing-updates", status: "OPTED_IN", has_custom_routing: true, custom_routing: ["email", "push"] }.

Parameters (5)

tenant_idstringrequired
The tenant ID
topic_idstringrequired
The subscription topic ID — must already exist in the workspace. A 404 response means the topic does not exist; create it in the Preferences Editor first.
statusstringrequired
Subscription status for the topic
custom_routingarray
Default channels when has_custom_routing is enabled
has_custom_routingboolean
When true, use custom_routing instead of template defaults

delete_tenant_preference

Remove default notification preference for a topic from a tenant.

Parameters (2)

tenant_idstringrequired
The tenant ID
topic_idstringrequired
The subscription topic ID

list_tenant_templates

List notification templates configured for a tenant.

Parameters (3)

tenant_idstringrequired
The tenant ID
cursorstring
Pagination cursor
limitnumber
Max results per page (default 20, max 100)

get_tenant_template

Get a tenant notification template association by template ID.

Parameters (2)

tenant_idstringrequired
The tenant ID
template_idstringrequired
The template ID

replace_tenant_template

Create or replace a tenant notification template (draft unless published is true).

Parameters (8)

tenant_idstringrequired
The tenant ID
template_idstringrequired
The template ID
titlestring
Optional title merged into template content when provided
contentany
Elemental content object (e.g. elements and version per Courier Elemental schema)
channelsany
Channel-specific delivery configuration
providersany
Provider-specific routing configuration
routingany
Message routing configuration
publishedboolean
When true, publish immediately after save

publish_tenant_template

Publish a version of a tenant notification template.

Parameters (3)

tenant_idstringrequired
The tenant ID
template_idstringrequired
The template ID
versionstring
Version to publish (e.g. v1, latest); defaults to latest if omitted

get_tenant_template_version

Get a specific version of a tenant notification template (e.g. latest, published, or v1).

Parameters (3)

tenant_idstringrequired
The tenant ID
template_idstringrequired
The template ID
versionstringrequired
Version identifier (latest, published, or v-prefixed)

delete_tenant_template

Delete a tenant notification template. Returns 204 on success, 404 if the template does not exist for this tenant.

Parameters (2)

tenant_idstringrequired
The tenant ID that owns the template
template_idstringrequired
The notification template ID to delete

get_translation

Get a translation for a specific locale (e.g. "en_US", "fr_FR").

Parameters (2)

localestringrequired
Locale code (e.g. en_US, fr_FR)
domainstring
Translation domain (only "default" is supported currently)

update_translation

Create or update a translation for a specific locale.

Parameters (3)

localestringrequired
Locale code (e.g. en_US, fr_FR)
bodystringrequired
Translation content (PO file format)
domainstring
Translation domain

list_user_push_tokens

List all push/device tokens for a user.

Parameters (1)

user_idstringrequired
The user ID

get_user_push_token

Get a specific push/device token for a user.

Parameters (2)

user_idstringrequired
The user ID
tokenstringrequired
The token identifier

create_or_replace_user_push_token

Create or replace a push/device token for a user.

Parameters (4)

user_idstringrequired
The user ID
tokenstringrequired
The token string
provider_keystringrequired
Push provider
deviceobject
Device metadata

bulk_add_user_tokens

Add multiple push/device tokens for a user in one request. Overwrites matching existing tokens.

Parameters (2)

user_idstringrequired
The user ID
tokensarrayrequired
Token records to upsert

patch_user_token

Apply a JSON Patch (RFC 6902) to a specific push token.

Parameters (3)

user_idstringrequired
The user ID
tokenstringrequired
The token identifier
patcharrayrequired
Array of JSON Patch operations

delete_user_token

Delete a specific push token for a user.

Parameters (2)

user_idstringrequired
The user ID
tokenstringrequired
The token identifier to delete

get_user_preferences

Get a user's notification preferences (subscriptions, opt-outs, channel preferences).

Parameters (2)

user_idstringrequired
The user ID
tenant_idstring
Scope preferences to a specific tenant

get_user_preference_topic

Get a user's preference for a specific subscription topic.

Parameters (3)

user_idstringrequired
The user ID
topic_idstringrequired
The subscription topic ID
tenant_idstring
Scope to a specific tenant

update_user_preference_topic

Update a user's preference for a specific subscription topic (opt in, opt out, or set channel preferences).

Parameters (5)

user_idstringrequired
The user ID
topic_idstringrequired
The subscription topic ID
statusstringrequired
Preference status
has_custom_routingboolean
Whether custom channel routing is set
custom_routingarray
Custom channel routing order

list_user_tenants

List all tenants a user belongs to.

Parameters (3)

user_idstringrequired
The user ID
cursorstring
Pagination cursor
limitnumber
Max results per page

add_user_to_tenant

Add a user to a tenant.

Parameters (3)

user_idstringrequired
The user ID
tenant_idstringrequired
The tenant ID
profileobject
Tenant-scoped profile overrides

remove_user_from_tenant

Remove a user from a tenant.

Parameters (2)

user_idstringrequired
The user ID
tenant_idstringrequired
The tenant ID

bulk_add_user_tenants

Add a user to multiple tenants at once. A custom profile can be supplied per tenant.

Parameters (2)

user_idstringrequired
The user ID
tenantsarrayrequired
Array of tenant associations

remove_all_user_tenants

Remove a user from all tenants.

Parameters (1)

user_idstringrequired
The user ID

archive_request

Archive a send request and all its associated messages by request ID.

Parameters (1)

request_idstringrequired
The request ID (requestId returned from /send)

create_routing_strategy

Create a routing strategy defining how notifications are delivered across channels and providers.

Parameters (6)

namestringrequired
Human-readable name for the routing strategy
routingobjectrequired
Routing tree defining channel selection method and order
channelsobject
Per-channel delivery configuration
providersobject
Per-provider delivery configuration
descriptionstring
Description of the routing strategy
tagsarray
Tags for categorization

get_routing_strategy

Retrieve a routing strategy by ID. Returns the full entity including routing, channels, and providers.

Parameters (1)

routing_strategy_idstringrequired
The routing strategy ID (rs_ prefix)

replace_routing_strategy

Replace a routing strategy. Full document replacement; missing optional fields are cleared.

Parameters (7)

routing_strategy_idstringrequired
The routing strategy ID
namestringrequired
Human-readable name
routingobjectrequired
Routing tree
channelsobject
Per-channel delivery configuration. Omit to clear.
providersobject
Per-provider delivery configuration. Omit to clear.
descriptionstring
Description. Omit to clear.
tagsarray
Tags. Omit to clear.

archive_routing_strategy

Archive a routing strategy. The strategy must not have associated notification templates; unlink all templates before archiving.

Parameters (1)

routing_strategy_idstringrequired
The routing strategy ID to archive

list_routing_strategies

List routing strategies in the workspace. Returns metadata only; use get for full details.

Parameters (2)

cursorstring
Pagination cursor
limitnumber
Max results per page (default 20, max 100)

list_routing_strategy_notifications

List notification templates associated with a routing strategy. Useful for checking linked templates before archiving.

Parameters (3)

routing_strategy_idstringrequired
The routing strategy ID (rs_ prefix)
cursorstring
Pagination cursor
limitnumber
Max results per page (default 20, max 100)

list_journeys

List journey templates in the workspace. Call this first to discover journey IDs before calling invoke_journey, get_journey, or replace_journey. Optionally filter by version (published or draft).

Parameters (2)

cursorstring
Pagination cursor
versionstring
Filter by version state. Defaults to published.

invoke_journey

Invoke a journey run from a journey template. Call list_journeys first to find the template_id. Example: { template_id: "j-onboarding", user_id: "user-123", data: { plan: "pro" } }.

Parameters (4)

template_idstringrequired
The journey template ID
user_idstring
Recipient user ID. Can also be resolved from profile or data.
dataobject
Data payload passed to the journey for conditions and template variables
profileobject
Profile data for the user (email, phone, custom fields)

create_journey

Create a new journey. Defaults to DRAFT state. Send nodes are not allowed on create — create the shell with a trigger node, then call replace_journey to add send nodes after linking notification templates. Call publish_journey to make it live. Node ids are server-generated; do NOT include an id field. Example: { name: "Welcome Journey", nodes: [{ type: "trigger", trigger_type: "api-invoke" }], enabled: true }.

Parameters (4)

namestringrequired
Journey display name
nodesarrayrequired
Array of journey node objects. Node ids are server-generated — do NOT include an id field. Trigger node example: { type: "trigger", trigger_type: "api-invoke" }. Send node example: { type: "send", template: "nt_abc" }. Delay node example: { type: "delay", mode: "duration", duration: "PT1H" }.
enabledboolean
Whether the journey is active. Defaults to true.
statestring
Create as DRAFT (default) or PUBLISHED immediately.

get_journey

Get a journey by ID. Pass version=draft to retrieve the working draft, or version=vN for a historical version. Defaults to published.

Parameters (2)

journey_idstringrequired
The journey template ID
versionstring
Version to retrieve: "draft", "published" (default), or a version string like "v001"

replace_journey

Replace (update) a journey draft. Full document replacement — include all nodes and properties in the body. Call publish_journey afterwards to make changes live, or pass state: "PUBLISHED" to publish immediately. Send node template IDs must already be scoped to this journey.

Parameters (5)

journey_idstringrequired
The journey template ID to update
namestringrequired
Journey display name
nodesarrayrequired
Complete array of journey nodes. Use server-assigned node ids from get_journey — do NOT invent new ids. Each node requires type plus type-specific fields.
enabledboolean
Whether the journey is active.
statestring
Set to PUBLISHED to publish immediately after replace.

publish_journey

Publish the current draft of a journey, making it live and invokable. Pass version to roll back to a prior published version instead of publishing the draft. Returns 404 if there is no draft to publish.

Parameters (2)

journey_idstringrequired
The journey template ID to publish
versionstring
Historical version to roll back to (e.g. "v001"). Omit to publish the current draft.

archive_journey

Archive a journey. Archived journeys cannot be invoked but existing runs continue to completion.

Parameters (1)

journey_idstringrequired
The journey template ID to archive

list_journey_versions

List published versions of a journey, ordered most recent first.

Parameters (1)

journey_idstringrequired
The journey template ID

list_journey_templates

List notification templates scoped to a journey. Journey-scoped templates can only be used by send nodes within the same journey. Call this to discover template IDs before wiring send nodes in replace_journey.

Parameters (3)

journey_idstringrequired
The journey template ID
cursorstring
Pagination cursor
limitnumber
Page size (1–100)

create_journey_template

Create a notification template scoped to a journey. Defaults to DRAFT; pass state: "PUBLISHED" to publish on create. The template can then be referenced in journey send nodes. Example: { journey_id: "j-abc", channel: "email", notification: { name: "Welcome Email", tags: [], brand: null, subscription: null, content: { version: "2022-01-01", elements: [{ type: "text", content: "Hello!" }] } } }.

Parameters (5)

journey_idstringrequired
The journey template ID
channelstringrequired
Channel for this template (e.g. "email", "push", "sms", "inbox")
notificationobjectrequired
Notification template definition
provider_keystring
Specific provider key to target
statestring
Initial state: "DRAFT" (default) or "PUBLISHED"

get_journey_template

Get a journey-scoped notification template by notification ID. Pass version=draft to retrieve the working draft (required before the template has been published). Defaults to published.

Parameters (3)

notification_idstringrequired
The notification template ID
journey_idstringrequired
The journey template ID that owns this notification
versionstring
Version to retrieve: "draft", "published" (default), or "vN"

replace_journey_template

Replace the draft of a journey-scoped notification template. Full document replacement. Call publish_journey_template afterwards to make it live.

Parameters (4)

notification_idstringrequired
The notification template ID
journey_idstringrequired
The journey template ID that owns this notification
notificationobjectrequired
Full notification template definition
statestring
"PUBLISHED" to publish immediately after replace

archive_journey_template

Archive a journey-scoped notification template. Archived templates cannot be sent.

Parameters (2)

notification_idstringrequired
The notification template ID
journey_idstringrequired
The journey template ID that owns this notification

publish_journey_template

Publish the current draft of a journey-scoped notification template. Optionally pass version to roll back to a prior version.

Parameters (3)

notification_idstringrequired
The notification template ID
journey_idstringrequired
The journey template ID that owns this notification
versionstring
Version to roll back to (e.g. "v1"). Omit to publish current draft.

list_journey_template_versions

List published versions of a journey-scoped notification template, ordered most recent first.

Parameters (2)

notification_idstringrequired
The notification template ID
journey_idstringrequired
The journey template ID that owns this notification

list_providers

List configured provider integrations for the workspace.

Parameters (1)

cursorstring
Pagination cursor

get_provider

Fetch a single provider configuration by ID.

Parameters (1)

provider_idstringrequired
The provider configuration ID

list_provider_catalog

List available provider types from the catalog with their configuration schemas.

Parameters (3)

keysstring
Comma-separated provider keys to filter by
namestring
Substring match on provider name
channelstring
Filter by channel type (email, sms, push, etc.)

create_provider

Create a new provider (integration) configuration. Once routing strategies or notification templates reference this config, credential or settings mistakes can affect live sends—confirm provider key and settings against list_provider_catalog before saving. The provider field must be a known Courier provider key.

Parameters (4)

providerstringrequired
Provider key from the catalog (e.g. sendgrid, twilio, firebase-fcm)
titlestring
Display name for this provider configuration
aliasstring
Short alias for referencing this provider
settingsobject
Provider-specific settings (API keys, credentials, etc.)

update_provider

Replace an existing provider configuration. Full replacement — retrieve current config with get_provider first; omitted optional fields are cleared. Changing API keys or settings affects live delivery if this integration is in use.

Parameters (5)

provider_idstringrequired
The provider configuration ID
providerstringrequired
Provider key (must match existing; changing provider type is not supported)
titlestring
Display name
aliasstring
Short alias
settingsobject
Provider-specific settings

delete_provider

Delete a provider configuration. Returns 409 if the provider is still referenced by routing or notifications.

Parameters (1)

provider_idstringrequired
The provider configuration ID to delete

README.md9 KBView on GitHub

Courier MCP Server

The official Model Context Protocol (MCP) server for the Courier notification API. It gives AI agents full access to the Courier API — send messages, manage profiles, debug deliveries, configure lists, and more — through 124 tools backed by the @trycourier/courier Node SDK.

Install

Hosted (recommended)

Courier runs a hosted MCP server at https://mcp.courier.com. No local setup required.

Cursor — add to .cursor/mcp.json:

json

{
  "mcpServers": {
    "Courier": {
      "url": "https://mcp.courier.com",
      "headers": {
        "api_key": "YOUR_COURIER_API_KEY"
      }
    }
  }
}

Claude Code:

bash

claude mcp add Courier --transport http --url https://mcp.courier.com --header "api_key: YOUR_COURIER_API_KEY"

Claude Desktop — add to claude_desktop_config.json:

json

{
  "mcpServers": {
    "Courier": {
      "url": "https://mcp.courier.com",
      "headers": {
        "api_key": "YOUR_COURIER_API_KEY"
      }
    }
  }
}

Local development

bash

git clone https://github.com/trycourier/courier-mcp.git
cd courier-mcp
sh dev.sh

Then point your IDE at http://localhost:3000 with the same config format above.

Tools

123 default tools organized by API resource, plus 1 diagnostic tool available in local installs.

Default tools

Category	Tools
Send	`send_message`, `send_message_template`, `send_message_to_list`, `send_message_to_list_template`
Messages	`list_messages`, `get_message`, `get_message_content`, `get_message_history`, `cancel_message`
Profiles	`get_user_profile_by_id`, `create_or_merge_user`, `replace_profile`, `patch_profile`, `delete_profile`, `get_user_list_subscriptions`, `subscribe_user_to_lists`, `delete_user_list_subscriptions`
Lists	`list_lists`, `get_list`, `get_list_subscribers`, `create_list`, `delete_list`, `restore_list`, `subscribe_user_to_list`, `unsubscribe_user_from_list`, `bulk_subscribe_to_list`, `add_subscribers_to_list`
Audiences	`get_audience`, `list_audience_members`, `list_audiences`, `update_audience`, `delete_audience`
Notifications	`list_notifications`, `get_notification`, `get_notification_content`, `get_notification_draft_content`, `create_notification`, `replace_notification`, `archive_notification`, `publish_notification`, `list_notification_versions`, `list_notification_checks`, `update_notification_checks`, `put_notification_content`, `put_notification_element`, `put_notification_locale`, `cancel_notification_submission`
Brands	`create_brand`, `get_brand`, `list_brands`, `update_brand`, `delete_brand`
Auth	`generate_jwt_for_user`
Device Tokens	`list_user_push_tokens`, `get_user_push_token`, `create_or_replace_user_push_token`, `bulk_add_user_tokens`, `patch_user_token`, `delete_user_token`
Docs	`courier_installation_guide`
Automations	`invoke_automation_template`, `invoke_ad_hoc_automation`, `list_automations`, `cancel_automation`
Bulk	`create_bulk_job`, `add_bulk_users`, `run_bulk_job`, `get_bulk_job`, `list_bulk_users`
Audit Events	`get_audit_event`, `list_audit_events`
Inbound	`track_inbound_event`
Tenants	`get_tenant`, `create_or_update_tenant`, `list_tenants`, `delete_tenant`, `list_tenant_users`, `update_tenant_preference`, `delete_tenant_preference`, `list_tenant_templates`, `get_tenant_template`, `replace_tenant_template`, `publish_tenant_template`, `get_tenant_template_version`, `delete_tenant_template`
Users	`get_user_preferences`, `get_user_preference_topic`, `update_user_preference_topic`, `list_user_tenants`, `add_user_to_tenant`, `remove_user_from_tenant`, `bulk_add_user_tenants`, `remove_all_user_tenants`
Routing Strategies	`create_routing_strategy`, `get_routing_strategy`, `replace_routing_strategy`, `archive_routing_strategy`, `list_routing_strategies`, `list_routing_strategy_notifications`
Journeys	`list_journeys`, `invoke_journey`, `create_journey`, `get_journey`, `replace_journey`, `publish_journey`, `archive_journey`, `list_journey_versions`, `list_journey_templates`, `create_journey_template`, `get_journey_template`, `replace_journey_template`, `archive_journey_template`, `publish_journey_template`, `list_journey_template_versions`
Requests	`archive_request`
Providers	`list_providers`, `get_provider`, `list_provider_catalog`, `create_provider`, `update_provider`, `delete_provider`
Translations	`get_translation`, `update_translation`

Diagnostic tools (local only)

Category	Tools
Config	`get_environment_config` — check which API key, base URL, and package version the MCP session is using

Safer defaults (optional client policies)

Tools that send live traffic, carry destructiveHint in MCP annotations, or mutate provider integrations are listed in code as RECOMMENDED_CLIENT_DISABLED_TOOLS (source). Export it from @trycourier/courier-mcp if you want to drive codegen or docs. Teams typically paste subsets into Claude Code (permissions.deny / mcp__<serverName>__<toolName>) or Codex ([mcp_servers.<name>.disabled_tools] in config.toml). This does not change hosted MCP behavior until each client applies its own policy.

Architecture

code

courier-mcp/
├── mcp/                    # MCP package (@trycourier/courier-mcp on npm)
│   └── src/
│       ├── index.ts        # CourierMcp server class
│       ├── policy/         # Optional client policy helpers (e.g. recommended disable list)
│       ├── tools/          # Tool definitions (one file per API resource)
│       └── utils/          # Config, error handling, registry
├── server/                 # Express server (hosts the MCP package via HTTP)
│   └── src/index.ts        # Stateless HTTP handler
└── dev.sh                  # Local development launcher

The MCP package uses the official @trycourier/courier Node SDK (Stainless-generated) for all API calls. The SDK stays in sync with the Courier API spec automatically, so tool implementations are thin wrappers with proper error handling.

Configuration

Header	Required	Description
`api_key`	Yes	Your Courier API key. Get one at app.courier.com/settings/api-keys.
`base_url`	No	Override the API base URL. Defaults to `https://api.courier.com`.

Development

bash

# Install dependencies
cd mcp && npm install && cd ../server && npm install && cd ..

# Start development server
sh dev.sh

# Run tests
cd mcp && npm test

# Build
cd mcp && npm run build

SDK dependency updates

The @trycourier/courier SDK dependency in mcp/ is updated automatically via Dependabot. Dependabot checks npm daily and opens a PR when a new SDK version is available.

Patch/minor bumps: review CI status, then merge.
Major bumps (labeled breaking-review): check whether any tool input schemas or error handling need updates before merging.

After merging a Dependabot PR, the full pipeline runs automatically:

auto-version-bump.yml bumps the MCP package patch version and pushes to main.
publish-npm.yml publishes the new version to npm.
bump-services.yml opens a PR in trycourier/services to update the hosted MCP server.

Secrets required (set in repo Settings > Secrets and variables > Actions):

REPO_TOKEN — PAT with Contents: Read and write on this repo. Used by auto-version-bump.yml to push to main and trigger downstream workflows.
SERVICES_REPO_TOKEN — PAT with Contents: Read and write + Pull requests: Read and write on trycourier/services. Used by bump-services.yml to open dependency bump PRs.
NPM_TOKEN — npm publish token. Used by publish-npm.yml.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "courier": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.courier.com"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.