Sandbox (Test Mode)

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.

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.