Sandbox & Testing

The Sandbox lets you build and test your integration end-to-end - request shapes, webhooks, error handling - without sending real email and without touching your plan quota. It's the same API surface as production; only the delivery is simulated.

How it works

Use a test API key (prefix esms_test_…, environment test - see API Keys). Any email you send with it is:

• Never delivered to a real inbox.
• Never billed and never counted against your daily/monthly limits.
• Fully simulated: it moves through queued → sent → delivered (or a failure state you choose) and fires the same webhooks as live email, marked "livemode": false inside the event data.
• Isolated in your logs - visible only under the Test environment filter or with ?environment=test.

curl -X POST https://send.esmsafrica.io/v1/emails \
  -H "Authorization: Bearer esms_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "[email protected]" },
    "to": [{ "email": "[email protected]" }],
    "subject": "Sandbox test",
    "html": "<p>Testing 1-2-3</p>"
  }'

Magic recipients

The Sandbox decides the simulated outcome from the recipient's local part (the text before @), so you can exercise every code path deterministically:

Every simulation emits sent first, then its final event.

For example, send to [email protected] to confirm your webhook handler and suppression logic react correctly to a bounce - no real bounce required.

Verifying webhooks

Point a webhook at your endpoint (or a tool like a request-bin), send to a magic recipient, and confirm you receive the events. Sandbox events carry "livemode": false inside data, so you can safely branch on them:

{
  "event_type": "bounced",
  "email_id": "…",
  "timestamp": "2026-07-31T12:00:00Z",
  "data": { "livemode": false, "sandbox": true }
}

Going live

When your integration works in the Sandbox, swap the esms_test_… key for a live esms_k_… key (same requests, same responses) and start sending for real. Nothing else changes.