Rate this page:

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; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

      
      
      

      Thank you for your feedback!

      We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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

      Thanks for your feedback!

      Refer us and get $10 in 3 simple steps!

      Step 1

      Get link

      Get a free personal referral link here

      Step 2

      Give $10

      Your user signs up and upgrade using link

      Step 3

      Get $10

      1,250 free SMSes
      OR 1,000 free voice mins
      OR 12,000 chats
      OR more