API Docs

API Documentation

Built for Developers

Integrate SMS in 10 languages with a simple REST API, consistent authentication, and dedicated developer support across Africa.

Browse Docs Get API Keys

REST

Simple API Style

24/7

Developer Support

2025-11-02

Last Updated

SMS API Documentation

eSMS Africa SMS API Documentation

Status: Successfully Implemented and Tested

All 5 API endpoints are working correctly. The /api/sms/countries endpoint returns data for 49 supported African countries.

More Endpoints Are Coming

The current documentation covers the 5 implemented SMS API endpoints available now. This is the first public API surface, and eSMS Africa will continue expanding the platform with additional endpoints for reporting, webhooks, sender management, billing, and broader messaging automation workflows.

Delivery reports and analytics endpointsWebhook management and event subscriptionsSender ID management endpointsAccount usage, balance, and billing endpointsMore messaging workflow and verification endpoints

Overview

This document describes the SMS API endpoints that use API Key authentication.

All endpoints under /api/ require API key authentication.
Use X-API-Key and X-Account-ID headers on every request.
The API is designed for SMS sending, country support, pricing lookup, and message tracking.
These 5 endpoints are the current production-ready foundation, with additional API modules planned next.

Base URL

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

Authentication

All API endpoints require API key authentication.

Headers

X-API-Key: your-api-key-here
X-Account-ID: your-account-id-here

API Key Endpoints

GET /user/api-key
POST /user/api-key

Endpoints

POST /api/sms/send

Send SMS messages

GET /api/sms/countries

List supported countries

GET /api/sms/pricing

Get pricing for all countries

GET /api/sms/pricing/{countryCode}

Get pricing for a specific country

GET /api/sms/message/{messageId}

Get SMS details by message ID

1. Send SMS

Send an SMS message to a phone number.

Endpoint

POST /api/sms/send

Request Body

{
  "phoneNumber": "+256701234567",
  "text": "Hello, this is a test message!",
  "senderId": "eSMSAfrica"
}

Response

{
  "status": "ACK",
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "reason": null
}

cURL Example

curl -X POST https://api.esmsafrica.io/api/sms/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -H "X-Account-ID: your-account-id-here" \
  -d '{
    "phoneNumber": "+256701234567",
    "text": "Hello from eSMS Africa API!",
    "senderId": "eSMSAfrica"
  }'

2. Get Supported Countries

Get a list of all countries supported for SMS sending.

Endpoint

GET /api/sms/countries

Response

[
  { "code": "UG", "name": "Uganda",       "currencyCode": "UGX", "senderId": "eSMSAfrica" },
  { "code": "KE", "name": "Kenya",        "currencyCode": "KES", "senderId": "eSMSAfrica" },
  { "code": "TZ", "name": "Tanzania",     "currencyCode": "TZS", "senderId": "eSMSAfrica" },
  { "code": "RW", "name": "Rwanda",       "currencyCode": "RWF", "senderId": "eSMSAfrica" },
  { "code": "NG", "name": "Nigeria",      "currencyCode": "NGN", "senderId": "eSMSAfrica" },
  { "code": "ZA", "name": "South Africa", "currencyCode": "ZAR", "senderId": "eSMSAfrica" },
  { "code": "GH", "name": "Ghana",        "currencyCode": "GHS", "senderId": "eSMSAfrica" },
  "... 42 more countries"
]

cURL Example

curl -X GET https://api.esmsafrica.io/api/sms/countries \
  -H "X-API-Key: your-api-key-here" \
  -H "X-Account-ID: your-account-id-here"

3. Get All Pricing

Get SMS pricing for all supported countries.

Endpoint

GET /api/sms/pricing

Response

