Courier MCP tools: every tool, grouped by resource

The hosted MCP server exposes 170 tools, one per Courier API operation. first, then describe the job to your agent and it picks the tools. A request like the one below maps to list_messages filtered to the recipient, then trace_message on the match, which returns the event history and the status reason.

MCP

With Courier MCP, find out why user_123 didn't get their order confirmation yesterday.

How an agent uses these tools

Your agent reads each tool’s name, description, and input schema when it connects. The descriptions below come from the same tool registry, trimmed to one line. You never call a tool by name yourself. The API key decides where every tool acts. A key belongs to one , and each environment has its own templates, users, and logs. Connect a Test key while the agent is learning your workspace, because Test’s built-in email provider only delivers to the address you signed up with. Write in the tables marks a tool that changes workspace state, including every send. Everything unmarked is a read. If your client can require approval per tool, require it for the write tools. A template edit is a draft until something publishes it. The put_ and replace_ tools for templates and journeys write the draft, and sends use the published version. An agent that edits content and stops there has changed nothing a recipient sees, so ask it to publish.

Common tasks

Task	Tools, in order
Send a template to a user	`list_notifications`, `send_message_template`
Find out why a message failed	`list_messages`, `trace_message`
Edit and ship a template	`get_notification_draft_content`, `put_notification_content`, `publish_notification`
Translate a template	`get_notification_draft_content`, `put_notification_locale`, `publish_notification`
Check a template’s delivery rates	`get_notification_metrics`
Start a journey for a user	`list_journeys`, `invoke_journey`
Debug a journey run	`list_journey_runs`, `list_journey_run_steps`, `trace_message`
Announce something to a list	`create_broadcast`, `put_broadcast_content`, `send_broadcast` or `schedule_broadcast`
See a template on real email clients	`list_preview_device_sets`, `create_preview_run`, `get_preview_run`
Onboard a customer organization	`create_or_update_tenant`, `add_user_to_tenant`
Connect a provider	`list_provider_catalog`, `create_provider`
Add Courier to an app	`courier_installation_guide`

Send

send_message and send_message_to_list take an inline title and body. The _template versions send a published template. A list send reaches every subscriber at once. For an announcement you want to schedule, use Broadcasts.

Tool	What it does	Write
`send_message`	Send a message to a user using inline title and body content (no template).	Yes
`send_message_template`	Send a message to a user using a published notification template.	Yes
`send_message_to_list`	Send a message to all subscribers of a list using inline title and body content.	Yes
`send_message_to_list_template`	Send a message to all subscribers of a list using a notification template.	Yes

Messages

Every read here comes from the message logs. trace_message is the one to reach for first. Give it a message_id, or the metadata.trace_id you set on a send, and it returns each matching message with its event history and status reason. explains what each status means.

Tool	What it does	Write
`list_messages`	List messages you’ve previously sent.
`get_message`	Get the full details and status of a single message by its ID.
`get_message_content`	Get the rendered content (HTML, text, subject) of a previously sent message.
`get_message_history`	Get the event history for a message, showing each step in the delivery pipeline (enqueued, sent, delivered, etc.).
`cancel_message`	Cancel a message that is currently being delivered.	Yes
`resend_message`	Resend a previously sent message.	Yes
`trace_message`	Trace delivery in one call.

Profiles

Three writes that behave differently. create_or_merge_user merges into an existing profile, replace_profile overwrites every field, and patch_profile applies JSON Patch operations. Ask for a merge when you mean “add this field”, or a replace can drop the fields you left out.

Tool	What it does	Write
`get_user_profile_by_id`	Get a user profile by their ID.
`create_or_merge_user`	Create a new user profile or merge supplied values into an existing profile (POST).	Yes
`replace_profile`	Fully replace a user profile (PUT).	Yes
`patch_profile`	Partially update a user profile via JSON Patch (RFC 6902).	Yes
`delete_profile`	Delete a user profile permanently.	Yes
`get_user_list_subscriptions`	Get all list subscriptions for a user.
`subscribe_user_to_lists`	Subscribe a user to one or more lists.	Yes
`delete_user_list_subscriptions`	Delete all list subscriptions for a user.	Yes

Lists

