eSMS AfricaeSMS Africa
API ReferenceSMS API

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

Send 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_key

Request 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"
}
FieldTypeRequiredDescription
recipientsarrayYes*Inline list of { to, name?, vars? }. vars fills {{key}} placeholders; {{name}} and {{phone}} are always available.
contact_list_idsarray of intYes*Saved contact list IDs to send to instead of (or as well as) recipients.
textstringYesMessage body. Supports {{variable}} and {variable} substitution with fallbacks (a default after a pipe, as in campaigns); rendered per recipient and billed per segment.
sender_idstringNoApproved 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.
routestringNoForce a public route code (e.g. ESMS_UG); otherwise auto-detected per number.
schedule_modestringNonow (default), scheduled, or drip.
scheduled_atstringNoISO 8601 UTC time, required when schedule_mode is scheduled (5 min - 7 days ahead).
drip_rateintegerNoMessages per minute (1-5000), required when schedule_mode is drip.
internationalbooleanNoBill the international-delivery rate (USD). Not supported with scheduled.
flashbooleanNoSend every message as Flash SMS (class 0). Default false.
validity_periodintegerNoMinutes (1-4320) the network keeps retrying before each message expires.
priorityintegerNo0 normal (default) to 3 highest/urgent.
skip_unavailablebooleanNoDefault 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"
}
FieldDescription
batch_idPass to Batch status or the batch_id filter on List messages.
total_recipientsUnique, non-opted-out recipients after deduplication.
estimated_costTotal charged to your wallet, in your wallet currency.
statussending, scheduled, or dripping depending on schedule_mode.

Errors

StatusDescription
400missing_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.
400No 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).
402Insufficient balance (required, available, segments, recipients).
403sender_not_approved: sender ID not approved for a destination country.
403sender_id_required: default sender IDs are not available in the destinations listed in countries. Register your own sender ID (register_url). Nothing is charged.
413A rendered message exceeds the segment cap (max_segments).
429Rate 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-precheck

Runs 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
}
FieldDescription
breakdown[]Per-country reach, segments and cost (route + wallet currency).
balance_afterYour wallet balance if you sent this batch now.
suppressed_countRecipients dropped because they are opted out (STOP).
unroutable / unroutable_countNumbers 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-precheck first to confirm reach and cost, then send-bulk with 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.

On this page