{
  "UG": { "countryCode": "UG", "countryName": "Uganda",       "currencyCode": "UGX", "cost": 35.0,  "senderId": "eSMSAfrica" },
  "KE": { "countryCode": "KE", "countryName": "Kenya",        "currencyCode": "KES", "cost": 0.55,  "senderId": "eSMSAfrica" },
  "TZ": { "countryCode": "TZ", "countryName": "Tanzania",     "currencyCode": "TZS", "cost": 25.0,  "senderId": "eSMSAfrica" },
  "RW": { "countryCode": "RW", "countryName": "Rwanda",       "currencyCode": "RWF", "cost": 20.0,  "senderId": "eSMSAfrica" },
  "NG": { "countryCode": "NG", "countryName": "Nigeria",      "currencyCode": "NGN", "cost": 9.10,  "senderId": "eSMSAfrica" },
  "ZA": { "countryCode": "ZA", "countryName": "South Africa", "currencyCode": "ZAR", "cost": 0.80,  "senderId": "eSMSAfrica" },
  "GH": { "countryCode": "GH", "countryName": "Ghana",        "currencyCode": "GHS", "cost": 0.080, "senderId": "eSMSAfrica" },
  "... 42 more countries": "..."
}

cURL Example

curl -X GET https://api.esmsafrica.io/api/sms/pricing \
  -H "X-API-Key: your-api-key-here" \
  -H "X-Account-ID: your-account-id-here"

4. Get Country-Specific Pricing

Get SMS pricing for a specific country.

Path parameter: `countryCode` uses a 2-letter country code such as `UG`, `KE`, `TZ`, or `RW`.

Endpoint

GET /api/sms/pricing/{countryCode}

Response

{
  "countryCode": "KE",
  "countryName": "Kenya",
  "currencyCode": "KES",
  "cost": 0.55,
  "senderId": "eSMSAfrica"
}

cURL Examples

# Get pricing for Uganda
curl -X GET https://api.esmsafrica.io/api/sms/pricing/UG \
  -H "X-API-Key: your-api-key-here" \
  -H "X-Account-ID: your-account-id-here"

# Get pricing for Kenya
curl -X GET https://api.esmsafrica.io/api/sms/pricing/KE \
  -H "X-API-Key: your-api-key-here" \
  -H "X-Account-ID: your-account-id-here"

# Get pricing for Tanzania
curl -X GET https://api.esmsafrica.io/api/sms/pricing/TZ \
  -H "X-API-Key: your-api-key-here" \
  -H "X-Account-ID: your-account-id-here"

# Get pricing for Rwanda
curl -X GET https://api.esmsafrica.io/api/sms/pricing/RW \
  -H "X-API-Key: your-api-key-here" \
  -H "X-Account-ID: your-account-id-here"

5. Get SMS Details

Get detailed information about a specific SMS by its message ID.

Path parameter: `messageId` is the unique message ID returned when sending SMS.

Endpoint

GET /api/sms/message/{messageId}

Response

{
  "id": 123,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "direction": "outbound",
  "group": "esmsafrica",
  "username": "admin",
  "userId": 1,
  "senderId": "eSMSAfrica",
  "phoneNumber": "+256701234567",
  "text": "Hello from eSMS Africa API!",
  "currencyCode": "UGX",
  "cost": 35.0000,
  "status": "ACK",
  "reason": null,
  "tryCount": null,
  "createdAt": "2026-02-27T08:32:55.123+00:00",
  "updatedAt": "2026-02-27T08:32:55.123+00:00"
}

cURL Example

# First send an SMS and get the messageId from the response
curl -X POST https://api.esmsafrica.io/api/sms/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -H "X-Account-ID: your-account-id-here" \
  -d '{
    "phoneNumber": "+256701234567",
    "text": "Test message"
  }'

# Then use the returned messageId to get SMS details
curl -X GET https://api.esmsafrica.io/api/sms/message/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-api-key-here" \
  -H "X-Account-ID: your-account-id-here"

Language Examples

JavaScript

const axios = require('axios');

