eSMS AfricaeSMS Africa
SMS Platform

HTTP API

Send SMS messages via the eSMS 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

FieldTypeRequiredDescription
tostringYesRecipient in international format (e.g. +254712345678).
textstringYesMessage content. 160 chars = 1 GSM-7 segment (70 for Unicode); longer messages split and bill per segment.
sender_idstringNoApproved sender ID. If omitted, uses the route default in the 8 default-sender countries; elsewhere a live send returns 403 sender_id_required. An unapproved sender returns 403.
routestringNoPublic route code (e.g. ESMS_UG); auto-detected from to otherwise.

Optional delivery controls - flash, validity_period, priority, binary and scheduling - are covered in Send options. International numbers must be in E.164 format (+447700900123); see Global Coverage for which countries are available.

Response

{
  "id": "msg_abc123",
  "status": "submitted",
  "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

StatusDescription
queuedMessage accepted and queued.
scheduledWaiting for its scheduled send time.
submittedAccepted by the gateway.
sentAccepted by the carrier, awaiting a handset receipt.
deliveredMessage delivered to handset.
retryingA failed attempt is being retried.
failedDelivery failed or was rejected by the gateway/carrier.

Requests that cannot be sent at all (invalid number, opted-out recipient, insufficient balance) are rejected with an HTTP error - see Errors.

Before you send

Bulk SMS

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 under API Keys at sms.esmsafrica.io/api-keys. Test keys (esms_test_...) simulate delivery without charging your wallet.

On this page