List Unsubscribe Header: Why and How to Use

In 2003, a new law concerning email was passed in the United States. Called CAN-SPAM, this law gave email recipients the right to stop receiving the bulk email messages they didn’t want. In turn, CAN-SPAM obligated email senders to implement opt-out mechanisms for all of their bulk email. In this article, we will discuss a native unsubscribe option, list-unsubscribe, and explain why and how to use it.

Update: We revisited this article in late 2023 and the tips provided are as strong as ever particularly in the light of the 2024 sender requirement update from Google and Yahoo.

What is the list-unsubscribe header?

The official (according to RFC2369) list-unsubscribe definition is as follows:

The list-unsubscribe field describes the command (preferably using mail) to directly unsubscribe users by removing them from the list.

Simply put, this is an unsubscribe link or button displayed next to the email sender information. The header is an especially user-friendly place for the opt-out function because the reader doesn’t have to search through the body of the email text to find it. Here is how it looks in Gmail:

And this is the view from Apple Mail:

Why should I provide users with the unsubscribe header?

According to the aforementioned CAN-SPAM act, a marketer must include an unsubscribe option in the email. If it’s missing, spam filters most likely won’t let your email through. As a result, your intended recipients will never see your email at all. We touched upon this in detail in Why Emails Going to Spam and How to Prevent It. While common advice says that the smart marketer provides the opt-out link somewhere in the email body text, we ask: is this decision really that smart? Consider these benefits of an unsubscribe header.

Benefit#1: Having a list-unsubscribe option in the email header is not a call to unsubscribe from emails. In fact, it is proof of your confidence that this content is worth the reader’s attention. A waffling or coward marketer will try to hide the unsubscribe link in the text. A bold one is confident in their email message and puts all the cards on the table. Also, just the fact of having this list-unsubscribe header raises your credibility as a sender.

Benefit#2: Let’s say the recipient is considering unsubscribing. He or she may be too busy to search through the email to find the unsubscribe link, so he or she just clicks “Report as SPAM” to stop the emails from coming. This is the last thing any marketer wants to see happen. It negatively impacts sender reputation, requiring extra work to improve email deliverability. With the list-unsubscribe header, you will avoid getting into this kind of trouble in the first place.

Benefit#3: Imagine what happens when subscribers change activities, interests, or focus. As a result, they may no longer be interested in the products and services you offer. The emails they receive from you are now either ‘marked as read’ in their inbox or simply ignored. They neither click the spam reporting button nor attempt to find the unsubscribe link in the text. They are no longer your customers, but you don’t know it. This is a dead weight for your email campaigns, and you have to let them go. Here, the list-unsubscribe header is a release trigger. You will lose inert subscribers but will raise the engagement rate.

How it works: unsubscribe implementation methods

To implement the opt-out option in your email header, your email server must first be configured. For example, this is how to add the list-unsubscribe header to all outgoing emails using Postfix:

in /etc/postfix/main.cf, set header_checks to:

header_checks = regexp:/etc/postfix/list_unsub_header

create a list_unsub_header file in /etc/postfix/ and add the following:

/^Content-Transfer-Encoding:/i PREPEND List-Unsubscribe: mailto:<sender-email-address>?subject=unsubscribe>"

Restart Postfix it with

service postfix restart

/etc/init.d/postfix restart

Contact your email administrator to insert this option for your particular server. If you use an email service provider, you can ask them to insert the list-unsubscribe header into your email. Or you can do this yourself, using the ESP’s documentation. To accomplish this, you will have to choose between two types of unsubscribing methods: mailto and http.

Mailto

Mailto is the most commonly used method for implementing the list-unsubscribe header. When a user clicks the unsubscribe link, the mail client generates an email with unsubscribe request and sends it to a specified email address. You also need to process the request and unsubscribe this user. Here is the flow of setting up a mailto list-unsubscribe:

Create a dedicated email address for unsubscribe requests. For example, unsubscribe@example.com
Provide this email address to your email administrator or ESP and ask them to insert it into the email header. The following syntax should be used:

List-Unsubscribe: <mailto: unsubscribe@example.com?subject=unsubscribe>

With the mailto method, you have to manually unsubscribe the users.

Http or unsubscribe URL

