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.

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)

Length1 <= length

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.

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"      }    },    "text": 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-08-17T13:29:05.1733992+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-08-17T13:29:05.173404+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-08-17T13:29:05.1734044+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-08-17T13:29:05.1734048+00:00",
    "version": "v3"
  }
}

Send a message

Request Body

Response Body

202application/json

400application/json

401

403

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`