Skip to navigation
API ReferenceSMS

Send SMS broadcast

View as Markdown

Creates a broadcast, records one message per recipient, atomically reserves credit (prepaid clients), and queues the job for asynchronous delivery. Final delivery status is reported via the delivered / failed webhook events.

Required scope: send_sms Rate limit: 1,000 requests / 15 min / client (subject to the global 200/15 min per-IP limit) Status lifecycle: pending → enqueued → sent → [delivered | failed]

Recipient modes

ModeFieldUse
Standardrecipients[]Same content for every recipient
DynamicrecipientVariables[]Per-recipient {name} substitution

Provide one of recipients or recipientVariables (not both). Maximum 10,000 recipients per request. Duplicate recipients are rejected, not silently de-duplicated.

Template resolution

Provide one of:

  • templateUid - reuses an existing template by its UUID
  • templateName - resolves an existing approved template owned by your client
  • templateContent - creates a one-off ad-hoc template for this broadcast

Creating a template by templateContent under a name that already exists returns 409; use templateUid to reuse it instead.

Keyword

Every SMS broadcast requires a sender keyword. Provide one of keyword or keywordUid. Omitting both returns 400.

Idempotency

The API does not dedupe identical request bodies. If the request times out client-side, query the dashboard’s Message Logs by broadcastUuid (returned in the response) before retrying.

Authentication

AuthorizationBearer

Bearer API keys are issued from the in-app /api-management page. Each key has a permission scope (send_sms, send_whatsapp, send_email) and an optional IP whitelist.

The IP whitelist, when set, is matched by exact string equality against the resolved caller IP - CIDR ranges are not supported. An empty whitelist allows any source address.

Request

This endpoint expects an object.
campaignNamestringRequired>=1 character

Free-text identifier shown in the dashboard. Required.

typeenumRequired
  • quick broadcast - send immediately
  • schedule broadcast - defer; requires scheduledAt. Not supported on the email channel.
Allowed values:
templateUidstringOptionalformat: "uuid"
UUID of an existing SMS template owned by your client.
templateNamestringOptional1-512 characters

Name of an SMS template owned by your client. Combined with templateContent this creates a new named template; a name that already exists returns 409.

templateContentstringOptional>=1 character

Ad-hoc template content for one-off broadcasts. Maximum 65,535 bytes (byte length, not character count).

scheduledAtdatetimeOptional

ISO 8601. Required when type = schedule broadcast, and must be strictly in the future.

keywordstringOptional1-10 characters

Sender-ID prefix; must be a registered keyword on your client. Required unless keywordUid is supplied.

keywordUidstringOptionalformat: "uuid"

UUID of a registered keyword. Required unless keyword is supplied.

recipientslist of stringsOptional
recipientVariableslist of objectsOptional

Response

Broadcast accepted (queued or scheduled)

dataobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
413
Content Too Large Error
429
Too Many Requests Error
500
Internal Server Error