HTTP API

Send an SMS

curl -X POST https://app.esmsafrica.io/api/sms/send \
  -H "X-Account-ID: your_account_id" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+254712345678",
    "text": "Hello from eSMS Africa!",
    "senderId": "eSMS"
  }'

Request body

Field	Type	Required	Description
`phoneNumber`	string	Yes	Recipient phone number in international format (e.g. `+254712345678`)
`text`	string	Yes	Message content (max 160 characters for a single SMS, longer messages are split)
`senderId`	string	No	Sender ID to display. Must be an approved sender ID.

Response

{
  "status": "success",
  "messageId": "msg_abc123",
  "reason": "SMS queued for delivery"
}

Check message status

curl https://app.esmsafrica.io/api/sms/message/{messageId} \
  -H "X-Account-ID: your_account_id" \
  -H "X-API-Key: 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`	Message rejected (invalid number, insufficient balance, etc.)

Sending bulk SMS

For bulk SMS, use the web portal at app.esmsafrica.io:

Go to Send SMS
Select a sender ID and contact list
Compose your message
Send

Bulk SMS deducts from your wallet based on per-country pricing.

Authentication

All API requests require two headers — your numeric account ID and your API key:

X-Account-ID: your_account_id
X-API-Key: your_api_key

Get your account ID and API key from your profile at app.esmsafrica.io.

Error codes

Code	Description
`401`	Invalid or missing API key
`400`	Invalid phone number or missing fields
`402`	Insufficient wallet balance
`429`	Rate limit exceeded

HTTP API

On this page