Read Time: 6 min

The Email Marketers Guide to Using List-Unsubscribe

List-unsubscribe is a native unsubscribe option offered by popular inbox providers like iOS Mail, Gmail, Yahoo Mail, and to make it easy for users to unsubscribe from unwanted emails. Because it gives subscribers an alternative to designating your email as “spam,” list-unsubscribe also provides a benefit to email marketers.

However, it is not a replacement for having unsubscribe messaging and links in your email. Consider it just one more way to give your subscribers a positive email experience.

Read on to learn what list-unsubscribe entails, how it works, and everything you need to know to set up list-unsubscribe for your campaigns.

What is list-unsubscribe?

Email marketers want subscribers to want to be on their email lists. But there are times when subscribers decide they’re no longer interested in receiving certain messages. Giving the option to unsubscribe easily is a much better alternative for sender reputation, email deliverability and list health than having the message marked as spam.

In addition to including easy to use unsubscribe links in your emails, the list-unsubscribe option offered by some inbox providers delivers a convenient alternative to searching for the unsubscribe link within the message itself. In some cases, it includes one-click functionality that makes for an even better subscriber experience.

How does list-unsubscribe look in the inbox?

The list-unsubscribe display depends on the inbox provider.

The Really Good Emails example below shows how Gmail displays list-unsubscribe as a text link next to the email sender information.

Gmail list-unsubscribe

This example shows how iOS Mail includes a more prominent unsubscribe banner at the very top of an email.

iOS list-unsubscribe example

Why list-unsubscribe benefits email marketers and subscribers

The unsubscribe option is one of the first pieces of content subscribers see when opening your message.  So how could list-unsubscribe be a good thing for email marketers? There are two key reasons this functionality can work to your advantage.

  1. A prominent unsubscribe option keeps your list clean.
    The size of your email list only matters if the people on it are engaging with your messages, and want to receive your emails. List-unsubscribe helps make sure you’re only sending emails to people who really want to hear from you.
  2. List-unsubscribe can help reduce spam complaints.
    If subscribers can’t find the unsubscribe link, they may click the spam reporting button instead. This could hurt your email deliverability and sender reputation. To mailbox providers, a spam complaint is a spam complaint, regardless of whether the recipient actually perceived the message as malicious.

Does list-unsubscribe happen automatically?

An email client can only provide a native list-unsubscribe option if it finds list-unsubscribe instructions in the email’s header. (List-unsubscribe links don’t automatically display on each promotional email).

There are two types of instructions a sender can provide to an inbox provider to power list-unsubscribe: a mailto link or an unsubscribe URL.

The email header shown below contains both:

  • A mailto unsubscribe
    When a recipient triggers the list-unsubscribe in a client that supports unsubscribes via the mailto link, this automatically generates an email notifying the sender that an email address has unsubscribed. The unsubscribe header is set up with the email address that will receive the unsubscribe requests.
  • An unsubscribe URL
    A link that will take the subscriber to a landing page to process the unsubscribe request. In most cases, that’s a subscription center or another type of landing page that asks the user to confirm the unsubscribe. Brands might also chose to offer a one-click list-unsubscribe that doesn’t require additional confirmation on a landing page, in accordance with RFC 8058.

Which email clients support list-unsubscribe?

Support for list-unsubscribe varies across email clients. While some email clients honor mailto or URL-based list-unsubscribe headers (or both), others don’t support list-unsubscribe at all.

The following email clients support list-unsubscribe:



1-Click (RFC 8058)

iOS Mail





Yahoo! Mail


While the list looks short, it covers the most popular email clients according to Litmus’ Email Client Market Share. The majority of consumers could benefit from being painlessly unsubscribed using the list-unsubscribe functionality—if the email senders have set it up.

How do I set up list-unsubscribe?

Adding unsubscribe information to your emails’ headers happens through your email service provider (ESP). If you’re seeing issues with your list-unsubscribe header or would like to add it to your emails, start with your ESP. Some add list-unsubscribe automatically to all emails sent through their services. Others may require that list-unsubscribe be enabled manually or is switched on and off for specific campaigns.

In the case of Marketo, for example, list-unsubscribe is not included in test emails. To see it in the inbox, you’d have to send yourself a live email. Likewise, if your ESP does not recognize list-unsubscribe in test emails this may impact the results you see in the email testing process. (Test emails would be flagged as not including list-unsubscribe, even though they actually do).

How do I set up list-unsubscribe for my campaigns?

Litmus Spam Testing can help you check your email’s list-unsubscribe setup with just one click. It tells you whether a list-unsubscribe header is set up for your email, shows if you’re set up to support both the mailto and the URL version of list-unsubscribe, and flags any issues it spots in your list-unsubscribe header.

You can also access your email’s header information manually, but it works a little differently for every inbox provider. In Gmail, for example, you can view your email’s header via the dropdown menu on the right of the sender details.

.Screenshot of Gmail inbox clicking "Show original"

Once you’re viewing the email header, search for the “list-unsubscribe” section and check if you can find a mailto link, unsubscribe URL, or both.

List-unsubscribe makes it easy for subscribers to stop receiving email messages they no longer want–and it helps email marketers maintain a current and healthy subscriber list. But remember, it is not a replacement for having unsubscribe messaging and links in your email. Consider it just one more way to give subscribers a positive email experience with your brand.

Does your email contain a list-unsubscribe header?

Does your email contain a list-unsubscribe header?

Litmus Spam Testing checks whether your email is set up to support list unsubscribe—and provides you with actionable advice in case it’s not.

Learn more →

Stephanie Christensen

Stephanie Christensen

Stephanie Christensen was the Director, Content Marketing at Litmus