Sandbox testing

What sandbox mode is

Sandbox is a property of the API key, not of the environment. Send a request with a sk_test_ key and Sendozi validates it exactly as it would a live one, records the message, and stops short of calling a provider or debiting the wallet.

This matters because the usual failure of a mock environment is that it diverges from production. Here there is nothing to diverge: same host, same routes, same validation code. Switching to production is a change of environment variable, not a change of code.

What sandbox does and does not check

Using it

# Development
export SENDOZI_API_KEY="sk_test_..."

# Production
export SENDOZI_API_KEY="sk_live_..."

curl -X POST https://api.sendozi.com/v1/sms/send \
  -H "Authorization: Bearer $SENDOZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "Sendozi",
    "recipient": "+2348012345678",
    "message": "Sandbox test.",
    "sms_type": "transactional"
  }'

The response reports mode: "sandbox" and a customer_price_kobo figure, so you can assert on what a send would have cost without paying it. Sandbox messages appear in GET /v1/messages alongside live ones and are distinguished by mode.

What to test in sandbox

• Recipient normalisation - assert that a local 0-prefixed number is rejected before it reaches production.
• Page counting - send your longest merge-field expansion and check customer_price_kobo matches your estimate.
• Error handling - assert your client branches on error.code rather than on the message text.
• Idempotency - send twice with the same key and confirm you get one message, not two.
• Webhook receivers - use POST /v1/webhooks/endpoints/{id}/test to exercise signature verification.
• Rate-limit backoff - confirm your client honours the delay in the resolution rather than hammering.

Before you switch keys

1. 1

   KYC approved

   Otherwise every live send returns kyc_required.

2. 2

   Sender ID registered and approved

   Otherwise sender_id_not_approved. Registration depends on the networks, so start early.

3. 3

   Wallet funded

   For the whole first campaign, not the first few messages.

4. 4

   Webhook endpoint registered and verified

   Test it before real deliveries depend on it.

5. 5

   One real message to your own phone

   The only test that exercises the last mile.