Going live with the eSMS SMS API means swapping your esms_test_ key for an esms_live_ key, and the code does not change. What does change is that real messages go out and are billed, so use this SMS API go live checklist first: enable your countries, sort out sender IDs and balance, protect the key, and make sure webhooks, retries and errors behave before your first real send.

Last reviewed: 29 October 2026

Your SMS API go live checklist

  1. Enable every destination country

    Live sending is off by default for every country. In the dashboard open Countries, find each country you send to and click Enable; it takes effect at once for African countries. This can only be done in the dashboard, never with an API key (dashboard_only). The page also shows which countries are Live and which are Coming soon; sends to a Coming soon country are refused with destination_unavailable and not charged.

  2. Decide your sender ID per country

    Verified accounts get a default sender for their home country with no approval needed, and leaving sender_id out uses each country's default. A custom sender ID must be requested per country on the Sender IDs page and approved before you use it live, otherwise the send fails with sender_not_approved. The fee is shown per country there and charged only on approval.

  3. Top up your balance

    Top up at auth.esmsafrica.io/topup by mobile money (minimum USD 20, with the 5% service provider fee included in the total shown), Mukuru, or crypto (USDT on Tron or USDC, minimum USD 50, no fee). Check prices per country on /pricing. Turn on the Low balance alert on the Alerts page so a campaign never stalls.

  4. Create and protect a live key

    On API Keys, generate a key with Environment Live and only the permissions the service needs. Keep it in an environment variable or a secrets manager on the server, never in a mobile app or front-end code, and use a different key per service so you can revoke one without an outage. Revoke any key you no longer use.

  5. Send numbers in E.164

    Check that every to number includes its country code, such as +256772123456. Local numbers are refused with missing_country_code. Clean old lists with POST /api/messages/validate (up to 1,000 numbers per call, no charge).

  6. Switch on and verify webhooks

    Save your delivery report URL under Settings > Webhooks, check the X-Webhook-Signature on every event, answer 2xx within 15 seconds, and confirm DLR tracking is All messages on the General tab. Use Send test event, then ignore events with "livemode": false in production.

  7. Make retries safe

    Send an Idempotency-Key with every send and reuse it on retries (the SDKs do this automatically). Retry only 429 and 5xx responses, with backoff. Never retry a message in Confirming state: it is refused with 409 delivery_being_confirmed and settles to sent, or to failed with a refund, on its own.

  8. Plan for rate limits

    Each key can make 20 single sends a second and 10 bulk or batch calls a minute; above that you get 429 rate_limited. For lists, use the bulk or personalised batch endpoints instead of a loop of single sends.

  9. Respect opt-outs and content rules

    Numbers that replied STOP are refused with recipient_opted_out and dropped from bulk sends. For promotional traffic, set quiet hours and the opt-out line under Settings > Messaging, and send promotional batches with "message_type": "promotional".

  10. Send one real message and check the logs

    Send a live message to your own phone. Confirm it arrives with the right sender, then find it on Message Logs and the API call on Request Logs, and check the webhook landed on Webhook Logs. Only then point production traffic at the live key.

Common errors and how to fix them

What you seeWhat it meansHow to fix it
403 country_not_enabledThe country is not switched on for live sends. Nothing was charged.Owner or admin: Countries, Enable.
403 sender_not_approvedYour sender ID is not approved in that country.Omit it to use the default, or wait for approval.
402 insufficient_balanceNo balance for the send.Top up; switch on the Low balance alert.
401 unauthorizedThe live key was not deployed, or the test key is still in use somewhere.Check the environment variable in each service; the key prefix shows which one is in use.
400 destination_unavailableThe country is Coming soon for live sends.Check the Countries page; keep using test keys for that country until it opens.
429 rate_limitedToo many calls per key.Move lists to bulk or batch endpoints and back off on 429.

Frequently asked questions

Do I need to change my code to go live?

No. Swap the test key for a live key. The endpoints, request and response shapes are the same.

Is onboarding and KYC required before going live?

It is currently optional, but completing Onboarding & KYC under ACCOUNT speeds up sender ID registration.

Can I go live in one country and keep testing another?

Yes. Enable only the countries you are ready for; test keys keep working for every African country.

What if a message fails after going live?

Messages the network rejects are refunded automatically, and the delivery report carries the reason in error_code.

Can I pay by card?

No. Top-ups are by mobile money, Mukuru or crypto. WhatsApp +254 114 494147 if you need help topping up.

Ready? Create your live API key, or create a free eSMS account if you have not yet. Questions before launch? WhatsApp +254 114 494147.