Send SMS broadcast | Teekrr | API Documentation

Creates a broadcast, inserts one row per recipient into sms_messages, atomically reserves credit (prepaid clients), and enqueues the job to AWS SQS for asynchronous delivery via Elfo. Final delivery status is reported via the delivered / failed webhook events.

Required scope: send_sms Rate limit: 10 requests / 15 min / client Status lifecycle: pending → enqueued → send → [delivered | failed]

Recipient modes

Mode	Field	Use
Standard	`recipients[]`	Same content for every recipient
Dynamic	`recipientVariables[]`	Per-recipient `{name}` substitution

Provide one of recipients or recipientVariables (not both). Maximum 10,000 recipients per request.

Template resolution

Provide one of:

templateName — resolves an existing approved template owned by your client
templateContent — creates a one-off ad-hoc template for this broadcast

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.

Creates a broadcast, inserts one row per recipient into `sms_messages`, atomically reserves credit (prepaid clients), and enqueues the job to AWS SQS for asynchronous delivery via Elfo. Final delivery status is reported via the `delivered` / `failed` webhook events. **Required scope:** `send_sms` **Rate limit:** 10 requests / 15 min / client **Status lifecycle:** `pending → enqueued → send → [delivered | failed]` ## Recipient modes | Mode | Field | Use | | --- | --- | --- | | Standard | `recipients[]` | Same content for every recipient | | Dynamic | `recipientVariables[]` | Per-recipient `{name}` substitution | Provide **one** of `recipients` or `recipientVariables` (not both). Maximum **10,000 recipients** per request. ## Template resolution Provide **one** of: - `templateName` — resolves an existing approved template owned by your client - `templateContent` — creates a one-off ad-hoc template for this broadcast ## 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.

Request

This endpoint expects an object.

campaignNamestringRequired>=1 character

Free-text identifier shown in the dashboard.

typeenumRequired

quick broadcast — send immediately
schedule broadcast — defer; requires scheduledAt

Allowed values:

templateNamestringOptional1-512 characters

Name of an existing approved SMS template owned by your client.

templateContentstringOptional>=1 character

Ad-hoc template content for one-off broadcasts.

scheduledAtdatetimeOptional

ISO 8601. Required when type = schedule broadcast.

keywordstringOptional1-10 characters

Sender-ID prefix; must be a registered keyword on your client.

recipientslist of stringsOptional

recipientVariableslist of objectsOptional

Response

Broadcast accepted (queued or scheduled)

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

429

Too Many Requests Error

500

Internal Server Error