A list is a set of users you subscribe explicitly. bulk_subscribe_to_list replaces every subscriber, while add_subscribers_to_list appends. Say “add” when you mean add, or the agent can pick the tool that removes everyone else.

Tool	What it does	Write
`list_lists`	Get all lists.
`get_list`	Get a list by its ID.
`get_list_subscribers`	Get all subscribers of a list.
`create_list`	Create or update a list by list ID.	Yes
`subscribe_user_to_list`	Subscribe a user to a list.	Yes
`unsubscribe_user_from_list`	Unsubscribe a user from a list.	Yes
`delete_list`	Delete a list by its ID.	Yes
`restore_list`	Restore a previously deleted list.	Yes
`bulk_subscribe_to_list`	Replace all subscribers on a list with the given recipients.	Yes
`add_subscribers_to_list`	Append subscribers to a list without removing existing subscribers.	Yes

Audiences

An audience is a filter on profile fields, so its membership updates as profiles change. You never add users to it, and a broadcast can target it.

Tool	What it does	Write
`get_audience`	Get an audience by its ID, including its filter definition.
`list_audience_members`	List all members of an audience.
`list_audiences`	List all audiences in the workspace.
`update_audience`	Create or update an audience with a filter definition.	Yes
`delete_audience`	Delete an audience by its ID.	Yes

Notification templates

Content is Elemental JSON, and writes land on the draft. publish_notification makes the draft live. put_notification_locale sets one locale’s translations and merges them into what’s there. put_notification_element replaces an element with only the fields it takes (type, data, channels, if, loop, ref), so change an element’s text or translations with put_notification_content or put_notification_locale.

Tool	What it does	Write
`list_notifications`	List notification templates.
`get_notification_content`	Get the published content blocks of a notification template.
`get_notification_draft_content`	Get the draft (unpublished) content blocks of a notification template.
`create_notification`	Create a V2 notification template.	Yes
`get_notification`	Retrieve a notification template by ID.
`replace_notification`	Replace a notification template entirely (full document PUT).	Yes
`archive_notification`	Archive a notification template by ID.	Yes
`get_notification_metrics`	Get one template’s delivery funnel over time: sent, delivered, opened, clicked, errors, and undeliverable, per provider and channel.
`list_notification_versions`	List version history for a notification template.
`publish_notification`	Publish a notification template, making it available for sending.	Yes
`list_notification_checks`	List checks for a notification submission.
`update_notification_checks`	Update check statuses for a notification submission.	Yes
`put_notification_content`	Replace the elemental content of a V2 notification template.	Yes
`put_notification_element`	Update a single element within a V2 notification template.	Yes
`put_notification_locale`	Set locale-specific content overrides for a V2 notification template.	Yes
`cancel_notification_submission`	Cancel a notification template submission.	Yes

Brands

A brand holds the styling a template renders with. update_brand replaces the whole brand, so read it first and send every field back.

Tool	What it does	Write
`create_brand`	Create a new brand.	Yes
`get_brand`	Get a brand by its ID.
`list_brands`	List all brands in the workspace.
`update_brand`	Replace an existing brand with new values.	Yes
`delete_brand`	Delete a brand by its ID.	Yes

Auth

generate_jwt_for_user issues the token a client SDK, such as Inbox, signs in with. Scope each token to one user.

Tool	What it does	Write
`generate_jwt_for_user`	Generate a JWT authentication token for a user.	Yes

Device tokens

Push tokens stored on a user, for Firebase FCM, APNs, Expo, and OneSignal.

Tool	What it does	Write
`list_user_push_tokens`	List all push/device tokens for a user.
`get_user_push_token`	Get a specific push/device token for a user.
`create_or_replace_user_push_token`	Create or replace a push/device token for a user.	Yes
`bulk_add_user_tokens`	Add multiple push/device tokens for a user in one request.	Yes
`patch_user_token`	Apply a JSON Patch (RFC 6902) to a specific push token.	Yes
`delete_user_token`	Delete a specific push token for a user.	Yes

Bulk

Same order as the API: create the job, add users, then run it. Nothing sends until run_bulk_job, and get_bulk_job reports progress.

