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
✅ 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
🔗 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:1. Dedicated Sandbox Credentials
1. Dedicated Sandbox Credentials
Create credentials that always operate in sandbox mode. Perfect for dedicated testing environments.
- Any email sent with these credentials is automatically simulated
- Prevents accidental production sends from test environments
- Clear separation between testing and production
- Best for development and staging environments
2. Switchable Credential Mode
2. Switchable Credential Mode
Change existing credentials between Production and Sandbox mode as needed.
- Toggle credentials between modes in your dashboard
- Useful for credentials shared across environments
- Immediate effect when mode is changed
- Flexibility to adapt to current testing needs
3. Production Credentials + Headers
3. Production Credentials + Headers
Use production credentials but add special headers to individual emails for sandbox testing.
- Add
AhaSend-Sandbox: true
header to any email - Perfect for one-off testing or selective simulation
- No credential configuration changes needed
- Fine-grained control over individual sends
Creating Sandbox Credentials
Access Credentials Dashboard
- Log in to your AhaSend Dashboard
- Navigate to the Credentials section
- Click the “Create Credential” button
Configure Sandbox Credential
Select Credential Type:
- Choose “SMTP” for SMTP credentials
- Use clear naming like “Development Sandbox SMTP” or “Testing Environment”
- Include environment info to avoid confusion later
- Check the “Sandbox” box to create a dedicated sandbox credential
- This ensures the credential always operates in sandbox mode
Save and Use
- Click “Create Credential” to generate your sandbox credentials
- Copy the username and password
- 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
- Go to the Credentials tab in your dashboard
- Find the credential you want to modify
- Click on the credential to open its settings
Change the Mode
- Locate the Mode field in the credential settings
- Select either “Sandbox” or “Production” from the dropdown
- 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 theAhaSend-Sandbox
header to your email like any other header:
API Header Method
Include the header in your API request’scontent.headers
:
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 theAhaSend-Sandbox-Result
header to specify the simulated result:
deliver
- Simulates successful delivery (default)bounce
- Simulates a hard bouncedefer
- Simulates temporary delivery deferralfail
- Simulates permanent delivery failuresuppress
- Simulates suppression list blocking
Examples
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:Webhook Events Still Fire
Webhook Events Still Fire
- All webhook events are triggered normally in sandbox mode
- Test delivery confirmations, bounces, opens, and clicks
- Verify your webhook endpoint receives correct payloads
- No difference in webhook behavior between sandbox and production
Test Different Scenarios
Test Different Scenarios
Use
AhaSend-Sandbox-Result
to test various outcomes:- Delivery success webhooks with
deliver
- Bounce handling webhooks with
bounce
- Retry logic with
defer
simulations - Failure processing with
fail
outcomes - Suppression handling with
suppress
results
Safe Integration Testing
Safe Integration Testing
- Test webhook endpoints without affecting real users
- Validate webhook signature verification
- Test error handling and retry mechanisms
- Ensure proper event processing in your application
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
Emails Still Being Delivered
Emails Still Being Delivered
Check these settings:
- Verify credential is in Sandbox mode (check dashboard)
- Confirm
AhaSend-Sandbox: true
header is properly set - Ensure you’re using the correct sandbox credentials
- Check for typos in header names or values
Webhooks Not Firing
Webhooks Not Firing
Troubleshooting steps:
- Verify webhook URL is correctly configured
- Check webhook endpoint is accessible and responding
- Confirm webhook signature verification is working
- Test with simple sandbox send to verify basic functionality
Simulated Outcomes Not Working
Simulated Outcomes Not Working
Common issues:
AhaSend-Sandbox-Result
header must be used with sandbox mode- Check header value spelling (
deliver
,bounce
,defer
,fail
,suppress
) - Ensure both sandbox and result headers are properly formatted
- Verify your webhook handler processes different event types
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.