Testing deferral simulation.
", > "text_content": "Testing deferral simulation.", > "sandbox": true, > "sandbox_result": "defer" > } > ``` > > ```json Permanent Failure theme={null} > { > "from": { "email": "hello@yourdomain.com" }, > "recipients": [{ "email": "test@example.com" }], > "subject": "Sandbox failure test", > "text_content": "This email simulates a permanent failure.", > "sandbox": true, > "sandbox_result": "fail" > } > ``` > > ```json Suppression Testing theme={null} > { > "from": { > "email": "hello@yourdomain.com", > "name": "Your Company" > }, > "recipients": [ > { > "email": "test@example.com", > "name": "Test User" > } > ], > "subject": "Test Suppression Handling", > "text_content": "This email will simulate suppression blocking.", > "sandbox": true, > "sandbox_result": "suppress" > } > ``` > > > [!TIP] > > > > **Webhook Testing:** Each simulated outcome triggers the appropriate webhook events, allowing you to test your entire event handling pipeline safely. > [tab] 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](https://ahasend.com/docs/smtp/credentials.md). An existing sending credential can switch modes from its **Mode** setting. Use the same [SMTP settings](https://ahasend.com/docs/smtp.md) in either mode. > > ### SMTP Header Method > > Add the `AhaSend-Sandbox` header to your email like any other header: > > ```plaintext theme={null} > From: hello@yourdomain.com > To: test@example.com > 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](https://ahasend.com/docs/send-api/sandbox.md). > > Include the header in your API request's `content.headers`: > > ```json theme={null} > { > "from": { > "name": "My App", > "email": "hello@yourdomain.com" > }, > "recipients": [ > { > "name": "Test User", > "email": "test@example.com" > } > ], > "content": { > "subject": "Sandbox Test", > "text_body": "Testing sandbox mode via API.", > "headers": { > "AhaSend-Sandbox": "true" > } > } > } > ``` > > > [!NOTE] > > > > **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 > > ```plaintext SMTP Example theme={null} > From: hello@yourdomain.com > To: test@example.com > Subject: Test Bounce Handling > AhaSend-Sandbox: true > AhaSend-Sandbox-Result: bounce > Content-Type: text/plain > > This email will simulate a bounce for testing. > ``` > > ```json Legacy API v1 Example theme={null} > { > "from": { > "name": "My App", > "email": "hello@yourdomain.com" > }, > "recipients": [ > { > "name": "Test User", > "email": "test@example.com" > } > ], > "content": { > "subject": "Test Deferral Handling", > "text_body": "Testing deferral simulation.", > "headers": { > "AhaSend-Sandbox": "true", > "AhaSend-Sandbox-Result": "defer" > } > } > } > ``` > > > [!NOTE] > > > > **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](https://ahasend.com/docs/smtp/special-headers.md) 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](https://ahasend.com/docs/api-reference/webhooks.md) for payloads. These are simulated delivery outcomes, not open or click events. ## How Do I Test Webhooks Locally? Use [CLI webhook testing](https://ahasend.com/docs/cli/webhook-testing.md) 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](https://ahasend.com/docs/api-reference/webhooks/security.md) before processing a test event, and follow the [retry policy](https://ahasend.com/docs/api-reference/webhooks/retry-policy.md) when acknowledging deliveries. ## Advanced Features API v2 sandbox mode supports advanced features for comprehensive testing: > [accordion] Bulk Operations > > Test bulk sending in sandbox mode: > > ```json theme={null} > { > "from": { > "email": "hello@yourdomain.com", > "name": "Your Company" > }, > "recipients": [ > { > "email": "user1@example.com", > "name": "User One" > }, > { > "email": "user2@example.com", > "name": "User Two" > } > ], > "subject": "Bulk Test Email", > "text_content": "Testing bulk operations in sandbox.", > "sandbox": true > } > ``` > [accordion] Scheduled Sending > > Test scheduled emails in sandbox mode: > > ```json theme={null} > { > "from": { > "email": "hello@yourdomain.com", > "name": "Your Company" > }, > "recipients": [ > { > "email": "test@example.com", > "name": "Test User" > } > ], > "subject": "Scheduled Test Email", > "text_content": "This is a scheduled sandbox email.", > "schedule": { > "first_attempt": "Total: ${{total}}
", > "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](https://ahasend.com/docs/cli/webhook-testing.md) 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](https://ahasend.com/docs/domains.md), [Send-only API keys](https://ahasend.com/docs/send-api/credentials.md), [API authentication](https://ahasend.com/docs/api-reference/authentication.md). * [Create Message reference](https://ahasend.com/docs/api-reference/messages/create-message.md), [SMTP settings](https://ahasend.com/docs/smtp.md), [CLI sending](https://ahasend.com/docs/cli/commands/messages.md). * [Node.js SDK](https://ahasend.com/docs/guides/nodejs-sdk.md), [Go SDK](https://ahasend.com/docs/guides/go-sdk.md), [CLI webhook testing](https://ahasend.com/docs/cli/webhook-testing.md). * [Permission scopes](https://ahasend.com/docs/api-reference/scopes.md), [Idempotency](https://ahasend.com/docs/api-reference/idempotency.md), [API errors](https://ahasend.com/docs/api-reference/errors.md). * [Rate limits](https://ahasend.com/docs/api-reference/rate-limits.md), [Suppression durations](https://ahasend.com/docs/bounces.md#suppression-duration). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.