Custom SMTP Headers

Custom SMTP headers let you attach additional metadata to every outbound email notification sent from Chargebee. These headers are useful for tracking, filtering, routing, and integrating with downstream email analytics systems.

Use Cases

Custom headers are commonly used for:

• Email tracking and analytics: Tag emails with campaign or category identifiers so your analytics platform can group and report on them (e.g., X-Email-Category: dunning).
• Routing and filtering: Add metadata that your email gateway or inbox rules can act on (e.g., X-Priority-Level: high).
• Compliance and audit: Stamp emails with internal identifiers for audit trails (e.g., X-Audit-Ref: inv-20260423).
• Downstream integrations: Pass context to third-party systems such as CRMs or ticketing tools that parse inbound email headers.

Prerequisites

Before configuring custom SMTP headers, ensure you have:

• Admin or equivalent permissions in Chargebee (Configure Chargebee role)

Configuring Custom Headers

Step 1: Navigate to SMTP Settings

1. Go to Settings > Configure Chargebee > Email Notifications
2. Scroll down to the Custom SMTP Headers section below your SMTP configuration
3. Click on Configure Custom Headers

Step 2: Add Headers

Each header is a name-value pair. To add a header:

1. Enter the Header Name — must start with the X- prefix (e.g., X-Campaign-ID)
2. Enter the Header Value — the value that will be included in every outbound email (e.g., chargebee-billing)
3. Click Add header to add more rows (up to the maximum allowed)
4. Click Confirm to persist your headers

A success notification confirms that the headers have been saved.

Step 3: Verify Headers

After saving, you can verify that your custom headers are being applied by:

1. Triggering a test email notification from Chargebee
2. Inspecting the email headers in your email client (most clients have a "View original" or "Show headers" option)
3. Confirming that the custom headers appear in the raw email source

Header Rules and Limits

Custom headers are validated against the following rules:

Reserved Headers

Certain headers are reserved and cannot be used as custom header names. These include:

• Standard email headers: From, To, CC, BCC, Subject, Date, Message-ID, Reply-To, Return-Path, MIME-Version, Content-Type, Content-Transfer-Encoding, Content-Disposition
• Trace and routing headers: Received, X-Received, Delivered-To, X-Forwarded-To, X-Forwarded-For, X-Originating-IP
• Authentication headers: DKIM-Signature, Authentication-Results, Received-SPF, ARC-Seal, ARC-Message-Signature, ARC-Authentication-Results
• Client and priority headers: X-Mailer, X-Priority
• Provider-specific headers: X-SMTPAPI (SendGrid), X-Mailgun-Tag, X-Mailgun-Variables, X-Mailgun-Track-Opens, X-Mailgun-SID, X-Mailgun-Sending-IP, X-MC-Tags (Mandrill), X-Mailjet-Campaign
• Chargebee internal headers: Any header starting with X-Chargebee (including X-Chargebee-*)
• Resent headers: Any header starting with Resent (e.g., Resent-From, Resent-To)

Managing Custom Headers

Editing Headers

To update an existing header:

1. Modify the Header Name or Header Value in the respective field
2. Click Confirm to apply the changes

Changes take effect for all emails sent after saving.

Removing Headers

To remove a header:

1. Click the trash icon next to the header row you want to remove
2. Click Confirm to persist the change

Validation Errors

Chargebee validates each header when you save. If any header fails validation, the specific error is displayed inline below the affected field.

Common validation errors include:

How It Works

When custom SMTP headers are configured:

1. On save: Headers are validated against naming rules, length limits, and the reserved list. Valid headers are stored with normalized (lowercased) names.
2. On email send: When Chargebee sends an email notification, the stored custom headers are read and appended to the email's MIME headers before delivery.
3. Conflict resolution: If a custom header name matches a header already present on the email (set by the email provider or Chargebee), the custom header is skipped for that email to prevent conflicts.

Frequently Asked Questions (FAQs)

1. Are custom headers applied to emails sent through Chargebee's default SMTP server?

Yes. Custom headers are applied to all outbound email notifications, regardless of whether you use Chargebee's built-in SMTP server or your own.

2. Can I use custom headers to override standard email headers like From or Reply-To?

No. Standard email headers and provider-specific headers are reserved and cannot be overridden. Custom headers must use the X- prefix and cannot conflict with reserved names.

3. When do header changes take effect?

Changes take effect immediately for all emails sent after the save action. There is no delay or propagation period.

4. Can I set different headers for different notification types?

No. Custom SMTP headers are applied uniformly to all outbound email notifications. They cannot be configured per notification type or per customer.

5. Do custom headers affect email deliverability?

Custom X- headers generally do not affect deliverability. However, adding excessively large or numerous headers could impact email size. Stay within the recommended limits to avoid issues.

6. How do I check if my custom headers are being applied?

Send a test email and inspect its raw headers. In most email clients, you can view the original message source to see all MIME headers, including your custom ones.

7. Why is my header name being converted to lowercase?

Email header names are case-insensitive per RFC 2616. Chargebee normalizes all header names to lowercase for consistent storage and duplicate detection. The email standard ensures that recipients treat X-Campaign-ID and x-campaign-id identically.

Related Articles

• SMTP Configuration Overview - Overview of SMTP options
• Basic Authentication - Configure username/password SMTP
• OAuth Authentication - Configure OAuth for Microsoft 365 and Google
• Email Notifications - Learn about email notification types
• Email Logs - Monitor your email delivery