Sandbox Credentials

As developers and testers, we know how important it is to test your email sending setup thoroughly before sending emails to real customers. You need to make sure your code connects correctly, your templates look right, and your webhook integrations are working as expected. But sending test emails over and over can clutter inboxes, potentially bother recipients, and even use up your sending credits.

That's where AhaSend's new Sandbox mode comes in. Sandbox mode lets you simulate sending emails without actually delivering them to the recipient. It's a safe, cost-free way to test your integration and ensure everything is working perfectly before you go live. When you send an email in Sandbox mode, AhaSend processes it just like a real email, triggering webhooks and showing up in your logs, but it stops short of trying to deliver it. This makes it ideal for development, staging, and testing environments.

Sandbox messages are completely free. They don't count towards your monthly email credits, so you can test as much as you need without worrying about your bill. This feature is designed to give you peace of mind and a reliable way to build and refine your email sending logic.

There are a couple of ways to use Sandbox mode: you can create specific credentials just for sandbox testing, or you can use your existing production credentials and add a special instruction to tell AhaSend to process the email in sandbox mode. Both methods are easy to set up and use, giving you flexibility depending on your testing needs. Let's look at how you can start using this powerful feature.

Creating Dedicated Sandbox Credentials

One way to use Sandbox mode is to create credentials specifically for this purpose. These credentials will always operate in Sandbox mode, meaning any email sent using them will be simulated and never actually delivered. This is a great option if you have separate environments for development or testing and want to ensure that no real emails are accidentally sent from those environments.

Creating a sandbox credential is very similar to creating a standard production credential. You'll do this directly from your AhaSend dashboard.

1. Log in to your AhaSend Dashboard.
2. Navigate to the Credentials tab. This is where you manage all your SMTP and API Key credentials.
3. Click on the Create Credential button. This will open a form where you can set up your new credential.
4. Choose the Type of credential you want to create, either SMTP or API Key.
5. Give your credential a descriptive Name. Something like "Development Sandbox SMTP" or "Testing API Key Sandbox" is helpful so you know its purpose later.

6. Here's the key step: Check the box labeled Sandbox. This tells AhaSend that this credential should only be used for simulated sending.

   

7. Click the Create Credential button at the bottom of the form.

AhaSend will then generate your new sandbox credential (username and password for SMTP, or the API Key). You can use these credentials in your development or testing environment just like you would use production credentials. Any email sent using these credentials will automatically be processed in Sandbox mode.

Using dedicated sandbox credentials helps prevent accidental sends from your testing setups. It's a clear separation between your test environment and your live production environment. Remember that even though these are sandbox credentials, you should still treat them securely, just like you would your production keys or passwords.

Changing an Existing Credential's Mode

What if you already have credentials set up and want to switch them between Sandbox and Production mode? AhaSend allows you to easily change the mode of an existing credential directly from the dashboard. This is useful if you have a credential that you might use for both testing and occasional production sending, or if you initially created a production credential but now want to use it only for sandbox testing, or vice versa.

To change the mode of an existing credential:

1. Log in to your AhaSend Dashboard.
2. Go to the Credentials tab.
3. Find the credential you want to modify in the list.
4. Click on the credential's name or an "Edit" option associated with it. This will open the details and editing form for that specific credential.
5. Look for the Mode field.

6. From the dropdown menu or options next to the Mode field, select either Sandbox or Production, depending on how you want this credential to behave.

   

7. Click the Save Changes button to update the credential's setting.

Once you save the change, that credential will immediately start operating in the selected mode. If you switch a production credential to Sandbox, emails sent with it will be simulated. If you switch a sandbox credential to Production, emails sent with it will be delivered normally (assuming your domain is set up correctly). This flexibility allows you to adapt your credentials to your current needs without having to create new ones constantly.

It's important to be mindful of the credential's mode when you are using it. Sending with a Production credential will use credits and attempt delivery, while sending with a Sandbox credential will not. Double-checking the mode is a good practice, especially if you are switching them often.

Using Production Credentials in Sandbox Mode

Sometimes you might want to test your sending logic using your actual production credentials, perhaps to minimize configuration changes in your application or to test a specific flow that uses that credential. AhaSend allows you to send emails in Sandbox mode even when using a production credential. You can do this by adding a special header to your email.

This method is particularly useful for one-off tests or for developers who are testing directly from their code editor or command line using existing setup without changing the credential itself in the dashboard or application configuration.

To activate Sandbox mode using a production credential, you need to include the AhaSend-Sandbox header in your email message.

• For SMTP, you would add this as a standard email header, just like Subject or From.
• For the API, you would include this as a custom header in your content.headers part of the JSON API payload.

The header should be included with a value of either true or 1.

For SMTP:

When sending via SMTP, you would add this header like any other email header (like Subject, From, To, etc.). The exact method depends on your email library or client, but conceptually it looks like this:

From: [email protected]
To: [email protected]
Subject: Test Email
AhaSend-Sandbox: true
Content-Type: text/plain
This is a test email sent in Sandbox mode.

Your SMTP client or library will handle adding these headers to the message data sent to AhaSend.

For API:

