eSMS AfricaeSMS Africa
API Reference

API Reference

Complete reference for the eSMS Africa REST API.

Base URL

https://sms.esmsafrica.io/api

Authentication

All endpoints require authentication. Pass your API key in the Authorization header:

Authorization: Bearer esms_live_YOUR_KEY

See Authentication for full details.

Response format

All responses are JSON. Successful responses return 2xx with the response body. Errors return 4xx or 5xx with an error object.

Error response

{
  "detail": {
    "code": "insufficient_balance",
    "message": "Insufficient balance. Required: 35 UGX, available: 10 UGX"
  }
}

Or for validation errors:

{
  "detail": [
    {
      "loc": ["body", "to"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Endpoints

Messages

MethodPathDescription
POST/messages/sendSend a single SMS
POST/messages/bulk-precheckPre-check bulk send cost
POST/messages/send-bulkSend bulk SMS
GET/messagesList messages
GET/messages/{id}Get message + timeline
POST/messages/{id}/retryRetry a failed message
GET/messages/statsDashboard KPIs
GET/messages/volumeDaily message volume
GET/messages/exportExport messages as CSV

Balance & Billing

MethodPathDescription
GET/balanceGet wallet balance
GET/balance/transactionsList transactions
POST/balance/topupInitiate top-up

Routes

MethodPathDescription
GET/routesList active routes
GET/routes/{code}Get a route
GET/routes/healthPer-route delivery stats
GET/pricingPublic pricing (no auth required)

Contacts

MethodPathDescription
POST/contact-listsUpload CSV contact list
GET/contact-listsList contact lists
GET/contact-lists/{id}Get a list
GET/contact-lists/{id}/contactsBrowse contacts
DELETE/contact-lists/{id}Delete a list

Webhooks

MethodPathDescription
GET/webhooksGet webhook config
PUT/webhooksUpdate webhook config
POST/webhooks/rotate-secretRotate signing secret

Sender IDs

MethodPathDescription
POST/sender-idsRequest a sender ID
GET/sender-idsList your sender IDs

API Keys

MethodPathDescription
POST/api-keysCreate an API key
GET/api-keysList your API keys
DELETE/api-keys/{id}Revoke an API key

Account

MethodPathDescription
GET/auth/meCurrent user info + balance
GET/workspaceGet workspace details
PUT/workspaceUpdate workspace
GET/notificationsList notifications
GET/notifications/unread-countUnread notification count
POST/notifications/read-allMark all as read

Pagination

List endpoints support pagination via page (0-indexed) and limit query params:

GET /api/messages?page=2&limit=50

Responses include total, page, and limit.

Rate limiting

Requests are rate-limited per API key. If you exceed the limit you receive 429 Too Many Requests with a Retry-After header.

API Keys

Create and manage API keys for programmatic access to eSMS Africa.

Messages API

Full reference for message send, status, and list endpoints.

On this page

Base URLAuthenticationResponse formatError responseEndpointsMessagesBalance & BillingRoutesContactsWebhooksSender IDsAPI KeysAccountPaginationRate limiting