> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox Mode

> Test your API v2 email integration safely with AhaSend's sandbox mode - simulate email sending without delivery and webhook testing at zero cost

Sandbox mode lets you simulate the entire email sending process without actually delivering emails to recipients. It's the perfect solution for testing your API v2 integration safely, testing webhook workflows, and developing email features without worrying about costs or accidental sends.

<Info>
  **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.
</Info>

## What is Sandbox Mode?

When you send an email using sandbox mode with API v2, 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

<CardGroup cols={2}>
  <Card title="What Happens in Sandbox" icon="check">
    ✅ Email is validated and processed<br />
    ✅ Webhooks are triggered<br />
    ✅ Messages appear in your dashboard logs<br />
    ✅ No delivery attempts are made<br />
    ✅ Completely free - no credit usage
  </Card>

  <Card title="Perfect For" icon="bullseye">
    🧪 **Development testing**<br />
    🔗 **Webhook integration testing**<br />
    🤖 **Automated test suites**<br />
    📧 **Template validation**<br />
    🚀 **Staging environment verification**
  </Card>
</CardGroup>

## Ways to Use Sandbox Mode

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

<AccordionGroup>
  <Accordion title="1. Dedicated Sandbox Credentials" icon="key">
    Create API v2 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
  </Accordion>

  <Accordion title="2. Switchable Credential Mode" icon="toggle-on">
    Change existing API v2 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
  </Accordion>

  <Accordion title="3. Production Credentials + Parameters" icon="code">
    Use production credentials but add the `sandbox` parameter to individual API requests for sandbox testing.

    * Add `"sandbox": true` to any API request
    * Perfect for one-off testing or selective simulation
    * No credential configuration changes needed
    * Fine-grained control over individual sends
  </Accordion>
</AccordionGroup>

## Creating Sandbox Credentials

<Steps>
  <Step title="Access Credentials Dashboard" icon="user">
    1. **Log in** to your [AhaSend Dashboard](https://dash.ahasend.com)
    2. **Navigate** to the **[Credentials](https://dash.ahasend.com/account/-/transactional/credentials)** section
    3. **Click** the **"Create Credential"** button
  </Step>

  <Step title="Configure Sandbox Credential" icon="gear">
    **Select Credential Type:**

    * Choose **"API Key v2"** for advanced API features

    **Choose a Descriptive Name:**

    * Use clear naming like "Development Sandbox API v2" or "Testing Environment v2"
    * Include environment info to avoid confusion later

    **Enable Sandbox Mode:**

    * **Select "Sandbox"** mode to create a dedicated sandbox credential
    * This ensures the credential always operates in sandbox mode
  </Step>

  <Step title="Save and Use" icon="floppy-disk">
    1. **Click** "Create Credential" to generate your sandbox API key
    2. **Copy** the API key securely
    3. **Use this API key** in your test environment exactly like production credentials

    <Tip>
      **Environment Separation:** Use sandbox API keys in development/staging and production keys only in live environments for clear separation.
    </Tip>
  </Step>
</Steps>

## Switching Credential Modes

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

<Steps>
  <Step title="Find Your Credential" icon="magnifying-glass">
    1. **Go to** the **Credentials** tab in your dashboard
    2. **Find** the API v2 credential you want to modify
    3. **Click** on the credential to open its settings
  </Step>

  <Step title="Change the Mode" icon="toggle">
    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

    <Warning>
      **Mode Effects:** Switching to sandbox stops actual delivery, while switching to production enables real email sending and credit usage.
    </Warning>
  </Step>
</Steps>

## Using Sandbox 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](https://ahasend.com/docs/api-reference/messages/create-message):

```json theme={null}
{
  "from": {
    "email": "hello@yourdomain.com",
    "name": "Your Company"
  },
  "recipients": [
    {
      "email": "test@example.com",
      "name": "Test User"
    }
  ],
  "subject": "Sandbox Test Email",
  "text_content": "This email will be processed in sandbox mode.",
  "sandbox": true
}
```

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

## Controlling Simulated Outcomes

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

### Available Outcomes

Use the `sandbox_result` parameter 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

<CodeGroup>
  ```json Successful Delivery theme={null}
  {
    "from": {
      "email": "hello@yourdomain.com",
      "name": "Your Company"
    },
    "recipients": [
      {
        "email": "test@example.com",
        "name": "Test User"
      }
    ],
    "subject": "Test Successful Delivery",
    "text_content": "This email will simulate successful delivery.",
    "sandbox": true,
    "sandbox_result": "deliver"
  }
  ```

  ```json Bounce Simulation theme={null}
  {
    "from": {
      "email": "hello@yourdomain.com",
      "name": "Your Company"
    },
    "recipients": [
      {
        "email": "test@example.com",
        "name": "Test User"
      }
    ],
    "subject": "Test Bounce Handling",
    "text_content": "This email will simulate a bounce for testing.",
    "sandbox": true,
    "sandbox_result": "bounce"
  }
  ```

  ```json Deferral Testing theme={null}
  {
    "from": {
      "email": "hello@yourdomain.com",
      "name": "Your Company"
    },
    "recipients": [
      {
        "email": "test@example.com",
        "name": "Test User"
      }
    ],
    "subject": "Test Deferral Handling",
    "html_content": "<h1>Deferral Test</h1><p>Testing deferral simulation.</p>",
    "text_content": "Testing deferral simulation.",
    "sandbox": true,
    "sandbox_result": "defer"
  }
  ```

  ```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"
  }
  ```
</CodeGroup>

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

## Testing Webhooks

Sandbox mode is perfect for testing webhook integrations with API v2:

<AccordionGroup>
  <Accordion title="Webhook Events Still Fire" icon="webhook">
    * 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
  </Accordion>

  <Accordion title="Test Different Scenarios" icon="list-check">
    Use `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
  </Accordion>

  <Accordion title="Safe Integration Testing" icon="shield-check">
    * Test webhook endpoints without affecting real users
    * Validate webhook signature verification
    * Test error handling and retry mechanisms
    * Ensure proper event processing in your application
  </Accordion>
</AccordionGroup>

## Advanced Features

API v2 sandbox mode supports advanced features for comprehensive testing:

<AccordionGroup>
  <Accordion title="Bulk Operations" icon="layer-group">
    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>

  <Accordion title="Scheduled Sending" icon="clock">
    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": "2024-12-25T10:30:00Z"
      },
      "sandbox": true
    }
    ```
  </Accordion>

  <Accordion title="Template Variables" icon="code">
    Test complex template substitutions:

    ```json theme={null}
    {
      "from": {
        "email": "hello@yourdomain.com",
        "name": "Your Company"
      },
      "recipients": [
        {
          "email": "test@example.com",
          "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
    }
    ```
  </Accordion>
</AccordionGroup>

## Benefits

<CardGroup cols={3}>
  <Card title="Cost-Free" icon="piggy-bank">
    No credit usage regardless of volume sent in sandbox mode
  </Card>

  <Card title="Safe Testing" icon="shield">
    Never accidentally email real users during development
  </Card>

  <Card title="Realistic Simulation" icon="microscope">
    Full processing pipeline without actual delivery
  </Card>

  <Card title="Webhook Testing" icon="webhook">
    Complete event simulation for integration testing
  </Card>

  <Card title="Flexible Control" icon="sliders">
    Multiple ways to enable and control sandbox behavior
  </Card>

  <Card title="CI/CD Ready" icon="robot">
    Perfect for automated testing pipelines
  </Card>
</CardGroup>