Special Email Headers

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.

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

Tracking Control

Override open and click tracking settings for individual emails

Sandbox Testing

Control sandbox mode behavior and simulated outcomes

Data Retention

Customize data retention policies per email

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.

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.

Open Tracking Header

Header: ahasend-track-opens
Values: true | false
Purpose: Enable or disable open tracking for individual emails

SMTP Example

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

Click Tracking Requirements: Your account must be manually verified to use click tracking. Only HTML emails with http:// and https:// links are supported.

SMTP Example

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:

<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

SMTP Example

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

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

SMTP Example

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.

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:

Message Metadata & Delivery Log Retention

Header: ahasend-metadata-retention
Values: 1-30 days
Purpose: Control how long metadata and delivery logs are retainedIncludes delivery status, timestamps, recipient information, and tracking data.

Message Data Retention

Header: ahasend-data-retention
Values: 0-30 days
Purpose: Control how long the actual email content is retainedIncludes email body, attachments, and complete message content. Set to 0 for immediate deletion after processing.

Retention Examples

SMTP Example

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

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

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

SMTP Example

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

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

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:

SMTP Example

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

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

Sandbox Headers

AhaSend-Sandbox: true | 1 - Enable sandbox mode
AhaSend-Sandbox-Result: deliver | bounce | defer | fail | suppress - Control simulated outcome

Data Management Headers

ahasend-metadata-retention: Number (1-30) - Metadata & delivery log retention in days
ahasend-data-retention: Number (0-30) - Email content retention in days
ahasend-tags: Comma-separated list - Message tags (max 10 tags, 64 chars each)

Important Notes

Header Processing

🗸 All AhaSend headers are removed before delivery
🗸 Recipients never see these special headers
🗸 Headers only affect AhaSend’s processing behavior

Priority & Overrides

🗸 Per-email headers override account settings
🗸 Headers take effect immediately
🗸 Sandbox headers work with any credential type

Getting Started

Sending with SMTP

Sending with the API

Email Tracking

Integrations

Data Retention

Security

Scaling up

Special Email Headers

Available Special Headers

Tracking Control

Sandbox Testing

Data Retention

Message Tagging

Tracking Headers

Open Tracking Header

Click Tracking Header

Excluding Individual Links

Sandbox Headers

Sandbox Mode Header

Sandbox Result Header

Retention Headers

Message Retention Headers

Retention Examples

Retention Use Cases

High Security

Message Tags Header

Tag Usage Examples

Tag Best Practices

Combining Headers

Header Reference Summary

Important Notes

Header Processing

Priority & Overrides

​Available Special Headers

Tracking Control

Sandbox Testing

Data Retention

Message Tagging

​Tracking Headers

​Open Tracking Header

​Click Tracking Header

​Excluding Individual Links

​Sandbox Headers

​Sandbox Mode Header

​Sandbox Result Header

​Retention Headers

​Message Retention Headers

​Retention Examples

​Retention Use Cases

High Security

​Message Tags Header

​Tag Usage Examples

​Tag Best Practices

​Combining Headers

​Header Reference Summary

​Important Notes

Header Processing

Priority & Overrides

Available Special Headers

Tracking Headers

Open Tracking Header

Click Tracking Header

Excluding Individual Links

Sandbox Headers

Sandbox Mode Header

Sandbox Result Header

Retention Headers

Message Retention Headers

Retention Examples

Retention Use Cases

Message Tags Header

Tag Usage Examples

Tag Best Practices

Combining Headers

Header Reference Summary

Important Notes