List-Unsubscribe header critical for sustained email delivery

In our daily work, we still encounter missing List-Unsubscribe headers in emails. Reason enough to publish another BLOG post on this topic. It has become even more important recently since Google and Yahoo now include the list-unsubscribe mechanism among their requirements.

What is a List-Unsubscribe header?

When subscribers want to unsubscribe from a mailing list and the unsubscribe process is too complex, subscribers will often use the SPAM button. Using the SPAM button will negatively impact sender reputation, thus lowering email deliverability. That is, unless List-Unsubscribe is used. This feature gives an additional way to unsubscribe and the number of times the SPAM button gets hit will be reduced. In addition, this unsubscribe feature is also used by webmails such as Gmail or Yahoo when an email is marked as spam by the recipient.

In GMAIL the List-Unsubscribe feature will be visualized for users like:



In the next two paragraphs we will explain the best practice set-up of the List-Unsubscribe header. We will share a case study on the situation before and after a List-Unsubscribe header implementation with mailto:link.

Best practice set-up of the List-Unsubscribe header

The List-Unsubscribe is an additional header inserted by email applications. It provides two mechanisms for mailbox providers to unsubscribe the recipient from a mailing list:

  1. by requesting a http(s):// link, or
  2. by sending to a mailto: link.

The List-Unsubscribe is a standard header and is defined in RFC 2369.

The List-Unsubscribe header formatting is:
List-Unsubscribe: <>,

Note: the links must be enclosed by angle brackets.

The List-Unsubscribe-Post=One-Click header

The List-Unsubscribe-Post=One-Click header (described in RFC 8058 ) is an extension of the List-Unsubscribe header. It is designed to prevent accidental unsubscribes by anti-spam software. When the List-Unsubscribe-Post header is used, the unsubscribe link (http:// link) should function differently depending on whether it received an HTTP GET or POST request.
To avoid unwanted unsubscribes when this link is called via a GET request performed by a spam filter, a confirmation page is presented. But when this same link is accessed via a POST request, it must cause an immediate unsubscribe (this is the method that MBPs will use).

List-Unsubscribe: <>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Here is an example of a simulated call using a curl command:

curl -X POST -H "Content-type: application/x-www-form-urlencoded" -d "List-Unsubscribe=One-Click"

Resulting POST request
POST /unsubscribe/opaquepart HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 26


The mailto:link

The local part of the mailto:link address should not exceed 64 characters.
Identifier(s) used for actual unsubscription should be encoded in the local part of the mailto: address (ex: Parameters passed in the subject ( may be ignored by the providers and the body of the email is typically empty.

The mailto:link is currently supported by Gmail, Hotmail, Yahoo, AOL, ATT, Time Warner and Comcast; European ISPs such as GMX, Libero, Ziggo, Orange, BTInternet; Russian ISPs such as and Yandex; and the Chinese domains, etc.

Gmail and Yahoo recently announced that they may stop using the mailto: method in the future and will only support the http method.
It is therefore preferable to offer both methods in the list-unsubscribe header to ensure optimal compatibility.

Case study: the effect of implementing a mailto:link

One of Postmastery's clients implemented a List-Unsubscribe header, but without a mailto:link. As soon as the mailto:link was added, the MTA received 55,000 unsubscribe requests via the mailto:link in 30 days (150 million emails were delivered during this period, but it is still a significant number of unsubscribes). Of these:

  • 20,000 unsubscribe requests were received from (not including GSuite domains)
  • 14,000 were from Yahoo related domains
  • 3,500 were from Hotmail related domains
  • 3,500 were from Apple domains such as etc.
  • The reminders were from other ISPs.

Hotmail only supports the mailto:link. When a user clicks on the 'unsubscribe' option in Hotmail, Hotmail tries to read the mailto:link in the List-Unsubscribe header. If the mailto:link is missing, it moves all the messages to the Junk folder. All further emails from the same sender will be pre-routed to the Junk folder without notifying the sender through a JMRP complaint. For more information, please read Hotmail Email Sender Guidelines.

More information?
If you would like to know more about how we can help you solve delivery issues, just send us a message via our contact form. We are always happy to assist!

Share this

Comments are closed.

There are many more interesting blogs by category for you to read.