--- title: "Send a message" method: POST path: "/send" tags: ["Send"] --- # Send a message `POST /send` Send a message to one or more recipients. ## 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" - `brand` string, nullable - `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. - … - `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 or a list of recipients of the message - 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 - `access_token` string, required - `channel` string, required - SendToSlackEmail - `access_token` string, required - `email` string, required - SendToSlackUserId - `access_token` string, required - `user_id` string, required - MsTeamsRecipient — Send via Microsoft Teams - `ms_teams` union, required - SendToMsTeamsUserId - `tenant_id` string, required - `service_url` string, required - `user_id` string, required - SendToMsTeamsEmail - `tenant_id` string, required - `service_url` string, required - `email` string, required - SendToMsTeamsChannelId - `tenant_id` string, required - `service_url` string, required - `channel_id` string, required - SendToMsTeamsConversationId - `tenant_id` string, required - `service_url` string, required - `conversation_id` string, required - SendToMsTeamsChannelName - `tenant_id` string, required - `service_url` string, required - `channel_name` string, required - `team_id` string, required - 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 - `mode` 'none' | 'basic' | 'bearer', required - `username` string, nullable — Username for basic authentication. - `password` string, nullable — Password for basic authentication. - `token` string, nullable — Token for bearer authentication. - `profile` 'limited' | 'expanded' ## 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. ## Changes - **2026-01-05** `361d17797dff` — 1 breaking, 1 info - removed `#/components/schemas/Recipient, subschema #2` from the `message/oneOf[subschema #1: ContentMessage]/allOf[subschema #2: BaseMessageSendTo]/to` request property `oneOf` list - added `#/components/schemas/UserRecipient, #/components/schemas/AudienceRecipient, #/components/schemas/ListRecipient, #/components/schemas/ListPatternRecipient, #/components/schemas/SlackRecipient, #/components/schemas/MsTeamsRecipient, #/components/schemas/PagerdutyRecipient, #/components/schemas/WebhookRecipient` to the `message/oneOf[subschema #1: ContentMessage]/allOf[subschema #2: BaseMessageSendTo]/to` request property `oneOf` list - **2025-12-16** `9859cb664d1a` — 1 info - added the new optional request property `message/oneOf[subschema #1: ContentMessage]/allOf[subschema #1: BaseMessage]/delay/timezone` - **2025-11-09** `33d5d7c18097` — 2 info - added the new optional request property `message/oneOf[subschema #1: ContentMessage]/allOf[subschema #2: BaseMessageSendTo]/to/oneOf[subschema #1: Recipient]/oneOf[subschema #1: UserRecipient]/list_id` - added the new optional request property `message/oneOf[subschema #1: ContentMessage]/allOf[subschema #2: BaseMessageSendTo]/to/oneOf[subschema #2]/items/oneOf[subschema #1: UserRecipient]/list_id` - **2025-10-15** `e67d02739533` — 2 info - api tag `Send` added - api tag `` removed - …earlier changes not shown [Full history](https://skmtc.dev/trycourier/apis/courier/changes/send/post.md) --- [API](https://skmtc.dev/trycourier/apis/courier.md) · [All operations](https://skmtc.dev/trycourier/apis/courier/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trycourier/courier/revisions/361d17797dff/schema)