Sandbox Mode: Test Email Without Sending

Test AhaSend API and SMTP email without delivery: use sandbox credentials or request options, simulate delivery outcomes, and check webhook handlers.

AhaSend sandbox mode lets you test API and SMTP sends, including delivery webhooks, without delivering email to recipients or using monthly email credits.

Sandbox is available on Free, Pro and Max. See plans and features.

What Happens in Sandbox Mode?

AhaSend validates and parses your message, records it in the dashboard, and simulates the selected delivery outcome. It makes no connection to the recipient’s mail server. Use it for local development, staging, automated tests and checking message substitutions.

Before testing, verify your sending domain and create the appropriate API key or SMTP credential.

How Do I Enable Sandbox Mode?

Choose the surface your application uses. Dedicated sandbox credentials keep all sends from that credential in sandbox mode; request parameters or headers let a production credential make an individual sandbox send.

API v2

Create a send-only key from Credentials → Add → API Key v2 and choose Sandbox mode. See API credentials for the key setup steps. To change an existing sending credential, open it in Credentials, change Mode, and save. Switching it to Production enables real delivery.

Use the API v2 Parameters

For maximum flexibility, you can use production credentials and control sandbox behavior with API parameters:

Sandbox Request Example

Add the sandbox parameter to your API v2 message request:

{
  "from": {
    "email": "[e-mail]",
    "name": "Your Company"
  },
  "recipients": [
    {
      "email": "[e-mail]",
      "name": "Test User"
    }
  ],
  "subject": "Sandbox Test Email",
  "text_content": "This email will be processed in sandbox mode.",
  "sandbox": true
}

Parameter Priority: When AhaSend sees the "sandbox": true parameter, it processes the email in sandbox mode regardless of the credential type used for authentication.

Choose an API Outcome

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

Use sandbox_result to choose one of the simulated outcomes.

Examples

Successful Delivery

{
  "from": {
    "email": "[e-mail]",
    "name": "Your Company"
  },
  "recipients": [
    {
      "email": "[e-mail]",
      "name": "Test User"
    }
  ],
  "subject": "Test Successful Delivery",
  "text_content": "This email will simulate successful delivery.",
  "sandbox": true,
  "sandbox_result": "deliver"
}

Webhook Testing: Each simulated outcome triggers the appropriate webhook events, allowing you to test your entire event handling pipeline safely.

SMTP

Create an SMTP credential in Credentials, select SMTP, and enable Sandbox. Copy its username and password into your server’s secret store; follow SMTP credential setup. An existing sending credential can switch modes from its Mode setting. Use the same SMTP settings in either mode.

SMTP Header Method

Add the AhaSend-Sandbox header to your email like any other header:

From: [e-mail]
To: [e-mail]
Subject: Test Email
AhaSend-Sandbox: true
Content-Type: text/plain

This email will be processed in sandbox mode.

API v1 Header Method

This is the legacy API v1 payload shape. For v2, use the top-level sandbox: true and sandbox_result fields shown in API sandbox mode.

Include the header in your API request’s content.headers:

{
  "from": {
    "name": "My App",
    "email": "[e-mail]"
  },
  "recipients": [
    {
      "name": "Test User",
      "email": "[e-mail]"
    }
  ],
  "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.

Choose an SMTP Outcome

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:

The same result values in the table below apply to SMTP.

Examples

SMTP Example

From: [e-mail]
To: [e-mail]
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.

Which Outcomes Can I Simulate?

Use sandbox_result in API v2 or AhaSend-Sandbox-Result in SMTP. See the special header reference for header parsing rules.

Result	Simulated outcome	Corresponding event
deliver (default)	Successful delivery	message.delivered
bounce	Hard bounce	message.bounced
defer	Temporary delivery failure	message.transient_error
fail	Permanent delivery failure	message.failed
suppress	Suppression blocking	message.suppressed

See the event reference for payloads. These are simulated delivery outcomes, not open or click events.

How Do I Test Webhooks Locally?

Use CLI webhook testing to forward events to your local handler. Sandbox sends trigger delivery, bounce, deferral, failure and suppression events. Opens and clicks require recipient interaction and are not simulated by sandbox sends; use CLI synthetic test events for those handlers.

Delivery, deferral and bounce webhooks include a representative delivery_attempt object. Its diagnostics are synthetic because no destination mail server was contacted. A sandbox classification may override the sample and may differ from its SMTP code or response text.

Verify signatures before processing a test event, and follow the retry policy when acknowledging deliveries.

Advanced Features

API v2 sandbox mode supports advanced features for comprehensive testing:

Bulk Operations

Test bulk sending in sandbox mode:

{
  "from": {
    "email": "[e-mail]",
    "name": "Your Company"
  },
  "recipients": [
    {
      "email": "[e-mail]",
      "name": "User One"
    },
    {
      "email": "[e-mail]",
      "name": "User Two"
    }
  ],
  "subject": "Bulk Test Email",
  "text_content": "Testing bulk operations in sandbox.",
  "sandbox": true
}

Scheduled Sending

Test scheduled emails in sandbox mode:

{
  "from": {
    "email": "[e-mail]",
    "name": "Your Company"
  },
  "recipients": [
    {
      "email": "[e-mail]",
      "name": "Test User"
    }
  ],
  "subject": "Scheduled Test Email",
  "text_content": "This is a scheduled sandbox email.",
  "schedule": {
    "first_attempt": "<RFC3339 time within the next 7 days>"
  },
  "sandbox": true
}

Template Variables

Test complex template substitutions:

{
  "from": {
    "email": "[e-mail]",
    "name": "Your Company"
  },
  "recipients": [
    {
      "email": "[e-mail]",
      "name": "Test User"
    }
  ],
  "subject": "Order {{order_id}} Confirmation",
  "html_content": "<h1>Order {{order_id}}</h1><p>Total: ${{total}}</p>",
  "substitutions": {
    "order_id": "12345",
    "total": "99.99"
  },
  "sandbox": true
}

Why Did My Test Not Work?

If an email was delivered, check that the credential is in Sandbox mode or the send includes the sandbox parameter or header. AhaSend-Sandbox accepts true or 1; use the result header only with sandbox mode.

If no event arrived, check your webhook URL, event filters and handler response. Use CLI webhook testing to inspect the event and the local response. Check the spelling of the five result values above if the outcome differs from the one you requested.

Related Guides

• Domain setup, Send-only API keys, API authentication.
• Create Message reference, SMTP settings, CLI sending.
• Node.js SDK, Go SDK, CLI webhook testing.
• Permission scopes, Idempotency, API errors.
• Rate limits, Suppression durations.