Send a message

Sends a message to one or more recipients using a template. Supports multi-channel broadcast — when multiple channels are specified (e.g. ["sms", "whatsapp"]), a separate message is created for each (recipient, channel) pair. To choose which of your own numbers a send goes out from, use 'channels': {"sms": [{"from": ["+12125550000", "+14155550000"]}]}. Each channel holds a list of entries, each with 'from' and optionally 'country' and 'strategy'; 'country' and 'strategy' are stored but not acted on yet, so every entry's numbers apply to every recipient on that channel. Every number listed must be an active sender on your account. Like the other account-level preconditions below, that is checked per message rather than when the request is received: the request is still accepted with 202, and each affected message is reported as BLOCKED with error code BUSINESS_029 on GET /messages/{id} and the message.blocked webhook. Each channel's numbers restrict which numbers that channel may use; it does not choose channels — 'channel' does, and the two can be combined. With 'channel' left at auto-detect, a recipient best served by a channel you listed no numbers for still goes out on it. Where several of the listed numbers could serve a recipient, routing prefers the one whose area code matches theirs. Keys: sms, whatsapp, rcs, mms. Returns immediately with per-recipient message IDs for async tracking via webhooks or the GET /messages/{id} endpoint. Sends gated before any delivery attempt do not reject the request — an account-level precondition such as insufficient balance, a template not approved for sending, or free-form content with no open conversation with the contact. The send is accepted with 202 and the affected messages are reported as BLOCKED on GET /messages/{id} and the message.blocked webhook. To send later, set scheduled_at (ISO-8601 with an explicit UTC offset; a value without one is rejected) between 1 minute and 30 days ahead: the response is a ScheduledSendMessageResponse (the same fields plus scheduled_at; status is still QUEUED), each message then moves to SCHEDULED, is held and released at that time (within a few minutes), and a message.scheduled webhook fires once it is held. Balance and template approval are evaluated at release, not at acceptance. Quiet hours are not checked when the request is accepted: if the time falls inside a legally protected quiet-hours window for a recipient, that message is moved to the next allowed time at release and a second message.scheduled webhook reports the new scheduled_at. An account may hold at most 1,000,000 scheduled messages at once (429 LIMIT_001).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

sandbox?boolean

Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution

to?array<string>

List of recipient phone numbers in E.164 format (multi-recipient fan-out)

channel?array<string>|

Channels to broadcast on, e.g. ["whatsapp", "sms"]. Each channel produces a separate message per recipient. "sent" = auto-detect. Defaults to ["sent"] (auto-detect) if omitted.

channels?|

Which of your own numbers to send from, keyed by channel, each channel holding a list of entries: {"sms": [{"country": "US", "from": ["+12125550000", "+14155550000"]}, {"from": ["+447700800001"]}]}. Any real channel may be a key; sent, which is auto-detect rather than a channel, is rejected. country and strategy are accepted and stored but not acted on yet: every entry's numbers apply to every recipient on that channel.

This does not choose channels — Channel does, and the two combine: "channel": ["sms"] with an sms list sends on SMS from those numbers. Each list only narrows which of its own channel's routes may win, so with Channel left at auto-detect a recipient best served by a channel with no list still goes out on it. Routing itself is unchanged: the same rules are scored and ranked the same way, with routes pinned to numbers you did not list removed from the running.

Every number must be an active sender on your account. The request itself is still accepted (202) if one is not — like every other send-time rule, that is decided per message, so each affected message is recorded BLOCKED with error code BUSINESS_029 and reported on GET /v3/messages and the status webhook.

template?|null

Template reference (by id or name, with optional parameters). Optional — provide either Template or Message.

text?|

Plain-text (free-form) message body. Provide either Template or this.

media_urls?array<string>|

Attachments for this send, as publicly fetchable https URLs. Used by the MMS channel and ignored by every other one.

Supplying these replaces the media on the template's mms body rather than adding to it, so a template can hold a default creative while a caller still sends something recipient-specific.

Their presence is also what makes a message eligible for MMS on an auto-detect send: a message with nothing attached is delivered as SMS, because an MMS with no media is a more expensive text message.

The recipient's carrier fetches each URL after the send is accepted, so it must stay publicly reachable — a link that expires, or one behind auth, arrives as a failed message.

subject?|

Subject line for this send, overriding the template's. MMS only; ignored on every other channel. Most handsets render it above the body, some ignore it entirely.

scheduled_at?|

Optional future send time as an ISO-8601 timestamp with an explicit UTC offset, e.g. 2026-10-01T09:00:00+02:00 or 2026-10-01T07:00:00Z. A value without an offset is rejected (400) rather than read in the server's zone. The offset only fixes the instant: it is stored and echoed in UTC as scheduled_at. Omit to send now. Must be at least one minute ahead and at most 30 days ahead. Accepted messages report SCHEDULED and are released for delivery at this time. Quiet hours, balance and template approval are evaluated at release, not at acceptance: a message whose time falls inside a recipient's protected quiet-hours window is moved to the next allowed time and a second message.scheduled webhook reports the new scheduled_at.

Formatdate-time

Response Body

`application/json`

curl -X POST "https://example.com/v3/messages" \  -H "Idempotency-Key: req_abc123_retry1" \  -H "Content-Type: application/json" \  -d '{    "to": [      "+14155551234",      "+14155555678"    ],    "channel": [      "sms",      "whatsapp"    ],    "channels": null,    "template": {      "id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",      "name": "order_confirmation",      "parameters": {        "name": "John Doe",        "order_id": "12345"      }    },    "text": null,    "media_urls": null,    "subject": null,    "scheduled_at": null,    "sandbox": false  }'

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "recipients": [
      {
        "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
        "to": "+14155551234",
        "channel": "sms",
        "body": "Hi John Doe, your order #12345 has been confirmed."
      },
      {
        "message_id": "8ba7b831-9dad-11d1-80b4-00c04fd430c8",
        "to": "+14155551234",
        "channel": "whatsapp",
        "body": "Hi John Doe, your order #12345 has been confirmed."
      },
      {
        "message_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
        "to": "+14155555678",
        "channel": "sms",
        "body": "Hi John Doe, your order #12345 has been confirmed."
      },
      {
        "message_id": "9ba7b841-9dad-11d1-80b4-00c04fd430c8",
        "to": "+14155555678",
        "channel": "whatsapp",
        "body": "Hi John Doe, your order #12345 has been confirmed."
      }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-20T13:42:48.7554143+00:00",
    "version": "v3"
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_004",
    "message": "Request validation failed",
    "details": {
      "to": [
        "'to' must contain at least one recipient"
      ],
      "template": [
        "'template' is required"
      ]
    },
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-20T13:42:48.7554238+00:00",
    "version": "v3"
  }
}

Empty

{
  "success": false,
  "data": null,
  "error": {
    "code": "RESOURCE_002",
    "message": "Template not found",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-20T13:42:48.7554244+00:00",
    "version": "v3"
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "LIMIT_001",
    "message": "Too many outstanding scheduled messages",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-20T13:42:48.7554247+00:00",
    "version": "v3"
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_001",
    "message": "Failed to queue message for processing.",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-10-20T13:42:48.7554266+00:00",
    "version": "v3"
  }
}

Send a message

Request Body

Response Body

202application/json

400application/json

401

403

404application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`