A Guide to the List-Unsubscribe Header in Email

How Does List-Unsubscribe Header Work?
Valeriia Dziubenko Valeriia Dziubenko 01 march 2022, 16:46 1685
For beginners

If for some reason your emails get delivered to the Spam folder of your recipients’ mailboxes but you don’t know exactly why — this guide on List-Unsubscribe may сlarify matters, and enhance your deliverability as well.

You’ll learn how to easily get into your audience’s inboxes, successfully pass through spam filters, test your newsletters with special tools, and lessen the chance of your subscriber marking your emails as spam.

What Is the List-unsubscribe Header?

A list-unsubscribe email header is an option that helps your recipients to opt out from your email list in just one click. This is what it might look like:

List-Unsubscribe: <mailto:unsub-userhash@cdp.mycompany.com>, <https://clicks.mycompany.com/unsub/hash>

It's a line that is written in the header section of the email that mailbox providers, like Google, use to generate a link enabling the recipient to unsubscribe quickly and easily.

However, Google may fail to generate such a link if List-Unsubscribe is improperly set up. Moreover, email providers can block such emails considering them spam. Why does this happen? Let’s find out.

Why Should I Provide Users With the Unsubscribe Header?

You should always add List-Unsubscribe so that your recipients don’t have to look for the unsubscribe button somewhere in the footer of the email or on your website.

If you don’t use this header, your audience might occasionally fail to notice the unsubscribe button. In this case, they’re more likely to click the Spam button if they do not want to receive any further emails from you. Though they might have unsubscribed if the option had been more visible.

Having a simple unsubscribe option is much better than eventually being marked as a spammer. The worst-case scenario is frightening: if a considerable number of people mark your emails as spam, the reputation of your domain will fall, and overall deliverability may be ruined.

How It Works: Unsubscribe Implementation Methods

There are three ways of setting up the unsubscribe option via the email header. The oldest and most widespread is including a Mailto address, in which case the notification about a subscription being canceled is sent to a specified email address.

Later the HTTP Unsubscribe URL method emerged. In fact, this is a link to a separate landing page of your website. It may utilize some creative visual templates. Unfortunately, not all email providers support this method, although it’s quite popular nowadays.

The third method is One-click List-Unsubscribe. This is most convenient for people as it enables them to opt out from an email newsletter with just one click, removing their address from the list.


This is the most common method of unsubscription.

In this case, you set up a special email address where all the queries about recipients’ unsubscriptions are sent.

After that, your email service provider incorporates the necessary code and address in the heading of the email. This is how it actually looks in the heading:

List-Unsubscribe: <mailto:unsubscribe@unsub.mydomain.com?usercode=F5zQ9nrPvUPib7qG9>

HTTP Unsubscribe URL

This method directs a recipient to a certain web page where they have to confirm their request to unsubscribe.

You must first set up a separate landing page for unsubscription, then your ESP should embed it into the header section of the email.

This is an example of this method in action:

List-Unsubscribe: <https://clicks.mycompany.com/unsubscribe_page/usercode>

No additional data is required from a recipient, which is convenient. A good advantage of this method is that your follower may potentially change his mind upon seeing a creatively designed page and instead switch to another kind of subscription.

This is what an unsubscribe page might look like:

Unsubscribe page example

One-Click List-Unsubscribe

A relatively new method that helps recipients to exclude themselves from your newsletters in just one click. You don’t have to process all queries received via email, and your audience doesn’t have to visit some new page or site. The only weak point of this option is that the whole algorithm is automated, so getting back your unsubscribed followers won’t be easy in comparison to the HTTP method where a person can change his mind at the last second.

Which Method Should I Choose?

Overall, the most useful tip is: don’t use only one method out of three, combine two of them. Due to the way email headers work, you can set up two at a time – such as Maito and URL, or Maito and One-Click Unsubscription.

Which Email Clients Support List-Unsubscribe Header

Different mailbox providers offer various levels of support. See a few popular ones below.



One-click (per rfc8058)





Yahoo! Mail




iOS Mail




How Do I Know if List-Unsubscribe Is properly Set Up for My Campaigns?

You can test your setup by sending a test message to the specified email address. In Gmail, the unsubscribe button will appear near the sender address line.

To check the original code of your email, you need to click on the ellipsis in the right corner of the email and select “Show original”. You'll see lots of lines of code that may be quite difficult to explore. Instead, you can use the special tools listed below.

Tools to Check List-Unsubscribe

There are a lot of tools for checking if your email newsletters have the correct headings and don’t land in spam folders. Let’s consider a few that offer additional functions and analytics for your email newsletters.


This is a useful tool for testing email newsletters. Mailtrap.io can check the email before sending it with regard to unsubscribe headings. If the List-Unsubscribe header is absent, it informs you immediately. The service is ideal for testing transactional email newsletters and can be useful for developers as well. There’s an infinite free subscription for users who test up to 500 emails per month and bonuses for non-profits.


Litmus checks the List-Unsubscribe header for compliance with various mailbox providers. This tool is ideal for mass mailings.

If you’re a large company, then Litmus could be your cup of tea. Marketing specialists would certainly appreciate this service. The functionality of Litmus is based on marketing analysis that can help you build further campaigns and strategies more effectively.

There is a 7-day free trial feature.


Mail-tester.com is another testing tool for newsletters. You can use it for free 3 times a day without any signing up, it’s really convenient for personal use or small companies.

Algorithm of usage: you have to send a trial letter to the auto-generated address on their website and then check the analytics of your email with scoring up to 10 grades on their website.

Which Method Should I Choose?

Overall, the best option is not to limit yourself to one method but to use two methods at a time. The functionality of the headers does give you such an option.


The List-Unsubscribe function offers a comfy means of unsubscription from your mailings and lowers the risk of ending up in the spam folder. Moreover, this option helps you protect your domain reputation as a sender.

To create this header, you have to address your email administrator or email service provider. For testing your email you may choose different tools, but it’s still up to you which one to choose based on your volume, budget, and business needs.

Related Articles
For beginners
How To Choose the Best Font for Email?
Fonts matter greatly for emails or any other form of written communication. Have you ever struggled
Alex Kachalov
16 november 2023, 11:267 min
For beginners
How Spam Traps Affect Your Email Deliverability
Spam traps are all over the internet, waiting for a slight mistake or a series of destructive behavi
Alex Kachalov
09 august 2022, 10:172 min
For beginners
What Is Email Validation and Why Is It Important?
Valid email addresses are the basis of any successful email marketing campaign. This makes it necess
Vitalii Poddubnyi
12 august 2022, 07:085 min