List-Unsubscribe Header: What It Is and How It Works
The List-Unsubscribe header is a standard email header, defined in RFC 2369, that advertises one or more ways to request removal from a mailing list. With the RFC 8058 companion List-Unsubscribe-Post, a provider can send a one-click HTTPS request. A header proves that a route was advertised; it does not prove that the sender processed the request or stopped later mail.
Verification note: This is a documentary source review checked against current sources on August 3, 2026. We did not hands-on test the named product or workflow during this review, so claims are limited to the cited documentation. Interfaces can vary by account, region, rollout, and app version.
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 an HTTPS URI, the Post header must carry List-Unsubscribe=One-Click, and the DKIM signature used for the message must cover both headers. When the provider invokes one-click, it sends a POST to the sender-declared HTTPS URI with List-Unsubscribe=One-Click in the body. The request must not depend on cookies, HTTP authentication, or other browser context. This specifies a machine action; it does not certify the endpoint as safe or prove later honor. Full protocol walk-through: one-click unsubscribe explained.
Why does Gmail show an unsubscribe button for some newsletters and not others?
The header is one input, but Google does not publish Gmail's full display logic. The button can be absent when:
- The header isn't there. Footer link only? Gmail has nothing to build a button from.
- The message does not qualify for one-click. RFC 8058 requires DKIM coverage of the unsubscribe headers, while Google's sender rules apply one-click to marketing and subscribed mail rather than transactional messages.
- Gmail does not expose the surface. Account, client, rollout, classification, and internal eligibility can differ; Google does not publish a complete decision tree.
For senders of more than 5,000 messages a day to personal Gmail accounts, Google requires RFC 8058 one-click for covered marketing and subscribed mail and says those requests should be processed within two days. Yahoo separately requires a functioning List-Unsubscribe route for subscribed mail, highly recommends the RFC 8058 POST method, accepts mailto:, and also states a two-day processing target. These are provider requirements with different scopes, not one universal law or shared volume threshold.
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 | Advertised capability still does not prove sender processing |
Does the header guarantee the sender stops?
No. The header is a request mechanism, not evidence of the outcome. The sender still has to process the request, and provider deadlines apply only within their stated programs. Whether unsubscribing actually works—and when it is safe to try—is its own topic: does unsubscribing work?
Flick (flicked.email) is a swipe-to-triage email client, and its unsubscribe action parses List-Unsubscribe and List-Unsubscribe-Post. You can paste raw headers into our unsubscribe checker to inspect the route a message advertises. The checker reports RFC 2369/RFC 8058 capability only; it cannot look up a sender or establish whether the request was honored. No honor grade publishes until the repeated-evidence gate in our research methodology is met.
Turn the next inbox decision into a finite deck.
Open Flick with an account you control, or practice first with fabricated sample mail. Provider results remain limited to the accounts, messages, and actions Flick actually confirms.
Open Flick with your inbox →FAQ
Is the List-Unsubscribe header required?
It depends on the provider and message class. Google requires RFC 8058 one-click for covered marketing and subscribed mail from senders of more than 5,000 messages a day to personal Gmail accounts. Yahoo requires a functioning List-Unsubscribe route for subscribed mail but documents the HTTPS POST method as highly recommended and mailto: as accepted. A sender outside those scopes may still publish the header, and a header alone does not guarantee that a client will display a button.
Why is the Gmail unsubscribe button missing on some emails?
The message may have no usable List-Unsubscribe route, may not meet one-click authentication requirements, may be outside the marketing/subscribed-mail scope, or may not be eligible in that Gmail account or client. Google does not publish the complete display logic, so inspect the raw header before assigning a cause.
Is header-based unsubscribing safer than clicking the footer link?
For a legitimate mailing list whose domain you have verified, the mailbox's native control avoids opening a footer page and is usually the cleaner route. It is not a trust certificate: a malicious sender can also declare a URI, and RFC 8058 authenticates the message/header relationship rather than the endpoint's safety. For suspicious mail, do not click or invoke its unsubscribe route—report it as spam or phishing instead. More in does unsubscribing work?.
What's the difference between List-Unsubscribe and List-Unsubscribe-Post?
List-Unsubscribe says where a request can be sent; List-Unsubscribe-Post declares RFC 8058 one-click support. Per RFC 8058, the Post header carries List-Unsubscribe=One-Click, telling providers they may POST to the HTTPS URI without further interaction. Without the Post header, a client may still use an RFC 2369 mailto: or HTTPS route, but it is not the RFC 8058 one-click mechanism.