Adding custom SMTP headers in your desktop email program

If you use a desktop email client to create emails to be sent through Mandrill, one thing you might be missing out on is the ability to use a template or specify some custom options for the emails that you're sending. Mandrill has an awesome SMTP headers API so you can add all kinds of goodies to your emails, but desktop email clients don't generally make it simple to add these custom headers. With a little bit of wrangling, though, you'll be off and running. Below I'll show you how you can add these for a couple of popular email programs.


Thunderbird is an awesome open source email client available in a variety of languages and for Mac, Windows and Linux. If you use (or want to use) Thunderbird, it's pretty darn easy to set things up to add custom SMTP headers. Here's how:

In the Preferences window (Tools > Options on Windows; Thunderbird > Preferences on a Mac), choose 'Advanced' and then make sure you're in the 'General' section. Click the 'Config Editor...' button which should bring up the configuration editor.

Thunderbird Advanced Pane

In the search bar, type mail.compose.other.header, and then double click the preference name that appears.

Thunderbird config editor

Now you just need to decide which headers you'll want to be able to set when composing a message in Thunderbird. Once you've decided, enter those headers, separated by commas for the value of the mail.compose.other.header preferences. For example, if you want to be able to specify a template and add Google Analytics parameters to links for your own website for each email, type X-MC-Template,X-MC-GoogleAnalytics.

Which Headers?

Click OK and close the configuration editor.

After you restart Thunderbird, when you compose a message, you'll now have the option to specify values for the X-MC-Template and X-MC-GoogleAnalytics headers.

New Header Options

In this example, my template named 'CompanyLogo' will be used, and any links that start with '' will have Google Analytics parameters added to the link automatically so I can see in Google Analytics that someone visited my page from a transactional email.

Compose Message

Mac Mail (

With a few quick terminal commands, you can specify custom headers to be added to your emails. First, you'll want to check whether any custom headers have already been added:

$ defaults read UserHeaders

If this command returns a message like this, no headers have been added yet:

The domain/default pair of (/Users/username/Library/Preferences/, UserHeaders) does not exist

If the defaults read command above returns something that starts with { and ends with }, copy that line so you can include the existing data when you add new information.

Now you'll want to write the custom headers information; if you already had custom headers set up and want to preserve those options, make sure to include them in between the { and } brackets. Each header should have a semicolon at the end:

$ defaults write UserHeaders '{"Header_Name1" = "Header_value1"; "Header_Name2" = "Header_value2";}'

Here's an example if you want to specify a template named CompanyLogo (that has an mc:edit section by the name of 'main' where you want your email contents to go) and tag your messages with the tag InquiryResponse:

$ defaults write UserHeaders '{"X-MC-Template" = "CompanyLogo"; "X-MC-Tags" = "InquiryResponse";}'

To delete all the custom headers you've added, you can use this command:

$ defaults delete UserHeaders

Other Email Clients

Other email programs may also allow customizing the headers for emails you send. Feel free to share in the comments if you've got a cool, nerdy, or interesting method for customizing the headers when working with a particular email program!