Sandbox mode

Estimated time to read: 3 minutes

European Transactional Email Service (EU TES) offers a powerful - and FREE - Sandbox mode that allows you to test your email implementation without sending actual messages to recipients. This feature is invaluable during development, integration testing, and troubleshooting phases of your email infrastructure setup.

Sandbox mode provides a safe environment where you can validate your email sending logic, test error handling capabilities, and verify integration without worrying about emails reaching real recipients or affecting your sender reputation.

What is Sandbox Mode?

Sandbox mode is a testing environment that simulates the email sending process without actually delivering messages to recipients. When using Sandbox mode:

• Your API calls and SMTP connections are processed normally
• Message content is validated as it would be in production
• Delivery is simulated rather than executed
• Detailed logs and responses are provided just like real sends
• No messages are actually delivered to recipients

This allows you to thoroughly test your email implementation in a risk-free environment.

Benefits of Using Sandbox Mode

Risk-Free Testing

• Eliminate the risk of accidentally sending test emails to real customers
• Test error scenarios without impacting real recipients

Development Advantages

• Test integration code without requiring specialized test environments
• Ensure authentication and connectivity are properly configured

How to Use Sandbox Mode

There are three ways to enable Sandbox mode for your email sending:

1. Create Dedicated Sandbox Credentials

You can create SMTP or API credentials that operate exclusively in Sandbox mode.

In the Dashboard:

1. Navigate to Credentials
2. Click Add Credential
3. Toggle on the Sandbox Mode option
4. Complete the credential creation process

Any messages sent using these credentials will automatically be processed in Sandbox mode.

2. Convert Existing Credentials to Sandbox Mode

You can also modify existing credentials to operate in Sandbox mode:

In the Dashboard:

1. Navigate to Credentials
2. Locate the credential you wish to modify
3. Click Edit
4. Toggle on the Sandbox Mode option
5. Save your changes

3. Use Special Headers for Individual Messages

For more granular control, you can enable Sandbox mode for individual messages by including special headers:

To enable Sandbox mode for a specific message: Add the seseu-Sandbox header with a value of either true or 1.

Example (API):

{
  "to": "recipient@example.com",
  "subject": "Test Message",
  "text": "This is a test message.",
  "headers": {
    "seseu-Sandbox": "true"
  }
}

Example (SMTP):

X-seseu-Sandbox: true

Simulating Different Delivery Outcomes

Sandbox mode allows you to simulate various delivery outcomes to test how your application handles different scenarios. By default, all messages in Sandbox mode simulate successful delivery, but you can customize this behavior.

Use the seseu-Sandbox-Result header to specify the desired outcome:

Value	Description
deliver	Simulates successful delivery (default)
bounce	Simulates a permanent failure (bounce)
defer	Simulates a temporary failure (will retry)
fail	Simulates an immediate sending failure
suppress	Simulates message suppression due to compliance issues

Example (API):

{
  "to": "recipient@example.com",
  "subject": "Test Bounce Scenario",
  "text": "This message will simulate a bounce.",
  "headers": {
    "seseu-Sandbox": "true",
    "seseu-Sandbox-Result": "bounce"
  }
}

Example (SMTP):

X-seseu-Sandbox: true
X-seseu-Sandbox-Result: bounce

Sandbox Mode Response Details

When using Sandbox mode, you'll receive responses that closely mirror production behavior:

• For API calls, you'll receive the same JSON structure with appropriate status codes
• For SMTP connections, you'll receive standard SMTP response codes
• Message IDs are generated just as they would be for real messages
• Webhook events are triggered based on the simulated outcome

The response will include a special field or header indicating that the message was processed in Sandbox mode.

Viewing Sandbox Messages in the Dashboard

Messages sent using Sandbox mode are clearly marked in the EU TES dashboard:

1. Navigate to Messages
2. Look for messages with the Sandbox label
3. Click on any message to view complete details of the simulated send

You can filter the message log to show only Sandbox messages or exclude them from view.