eSMS AfricaeSMS Africa
API ReferenceSMS API

Send SMS

POST /api/messages/send - Send a single SMS message.

Endpoint

POST https://sms.esmsafrica.io/api/messages/send

Also reachable as POST /v1/messages/send. Sends to any available country - Africa and, once enabled for you, the rest of the world.

Authentication

All requests use a Bearer token - your API key from the dashboard. Live keys start with esms_live_; test keys start with esms_test_ and simulate delivery without charging your wallet or sending a real message.

Authorization: Bearer esms_live_your_api_key

Request body

{
  "to": "+254712345678",
  "text": "Your OTP is 123456",
  "sender_id": "MyApp"
}
FieldTypeRequiredDescription
tostringYesRecipient in E.164 format: +, country code, national number, no trunk 0, no spaces (e.g. +254712345678, +447700900123, +14155550123). Numbers without a country code are rejected.
textstringYes*Message content. 160 chars = 1 segment (GSM-7), or 70 chars (Unicode); longer messages are split and billed per segment.
sender_idstringNoApproved sender ID. When omitted, uses the route default in the 8 default-sender countries; elsewhere a live send returns 403 sender_id_required and nothing is charged. With a live key, a sender ID that is not approved for the destination country returns 403; a test key accepts it and sets live.sender_approved to false.
routestringNoPublic route code (e.g. ESMS_UG). Auto-detected from to when omitted.
schedule_modestringNonow (default) or scheduled.
scheduled_atstringNoISO 8601 time with timezone, required when schedule_mode is scheduled (5 min - 7 days ahead).
internationalbooleanNoBill the international-delivery rate (USD) for this send. Default false.
flashbooleanNoFlash SMS (message class 0): shown immediately on screen, not stored in the inbox by most handsets. GSM-7 or Unicode; billed like a normal SMS. Handset support varies. Default false.
validity_periodintegerNoMinutes (1-4320) the network keeps retrying before the message expires (e.g. 10 for an OTP). Omit for the network default.
priorityintegerNo0 normal (default), 1 high, 2 higher, 3 highest/urgent. Relative priority on the platform queue; same price.
binaryobjectNoRaw binary SMS: { "data": "<hex>", "udh": "<hex>", "data_coding": 4 }. data is required; udh is optional (first byte = UDH length); data_coding is 4 (8-bit, default) or 8 (UCS-2). UDH + data max 140 octets, billed as 1 segment. Omit text. Cannot be combined with flash.

* text is required unless you send binary.

See Send options for flash, validity, priority, binary and scheduling examples in cURL, Node.js, Python, PHP and Go.

Idempotency

Send an Idempotency-Key: <unique-string> header to make network retries safe. A repeat request with the same key returns the original result (with "idempotent_replay": true) instead of charging and sending again.

Cancel a scheduled message

POST https://sms.esmsafrica.io/api/messages/{id}/cancel

Cancels a message that is still scheduled and refunds what was charged when it was scheduled. Returns {"id", "status": "cancelled", "refund": {...}}; any other status returns 409 not_cancellable.

Response

Success (200)

{
  "id": "msg_abc123",
  "status": "submitted",
  "segments": 1,
  "encoding": "GSM7",
  "recipients": 1,
  "price_per_sms": 1.2,
  "cost": 0.0096,
  "cost_currency": "USD",
  "route_cost": 1.2,
  "route_currency": "KES",
  "route": "ESMS_KE",
  "balance_after": 12.34,
  "scheduled_at": null,
  "options": {
    "flash": false,
    "validity_period": null,
    "priority": 0,
    "binary": false
  }
}

cost/cost_currency is what your wallet is charged; route_cost/route_currency is the price in the route's own currency. encoding is GSM7 or UCS2. balance_after is your remaining wallet balance. status is submitted (accepted by the gateway), scheduled (when scheduled) or failed (gateway rejected - the charge is refunded automatically). options echoes the flash, validity_period, priority and binary settings that were applied.

Errors

StatusDescription
400Invalid phone number, unroutable country, or missing text (invalid_option: text is required). Also invalid_option, invalid_binary, feature_not_enabled (flash, or binary with a udh, is not switched on for the platform yet - contact support) and destination_unavailable (the country is on request - contact sales; not charged). Body: the error envelope, e.g. {"error": {"code": "...", "message": "...", "request_id": "..."}, "detail": {...}}.
401Invalid or missing API key.
402Insufficient wallet balance (body includes required, available, cost).
403Sender ID not approved for this country (sender_not_approved), no own sender ID in a country where default sender IDs are not available (sender_id_required, with register_url; not charged), the recipient has opted out (recipient_opted_out), the API key lacks the send scope (insufficient_scope), or the account is suspended (account_suspended).
409Duplicate - identical message to the same number within 5 minutes (only when duplicate protection is enabled in your workspace).
413Message exceeds the maximum segment count (message_too_long).
422Request body failed schema validation (e.g. missing to, or a field of the wrong type).
429Rate limit exceeded (20 single sends per second per API key).

Example

curl -X POST https://sms.esmsafrica.io/api/messages/send \
  -H "Authorization: Bearer esms_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+254712345678",
    "text": "Your OTP is 123456",
    "sender_id": "MyApp"
  }'

Tips

  • Call Check price first to preview the segment count and cost, and Validate numbers to drop invalid or non-mobile numbers before you spend.
  • Use a esms_test_ key while integrating - nothing is charged or delivered. The response has the same fields, with status: "queued", environment: "test", livemode: false, balance_after: null and an id starting test_; the message then moves through a simulated lifecycle (see Sandbox).

On this page