What is the List-Unsubscribe header?
Still have a question, spotted an error, or have a better explanation or a source we should cite?
You've probably noticed that little "Unsubscribe" link that appears next to a sender's name in Gmail or Yahoo Mail. That's the List-Unsubscribe header doing its job. It's a hidden signal in the email's technical headers that tells mail clients how to let someone leave your list without ever having to open the email and hunt for a link buried in the footer.
The idea is simple. When your ESP adds this header to outgoing mail, inbox providers can surface a clean unsubscribe option right in their interface. That gives subscribers a fast exit. And a fast exit is actually a good thing for you.
There are two ways the header can point to an unsubscribe mechanism. A URL method looks like this:
List-Unsubscribe: <https://example.com/unsubscribe?id=abc123>A mailto method looks like this:
List-Unsubscribe: <mailto:unsubscribe@yourlist.com?subject=unsubscribe-abc123>You can include both in the same header, separated by a comma. Most modern senders do. A companion header, List-Unsubscribe-Post, enables the true one-click version that Gmail and Yahoo now require for bulk senders. It tells the mail client it can POST directly to the URL with no extra confirmation step from the subscriber.
Speaking of requirements: since February 2024, Gmail and Yahoo mandate that senders hitting 5,000 or more messages per day include both List-Unsubscribe and List-Unsubscribe-Post, and honor unsubscribes within two days. This isn't optional. Ignoring it puts your sender reputation at risk.
Now, back to that "fast exit is good" point. It might feel counterintuitive, but making it easy to unsubscribe protects you. When someone can't find how to leave, they hit the spam button instead. A spam complaint does far more damage to your deliverability than a clean unsubscribe ever will. The List-Unsubscribe header is essentially a pressure valve.
Most ESPs add these headers automatically, so you may already have them. It's worth checking your raw email headers to confirm they're there and pointing to a working endpoint. If you need to dig into a live email to verify, our free Email Header Analyzer can show you exactly what's being sent.
Want to understand the difference between the mailto and URL approaches? That's worth a closer look in the next question.
Contributors
Who worked on this answer
Every name links to their profile. Every company links to their site. Real people, real accountability.