const sendSMS = async () => {
  try {
    const response = await axios.post(
      'https://api.esmsafrica.io/api/sms/send',
      {
        phoneNumber: '+254712345678',
        text: 'Hello from JS',
        senderId: 'eSMSAfrica'
      },
      {
        headers: {
          'X-Account-ID': 'your-account-id',
          'X-API-Key': 'your-api-key'
        }
      }
    );
    console.log('Response:', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
};

sendSMS();

Important Notes

All implementations require proper error handling. Production code should include retry logic.
The `phoneNumber` must always include the country code.
`senderId` must be pre-approved in your eSMSAfrica dashboard.
API keys should never be hardcoded. Use environment variables.
All examples use HTTPS. Never use HTTP for production.
Number formats must match local conventions.

Country	Code	Example Number
Kenya	+254	+254712345678
Uganda	+256	+256712345678
Tanzania	+255	+255712345678
Rwanda	+250	+250712345678
Ethiopia	+251	+251911234567
Burundi	+257	+25771234567
South Sudan	+211	+211912345678
Nigeria	+234	+2348012345678
Ghana	+233	+233242345678
Senegal	+221	+221701234567
Ivory Coast	+225	+2250712345678
Burkina Faso	+226	+22670123456
Mali	+223	+22360123456
Benin	+229	+22997123456
Niger	+227	+22790123456
Guinea	+224	+224621234567
Sierra Leone	+232	+23276123456
Liberia	+231	+231770123456
Togo	+228	+22890123456
Gambia	+220	+2203012345
Guinea-Bissau	+245	+2455512345
South Africa	+27	+27712345678
Zambia	+260	+260961234567
Malawi	+265	+265991234567
Mozambique	+258	+258841234567
Zimbabwe	+263	+263771234567
Botswana	+267	+26771234567
Namibia	+264	+264811234567
Lesotho	+266	+26657123456
Eswatini	+268	+26876123456
Angola	+244	+244912345678
DRC	+243	+243812345678
Republic of the Congo	+242	+242061234567
Cameroon	+237	+237671234567
Gabon	+241	+24106123456
Chad	+235	+23563123456
Central African Republic	+236	+23670123456
Equatorial Guinea	+240	+240222123456
Egypt	+20	+201012345678
Morocco	+212	+212612345678
Algeria	+213	+213551234567
Tunisia	+216	+21620123456
Libya	+218	+21891234567
Sudan	+249	+249912345678
Somalia	+252	+252612345678
Djibouti	+253	+25377123456
Eritrea	+291	+29171234567
Madagascar	+261	+261321234567
Mauritius	+230	+2305712345
Seychelles	+248	+2482512345
Comoros	+269	+2697712345

Error Responses

Authentication Errors

If the API key or Account ID is missing or invalid, the request will be rejected with a 401 Unauthorized response.

No JSON body is returned for this case.

Country Not Found

For invalid country codes in pricing endpoints:

{
  "timestamp": "2026-02-27T08:32:55.123Z",
  "status": 404,
  "error": "Not Found",
  "message": "Country not supported: XX",
  "path": "/api/sms/pricing/XX"
}

Invalid Phone Number

For invalid phone numbers in send endpoint:

{
  "timestamp": "2026-02-27T08:32:55.123Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid phone number",
  "path": "/api/sms/send"
}

Insufficient Balance

If wallet has insufficient balance for SMS:

{
  "timestamp": "2026-02-27T08:32:55.123Z",
  "status": 500,
  "error": "Internal Server Error",
  "message": "Failed to deduct wallet(s)",
  "path": "/api/sms/send"
}

SMS Not Found

For invalid message IDs in the SMS details endpoint:

{
  "timestamp": "2026-02-27T08:32:55.123Z",
  "status": 404,
  "error": "Not Found",
  "message": "SMS not found",
  "path": "/api/sms/message/invalid-message-id"
}

Summary

The API now provides 5 endpoints that require API key authentication:

`POST /api/sms/send` - Send SMS messages
`GET /api/sms/countries` - List supported countries
`GET /api/sms/pricing` - Get pricing for all countries
`GET /api/sms/pricing/{countryCode}` - Get pricing for a specific country
`GET /api/sms/message/{messageId}` - Get SMS details by message ID

More endpoints will be added over time. This documentation will expand as new API capabilities are released.

Testing with Real API Keys

To test these endpoints with actual API keys:

1. Register at app.esmsafrica.io to create your account and get your API key and Account ID from the dashboard.

Create Free Account

2. Use the API key and Account ID from your dashboard in the X-API-Key and X-Account-ID headers for all API calls above.

Ready To Build

Start Building Today

Get your API keys and start integrating in minutes. Our developer-friendly API works with all major programming languages and frameworks.

Get API Keys Contact Support

99.9% Uptime <100ms Response 24/7 Developer Support Unlimited Scalability