---
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.
    - `expiry` Expiry
      - `expires_at` string, nullable — Epoch or ISO8601 timestamp with timezone.
      - `expires_in` union, required
        - string
        - integer
    - `to` union
      - Recipient
      - Recipient[]

## 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

- **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/59c9efb45644/schema)