> ## 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.

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# SMTP Headers for Tracking, Tags and Sandbox

> Reference for AhaSend custom SMTP headers for open and click tracking, tags, retention and sandbox mode, with accepted values and limits.

AhaSend supports special email headers that allow you to override default settings and customize email behavior on a per-message basis. These headers give you fine-grained control over tracking, testing, data retention, and message organization without changing your account-wide settings.

Available on Free, Pro and Max. See [plans and features](https://ahasend.com/docs/facts.md#plans-and-features).

> [!NOTE]
>
> **Header Usage:** All AhaSend special headers are removed before email delivery and are never visible to recipients. They're used only to control AhaSend's processing behavior.

## Available Special Headers

> [card] Tracking Control
>
> Override open and click tracking settings for individual emails

> [card] Sandbox Testing
>
> Control sandbox mode behavior and simulated outcomes

> [card] Data Retention
>
> Customize data retention policies per email

> [card] Message Tagging
>
> Add custom tags for organization and filtering

## Tracking Headers

Control email tracking behavior on a per-message basis, overriding your account-wide settings.

> [!WARNING]
>
> **Privacy Considerations:** Email tracking has privacy implications. Many email clients block remote content loading, and some providers prefetch content, which can lead to inaccurate tracking results.

Header names are case-insensitive. This page uses `AhaSend-` casing for readability.

## Open Tracking Header

**Header:** `ahasend-track-opens`\

**Values:** `true` | `false`\

**Purpose:** Enable or disable open tracking for individual emails

> [!NOTE]
>
> **Open Tracking Requirements:** The sending domain's tracking domain must be set up, or the message is sent without tracking. Only HTML emails are supported.

```plaintext SMTP Example theme={null}
From: hello@yourdomain.com
To: user@example.com
Subject: Newsletter
ahasend-track-opens: true
Content-Type: text/html

<html>
<body>
<h1>Your Newsletter</h1>
<p>This email will track opens even if account-wide tracking is disabled.</p>
</body>
</html>
```

### Click Tracking Header

**Header:** `ahasend-track-clicks`\

**Values:** `true` | `false`\

**Purpose:** Enable or disable click tracking for individual emails

> [!NOTE]
>
> **Click Tracking Requirements:** The sending domain's tracking domain must be set up, or the message is sent without tracking. Only HTML emails with `http://` and `https://` links are supported.

```plaintext SMTP Example theme={null}
From: hello@yourdomain.com
To: user@example.com
Subject: Product Update
ahasend-track-clicks: true
Content-Type: text/html

<html>
<body>
<h1>New Product Features</h1>
<p>Check out our <a href="https://example.com/features">latest features</a>!</p>
<p>Excluded link: <a href="https://example.com/unsubscribe" data-as-no-track>Unsubscribe</a></p>
</body>
</html>
```

### Excluding Individual Links

To exclude specific links from click tracking while keeping it enabled for the email, add the `data-as-no-track` attribute:

```html theme={null}
<a href="https://example.com/unsubscribe" data-as-no-track>Unsubscribe</a>
```

## Sandbox Headers

Control sandbox mode behavior for testing without affecting real email delivery.

### Sandbox Mode Header

**Header:** `AhaSend-Sandbox`\

**Values:** `true` | `1`\

**Purpose:** Enable sandbox mode for individual emails, even with production credentials

```plaintext SMTP Example 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 and not delivered.
```

### Sandbox Result Header

**Header:** `AhaSend-Sandbox-Result`\

**Values:** `deliver` | `bounce` | `defer` | `fail` | `suppress`\

**Purpose:** Control the simulated outcome for sandbox emails

> [accordion] Available Outcomes
>
> * **`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

```plaintext SMTP Example theme={null}
From: hello@yourdomain.com
To: test@example.com
Subject: Bounce Test
AhaSend-Sandbox: true
AhaSend-Sandbox-Result: bounce
Content-Type: text/plain

This email will simulate a bounce for testing error handling.
```

Header names are case-insensitive. See the [SMTP language examples](https://ahasend.com/docs/smtp.md) for setting them in your library.

## Retention Headers

Customize data retention policies for individual emails, overriding your account defaults.

### Message Retention Headers

AhaSend provides two types of retention control for different aspects of your email data:

> [accordion] Message Metadata & Delivery Log Retention
>
> **Header:** `ahasend-metadata-retention`\\
>
> **Values:** 1 day to your [plan's maximum](https://ahasend.com/docs/retention.md)\\
>
> **Purpose:** Control how long metadata and delivery logs are retained
>
> Includes delivery status, timestamps, recipient information, and tracking data.

> [accordion] Message Data Retention
>
> **Header:** `ahasend-data-retention`\\
>
> **Values:** Within your [plan's range](https://ahasend.com/docs/retention.md); 0 needs approval\\
>
> **Purpose:** Control how long the actual email content is retained
>
> Includes email body, attachments, and complete message content. Set to 0 for immediate deletion after processing.

### Retention Examples

```plaintext SMTP Example theme={null}
From: hello@yourdomain.com
To: user@example.com
Subject: Sensitive Document
ahasend-metadata-retention: 7
ahasend-data-retention: 0
Content-Type: text/plain

This email's metadata will be retained for 7 days, but content will be deleted immediately after processing.
```

### Retention Use Cases

> [card] High Security
>
> For emails containing sensitive data you can disable data retention to prevent it from being stored in our database:
>
> * `ahasend-metadata-retention`: 1-3 days
> * `ahasend-data-retention`: 0 days
>
> **Use for:** Sensitive communications, financial data, personal information

## Message Tags Header

Add custom tags to emails for organization, filtering, and analytics.

**Header:** `ahasend-tags`\

**Format:** Comma-separated list of tags\

**Limits:**\


* Maximum 10 tags per email
* Each tag maximum 64 characters
* Tags are case-sensitive

> [!TIP]
>
> **Pro Tip:** Use tags consistently across your emails to build powerful filtering and analytics. Start with basic categories like email type and campaign, then expand based on your tracking needs.

### Tag Usage Examples

```plaintext SMTP Example theme={null}
From: hello@yourdomain.com
To: user@example.com
Subject: Welcome Email
ahasend-tags: welcome,onboarding,new-user
Content-Type: text/html

<html>
<body>
<h1>Welcome to our platform!</h1>
<p>Get started with your account setup.</p>
</body>
</html>
```

### Tag Best Practices

> [accordion] Naming Conventions
>
> * Use lowercase with hyphens: `welcome-series`, `product-update`
> * Be descriptive: `password-reset` vs `reset`
> * Use consistent naming across campaigns
> * Consider hierarchical tags: `email-type:welcome`, `campaign:q1-2024`

> [accordion] Organization Strategies
>
> * **Campaign tracking:** `campaign:black-friday`, `campaign:welcome-series`
> * **Email types:** `transactional`, `marketing`, `notification`
> * **User segments:** `premium-users`, `trial-users`, `enterprise`
> * **Content categories:** `product-updates`, `security-alerts`, `newsletters`

## Combining Headers

You can use multiple special headers together for comprehensive email customization:

```plaintext SMTP Example theme={null}
From: hello@yourdomain.com
To: test@example.com
Subject: Comprehensive Test
AhaSend-Sandbox: true
AhaSend-Sandbox-Result: deliver
ahasend-track-opens: true
ahasend-track-clicks: false
ahasend-tags: test,integration,staging
ahasend-metadata-retention: 3
ahasend-data-retention: 1
Content-Type: text/html

<html>
<body>
<h1>Test Email</h1>
<p>This email combines multiple headers for comprehensive testing.</p>
<a href="https://example.com">Test Link</a>
</body>
</html>
```

## Header Reference Summary

> [accordion] Tracking Headers
>
> * `ahasend-track-opens`: `true` | `false` - Control open tracking
> * `ahasend-track-clicks`: `true` | `false` - Control click tracking
> * Use `data-as-no-track` attribute to exclude individual links from click tracking

> [accordion] Sandbox Headers
>
> * `AhaSend-Sandbox`: `true` | `1` - Enable sandbox mode
> * `AhaSend-Sandbox-Result`: `deliver` | `bounce` | `defer` | `fail` | `suppress` - Control simulated outcome

> [accordion] Data Management Headers
>
> * `ahasend-metadata-retention`: Integer within your plan's range - metadata and delivery log retention in days
> * `ahasend-data-retention`: Integer within your plan's range - email content retention in days; 0 needs approval
> * `ahasend-tags`: Comma-separated list - Message tags (max 10 tags, 64 chars each)

## Important Notes

> [card] Header Processing
>
> 🗸 All AhaSend headers are removed before delivery\\
>
> 🗸 Recipients never see these special headers\\
>
> 🗸 Headers only affect AhaSend's processing behavior

> [card] Priority & Overrides
>
> 🗸 Per-email headers override account settings\\
>
> 🗸 Headers take effect immediately\\
>
> 🗸 Sandbox headers work with any credential type

## Related Guides

* [Domain setup](https://ahasend.com/docs/domains.md), [SMTP credentials](https://ahasend.com/docs/smtp/credentials.md), [SMTP settings](https://ahasend.com/docs/smtp.md).
* [Sandbox mode](https://ahasend.com/docs/send-api/sandbox.md), [Retention](https://ahasend.com/docs/retention.md), [API sending](https://ahasend.com/docs/send-api/send-email.md).
* [SMTP CLI](https://ahasend.com/docs/cli/commands/smtp.md), [Node.js SDK](https://ahasend.com/docs/guides/nodejs-sdk.md), [Go SDK](https://ahasend.com/docs/guides/go-sdk.md).
* [Plans and limits](https://ahasend.com/docs/facts.md), [Tracking setup](https://ahasend.com/docs/tracking/open-tracking.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.