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.
Header Parameters
Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.
^[a-zA-Z0-9_-]+$length <= 255Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.sent.dm/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": "accepted",
"body": "Hi John Doe, your order #12345 has been confirmed.",
"template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
"template_name": "order_confirmation",
"recipients": [
{
"message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
"to": "+14155551234",
"channel": "sms"
},
{
"message_id": "8ba7b831-9dad-11d1-80b4-00c04fd430c8",
"to": "+14155551234",
"channel": "whatsapp"
},
{
"message_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
"to": "+14155555678",
"channel": "sms"
},
{
"message_id": "9ba7b841-9dad-11d1-80b4-00c04fd430c8",
"to": "+14155555678",
"channel": "whatsapp"
}
]
},
"error": null,
"meta": {
"request_id": "req_7X9zKp2jDw",
"timestamp": "2026-03-11T21:50:50.1796606+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/errors/VALIDATION_004"
},
"meta": {
"request_id": "req_7X9zKp2jDw",
"timestamp": "2026-03-11T21:50:50.1796657+00:00",
"version": "v3"
}
}{
"success": false,
"data": null,
"error": {
"code": "BUSINESS_003",
"message": "Insufficient balance to send message.",
"details": null,
"doc_url": "https://docs.sent.dm/errors/BUSINESS_003"
},
"meta": {
"request_id": "req_7X9zKp2jDw",
"timestamp": "2026-03-11T21:50:50.1796669+00:00",
"version": "v3"
}
}{
"success": false,
"data": null,
"error": {
"code": "RESOURCE_002",
"message": "Template not found",
"details": null,
"doc_url": "https://docs.sent.dm/errors/RESOURCE_002"
},
"meta": {
"request_id": "req_7X9zKp2jDw",
"timestamp": "2026-03-11T21:50:50.1796664+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/errors/INTERNAL_001"
},
"meta": {
"request_id": "req_7X9zKp2jDw",
"timestamp": "2026-03-11T21:50:50.1796687+00:00",
"version": "v3"
}
}