eSMS AfricaeSMS Africa
API ReferenceSMS API

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.

MethodPathDescription
GET/api/sender-ids/feesSender ID fees for all 54 countries (public, no auth)
GET/api/sender-ids/defaultYour default sender
GET/api/sender-idsList your sender IDs
POST/api/sender-idsRequest a sender ID

Get Sender ID fees

GET https://sms.esmsafrica.io/api/sender-ids/fees

Public - 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
    }
  ]
}
FieldTypeDescription
country_codestringISO 3166-1 alpha-2 code.
country_namestringDisplay name.
fee_usdnumber | nullThe 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_typestringone_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.
coversstring | nullall_networks when one payment registers the sender ID on every network in the country.
fee_tablearray | nullKept for older clients. Use fee_usd and bundle for what you pay.
bundleobjectKenya 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.
notestring | nullExtra 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

CountriesFee
All African countries except Kenya and UgandaUSD 100 one-time per country - covers registration on all networks
KenyaUSD 212.57 one-time, no monthly maintenance - one payment covers all 4 networks
UgandaUSD 268 - one payment covers all networks

Kenya

NetworkCalculationAmount
Safaricom and Airtel (bundled rate)One-timeUSD 108.59
TelkomOne-timeUSD 34.66
EquitelOne-timeUSD 69.32
TotalUSD 212.57

Uganda

NetworkCalculationAmount
MTN3 months x USD 67USD 201
AirtelOne-timeUSD 67
TotalUSD 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/fees

Get your default sender

GET https://sms.esmsafrica.io/api/sender-ids/default

Needs 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"
}
FieldDescription
country_codeYour account's home country.
default_senderThe default sender for your home country, or null when it is not available to you.
default_availableWhether you can use it.
default_countriesThe countries where default sender IDs can be used.
affected_countriesThe countries on your account where you must register your own sender ID.
register_urlWhere to request a sender ID.

List your sender IDs

GET https://sms.esmsafrica.io/api/sender-ids

Needs 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"
  }
]
FieldDescription
statuspending, waiting (the team needs more from you - see waiting_message), approved or rejected.
fee_usdThe Sender ID fee settled for this request (0 when no fee applied).
fee_charged_atWhen the fee was settled from the payments held on the request, or null.
payment_stateno_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_usdWhat is still due in USD. A part_paid request is not fully paid until this is cleared.
fee_breakdownOne 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"
}
FieldTypeRequiredDescription
namestringYes3 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.
countriesstring[]YesISO country codes to register in.
use_casestringNoWhat 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.

On this page