Send SMS broadcast | Teekrr | API Documentation

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

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. 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.

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 | 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. 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.

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.

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