What is List-Unsubscribe? The header behind every real unsubscribe

List-Unsubscribe is an email header. It's metadata that travels with the message, invisible in the body you read. It tells the receiving mail system: here is the official way to get off this list.

I run Gmail Unsubscribe, a Chrome extension that has processed unsubscribe requests for a lot of inboxes, so I spend an unreasonable amount of time looking at this header. This page is the explainer I wish existed: what the header looks like, the two RFCs behind it, and why Google and Yahoo turned it from a nice-to-have into a requirement in 2024.

What the header actually looks like

Open any newsletter in Gmail, click the three-dot menu, and choose "Show original". In the raw message you'll find something like this:

List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsubscribe>,
 <https://example.com/unsubscribe/abc123>

The rules are simple:

• Each destination is a URI wrapped in angle brackets.
• There are two kinds: a mailto: address (send an email here to unsubscribe) and an https: URL (make a web request here).
• A sender can include one or both, separated by a comma. Including both is the safest practice, because different mail systems prefer different mechanisms.

Note what's absent: none of this appears in the visible email. The "click here to unsubscribe" link at the bottom of a newsletter is a separate thing, an ordinary link in the body. The header is machine-readable plumbing, which is exactly why mail providers trust it more than body links.

RFC 2369 vs RFC 8058: the confirmation-page problem

The header dates to 1998. RFC 2369 defined List-Unsubscribe along with its sibling headers (List-Help, List-Subscribe, and others). It was built for mailing-list software, and it worked, with one catch: the RFC didn't say what should happen when the URL gets visited.

That gap mattered. If a mail client automatically fetched every unsubscribe URL (say, while prefetching links or scanning for malware), people would get unsubscribed from lists they wanted. So senders defended themselves with confirmation pages: click the link, land on a page, click another button to confirm. Safe, but no longer one click.

RFC 8058, published in January 2017, fixed this with a second header:

List-Unsubscribe: <https://example.com/unsubscribe/abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The design is clever. List-Unsubscribe-Post signals that the HTTPS URL accepts a POST request with the body List-Unsubscribe=One-Click. A POST can't be triggered by accidental link prefetching, so the sender can safely honor it immediately: no page visit, no confirmation click, no login. The RFC also requires the message to carry a valid DKIM signature that covers both headers, so a forwarded or tampered message can't fire someone else's unsubscribe.

That combination, an HTTPS URI plus the POST header plus DKIM alignment, is what "one-click unsubscribe" technically means. If a vendor claims RFC 8058 support but their endpoint redirects you to a preferences page, they don't support it.

2024: Google and Yahoo made it mandatory

For seven years RFC 8058 was optional and adoption was mediocre. Then in February 2024, Google and Yahoo jointly rolled out new bulk sender requirements. Senders delivering 5,000 or more messages per day to Gmail addresses must support RFC 8058 one-click unsubscribe in their marketing and promotional mail, and must honor unsubscribe requests within two days. Miss the bar and your mail starts landing in spam or gets rejected outright.

This is why Gmail's own Unsubscribe button, the one that appears next to the sender's name at the top of a message (as of 2026), became so much more reliable. Gmail reads the List-Unsubscribe headers and fires the sender's official mechanism for you. The same header powers Gmail's Manage subscriptions view, which lists your subscription senders in one place in the left navigation.

Why header-based unsubscribing is safer for you

If you take one practical thing from this page: prefer the header over the link at the bottom of the email.

• No tracking. Body unsubscribe links usually route through click trackers and confirm your address is live before you reach the actual page. A one-click POST goes straight to the endpoint.
• No phishing surface. In a spoofed email, the body link goes wherever the attacker wants. An RFC 8058 unsubscribe only fires if the DKIM signature checks out.
• No dark patterns. No "are you sure" pages, no surveys, no login walls.

We wrote a full breakdown of when unsubscribing is safe and when you should block instead in Is it safe to unsubscribe from emails?

The honest gap: a third of senders still fail

Now the part vendors don't put on their homepages. Across our users' real unsubscribe attempts, we measured that roughly a third hit senders with no working unsubscribe mechanism at all. No one-click endpoint, no functioning mailto, sometimes a link that 404s. The 5,000-per-day threshold leaves plenty of smaller and sloppier senders out of scope, and enforcement isn't instant.

So our extension works down a ladder. We try the RFC 8058 one-click POST first. If the header only offers mailto:, we send the unsubscribe email. If there's no usable header, we fall back to the link. And when nothing works, we tell you it failed, so you can block the sender instead of assuming you're off the list. Any tool that reports 100% success is hiding this problem from you.

If you're a sender reading this

Implement RFC 8058 properly. Put an HTTPS URI in List-Unsubscribe, add List-Unsubscribe-Post: List-Unsubscribe=One-Click, sign both headers with DKIM, accept the POST without any further interaction, and actually stop mailing within two days. Keep a mailto: variant alongside for older clients. It's a small amount of engineering, and it's the difference between users leaving your list cleanly and users marking you as spam, which hurts your deliverability far more than any unsubscribe ever will.

And if you'd rather compare every way to get off a list, header-based and otherwise, start with our hub guide: how to unsubscribe from emails.