Send SMS
POST /api/messages/send - Send a single SMS message.
Endpoint
POST https://sms.esmsafrica.io/api/messages/sendAlso 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_keyRequest body
{
"to": "+254712345678",
"text": "Your OTP is 123456",
"sender_id": "MyApp"
}| Field | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient 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. |
text | string | Yes* | Message content. 160 chars = 1 segment (GSM-7), or 70 chars (Unicode); longer messages are split and billed per segment. |
sender_id | string | No | Approved 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. |
route | string | No | Public route code (e.g. ESMS_UG). Auto-detected from to when omitted. |
schedule_mode | string | No | now (default) or scheduled. |
scheduled_at | string | No | ISO 8601 time with timezone, required when schedule_mode is scheduled (5 min - 7 days ahead). |
international | boolean | No | Bill the international-delivery rate (USD) for this send. Default false. |
flash | boolean | No | Flash 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_period | integer | No | Minutes (1-4320) the network keeps retrying before the message expires (e.g. 10 for an OTP). Omit for the network default. |
priority | integer | No | 0 normal (default), 1 high, 2 higher, 3 highest/urgent. Relative priority on the platform queue; same price. |
binary | object | No | Raw 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}/cancelCancels 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
| Status | Description |
|---|---|
400 | Invalid 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": {...}}. |
401 | Invalid or missing API key. |
402 | Insufficient wallet balance (body includes required, available, cost). |
403 | Sender 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). |
409 | Duplicate - identical message to the same number within 5 minutes (only when duplicate protection is enabled in your workspace). |
413 | Message exceeds the maximum segment count (message_too_long). |
422 | Request body failed schema validation (e.g. missing to, or a field of the wrong type). |
429 | Rate 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, withstatus: "queued",environment: "test",livemode: false,balance_after: nulland an id startingtest_; the message then moves through a simulated lifecycle (see Sandbox).