Tool	What it does	Write
`create_bulk_job`	Create a new bulk job for sending messages to multiple recipients.	Yes
`add_bulk_users`	Add users to an existing bulk job.	Yes
`run_bulk_job`	Run a bulk job, triggering delivery to all added users.	Yes
`get_bulk_job`	Get the status of a bulk job.
`list_bulk_users`	List the users in a bulk job.

Tenants

A tenant is one of your customer organizations. Tenant templates override a workspace template for that one tenant, and tenant preferences set the defaults its users start from.

Tool	What it does	Write
`get_tenant`	Get a tenant by its ID.
`create_or_update_tenant`	Create or replace a tenant.	Yes
`list_tenants`	List all tenants in the workspace.
`delete_tenant`	Delete a tenant by its ID.	Yes
`list_tenant_users`	List users associated with a tenant.
`update_tenant_preference`	Set the default notification preference for a subscription topic on a tenant.	Yes
`delete_tenant_preference`	Remove default notification preference for a topic from a tenant.	Yes
`list_tenant_templates`	List notification templates configured for a tenant.
`get_tenant_template`	Get a tenant notification template association by template ID.
`replace_tenant_template`	Create or replace a tenant notification template (draft unless published is true).	Yes
`publish_tenant_template`	Publish a version of a tenant notification template.	Yes
`get_tenant_template_version`	Get a specific version of a tenant notification template: `latest`, `published`, or a version such as `v1`.
`delete_tenant_template`	Delete a tenant notification template.	Yes

Users

Per-user preferences and tenant membership. bulk_update_user_preferences adds to what the user already has, and bulk_replace_user_preferences replaces their whole set.

Tool	What it does	Write
`get_user_preferences`	Get a user’s notification preferences (subscriptions, opt-outs, channel preferences).
`get_user_preference_topic`	Get a user’s preference for a specific subscription topic.
`update_user_preference_topic`	Update a user’s preference for a specific subscription topic (opt in, opt out, or set channel preferences).	Yes
`delete_user_preference_topic`	Delete a user’s preference for a specific subscription topic, reverting it to the topic’s default status.	Yes
`list_user_tenants`	List all tenants a user belongs to.
`add_user_to_tenant`	Add a user to a tenant, with optional tenant-scoped profile overrides.	Yes
`remove_user_from_tenant`	Remove a user from a tenant.	Yes
`bulk_add_user_tenants`	Add a user to multiple tenants at once.	Yes
`remove_all_user_tenants`	Remove a user from all tenants.	Yes
`bulk_update_user_preferences`	Additively create or update a user’s preferences for one or more topics in a single request.	Yes
`bulk_replace_user_preferences`	Replace a user’s complete set of preference overrides in one request.	Yes

update_user_preference_topic takes tenant_id to write the preference in one tenant’s context, and digest_schedule_id to move the user onto another of the topic’s digest schedules.

Routing strategies

A routing strategy is a reusable channel and provider order that templates reference. list_routing_strategy_notifications shows which templates a change would affect.

Tool	What it does	Write
`create_routing_strategy`	Create a routing strategy defining how notifications are delivered across channels and providers.	Yes
`get_routing_strategy`	Retrieve a routing strategy by ID.
`replace_routing_strategy`	Replace a routing strategy.	Yes
`archive_routing_strategy`	Archive a routing strategy.	Yes
`list_routing_strategies`	List routing strategies in the workspace.
`list_routing_strategy_notifications`	List notification templates associated with a routing strategy.

Journeys

A journey has a draft and published versions, like a template, and only a published journey can be invoked. Journey-scoped templates live inside one journey and publish separately. list_journey_run_steps shows what happened at each node of a run.

