API ReferenceSMS API
Check price
POST /api/messages/rate - Price a message before sending, no charge.
Endpoint
POST https://sms.esmsafrica.io/api/messages/rateAlso available as POST /api/rate. This never sends or charges - it returns the
exact segment count and cost the send would use, so you can show a live estimate
or reconcile spend up front.
Authentication
Authorization: Bearer esms_live_your_api_keyRequest body
{
"to": ["+256772123456", "+254712345678"],
"text": "Hello from eSMS Africa!"
}| Field | Type | Required | Description |
|---|---|---|---|
to | string or array | Yes | One number, or up to 1000 numbers in international format. |
text | string | Yes | The message to price (drives encoding + segment count). |
route | string | No | Force a public route code (e.g. ESMS_UG); otherwise auto-detected per number. |
Response
{
"encoding": "GSM7",
"segments": 1,
"characters": 25,
"units": 25,
"over_segment_cap": false,
"max_segments": 10,
"wallet_currency": "USD",
"wallet_balance": 12.50,
"recipients": [
{
"to": "+256772123456",
"country": "UG",
"route": "ESMS_UG",
"routable": true,
"segments": 1,
"encoding": "GSM7",
"price_per_segment": 35,
"route_currency": "UGX",
"cost_route": 35,
"cost_wallet": 0.0096
}
],
"routable_count": 2,
"unroutable": [],
"total_cost": 0.0192,
"affordable": true
}| Field | Description |
|---|---|
encoding / segments | GSM7 or UCS2, and how many segments the text bills as. |
recipients[] | Per-number breakdown: resolved route, price per segment, and cost in both route and wallet currency. |
unroutable | Numbers no active route matched (no country detected). |
total_cost | Sum across routable recipients, in your wallet currency. |
affordable | Whether your wallet balance covers total_cost (null if you have no wallet yet). |
Example
curl -X POST https://sms.esmsafrica.io/api/messages/rate \
-H "Authorization: Bearer esms_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "to": "+256772123456", "text": "Hello from eSMS Africa!" }'