Sandbox (Test Mode)
Build and test your integration with test API keys - no real messages, no charges.
New to test keys? Start with Test keys and the sandbox. Test keys work for all 54 African countries with no country enablement.
Every eSMS Africa account has a sandbox so you can build and test your integration end to end without sending real SMS or spending balance.
Use a test API key (prefixed esms_test_) instead of a live key
(esms_live_). Create one under API keys → Environment: Test in the
dashboard. The SDKs auto-detect the key prefix - no other change is needed.
What test mode does
- Nothing is sent to a real network and nothing is billed - your balance is never touched.
- Responses are realistic: real segment/encoding calculation, a
test_…message id, and"environment": "test","livemode": false. - The delivery lifecycle is simulated (
queued → submitted → delivered) and your webhook fires with"livemode": false, so you can build your delivery handling for real. - Test traffic appears only in your test logs (live logs stay clean).
curl https://sms.esmsafrica.io/api/messages/send \
-H "Authorization: Bearer esms_test_xxx" \
-H "Content-Type: application/json" \
-d '{"to":"+254712341234","text":"Hello from the sandbox"}'{
"id": "test_ff13a...",
"status": "queued",
"environment": "test",
"livemode": false,
"segments": 1,
"encoding": "GSM7",
"recipients": 1,
"price_per_sms": 0.015,
"cost": 0.015,
"note": "Sandbox message - simulated, not sent to a real network and not billed."
}Magic numbers
Control the simulated outcome with the last 4 digits of the destination number. Anything not listed is delivered.
| Destination ends in | Simulated result |
|---|---|
| any other number | delivered |
…0000 | undelivered |
…0002 | sent (submitted, no final DLR) |
…0003 | failed (rejected by carrier) |
…0404 | failed (unknown subscriber) |
…0009 | 402 insufficient balance |
For example, send to +254712340000 to test how your app handles an
undelivered webhook, or to +254712340009 to test your insufficient
balance (HTTP 402) handling.
Going live
When you're ready, swap the test key for your live key (esms_live_). Same
request, same response shape - live messages are sent to real networks and billed
per segment. Nothing else changes.
Test and live traffic are fully isolated: a test key can only see test messages,
and live keys/dashboard default to live (filter with ?environment=test to view
your sandbox logs).