API ReferenceSMS API
Message status
GET /api/messages/{id} - Check an SMS's delivery status.
Endpoint
GET https://sms.esmsafrica.io/api/messages/{id}{id} is the id returned when you sent the message. To list recent messages,
use GET /api/messages.
Authentication
Authorization: Bearer esms_live_your_api_keyResponse
{
"id": "msg_abc123",
"phone": "+254712345678",
"text": "Your OTP is 123456",
"sender_id": "MyApp",
"route": "ESMS_KE",
"country": "KE",
"segments": 1,
"cost": 0.0096,
"cost_currency": "USD",
"price_per_segment": 1.24,
"price_currency": "KES",
"status": "delivered",
"error_code": null,
"error_message": null,
"retry_count": 0,
"created_at": "2026-08-14T12:30:00+00:00",
"submitted_at": "2026-08-14T12:30:01+00:00",
"delivered_at": "2026-08-14T12:30:04+00:00",
"failed_at": null,
"timeline": [
{ "event": "accepted", "status": "queued", "detail": "API request received", "at": "2026-08-14T12:30:00+00:00", "metadata": {} },
{ "event": "delivered", "status": "delivered", "detail": "DLR: DELIVRD", "at": "2026-08-14T12:30:04+00:00", "metadata": {} }
]
}Statuses
| Status | Description |
|---|---|
queued | Accepted and queued for sending. |
scheduled | Waiting for its scheduled_at time. |
submitted | Accepted by the gateway. |
sent | Accepted by the carrier network, awaiting a handset receipt. |
delivered | Confirmed delivered to the handset. |
unknown | We're confirming delivery with the network after a gateway timeout (shown as Confirming in the dashboard and confirming in CSV exports). It resolves to sent (or a later status), or to failed with an automatic refund, within about 10 minutes. It cannot be retried while confirming. |
retrying | A failed attempt is being retried. |
failed | Delivery failed or was rejected (see error_code / error_message). |
undelivered | Not delivered (seen on sandbox magic numbers). |
Rather than polling, you can receive status updates in real time - see Delivery webhooks.
Example
curl https://sms.esmsafrica.io/api/messages/msg_abc123 \
-H "Authorization: Bearer esms_live_your_api_key"