Tool	What it does	Write
`list_journeys`	List journey templates in the workspace, returning the journey IDs and version state of each.
`invoke_journey`	Invoke a journey run from a journey template.	Yes
`create_journey`	Create a new journey.	Yes
`get_journey`	Get a journey by ID.
`replace_journey`	Replace (update) a journey draft.	Yes
`publish_journey`	Publish the current draft of a journey, making it live and invokable.	Yes
`archive_journey`	Archive a journey.	Yes
`list_journey_versions`	List published versions of a journey, ordered most recent first.
`list_journey_templates`	List notification templates scoped to a journey.
`create_journey_template`	Create a notification template scoped to a journey, as a draft.	Yes
`get_journey_template`	Get a journey-scoped notification template by notification ID.
`replace_journey_template`	Replace the draft of a journey-scoped notification template.	Yes
`archive_journey_template`	Archive a journey-scoped notification template.	Yes
`publish_journey_template`	Publish the current draft of a journey-scoped notification template.	Yes
`list_journey_template_versions`	List published versions of a journey-scoped notification template, ordered most recent first.
`get_journey_template_content`	Fetch the elemental content of a journey-scoped notification template.
`put_journey_template_content`	Replace the elemental content of a journey-scoped notification template.	Yes
`put_journey_template_locale`	Set locale-specific content overrides for a journey-scoped notification template.	Yes
`cancel_journey`	Cancel journey runs.	Yes
`list_journey_runs`	List journey runs, newest first.
`get_journey_run`	Get one journey run by id: its journey, status, and timestamps.
`list_journey_run_steps`	List the steps of a journey run in order, with each node and what happened at it.

Broadcasts

One message to a list or audience on one channel, sent now or scheduled. A scheduled broadcast locks its content, so call cancel_broadcast_schedule before editing it.

Tool	What it does	Write
`list_broadcasts`	List broadcasts in the workspace.
`create_broadcast`	Create a broadcast: a one-off message to a list or audience on a single channel.	Yes
`get_broadcast`	Get a broadcast by id, including its channel and send or schedule state.
`rename_broadcast`	Rename a broadcast.	Yes
`delete_broadcast`	Delete a broadcast.	Yes
`get_broadcast_content`	Get a broadcast’s Elemental content.
`put_broadcast_content`	Replace a broadcast’s content with an Elemental document.	Yes
`send_broadcast`	Send a broadcast now to every member of a list or audience.	Yes
`schedule_broadcast`	Schedule a broadcast to send later to a list or audience.	Yes
`cancel_broadcast_schedule`	Cancel a broadcast’s scheduled send.	Yes
`duplicate_broadcast`	Copy a broadcast into a new draft.	Yes

Previews

Render a template’s email on real email clients and read the screenshots back. A run is billed to the workspace’s previews add-on and finishes asynchronously, so poll get_preview_run until its status is COMPLETED or FAILED. Every workspace has a read-only Courier Recommended device set to start from.

Tool	What it does	Write
`list_preview_devices`	List the email clients a preview can render on.
`list_preview_device_sets`	List saved preview device sets.
`create_preview_device_set`	Create a named, reusable set of preview devices.	Yes
`get_preview_device_set`	Get a preview device set by id.
`replace_preview_device_set`	Replace a preview device set’s name and devices.	Yes
`archive_preview_device_set`	Archive a preview device set.	Yes
`create_preview_run`	Render a template’s email on real email clients and capture screenshots.	Yes
`list_preview_runs`	List a template’s preview runs, newest first.
`get_preview_run`	Get a preview run with its per-device results and screenshot URLs.

Requests

One send request can produce several messages. Archiving the request archives all of them.

Tool	What it does	Write
`archive_request`	Archive a send request and all its associated messages by request ID.	Yes

Providers

A provider configuration holds your credentials for one delivery service. list_provider_catalog returns the fields each provider type needs, which the agent reads before create_provider.

Tool	What it does	Write
`list_providers`	List configured provider integrations for the workspace.
`get_provider`	Fetch a single provider configuration by ID.
`list_provider_catalog`	List available provider types from the catalog with their configuration schemas.
`create_provider`	Create a new provider (integration) configuration.	Yes
`update_provider`	Replace an existing provider configuration.	Yes
`delete_provider`	Delete a provider configuration.	Yes

Translations

Workspace .po files for the , one per locale. Only the default domain exists today.

Tool	What it does	Write
`get_translation`	Get a translation for a specific locale, such as `en_US` or `fr_FR`.
`update_translation`	Create or update a translation for a specific locale.	Yes

Inbound

Sends an event into Courier that can trigger automations.

Tool	What it does	Write
`track_inbound_event`	Track an inbound event that can trigger automations.	Yes

