Send SMS to an audience

Audience send: you supply a segment, the platform resolves it to however many contacts it contains, and sends. No endpoint in this API provides this today.

How this differs from /messages/{channel}/batch — it is not a bigger batch:

Recipients are resolved by the platform, not enumerated by the caller.

Scale is unbounded; 300 000 is ordinary.

Suppressed recipients are counted, not rejected. "12 000 of 300 000 filtered" is a statistic; failing the request over it would be absurd. A batch, by contrast, returns 422 no_consent for the individual it concerns.

One content, many recipients, with per-language variants via assets[].

Job lifecycle reuses /v4/jobs. Poll GET /v4/jobs/{jobId}, cancel with POST /v4/jobs/{jobId}/cancel. It deliberately does NOT get a jobs surface of its own: /v4/jobs is the one jobs surface in this API, and duplicating it under another prefix would leave integrators building against a path that does not exist. The jobs framework has no pause, so no pause is documented here.

type: transactional is legitimate here, unusually for an audience send. A product recall to everyone who bought item X, or a terms-of-service change, is a legal-obligation message to a segment — type: transactional, basis: legal_obligation. That is why type is not pinned to marketing. It makes the entitlement gate and the audit record matter more here, not less.

Before implementing: settle the segmentation DSL, then specify audience as that DSL.

curl --location '/messages/sms/audience' \ --header 'Authorization: Bearer <token>' \ --header 'Idempotency-Key: 0f3e2b1a-7c4d-4e2a-9b11-2f6d8c1a5e30' \ --header 'Content-Type: application/json' \ --data '{ "type": "transactional", "basis": "contract_performance", "audience": {}, "assets": [ { "language": "string", "templateId": 0 } ], "variables": {}, "from": "string", "name": "string", "sendAt": "string", "tags": [ "string" ], "metadata": {}, "event": "string" }'

{ "jobId": "string", "status": "string", "audience": { "intended": 0, "suppressed": 0, "deliverable": 0, "suppressionBreakdown": { "unsubscribed": 0, "invalidAddress": 0, "hardBounced": 0, "blocked": 0 } }, "languages": [ { "language": "string", "recipients": 0, "templateId": 0 } ], "links": { "self": "string", "items": "string" } }

Request

Responses