When sending via the API, you include the AhaSend-Sandbox email header in the content.headers part of your email payload. Please note that this is not an email header, not an HTTP header.

Using a tool like curl, it would look like this:

curl https://api.ahasend.com/v1/email/send \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'X-Api-Key: YOUR-PRODUCTION-API-KEY' \
    -d '{
        "from": {
            "name": "My App",
            "email": "[email protected]"
        },
        "recipients": [
            {
                "name": "Test User",
                "email": "[email protected]"
            }
        ],
        "content": {
            "subject": "API Sandbox Test",
            "text_body": "Testing API send in sandbox mode.",
            "headers": {
            	"AhaSend-Sandbox": "true"
            }
        }
    }'

When AhaSend receives a message with the AhaSend-Sandbox: true email header, it will process it as if it were sent using a Sandbox credential, regardless of the credential type used for authentication.

Using this header gives you fine-grained control, allowing you to switch individual email sends between production and sandbox behavior on the fly, without changing the credential configuration itself.

Controlling the Simulated Outcome

When you send an email in Sandbox mode, by default, AhaSend simulates a successful delivery. This is useful for testing the happy path of your application. However, in real-world scenarios, emails can bounce, be deferred, fail, or be suppressed. To help you test how your application handles these different outcomes, Sandbox mode allows you to specify the simulated result using another special header: AhaSend-Sandbox-Result.

By adding the AhaSend-Sandbox-Result email header, you can tell AhaSend to simulate a specific outcome for that particular sandbox message. This header can be used with dedicated sandbox credentials or when using a production credential with the AhaSend-Sandbox: true header.

The possible values for the AhaSend-Sandbox-Result header are:

• deliver: Simulates a successful delivery (this is the default if the header is not included).
• bounce: Simulates a hard bounce.
• defer: Simulates a temporary delivery deferral.
• fail: Simulates a permanent delivery failure for a reason other than a bounce (e.g., block).
• suppress: Simulates the email being suppressed (e.g., recipient is on a suppression list).

Here's how you would include this header:

AhaSend-Sandbox-Result: bounce

or

AhaSend-Sandbox-Result: defer

...and so on for the other values.

By using this email header, you can effectively test how your application processes different email statuses. For example, you can simulate a bounce to see if your application correctly updates a user's status or triggers a notification. You can simulate a deferral to test your retry logic. You can simulate a suppression to see if your system recognizes that the email wasn't sent due to a suppression list entry.

Example using SMTP with AhaSend-Sandbox-Result:

From: [email protected]
To: [email protected]
Subject: Test Bounce
AhaSend-Sandbox: true
AhaSend-Sandbox-Result: bounce
Content-Type: text/plain
This email is designed to simulate a bounce in sandbox mode.

Example using API with AhaSend-Sandbox-Result:

curl https://api.ahasend.com/v1/email/send \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'X-Api-Key: YOUR-API-KEY' \
    -d '{
        "from": {
            "name": "My App",
            "email": "[email protected]"
        },
        "recipients": [
            {
                "name": "Test User",
                "email": "[email protected]"
            }
        ],
        "content": {
            "subject": "API Sandbox Defer Test",
            "text_body": "Testing API send and simulating a deferral.",
            "headers": {
            	"AhaSend-Sandbox": "true",
            	"AhaSend-Sandbox-Result": "defer"
            }
        }
    }'

By using these email headers, you can thoroughly test how your system reacts to various potential outcomes without affecting your reputation or billing.

Benefits of Using Sandbox Mode

Using AhaSend's Sandbox mode offers several significant benefits for anyone integrating email sending into their application:

• Cost-Free Testing: Sandbox messages do not consume your email credits. You can send as many test emails as you need during development and testing cycles without impacting your billing.
• Safe Testing: Emails sent in Sandbox mode are never actually delivered to recipients. This prevents accidental emails from reaching real users during development, staging, or automated testing, avoiding confusion or spam complaints.
• Realistic Simulation: Sandbox mode processes emails much like production, including parsing, validation, and triggering events. This gives you a realistic test environment without the risks of live sending.
• Webhook Testing: Emails sent through Sandbox mode do trigger webhooks. This is a critical feature for testing your webhook integration logic. You can simulate different delivery outcomes (deliver, bounce, defer, fail, suppress) using the AhaSend-Sandbox-Result header and verify that your webhook endpoint receives the correct event payloads and that your application processes them correctly. This allows you to fully test your event handling for various scenarios. You can learn more about Using webhooks to receive real-time system and email events in our help center.
• Development Efficiency: Developers can quickly test changes to email content, templates, or sending logic without waiting for actual delivery or worrying about cleanup. The ability to force specific outcomes speeds up the development of error handling and status tracking.
• Automated Testing: Sandbox mode is perfect for integration tests and end-to-end tests in your continuous integration (CI) pipeline. You can automate sending test emails and verifying webhook events without relying on external email services or dummy email addresses that might have sending limits or spam filters.

By providing a dedicated environment for testing, Sandbox mode helps you build more reliable and robust email features in your application. It reduces the friction associated with testing email sending and integration, allowing you to iterate faster and deploy with confidence.