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

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"    ],    "template": {      "id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",      "name": "order_confirmation",      "parameters": {        "name": "John Doe",        "order_id": "12345"      }    },    "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-09-30T14:13:13.6097335+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-09-30T14:13:13.6097359+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-09-30T14:13:13.6097365+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-09-30T14:13:13.6097369+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-09-30T14:13:13.6097381+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`