HTTP API

The SMS HTTP API is served at https://sms.esmsafrica.io and authenticated with a Bearer API key (esms_live_..., or esms_test_... for the sandbox). For the full reference see Send SMS.

Send an SMS

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": "Hello from eSMS Africa!",
    "sender_id": "eSMS"
  }'

Request body

Field	Type	Required	Description
`to`	string	Yes	Recipient in international format (e.g. `+254712345678`).
`text`	string	Yes	Message content. 160 chars = 1 GSM-7 segment (70 for Unicode); longer messages split and bill per segment.
`sender_id`	string	No	Approved sender ID. Falls back to the route default if omitted.
`route`	string	No	Public route code (e.g. `ESMS_UG`); auto-detected from `to` otherwise.

Response

{
  "id": "msg_abc123",
  "status": "sent",
  "segments": 1,
  "encoding": "GSM7",
  "recipients": 1,
  "cost": 0.0096,
  "cost_currency": "USD",
  "route": "ESMS_KE",
  "balance_after": 12.34
}

Check message status

curl https://sms.esmsafrica.io/api/messages/{id} \
  -H "Authorization: Bearer esms_live_your_api_key"

Delivery statuses

Status	Description
`queued`	Message accepted and queued.
`sent`	Message submitted to carrier.
`delivered`	Message delivered to handset.
`failed`	Delivery failed.
`rejected`	Rejected (invalid number, content policy, opt-out, insufficient balance).

Before you send

Check price previews segments + cost with no charge.
Validate numbers drops invalid or non-mobile numbers.

Send to many recipients in one call with POST /api/messages/send-bulk, or use the dashboard at sms.esmsafrica.io (Send SMS → pick a sender ID + contact list → compose → send). Bulk deducts from your wallet per-country.

Authentication

Every request carries your API key as a Bearer token:

Authorization: Bearer esms_live_your_api_key

Create keys in your dashboard at sms.esmsafrica.io. Test keys (esms_test_...) simulate delivery without charging your wallet.