Menu
 

Set custom email headers

Email headers specify specific sending and return options for an email. When sending via SMTP, you can use custom headers to do a great many things: customize messages, tag them, track them, or control specific behaviors.

For example:

  • Set the X-Mailgun-Tag header if you’re using Mailgun’s “Topic” subscription functionality
  • Set your own List-Unsubscribe header for specific emails (if you use our unsubscribe link, we add this header automatically)
  • Stop emails from being shown as a thread by Gmail with the X-Entity-Ref-ID header
  • Use X-Auto-Response-Suppress:OOF to suppress auto-replies from Exchange servers

Adding, editing, and removing custom headers

You’ll find the custom headers option in the email composer, and you can add and remove them easily:

Adding and removing headers

Errors

There are a few guidelines:

  • You can add up to four custom headers at a time, in addition to Reply-to, BCC, and Subject.
  • Your header’s name can’t be blank, but the value can be.
  • There are some headers you can’t use (see “Blacklisted headers” below)
  • You can use Liquid here! If there are errors, you’ll see them in the ‘Review Errors’ modal.

When there’s a problem with your headers, our ‘Review Errors’ button animates:

Review errors animation

And we show you an indicator on the relevant header.

Error indicator

Then, you can review your errors in the resulting modal: It looks like this:

Error with custom headers

If you’re concerned about how to deal with a specific error here, you should be able to find it in our our Composer Errors documentation.

Blacklisted headers

There are some headers that we need to keep control of at Customer.io:

  • Message data such as Subject or To
  • MIME headers which dictate email formatting, as well as Return Path information (Received or Return-Path): these are generated by our servers at time of delivery
  • Mail client information tags, such as X-Mailer: Customer.io needs to set X-Mailer and X-Report-Abuse-To, to allow receiving services to notify us of bad Authentication-Results
  • Provider-specific tags like X-MC-Metadata (Mandrill), X-Mailgun-Dkim (Mailgun), or X-SMTPAPI (Sendgrid): we need these to ensure tracking and deliverability.

The full list:

Message data MIME Return Path Information Client-specific Provider-specific
Message-ID Mime-Version Received Mail-System-Version X-SMTPAPI
Date Content-ID Return-Path Mailer X-Mailgun-Variables
From Content-Base Authentication-Results Originating-Client X-Mailgun-Dkim
Subject Content-Alias Received-SPF X-Mailer X-Mailgun-Track-Opens
To Content-Identifier Auto-Submitted X-Report-Abuse-To X-Mailgun-Track-Clicks
Reply-To Content-Length VBR-Info   X-MC-Metadata
CC Lines      
  Content-Type      
  Content-Disposition      
  Content-Transfer-Encoding      
  Encoding      

Feedback?

This is a fairly advanced feature, and we want to make it as useful as possible, and help you better track and customize your emails. If you have any questions or feedback on this feature, please let us know!