--- title: "Send a message" method: POST path: "/send" tags: ["Send"] --- # Send a message `POST /send` Sends a message to one or more recipients and returns a requestId. Courier routes it to email, SMS, push, chat, or in-app based on your rules. ## Headers - `Idempotency-Key` string - `x-idempotency-expiration` string ## Request body - object - `message` Message, required — The message property has the following primary top-level properties. They define the destination and content of the message. - `content` union - ElementalContentSugar — Syntactic sugar to provide a fast shorthand for Courier Elemental Blocks. - `title` string, required — Title/subject displayed by supported channels. - `body` string, required — The text content displayed in the notification. - ElementalContent - `version` string, required — For example, "2022-01-01" - `elements` ElementalNode[], required - union - object — Represents a body of text to be rendered inside of the notification. - … - object — The meta element contains information describing the notification that may be used by a particular channel or provider. One important field is the title field which will be used as the title for channels that support it. - … - object — The channel element allows a notification to be customized based on which channel it is sent through. For example, you may want to display a detailed message when the notification is sent through email, and a more concise message in a push notification. Channel elements are only valid as top-level elements; you cannot nest channel elements. If there is a channel element specified at the top-level of the document, all sibling elements must be channel elements. Note: As an alternative, most elements support a `channel` property. Which allows you to selectively display an individual element on a per channel basis. See the [control flow docs](https://www.courier.com/docs/platform/content/elemental/control-flow/) for more details. - … - object — Used to embed an image into the notification. - … - object — Allows the user to execute an action. Can be a button or a link. - … - object — Renders a dividing line between elements. - … - object — Renders a quote block. - … - object — Raw HTML string inside an Elemental document. When rendering a message, this node is turned into output only for the email channel; for other channels it produces no blocks. - … - `template` string, nullable - `data` MessageData - `brand_id` string, nullable - `channels` MessageChannels - `context` MessageContext - `tenant_id` string, nullable — Tenant id used to load brand/default preferences/context. - `metadata` MessageMetadata - `event` string, nullable - `tags` string[], nullable - `utm` UTM - `source` string, nullable - `medium` string, nullable - `campaign` string, nullable - `term` string, nullable - `content` string, nullable - `trace_id` string, nullable - `preferences` MessagePreferences - `subscription_topic_id` string, required — The subscription topic to apply to the message. - `providers` MessageProviders - `routing` Routing — Customize which channels/providers Courier may deliver the message through. - `method` 'all' | 'single', required - `channels` MessageRoutingChannel[], required — A list of channels or providers (or nested routing rules). - union - string - MessageRouting - `method` 'all' | 'single', required - `channels` MessageRoutingChannel[], required - `timeout` Timeout - `provider` object, nullable - `channel` object, nullable - `message` integer, nullable - `escalation` integer, nullable - `criteria` 'no-escalation' | 'delivered' | 'viewed' | 'engaged' - `delay` Delay - `duration` integer, nullable — The duration of the delay in milliseconds. - `until` string, nullable — ISO 8601 timestamp or opening_hours-like format. - `timezone` string, nullable — IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Used when resolving opening hours expressions. Takes precedence over user profile timezone settings. - `expiry` Expiry - `expires_at` string, nullable — Epoch or ISO8601 timestamp with timezone. - `expires_in` union, required - string - integer - `to` union — The recipient of a message. Can be a single recipient or an array of recipients. - union — A single recipient of the message. Choose one of the following types based on how you want to identify the recipient: - **User**: Send to a specific user by user_id, email, or phone number - **Audience**: Send to all users in an audience - **List**: Send to all users in a list - **List Pattern**: Send to users in lists matching a pattern - **Slack**: Send via Slack (channel, email, or user_id) - **MS Teams**: Send via Microsoft Teams - **PagerDuty**: Send via PagerDuty - **Webhook**: Send via webhook - UserRecipient - AudienceRecipient — Send to all users in an audience - `audience_id` string, required — A unique identifier associated with an Audience. A message will be sent to each user in the audience. - `data` MessageData - `filters` AudienceFilter[], nullable - `operator` 'MEMBER_OF', required — Send to users only if they are member of the account - `path` 'account_id', required - `value` string, required - ListRecipient — Send to all users in a specific list - `list_id` string, nullable - `data` MessageData - `filters` ListFilter[], nullable - `operator` 'MEMBER_OF', required — Send to users only if they are member of the account - `path` 'account_id', required - `value` string, required - ListPatternRecipient — Send to users in lists matching a pattern - `list_pattern` string, nullable - `data` MessageData - SlackRecipient — Send via Slack (channel, email, or user_id) - `slack` union, required - SendToSlackChannel - … - SendToSlackEmail - … - SendToSlackUserId - … - MsTeamsRecipient — Send via Microsoft Teams - `ms_teams` union, required - SendToMsTeamsUserId - … - SendToMsTeamsEmail - … - SendToMsTeamsChannelId - … - SendToMsTeamsConversationId - … - SendToMsTeamsChannelName - … - PagerdutyRecipient — Send via PagerDuty - `pagerduty` Pagerduty, required - `routing_key` string, nullable - `event_action` string, nullable - `severity` string, nullable - `source` string, nullable - WebhookRecipient — Send via webhook - `webhook` WebhookProfile, required - `url` string, required — The URL to send the webhook request to. - `method` 'POST' | 'PUT' - `headers` object, nullable — Custom headers to include in the webhook request. - `authentication` WebhookAuthentication - … - `profile` 'limited' | 'expanded' - Recipient[] - union — A single recipient of the message. Choose one of the following types based on how you want to identify the recipient: - **User**: Send to a specific user by user_id, email, or phone number - **Audience**: Send to all users in an audience - **List**: Send to all users in a list - **List Pattern**: Send to users in lists matching a pattern - **Slack**: Send via Slack (channel, email, or user_id) - **MS Teams**: Send via Microsoft Teams - **PagerDuty**: Send via PagerDuty - **Webhook**: Send via webhook - UserRecipient - AudienceRecipient — Send to all users in an audience - `audience_id` string, required — A unique identifier associated with an Audience. A message will be sent to each user in the audience. - `data` MessageData - `filters` AudienceFilter[], nullable - … - ListRecipient — Send to all users in a specific list - `list_id` string, nullable - `data` MessageData - `filters` ListFilter[], nullable - … - ListPatternRecipient — Send to users in lists matching a pattern - `list_pattern` string, nullable - `data` MessageData - SlackRecipient — Send via Slack (channel, email, or user_id) - `slack` union, required - … - MsTeamsRecipient — Send via Microsoft Teams - `ms_teams` union, required - … - PagerdutyRecipient — Send via PagerDuty - `pagerduty` Pagerduty, required - … - WebhookRecipient — Send via webhook - `webhook` WebhookProfile, required - … ## Response `200` - SendMessageResponse - `requestId` string, required — A successful call to `POST /send` returns a `202` status code along with a `requestId` in the response body. For single-recipient requests, the `requestId` is the derived message_id. For multiple recipients, Courier assigns a unique message_id to each derived message. --- [API](https://skmtc.net/trycourier/apis/courier.md) · [All operations](https://skmtc.net/trycourier/apis/courier/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trycourier/courier/versions/04f69fbf96a5/schema)