Sender IDs
Per-country Sender ID fees, and listing and requesting sender IDs for your account.
Overview
A sender ID is the name (up to 11 characters) or number shown as the sender of your SMS. Registration rules and fees differ by country. For the product overview and how approval works, see the Sender IDs guide.
| Method | Path | Description |
|---|---|---|
GET | /api/sender-ids/fees | Sender ID fees for all 54 countries (public, no auth) |
GET | /api/sender-ids/default | Your default sender |
GET | /api/sender-ids | List your sender IDs |
POST | /api/sender-ids | Request a sender ID |
Get Sender ID fees
GET https://sms.esmsafrica.io/api/sender-ids/feesPublic - no authentication. Cached for up to 5 minutes. Returns the Sender ID fee for every one of the 54 African countries, in USD.
Fees are stated in USD, one per country in the request that has a fee. Pay them through Pay for Sender ID. Your SMS credit is not used for Sender ID fees.
Response
{
"currency": "USD",
"countries": [
{
"country_code": "GH",
"country_name": "Ghana",
"fee_usd": 100,
"fee_type": "one_time",
"covers": "all_networks",
"fee_table": null,
"note": null
},
{
"country_code": "KE",
"country_name": "Kenya",
"fee_usd": 212.57,
"fee_type": "bundle",
"covers": "all_networks",
"note": "One payment covers Safaricom, Airtel, Telkom and Equitel. These are one-time fees with no monthly maintenance.",
"bundle": {
"total_usd": 212.57,
"lines": [
{ "network": "Safaricom and Airtel", "detail": "One-time, bundled rate", "units": 1, "amount_usd": 108.59 },
{ "network": "Telkom", "detail": "One-time", "units": 1, "amount_usd": 34.66 },
{ "network": "Equitel", "detail": "One-time", "units": 1, "amount_usd": 69.32 }
]
}
},
{
"country_code": "NG",
"country_name": "Nigeria",
"fee_usd": 100,
"fee_type": "one_time",
"covers": "all_networks",
"fee_table": null,
"note": null
}
]
}| Field | Type | Description |
|---|---|---|
country_code | string | ISO 3166-1 alpha-2 code. |
country_name | string | Display name. |
fee_usd | number | null | The fee in USD. 100 for flat-fee countries (every country except Kenya and Uganda); 212.57 for Kenya and 268 for Uganda; null when the fee is confirmed at onboarding. |
fee_type | string | one_time - a single flat fee for the country. bundle - one total covering all networks, with a per-network breakdown in bundle (Kenya, Uganda). on_request - fees are confirmed during onboarding. |
covers | string | null | all_networks when one payment registers the sender ID on every network in the country. |
fee_table | array | null | Kept for older clients. Use fee_usd and bundle for what you pay. |
bundle | object | Kenya and Uganda only. total_usd, note and lines, one per network: network, detail, units, amount_usd. Other fields in bundle are kept for older clients; amount_usd and fee_usd are the source. |
note | string | null | Extra detail, for example Confirmed during onboarding. |
The response also has a legacy top-level fees map (country code to USD fee, including Kenya and Uganda) and a note.
Fees by country
| Countries | Fee |
|---|---|
| All African countries except Kenya and Uganda | USD 100 one-time per country - covers registration on all networks |
| Kenya | USD 212.57 one-time, no monthly maintenance - one payment covers all 4 networks |
| Uganda | USD 268 - one payment covers all networks |
Kenya
| Network | Calculation | Amount |
|---|---|---|
| Safaricom and Airtel (bundled rate) | One-time | USD 108.59 |
| Telkom | One-time | USD 34.66 |
| Equitel | One-time | USD 69.32 |
| Total | USD 212.57 |
Uganda
| Network | Calculation | Amount |
|---|---|---|
| MTN | 3 months x USD 67 | USD 201 |
| Airtel | One-time | USD 67 |
| Total | USD 268 |
After the first 3 months, MTN is UGX 250,000 per month, charged in USD at the exchange rate at that time. Your SMS credit is not used for it. Nothing is debited automatically: we contact you when it is due.
The endpoint is the source of truth - read it for current fees.
Example
curl https://sms.esmsafrica.io/api/sender-ids/feesGet your default sender
GET https://sms.esmsafrica.io/api/sender-ids/defaultNeeds a signed-in session or an API key. Default sender IDs can be used only in 8 countries.
{
"country_code": "CM",
"default_sender": null,
"default_available": false,
"default_countries": ["CD", "CI", "GH", "KE", "NG", "RW", "TZ", "UG"],
"affected_countries": ["CM"],
"register_url": "https://sms.esmsafrica.io/sender-ids"
}| Field | Description |
|---|---|
country_code | Your account's home country. |
default_sender | The default sender for your home country, or null when it is not available to you. |
default_available | Whether you can use it. |
default_countries | The countries where default sender IDs can be used. |
affected_countries | The countries on your account where you must register your own sender ID. |
register_url | Where to request a sender ID. |
List your sender IDs
GET https://sms.esmsafrica.io/api/sender-idsNeeds a signed-in session or an API key (Authorization: Bearer esms_live_your_api_key).
Returns your sender IDs, newest first. GET /api/sender-ids/payable returns the requests you
can still pay for from Pay for Sender ID, with the same payment fields.
[
{
"id": 17,
"name": "AcmeFoods",
"countries": ["GH", "KE"],
"use_case": "Order updates",
"status": "approved",
"rejection_reason": null,
"waiting_message": null,
"fee_usd": 100,
"fee_charged_at": "2026-10-08T09:30:00+00:00",
"payment_state": "settled",
"balance_due_usd": 0,
"created_at": "2026-10-07T14:12:00+00:00"
}
]| Field | Description |
|---|---|
status | pending, waiting (the team needs more from you - see waiting_message), approved or rejected. |
fee_usd | The Sender ID fee settled for this request (0 when no fee applied). |
fee_charged_at | When the fee was settled from the payments held on the request, or null. |
payment_state | no_fee, unpaid, part_paid (part of the fee is held and a balance is due; only that exact balance can be paid), paid_in_full (the payments held cover the fee) or settled (the fee has been settled). |
balance_due_usd | What is still due in USD. A part_paid request is not fully paid until this is cleared. |
fee_breakdown | One row per country still owing a fee: country_code, fee_usd and, for Kenya and Uganda, bundle with the per-network lines. |
Request a sender ID
POST https://sms.esmsafrica.io/api/sender-ids{
"name": "AcmeFoods",
"countries": ["GH", "KE"],
"use_case": "Order updates"
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 3 to 11 characters: letters A-Z / a-z, digits 0-9 and single hyphens, for example eSMS, eSMSAfrica or eSMS-UG. No spaces or underscores, no hyphen at the start or end. Case is kept as typed. |
countries | string[] | Yes | ISO country codes to register in. |
use_case | string | No | What you will send. Helps the networks approve faster. |
Response
{
"id": 17,
"name": "AcmeFoods",
"status": "awaiting_payment",
"estimated_fee_usd": 100,
"amount_due_usd": 100,
"pay_url": "/sender-ids/pay?request=17",
"fee_countries": ["GH"]
}status is awaiting_payment until the fee is paid in full, then pending (under review) on its own. The
default senders eSMS and eSMSAfrica have no fee: in the default-sender countries a request for them is
approved at once.
A name that breaks the format returns 400 with code invalid_sender_name and the rule in error.details.hint.
A name that looks like a protected brand (banks, mobile money, postal services, government bodies, large brands)
is accepted but needs brand proof: upload a letter from the brand owner with
POST /api/sender-ids/{id}/brand-proof (multipart file, PDF, JPG or PNG, up to 10 MB). Until our team has
checked it, paying returns brand_proof_required and nothing is charged.
estimated_fee_usd is the Sender ID fee for the request (one fee per country in
fee_countries; in Kenya and Uganda, the total that covers all networks). Nothing is charged
now. Pay it through Pay for Sender ID, in one payment of the exact
amount due. Your SMS credit is not used for Sender ID fees. Approving a
request with a balance due returns 402 with code sender_fee_unpaid.
The payment is held on the request and goes to your balance if it is rejected or deleted. A request
that includes a country we cannot send to today can be submitted but cannot be paid, and nothing is
charged: unavailable_countries in the response lists those countries.
Completing Onboarding and KYC first is recommended: the networks need
those documents to register a sender ID. If your account is set up to require it, a request without an approved
onboarding returns 403 with code onboarding_required and an onboarding_url.
Sandbox
The Two-Way SMS sandbox API - simulated phones, simulated inbound with the live matching rules and a debug record, sends to simulated phones, the sandbox clock, a sandbox webhook URL, reset and request bins.
Opt-outs
GET/POST/DELETE /api/opt-outs - Manage your STOP list; STOP/START handled automatically.