List & search messages

GET /api/messages - List, filter and paginate sent messages; GET /api/messages/status for bulk lookups.

Endpoint

GET https://sms.esmsafrica.io/api/messages

Returns your sent (and received) messages, newest first, with pagination and filters. A esms_test_ key only ever sees test-environment messages.

Authentication

Authorization: Bearer esms_live_your_api_key

Query parameters

Parameter	Type	Description
`page`	integer	Zero-based page index (default `0`).
`limit`	integer	Page size, `1`-`100` (default `20`).
`status`	string	Filter by status (`queued`, `submitted`, `delivered`, `failed`, ...).
`environment`	string	`live` (default for live keys), `test`, or `all`.
`to`	string	Filter by recipient phone (E.164).
`batch_id`	string	Only messages from this bulk batch (returned by Send bulk).
`date_from`	string	ISO 8601 lower bound on `created_at`.
`date_to`	string	ISO 8601 upper bound on `created_at`.

Response

{
  "messages": [
    {
      "id": "msg_abc123",
      "phone": "+254712345678",
      "text": "Your OTP is 123456",
      "sender_id": "MyApp",
      "route": "ESMS_KE",
      "country": "KE",
      "segments": 1,
      "encoding": "GSM7",
      "environment": "live",
      "cost": 0.0096,
      "currency": "KES",
      "status": "delivered",
      "error_code": null,
      "retry_count": 0,
      "created_at": "2026-08-14T12:30:00+00:00",
      "delivered_at": "2026-08-14T12:30:04+00:00"
    }
  ],
  "total": 1,
  "page": 0,
  "limit": 20
}

text is truncated to 100 characters in the list view; fetch the full message with Message status.

Example

curl "https://sms.esmsafrica.io/api/messages?status=delivered&limit=50" \
  -H "Authorization: Bearer esms_live_your_api_key"

Bulk status lookup

GET https://sms.esmsafrica.io/api/messages/status?ids=msg_abc123,msg_def456

Look up the delivery status of many messages in one call - pass up to 100 comma-separated message IDs in ids. Unknown IDs come back with status: "not_found" so the result order matches your input.

Response

{
  "messages": [
    {
      "id": "msg_abc123",
      "status": "delivered",
      "segments": 1,
      "error_code": null,
      "error_message": null,
      "submitted_at": "2026-08-14T12:30:01+00:00",
      "delivered_at": "2026-08-14T12:30:04+00:00"
    },
    { "id": "msg_unknown", "status": "not_found" }
  ]
}

Example

curl "https://sms.esmsafrica.io/api/messages/status?ids=msg_abc123,msg_def456" \
  -H "Authorization: Bearer esms_live_your_api_key"

Tips

To track a whole bulk send at once, use Batch status with the batch_id instead of listing individual IDs.
Prefer Delivery webhooks over polling for real-time status updates.

List & search messages

On this page