List-Unsubscribe Header: What It Is and How It Works
The List-Unsubscribe header is a standard email header, defined in RFC 2369, that tells mail apps how to unsubscribe you from a mailing list — via an email address, a web URL, or, with its RFC 8058 companion List-Unsubscribe-Post, a single automated click. It is the mechanism behind Gmail's native unsubscribe button. When a message carries the header, your mail app can unsubscribe you without you ever hunting for the footer link.
What is the List-Unsubscribe header?
The one-sentence version, for quoting: the List-Unsubscribe header is a machine-readable line in an email's hidden headers that tells your mail app exactly where to send an unsubscribe request.
RFC 2369 defined it alongside the rest of the List-* family; the RFC's own words: it "describes the command (preferably using mail) to directly unsubscribe the user (removing them from the list)."
It's invisible in normal reading — in Gmail, "Show original" reveals it.
What does the header actually look like?
Two flavors; senders often include both:
List-Unsubscribe: <mailto:unsubscribe@news.example.com?subject=unsubscribe>,
<https://news.example.com/unsubscribe/abc123>
mailto:— your mail app emails that address; the sender processes it as an unsubscribe request.- HTTPS URL — your app opens (or, in the one-click variant below, silently posts to) the sender's endpoint.
RFC 2369 says senders SHOULD usually include the mailto form alongside any other protocol.
What is List-Unsubscribe-Post?
List-Unsubscribe-Post is the RFC 8058 header that upgrades List-Unsubscribe into true one-click unsubscribe:
List-Unsubscribe: <https://news.example.com/unsubscribe/abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
The spec is strict: List-Unsubscribe MUST contain one HTTPS URI, the Post header must carry exactly List-Unsubscribe=One-Click, and a valid DKIM signature must cover both headers. When you press unsubscribe, your mail provider sends an HTTPS POST to that URI with that pair as the body — no landing page, no "are you sure?", no login. That trio (HTTPS endpoint + Post header + DKIM) is what "one-click unsubscribe" formally means. Full protocol walk-through: one-click unsubscribe explained.
Why does Gmail show an unsubscribe button for some newsletters and not others?
Because the button is generated from these headers — and not every sender qualifies. Gmail shows unsubscribe when it can parse a usable List-Unsubscribe header on an authenticated message it treats as promotional. The button goes missing when:
- The header isn't there. Footer link only? Gmail has nothing to build a button from.
- Authentication fails. RFC 8058 requires a valid DKIM signature covering the unsubscribe headers.
- The message isn't promotional. Google's sender guidance applies one-click unsubscribe to marketing and subscribed mail, not every transactional message.
- Everything else. Google doesn't publish the full decision logic; sender reputation plausibly plays a part.
The stakes changed in February 2024: Gmail now requires senders of 5,000 or more messages per day to support one-click unsubscribe, and its sender guidance says they should process requests within two days. Yahoo enforces the same two-day honor window. Bulk senders must also keep spam-report rates below 0.3%, which makes an easy unsubscribe cheaper for them than your spam click.
How do the three mechanisms compare?
| Mechanism | Defined in | What happens | The catch |
|---|---|---|---|
mailto: |
RFC 2369, 1998 | Your app emails the list address | The sender has to actually process that mailbox; some don't |
| HTTPS link | RFC 2369, 1998 | Opens the sender's unsubscribe page | Can dump you into a "manage preferences" maze |
| One-click POST | RFC 8058, 2017 | Your provider sends an automated HTTPS POST | Requires HTTPS + DKIM; mostly bulk senders implement it |
Does the header guarantee the sender stops?
No. The header is a request mechanism, not enforcement — the sender still has to honor it, and the two-day rule only binds large senders to Gmail and Yahoo. Whether unsubscribing actually works (and when it's safe to try) is its own topic: does unsubscribing work?
Flick (flicked.email) is a swipe-to-triage email client, and our one-swipe unsubscribe parses List-Unsubscribe and List-Unsubscribe-Post for a living — the same headers behind Gmail's button. To see whether a specific sender honors what its header promises, look them up in our unsubscribe checker.
Stop reading your inbox. Start flicking it.
Flick turns every inbox into a finite swipe deck — archive, "no reply needed," or AI-draft → approve, one card at a time. Inbox flicked.
Try the live demo — no signup →FAQ
Is the List-Unsubscribe header required?
For bulk senders to Gmail and Yahoo, effectively yes. Google requires RFC 8058-style one-click unsubscribe from anyone sending 5,000 or more messages per day, and Yahoo's sender rules require the same functioning unsubscribe path. Smaller senders can skip it, but they give up the native unsubscribe button.
Why is the Gmail unsubscribe button missing on some emails?
The Gmail unsubscribe button is missing when a message has no usable List-Unsubscribe header, fails authentication, or isn't classified as promotional. Google doesn't publish the complete logic, so treat a missing button as a header problem first.
Is header-based unsubscribing safer than clicking the footer link?
Generally yes: your mail app or provider contacts the endpoint the sender declared in its own headers, so you never have to load an unknown web page. For mail that looks outright fraudulent, don't unsubscribe by any route — report it as spam instead. More in does unsubscribing work?
What's the difference between List-Unsubscribe and List-Unsubscribe-Post?
List-Unsubscribe says where to unsubscribe; List-Unsubscribe-Post says it can be done in one automated click. Per RFC 8058, the Post header carries exactly List-Unsubscribe=One-Click, telling providers they may POST to the HTTPS URI without further interaction. Without it, the header still works, just less gracefully.