Skip to main content
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: [email protected]
To: [email protected]
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: [email protected]
To: [email protected]
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>
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: [email protected]
To: [email protected]
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
  • 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: [email protected]
To: [email protected]
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:
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.
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: [email protected]
To: [email protected]
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: [email protected]
To: [email protected]
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

  • 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
  • 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: [email protected]
To: [email protected]
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

  • 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
  • AhaSend-Sandbox: true | 1 - Enable sandbox mode
  • AhaSend-Sandbox-Result: deliver | bounce | defer | fail | suppress - Control simulated outcome
  • 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