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.
• 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": "hello@yourdomain.com",
    "to": ["delivered@sandbox.test"],
    "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:

For example, send to bounce@sandbox.test 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 so you can safely branch on them:

{
  "event_type": "email.bounced",
  "email_id": "…",
  "livemode": false,
  "timestamp": "2026-07-31T12:00:00Z",
  "data": { "to": "bounce@sandbox.test", "reason": "simulated hard bounce" }
}

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.