Sandbox Mode

Sandbox mode simulates a mutation request without executing it. When the request body of a supported endpoint contains "sandbox": true, the API authenticates and validates the request as usual, then returns a simulated response with sample data instead of performing the operation.

For test-suite, CI, and debugging workflows built on sandbox mode, see Testing with sandbox mode.

Request Field

sandbox must be the JSON boolean true; the string "true" is not a valid value. The API reads the field from the request body of the endpoints listed under Supported Endpoints, never from headers or query parameters.

Two endpoints also accept a multipart form body:

• PATCH /v3/channels/sms/{country}/{type}: send sandbox as its own form field with the text value true.
• POST /v3/sender-profiles: include "sandbox": true inside the JSON document in the profile form field.

How It Works

For a request with "sandbox": true:

1. Authentication runs. An invalid or missing API key is rejected with 401.
2. Request validation runs. A malformed payload returns the same 400 errors as a live request.
3. Execution is skipped. The database, the send queue, downstream provider APIs, and your balance are all left untouched.
4. A simulated response is returned. It uses the same envelope and schema as a live response, populated with sample data, and the same status code except where Supported Endpoints notes otherwise. Identifiers such as message_id are newly generated and do not reference stored resources.

Sandbox mode does not look up stored resources for most endpoints. A sandbox send referencing a nonexistent template ID still returns 202; only request-level validation is applied. The exceptions are the channel and Sender Profile endpoints below. They read your stored account state first and return the same errors as a live request:

Response Headers

Example

POST /v3/messages
Content-Type: application/json
x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

{
  "sandbox": true,
  "to": ["+14155550123"],
  "channel": ["sms"],
  "template": {
    "id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "parameters": {
      "name": "Test User"
    }
  }
}

Response:

HTTP/1.1 202 Accepted
X-Sandbox: true
X-Request-Id: req_5f2c1b3a9d8e4f67
Content-Type: application/json

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "",
    "recipients": [
      {
        "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
        "to": "+14155550123",
        "channel": "sms",
        "body": null
      }
    ]
  },
  "meta": {
    "request_id": "req_5f2c1b3a9d8e4f67",
    "timestamp": "2026-07-25T10:30:00Z",
    "version": "v3"
  }
}

In the simulated response, template_name is empty and body is null because the template is referenced by id and sandbox mode performs no template lookup. message_id is generated per recipient and does not correspond to a stored message.

Supported Endpoints

Deprecated Endpoints

These endpoints are deprecated and will be removed in a future release. They still accept "sandbox": true, but new integrations should use the replacement. Responses from the /v3/profiles endpoints, sandbox or live, carry a Deprecation: true header and a Link header pointing to /v3/sender-profiles with rel="successor-version".

Sandbox Mode vs Idempotency

Refer to Idempotency for key format, expiry, and replay headers.

Troubleshooting