technical · sourced answer
List-Unsubscribe Header Definition and Implementation
The List-Unsubscribe header is an optional email header that allows recipients to unsubscribe from a mailing list using a single click or a specific email address provided in the message metadata. It enables email clients like Gmail and Outlook to display an Unsubscribe link directly in the user interface, separate from the email body.
Mechanical Function
The header operates by providing the mail client with a specific instruction on how to handle an unsubscribe request. There are two primary methods: a mailto link and an HTTP POST request. When a user clicks the unsubscribe button in their client, the client either sends a formatted email to the specified address or executes a background HTTP request to the provided URL. This removes the need for the user to find and click a link within the HTML body of the email.
Sender Importance
Implementing this header reduces the likelihood that users will mark emails as spam when they cannot find an easy way to opt out. Because spam filters track the rate of spam complaints, providing a native unsubscribe mechanism protects sender reputation. Major providers now require this header for high volume senders to ensure a consistent user experience and to lower the overall volume of spam reports across their networks.
Operational Notes
A common mistake is failing to implement the HTTP POST method correctly. For the one click unsubscribe experience, the server must respond to the POST request with a 200 OK status without requiring further user interaction or authentication. Senders should also ensure that the unsubscribe action is processed quickly to avoid users clicking the spam button out of frustration when the process feels slow.
Implementation Example
A standard implementation includes two headers. The first is List-Unsubscribe: <mailto:unsubscribe@example.com>, <https://example.com/unsubscribe>. The second is List-Unsubscribe-Post: List-Unsubscribe=One-Click. This combination tells the client that both email and web-based unsubscribes are available and that the web method supports the one click standard. You can use SendHQ or its free tools to verify your overall email configuration.
Header Validation
Validation involves sending a test message and inspecting the raw headers to ensure the syntax is correct. The header must be placed in the message head, not the body. If the URL provided is broken or the mailto address is invalid, the email client may hide the unsubscribe button entirely, forcing users back to the manual process of marking the message as spam.
Questions teams ask
Is the List-Unsubscribe header mandatory?
While not mandatory by SMTP standards, it is effectively required by major providers like Google and Yahoo for bulk senders to maintain deliverability.
What is the difference between mailto and HTTP unsubscribe?
Mailto sends an email to the sender, while HTTP triggers a web request. HTTP is preferred for one click unsubscribes as it is faster for the user.
Does this replace the unsubscribe link in the email body?
No. You must still include a visible unsubscribe link in the email body to comply with legal requirements like CAN-SPAM and GDPR.
How does it affect spam rates?
It lowers spam rates by providing a low friction path for users to opt out, preventing them from using the report spam button.
Primary sources
- RFC 5322: Internet Message Format — RFC Editor
- M3AAWG Best Common Practices — M3AAWG