What are “List-Unsubscribe” headers?
Still have a question, spotted an error, or have a better explanation or a source we should cite?
You've probably noticed that some emails in Gmail or Apple Mail show a small "Unsubscribe" link right at the top of the message, before you even open it. That's not magic from the email client. It's responding to List-Unsubscribe headers that the sender included in the message.
List-Unsubscribe is a standard email header that tells mailbox providers how to process an unsubscribe request without the recipient having to find and click a link inside the email. There are two formats. The mailto format sends an email to a specified address: List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsubscribe>. The https format hits a URL endpoint: List-Unsubscribe: <https://example.com/unsub?id=abc>.
The more important upgrade is List-Unsubscribe-Post. This is the one-click unsubscribe standard that Google and Yahoo now require for bulk senders. When a user clicks the "Unsubscribe" button in Gmail, it sends a POST request to your endpoint directly, rather than opening a browser or sending an email. The whole process takes one click. No landing page. No confirmation email.
Why does this matter for complaint rates? Because recipients who can't easily unsubscribe often hit "Report Spam" instead. Making the unsubscribe path as frictionless as possible is one of the most effective ways to keep your complaint rate low. Most major ESPs handle List-Unsubscribe headers automatically. If you're building your own sending system, implementing both the mailto and https formats is worth the effort.
Check that your headers are working correctly by viewing a test message's raw source and confirming both List-Unsubscribe and List-Unsubscribe-Post headers are present.
Contributors
Who worked on this answer
Every name links to their profile. Every company links to their site. Real people, real accountability.
