Sandbox Mode

Sandbox mode is only used to validate your request. The email will never be delivered while this feature is enabled! Any requests made in sandbox mode will not generate events in either Event Webhook or Email Activity. No Credits will be consumed.

Sandbox mode is an optional parameter within mail_settings. Enabling sandbox mode allows you to send a test email to ensure that your request body is formatted correctly without delivering the email to any of your recipients.

When making a request with sandbox mode enabled, we will validate the form, type, and shape of your request. In other words, sandbox mode will validate each parameter you include and the structure of your JSON payload. If you include a template_id in your sandbox mode request, it will be assumed that you have included a subject line and body within the template. We will not validate this content.

Using Sandbox Mode

When using sandbox mode, you must include the "enable" parameter, and it must be given a boolean value of either true or false. Do not enclose the boolean value in quotes or you will receive the error:

The sandbox mode enable param should be a boolean value.

Valid Request Body

When your request validates, you will receive a 200 OK response (as opposed to the 202 ACCEPTED response that is returned for successful non-sandbox requests).

Invalid Request Body

If you submit a request with sandbox mode enabled, but your request body is invalid, you will receive one or more error messages with error codes, detailed explanations for the error or errors, and links to any relevant documentation.

Example Sandbox Mode JSON

The following is an invalid request body intended to demonstrate the validation behavior of sandbox mode for a bad request.

Request

{
    "personalizations": [{
        "to": [{
            "email": "john@example.com"
        }],
        "subject": "Hello, World!"
    }],
    "from": {
        "email": "John Doe"
    },
    "content": {
        "type": "text",
        "value": "Hello, World!"
    },
    "mail_settings": {
        "sandbox_mode": {
            "enable": true
        }
    }
}

Response

{
  "errors": [
    {
      "field": "from",
      "message": "The from object must at least have an 'email'
parameter with a valid email address and may also contain a 'name' parameter. e.g. {"email": "example@example.com"} or {"email": "example@example.com", "name": "Example Recipient"}"
    }
  ]
}
Rate this page:

Need some help?

We all do sometimes. Get help now from the Twilio SendGrid Support Team.

Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif