Bulk SMS
POST /api/messages/send-bulk - Send to a contact list or an inline batch, with scheduling and drip.
Endpoint
POST https://sms.esmsafrica.io/api/messages/send-bulkSend one message to many recipients in a single call. Supply recipients either
inline (recipients) or by referencing saved contact lists
(contact_list_ids). The message body can carry {{variable}} placeholders that
are filled per recipient. The call returns a batch_id immediately and delivery
happens in the background - track it with Batch status.
Authentication
Authorization: Bearer esms_live_your_api_keyRequest body
{
"recipients": [
{ "to": "+254712345678", "name": "Amina", "vars": { "code": "4821" } },
{ "to": "+256772123456", "name": "Brian", "vars": { "code": "9930" } }
],
"text": "Hi {{name}}, your code is {{code}}.",
"sender_id": "MyApp",
"schedule_mode": "now"
}| Field | Type | Required | Description |
|---|---|---|---|
recipients | array | Yes* | Inline list of { to, name?, vars? }. vars fills {{key}} placeholders; {{name}} and {{phone}} are always available. |
contact_list_ids | array of int | Yes* | Saved contact list IDs to send to instead of (or as well as) recipients. |
text | string | Yes | Message body. Supports {{variable}} and {variable} substitution with fallbacks (a default after a pipe, as in campaigns); rendered per recipient and billed per segment. |
sender_id | string | No | Approved sender ID. If it is not approved for the destination country the call returns 403. When omitted, uses the route default in the 8 default-sender countries; elsewhere the call returns 403 sender_id_required. |
route | string | No | Force a public route code (e.g. ESMS_UG); otherwise auto-detected per number. |
schedule_mode | string | No | now (default), scheduled, or drip. |
scheduled_at | string | No | ISO 8601 UTC time, required when schedule_mode is scheduled (5 min - 7 days ahead). |
drip_rate | integer | No | Messages per minute (1-5000), required when schedule_mode is drip. |
international | boolean | No | Bill the international-delivery rate (USD). Not supported with scheduled. |
flash | boolean | No | Send every message as Flash SMS (class 0). Default false. |
validity_period | integer | No | Minutes (1-4320) the network keeps retrying before each message expires. |
priority | integer | No | 0 normal (default) to 3 highest/urgent. |
skip_unavailable | boolean | No | Default false: the request is rejected with destinations_unavailable if any recipient is in a country that is on request, or has an invalid number. Set true to drop those recipients instead (they are not charged) and send to the rest. |
binary is not available on bulk sends. See Send options
for details and examples.
* Provide at least one of recipients or contact_list_ids. Scheduled sends accept contact_list_ids only.
Multi-country batches price each recipient at its own country's rate.
Duplicate numbers are collapsed, and anyone on your opt-out (STOP) list is dropped before sending.
Idempotency
Send an Idempotency-Key: <unique-string> header to make retries safe. The key
is reserved before anything is charged; a repeat request with the same key
(within 24 hours) returns the original batch with "idempotent_replay": true
instead of charging and sending again. A repeat that arrives while the first is
still running waits briefly, then returns 409 idempotency_in_progress.
A scheduled batch can be cancelled (and refunded) before its send time with
POST /api/messages/batch/{batch_id}/cancel - see Batch status.
Response
{
"batch_id": "b6c2f1e0-1d2c-4a55-9b3f-8e6b0c2d4a11",
"total_recipients": 2,
"estimated_cost": 0.0192,
"status": "sending"
}| Field | Description |
|---|---|
batch_id | Pass to Batch status or the batch_id filter on List messages. |
total_recipients | Unique, non-opted-out recipients after deduplication. |
estimated_cost | Total charged to your wallet, in your wallet currency. |
status | sending, scheduled, or dripping depending on schedule_mode. |
Errors
| Status | Description |
|---|---|
400 | missing_merge_field: some recipients have no value for a placeholder that has no fallback (fields lists each field, how many recipients and an example number). Add a fallback or fix the data - nothing is sent or charged, and a literal {{field}} is never sent. |
400 | No recipients, missing text, an unroutable country, or an incomplete schedule_mode (missing scheduled_at / drip_rate). Also invalid_option, feature_not_enabled, and destinations_unavailable (the countries list shows destinations that are on request - nothing is charged). |
402 | Insufficient balance (required, available, segments, recipients). |
403 | sender_not_approved: sender ID not approved for a destination country. |
403 | sender_id_required: default sender IDs are not available in the destinations listed in countries. Register your own sender ID (register_url). Nothing is charged. |
413 | A rendered message exceeds the segment cap (max_segments). |
429 | Rate limit exceeded (bulk sends: 10 per minute per key). |
Example
curl -X POST https://sms.esmsafrica.io/api/messages/send-bulk \
-H "Authorization: Bearer esms_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"recipients": [
{ "to": "+254712345678", "name": "Amina", "vars": { "code": "4821" } }
],
"text": "Hi {{name}}, your code is {{code}}.",
"sender_id": "MyApp"
}'Pre-check a bulk send
POST https://sms.esmsafrica.io/api/messages/bulk-precheckRuns the same recipient gathering, deduplication and opt-out suppression as
send-bulk, but only returns a cost estimate - nothing is sent or charged. Use
it to preview spend and per-country reach before committing.
Request body
Same as send-bulk but only contact_list_ids/recipients, text,
sender_id and international are read:
{
"recipients": [{ "to": "+254712345678" }, { "to": "+256772123456" }],
"text": "Hi {{name}}, your code is {{code}}."
}Response
{
"total_contacts": 2,
"total_segments": 2,
"total_cost": 0.0192,
"wallet_currency": "USD",
"wallet_balance": 12.50,
"balance_after": 12.4808,
"sufficient_balance": true,
"countries": 2,
"breakdown": [
{
"country_code": "KE",
"country_name": "Kenya",
"currency": "KES",
"route_code": "ESMS_KE",
"contacts": 1,
"segments": 1,
"route_cost": 1.2,
"wallet_cost": 0.0096,
"price_per_segment": 1.2
}
],
"unroutable": [],
"unroutable_count": 0,
"unavailable_countries": [],
"not_enabled_countries": [],
"suppressed_count": 0
}| Field | Description |
|---|---|
breakdown[] | Per-country reach, segments and cost (route + wallet currency). |
balance_after | Your wallet balance if you sent this batch now. |
suppressed_count | Recipients dropped because they are opted out (STOP). |
unroutable / unroutable_count | Numbers with no live route (up to 10 samples). |
unavailable_countries[] | Countries that are Coming soon for live sends. send-bulk refuses them (or skips them with skip_unavailable); nothing is charged. A test key can simulate them. |
not_enabled_countries[] | Live countries not enabled for your account yet (blocked: true if eSMS Africa disabled one). send-bulk answers 403 country_not_enabled until you enable them at Countries. Always empty for a test key. |
Tips
- Call
bulk-precheckfirst to confirm reach and cost, thensend-bulkwith the same body. - Use a
esms_test_key to simulate a blast end to end - members are created and reach a final status, but nothing is charged or delivered.