With the http method, behind the list-unsubscribe header, there is a URL leading to a web page for opting out. When a user clicks the unsubscribe link, a landing page opens, and the user is asked to confirm unsubscription. Here is the flow of setting up an http list-unsubscribe:

Create a web page dedicated to unsubscribe requests. Both http: and https: are acceptable. For example, http://www.example.com/unsubscribe.html
Provide the unsubscribe URL to your email administrator or ESP, and ask them to insert it into the email header. It is best to use this method in conjunction with mailto because the recipient’s inbox client may not support http list-unsubscribe. That’s why it is advisable to use the following syntax:

List-Unsubscribe:  <mailto: unsubscribe@example.com?subject=unsubscribe>,  <http://www.example.com/unsubscribe.html>

Also, make sure a user does not need to enter credentials or select a checkbox to complete the unsubscription process.

One-click list-unsubscribe

From a user’s perspective, one-click functionality for the list-unsubscribe is awesome. It spares them the requirement of providing additional confirmation on a landing page. The unsubscribe decision is simply made with one click. From a marketer’s perspective, this option is a killer. On the landing page, users may change their mind and recall unsubscription.

However, in 2024 the one-click list-unsubscribe becomes a necessity. Going back to the most recent update mentioned in the intro, both Google and Yahoo state almost the same thing: “You shouldn’t have to jump through hoops to stop receiving unwanted messages from a particular email sender. It should take one click.” (Source: Google)

Which method should I choose?

“Both” is the best answer. Unfortunately, not all email clients support the http method. If you bet on using it alone, you run the risk of damaging your sender reputation. With mailto list-unsubscribe provided as an alternative, your sender reputation is better protected and your recipients are all able to accomplish the unsubscribe function.

Which email clients support list-unsubscribe header

Tools to check list-unsubscribe and spamminess of your emails

Let’s say, you’ve set up the list-unsubscribe header to you email campaign. Check out whether it works by sending an email to a test inbox. For Gmail, you’ll see the unsubscribe option in the header right next to the sender name. Also, you can verify headers in detail. For this, click the three dots near the Reply button and choose “Show original” in the dropdown menu.

You’ll see information about the main headers like Message-ID, To:, and others. List-unsubscribe won’t be there; you’ll need to search for it as well as for the method used (mailto, http or both). It may look like this:

List-Unsubscribe: <mailto:1sdfnlmksafldim4v4yy3jd4n\jf4ssf2sd3@sdf5.hubspotemail.net?subject=unsubscribe>

But you will probably not want to search through email headers when there are some great tools that can do this for you!

Mailtrap Email Sandbox

Mailtrap Email Sandbox is a safe email testing environment designed especially for developers. With the Sandbox, you can catch any outgoing SMTP traffic and analyze it for spam. The spam analysis report is verified through an integrated Apache SpamAssassin filter and helps you understand what elements of an email need to be changed or corrected for a better spam score.

Additionally, in the Spam Analysys tab, your IP address is checked against the most popular DNS blacklists and alerts in case it appears in any.

For more on what else you can do with Mailtrap Email Sandbox, read the Gett i ng Started Guide.

Litmus

Lit m us is a powerful tool oriented toward marketers that allows them building and testing mail campaigns. Litmus pre-screens your emails across major spam filters from different inbox providers as well as score-based filters used for corporate filtering. If the list-unsubscribe header is the only thing you’re interested in, you’ll need only one click to check if it’s set up. Litmus flags any issues it finds and provides actionable advice for how to fix them.

Mail-tester.com

Mail Tester is an easy but actionable testing tool. And you’ll adore it for the home-page. You need to take two steps to have your email verified:

Copy a randomly generated email address
Send your email to this address

After that, simply click “Then Check Your Score” to get both score and a detailed spam report on your email. And yes, Mail Tester will flag it if the list-unsubscribe header is missing. See how this looked with our test email:

In our blog post Email Testing Checklist, you will find even more tools and services for deliverability and email spam testing.

To wrap up

We do not force you to set up the list-unsubscribe header for your email campaign. To get through spam filters, a regular opt-out option placed in the body text will do. But having it in the header provides special benefits that will definitely raise the quality of your emails. We’re sure you’ll make the right choice. Read more interesting email-related things on the Mailtrap blog, and good luck in your endeavors!

List Unsubscribe Header in Email