eSMS AfricaeSMS Africa
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_key

Response

{
  "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

StatusDescription
queuedAccepted and queued for sending.
scheduledWaiting for its scheduled_at time.
submittedAccepted by the gateway.
sentAccepted by the carrier network, awaiting a handset receipt.
deliveredConfirmed delivered to the handset.
unknownWe'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.
retryingA failed attempt is being retried.
failedDelivery failed or was rejected (see error_code / error_message).
undeliveredNot 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"

On this page