Audit events

A record of who changed what in the workspace.

Tool	What it does	Write
`get_audit_event`	Get a specific audit event by its ID.
`list_audit_events`	List audit events in the workspace.

Preferences

Workspace-level preference setup. Sections group topics, and a topic is what a user opts in or out of. publish_preferences pushes changes to the hosted preferences page.

Tool	What it does	Write
`list_preference_sections`	List the workspace’s preference sections.
`create_preference_section`	Create a preference section in your workspace.	Yes
`get_preference_section`	Retrieve a preference section by id, including its topics.
`replace_preference_section`	Replace a preference section.	Yes
`archive_preference_section`	Archive a preference section.	Yes
`publish_preferences`	Publish the workspace’s preferences page.	Yes
`list_preference_topics`	List the topics in a preference section.
`create_preference_topic`	Create a subscription preference topic inside a section.	Yes
`get_preference_topic`	Retrieve a topic within a section.
`replace_preference_topic`	Replace a topic within a section.	Yes
`archive_preference_topic`	Archive a topic within a section.	Yes

create_preference_topic and replace_preference_topic take a digest object: its template, schedules, and categories. Leaving digest out of a replace keeps the topic’s digest, and null turns it off.

Digests

release_digest sends every recipient’s held digest for a schedule now. release_user_digest does the same for one recipient and topic.

Tool	What it does	Write
`release_digest`	Release a digest schedule early, sending what users have collected so far instead of waiting for the scheduled time.	Yes
`list_digest_instances`	List the digest instances for a schedule.
`release_user_digest`	Release one recipient’s held digest for a topic now, instead of waiting for its schedule.	Yes

Automations (legacy)

Automations is the previous workflow product. Existing automations keep running, and new workflows are built as .

Tool	What it does	Write
`list_automations`	List automation templates in the workspace, with each template ID and its version state.
`invoke_automation_template`	Invoke an automation run from an existing automation template.	Yes
`invoke_ad_hoc_automation`	Invoke an ad-hoc automation with inline steps.	Yes
`cancel_automation`	Cancel a running automation by its `cancelation_token`.	Yes

Docs

Returns the SDK install steps for a platform, so an agent adding Courier to your app installs the current package.

Tool	What it does	Write
`courier_installation_guide`	Get the Courier SDK installation guide for a specific platform.

Diagnostics

Reports the key, base URL, and package version a session is using, which answers “which workspace is this agent talking to?”

Tool	What it does	Write
`get_environment_config`	Check which Courier API key, base URL, and package version this MCP session is using.

FAQ

How many tools does the Courier MCP server have?

The hosted Courier MCP server exposes 170 tools, covering sends, message logs, profiles, lists, audiences, templates, journeys, broadcasts, email previews, tenants, preferences, providers, and more. Ask your agent to list its Courier tools to see the set it loaded.

Which Courier MCP tools change data?

Every Courier MCP tool marked Write on this page changes workspace state, and that includes every send. The unmarked tools only read. Require approval for the write tools if your client supports it.

Can an AI agent send real notifications through Courier MCP?

The Courier MCP send tools deliver through the providers configured in the API key’s environment, so a Production key reaches real customers. Connect a Test key while you experiment. Test’s built-in email provider only delivers to the address you signed up with.

Why didn't a template change made through Courier MCP reach recipients?

Template writes through Courier MCP land on the draft, and sends use the published version. Ask the agent to call publish_notification, or publish_journey_template for a template inside a journey.

What is the difference between Courier MCP and Courier Skills?

The Courier MCP server gives an agent tools that call the Courier API on your workspace. gives a coding agent instructions for writing Courier code in your app. Most setups use both: Skills while the agent writes code, MCP when it needs to read or change the workspace.

​How an agent uses these tools

​Common tasks

​Send

​Messages

​Profiles

​Lists

​Audiences

​Notification templates

​Brands

​Auth

​Device tokens

​Bulk

​Tenants

​Users

​Routing strategies

​Journeys

​Broadcasts

​Previews

​Requests

​Providers

​Translations

​Inbound

​Audit events

​Preferences

​Digests

​Automations (legacy)

​Docs

​Diagnostics

​FAQ