Skip to main content
Sandbox is Rewrite’s testing mode for validating integrations without relying on a real carrier path. When a project runs in sandbox, the API still accepts sends and webhooks, but the backend uses controlled simulation instead of live dispatch.

​
What changes in sandbox

No live traffic

Messages and OTP flows can be simulated without real carrier delivery.

Explicit signaling

Responses, events, logs, and deliveries expose sandbox: true whenever that field is part of the public contract.

Predictable OTP

Sandbox OTP verification uses deterministic behavior for automated tests.

Real webhooks

Events still use Svix signing and the same retry semantics as production.

​
Important rules

  • Sandbox does not allow scheduled messages.
  • API keys must match the current project mode. When they do not, the API can return 403 API_KEY_MODE_MISMATCH.
  • The magic numbers set lets you force FAILED, QUEUED, SENT, and DELIVERED outcomes.

​
Where the mode shows up

  • POST /messages and POST /messages/batch return sandbox in the create result.
  • Message webhook payloads include sandbox.
  • The webhook event envelope includes sandbox.
  • Request logs and webhook deliveries exposed by the API include sandbox.
  1. Enable sandbox for the project in the appropriate test environment.
  2. Send messages or OTP requests normally.
  3. Use magic numbers to force specific outcomes.
  4. Validate emitted webhooks, especially message.sent, message.delivered, message.failed, message.queued, sms.otp, and message.received.
  5. Only then promote the flow to live mode.