Implement the List-Unsubscribe Header to Protect Your Email Deliverability

2024/01/23 by Olivier Moulene.

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:

by requesting a http(s):// link, or
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: <mailto:unsubscribe-espc-tech-12345N@domain.com>,
<https://domain.com/member/unsubscribe/?listname=espc-tech@domain.com?id=12345N>

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: <https://example.com/unsubscribe/opaquepart>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

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

Resulting POST request
POST /unsubscribe/opaquepart HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26
List-Unsubscribe=One-Click.

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: unsub-123-456@example.com). Parameters passed in the subject (ex:unsub@example.com?subject=123-456) 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 mail.ru and Yandex; and the Chinese domains qq.com, naver.com 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.

Important notice

Please note that both fields must be taken into account when generating the DKIM signature.
Ensure that they are included in the list of headers covered by the DKIM header hash.
ex:

 
DKIM-Signature: a=rsa-sha256; bh=Ij5fJxvHbJiPjyodNJkrvUFfwjAzA79KKobERT23XPh4=;
c=relaxed/relaxed; d=domain.com;
h=to:cc:from:reply-to:subject:date:mime-version:content-type:list-id:list-unsubscribe:x-csa-complaints:list-unsubscribe-post:message-id:sender:feedback-id;
q=dns/txt; s=selector; t=1784125045; v=1;