What Is the List-Unsubscribe Header? One-Click Opt-Out

If you have ever seen an Unsubscribe link right next to a sender's name in Gmail, you have already met the List-Unsubscribe header at work. So what is the List-Unsubscribe header? It is a hidden email header that senders add to bulk messages to tell your mail client exactly how to opt you out — and, with a newer extension, to let you leave a list with a single click.

This guide explains the two standards behind it: the original List-Unsubscribe header from 1998 and the one-click extension from 2017. It covers why the mailto and https versions behave differently, why bulk senders are now expected to support the one-click form, and how to tell the two apart when you see them in a real message.

What is the List-Unsubscribe header?#

The List-Unsubscribe header is defined by RFC 2369, a Standards Track specification from 1998. It lives in the hidden header block of an email — the same place as the From and Subject lines — where a person never sees it but a mail client does. Its value is one or more URIs wrapped in angle brackets and separated by commas, listed in the sender's order of preference.

Each URI tells the client one way to unsubscribe. RFC 2369 allows both a mailto: address and an http or https URL, and it says senders should usually include a mailto option alongside any web link. It is one of a small family of List-* headers the same RFC defines, which also includes List-Help, List-Subscribe, List-Post, List-Owner, and List-Archive.

On its own, RFC 2369 is a way to describe an unsubscribe command. It does not promise that the click happens without leaving your inbox, and it does not by itself mean one-click. That is what the second standard adds.

How does one-click unsubscribe work?#

One-click unsubscribe is defined by RFC 8058, a Standards Track RFC published in 2017 that builds on the original header. It introduces a second header, List-Unsubscribe-Post, whose only valid value is List-Unsubscribe=One-Click. That header is a signal: it tells the mail client that the HTTPS URL in the List-Unsubscribe header supports being unsubscribed without any further steps.

When both headers are present and the List-Unsubscribe header contains an HTTPS URL, the flow is automatic. The moment you click Unsubscribe, your mail provider — not you — sends an HTTPS POST request to that URL, carrying List-Unsubscribe=One-Click in the request body. No page opens, no form loads, and you are not asked to log in or confirm.

RFC 8058 is specific about the requirements: for one-click to work, the List-Unsubscribe header must contain an HTTPS URI, and the receiver performs the POST on the user's behalf. The example below shows the two headers together and what happens on the click.

Is the List-Unsubscribe header required now?#

For most senders it is not required, but for bulk senders it effectively is. Since February 2024, Google's sender guidelines have required anyone sending more than 5,000 messages a day to personal Gmail accounts to support one-click unsubscribe and include a clearly visible unsubscribe link in the message body.

Yahoo introduced matching rules on the same timeline. Yahoo's sender best-practices page requires bulk senders to implement a working List-Unsubscribe header that supports one-click, calls the RFC 8058 POST method highly recommended and the mailto method acceptable, and requires senders to honor unsubscribe requests within two days.

Microsoft and Apple have moved in the same direction — Microsoft recommends one-click unsubscribe for its Outlook.com senders, and Apple asks bulk marketing senders to support it. Because these rules change, verify the current wording on each provider's own sender page before you rely on a specific threshold. The figures here are accurate as of August 2026.

Why the header matters, and what breaks without it#

The header is not cosmetic. Its real job is to give recipients a fast, obvious exit so they do not reach for the spam button instead. Google asks bulk senders to keep the spam rate reported in Postmaster Tools below 0.1% and never let it reach 0.3%. When people cannot find an easy way out, they mark the message as spam, which pushes that rate up and damages the sending reputation for everyone on the domain.

The consequences have hardened over time. Google's enforcement escalated in November 2025: non-compliant bulk traffic can now draw temporary and permanent rejections, not merely spam-foldering. Microsoft's Outlook.com returns the error 550 5.7.515 for bulk mail that fails its requirements. A missing or broken one-click header is now a deliverability problem, not a nicety.

For a recipient, the header is what turns unsubscribing from a scavenger hunt into a single, trustworthy action. For a sender, supporting it is the difference between an unhappy reader who leaves quietly and one who files a spam complaint that follows the whole domain around.

mailto vs https: why the two forms behave differently#

Both forms can live in the same List-Unsubscribe header, and they are not interchangeable. The mailto form is the older mechanism from RFC 2369; the https form paired with List-Unsubscribe-Post is the one-click mechanism from RFC 8058. The table below shows how each one actually behaves.

The same click, two different paths#

When a message carries both forms, your mail client picks one. A modern provider like Gmail or Yahoo prefers the HTTPS one-click path when List-Unsubscribe-Post is present, and falls back to the mailto path otherwise. The illustration below traces where a single unsubscribe click can go.

Common misconceptions about List-Unsubscribe#

• It deletes you the instant you click. The header triggers a mechanism; actually honoring the request is a separate obligation. Yahoo, for example, gives bulk senders two days to process it, and one click removes you from that specific list or stream — not necessarily every message the company sends.
• mailto and https do the same thing. Only the HTTPS URL paired with List-Unsubscribe-Post is true one-click. A mailto entry works by sending an email that the sender's system still has to read and act on, which is slower and is not the mechanism Google and Yahoo now expect from bulk senders.
• The header makes my mail compliant. It is not a substitute for the visible unsubscribe link in the message body, and it does not by itself satisfy laws such as CAN-SPAM or GDPR. It is one required piece, not the whole obligation.
• The built-in Gmail unsubscribe link is risky. The header-based control is generally safer than an unknown link buried in the message body, because it posts to the address the sender registered in the header rather than an arbitrary tracking URL. For a legitimate list, using the built-in control is the safer way to leave.
• It is optional for everyone. For bulk senders to Gmail and Yahoo, one-click unsubscribe has been required since February 2024.

How this shows up in AI Emaily#

The List-Unsubscribe header is something senders add on their side, and it only helps you once an unwanted message has already reached you. That receiving-side problem is the one AI Emaily works on. AI Emaily is an AI email client that triages bulk mail before it piles up — its spam protection and cold-email filter keep newsletters, promotions, and unsolicited outreach out of your main inbox, so the streams you never opted into do not become a daily unsubscribe chore. We build AI Emaily, and we are honest about where the line sits.

That line is worth stating plainly: AI Emaily is not an email service provider or a bulk-sending platform, so it is not where you would add a List-Unsubscribe header to your own campaigns — that belongs in your ESP. What we do is the inbox side of the same problem. You can try it on a 7-day free trial to see how much bulk mail it clears before it ever reaches you.