Sandbox mode lets you simulate the entire email sending process without actually delivering emails to recipients. It’s the perfect solution for testing your email integration safely, testing webhook workflows, and developing email features without worrying about costs or accidental sends.
Cost-Free Testing: Sandbox emails are completely free and don’t count toward your monthly email credits, no matter how many you send during development and testing.

​
What is Sandbox Mode?

When you send an email using sandbox mode, AhaSend processes it exactly like a production email - it goes through validation, parsing, and triggers all relevant webhooks - but stops just before attempting actual delivery. This makes it ideal for:
  • Development environments where you need to test email functionality
  • Staging environments to verify integrations before going live
  • Automated testing in CI/CD pipelines
  • Webhook testing to ensure your event handling works correctly
  • Template testing to verify email content and formatting

What Happens in Sandbox

✅ Email is validated and processed
✅ Webhooks are triggered
✅ Messages appear in your dashboard logs
✅ No delivery attempts are made
✅ Completely free - no credit usage

Perfect For

🧪 Development testing
🔗 Webhook integration testing
🤖 Automated test suites
📧 Template validation
🚀 Staging environment verification

​
Ways to Use Sandbox Mode

There are three flexible approaches to using sandbox mode, depending on your testing needs:

​
Creating Sandbox Credentials

Access Credentials Dashboard

  1. Log in to your AhaSend Dashboard
  2. Navigate to the Credentials section
  3. Click the “Create Credential” button

Configure Sandbox Credential

Select Credential Type:
  • Choose “SMTP” for SMTP credentials
Choose a Descriptive Name:
  • Use clear naming like “Development Sandbox SMTP” or “Testing Environment”
  • Include environment info to avoid confusion later
Enable Sandbox Mode:
  • Check the “Sandbox” box to create a dedicated sandbox credential
  • This ensures the credential always operates in sandbox mode

Save and Use

  1. Click “Create Credential” to generate your sandbox credentials
  2. Copy the username and password
  3. Use these credentials in your test environment exactly like production credentials
Environment Separation: Use sandbox credentials in development/staging and production credentials only in live environments for clear separation.

​
Switching Credential Modes

You can easily change existing credentials between Production and Sandbox modes:

Find Your Credential

  1. Go to the Credentials tab in your dashboard
  2. Find the credential you want to modify
  3. Click on the credential to open its settings

Change the Mode

  1. Locate the Mode field in the credential settings
  2. Select either “Sandbox” or “Production” from the dropdown
  3. Click “Save Changes” to apply the new mode
Mode Effects: Switching to sandbox stops actual delivery, while switching to production enables real email sending and credit usage.

​
Using Headers for Sandbox Mode

For maximum flexibility, you can use production credentials and control sandbox behavior with email headers:

​
SMTP Header Method

Add the AhaSend-Sandbox header to your email like any other header: 
From: [email protected]
To: [email protected]
Subject: Test Email
AhaSend-Sandbox: true
Content-Type: text/plain

This email will be processed in sandbox mode.

​
API Header Method

Include the header in your API request’s content.headers: 
{
  "from": {
    "name": "My App",
    "email": "[email protected]"
  },
  "recipients": [
    {
      "name": "Test User",
      "email": "[email protected]"
    }
  ],
  "content": {
    "subject": "Sandbox Test",
    "text_body": "Testing sandbox mode via API.",
    "headers": {
      "AhaSend-Sandbox": "true"
    }
  }
}
Header Priority: When AhaSend sees the AhaSend-Sandbox: true header, it processes the email in sandbox mode regardless of the credential type used for authentication.

​
Controlling Simulated Outcomes

Test how your application handles different delivery scenarios by controlling the simulated outcome:

​
Available Outcomes

Use the AhaSend-Sandbox-Result header to specify the simulated result:
  • deliver - Simulates successful delivery (default)
  • bounce - Simulates a hard bounce
  • defer - Simulates temporary delivery deferral
  • fail - Simulates permanent delivery failure
  • suppress - Simulates suppression list blocking

​
Examples

From: [email protected]
To: [email protected]
Subject: Test Bounce Handling
AhaSend-Sandbox: true
AhaSend-Sandbox-Result: bounce
Content-Type: text/plain

This email will simulate a bounce for testing.
Webhook Testing: Each simulated outcome triggers the appropriate webhook events, allowing you to test your entire event handling pipeline safely.

​
Testing Webhooks

Sandbox mode is perfect for testing webhook integrations:

​
Benefits

Cost-Free

No credit usage regardless of volume sent in sandbox mode

Safe Testing

Never accidentally email real users during development

Realistic Simulation

Full processing pipeline without actual delivery

Webhook Testing

Complete event simulation for integration testing

Flexible Control

Multiple ways to enable and control sandbox behavior

CI/CD Ready

Perfect for automated testing pipelines

​
Troubleshooting

​
Next Steps

Special Headers

Discover other useful headers for email customization

Send with SMTP

Send emails with SMTP credentials
Pro Tip: Set up dedicated sandbox credentials for each environment (development, staging, testing) and use descriptive names to avoid confusion. Include sandbox testing in your deployment pipeline to catch integration issues early.