One-Click Unsubscribe

24 May 2026 · 11 min read

Why a header decides whether your mail reaches the inbox

In February 2024 Google and Yahoo turned a long-standing recommendation into a hard requirement: if you send bulk email to their users, every marketing message must carry a working one-click unsubscribe, and a recipient must be able to opt out in a single action without logging in, hunting through a landing page or ticking a confirmation box. Microsoft followed with the same expectation for Outlook and Hotmail. What used to be a politeness, a footer link people rarely clicked, is now a deliverability control that mailbox providers actively check and enforce.

This article explains exactly what that requirement is, the two HTTP and email headers that make it work, how to implement them correctly, the failure modes that quietly get your mail filtered, and where it sits alongside the authentication work, SPF, DKIM and DMARC, that you have probably already started. One-click unsubscribe is not part of DMARC, but it lives in the same rulebook the big providers published, and the same domains that fail authentication are usually the ones that also botch unsubscribe. Getting both right is what keeps a sending domain in good standing.

If you want to see where your domain stands on the authentication side before reading further, run it through the DMARC checker, the SPF checker and the DKIM checker. Those tell you whether the foundation is in place. This article covers the layer that sits on top of it.

Two different things both called "List-Unsubscribe"

The single biggest source of confusion here is that people use "List-Unsubscribe" to mean two related but distinct features, and the providers require both. Keeping them separate in your head is the key to implementing this correctly.

List-Unsubscribe is an email header, defined in RFC 2369, that has existed since 1998. It carries one or more URIs telling the receiving mail client how a recipient can unsubscribe. It can hold a mailto: address, an https:// URL, or both. This header is what lets Gmail and Apple Mail show that neat "Unsubscribe" button at the top of a message, next to the sender name, instead of forcing the reader to scroll to a footer link.
List-Unsubscribe-Post is the newer companion header, defined in RFC 8058 in 2018, that enables genuine one-click unsubscribe. Its presence tells the mail client: "you may send an HTTP POST to the URL in the List-Unsubscribe header and that single request will unsubscribe this person, no further interaction required."

The distinction matters because the old List-Unsubscribe header on its own does not give you one-click. Without List-Unsubscribe-Post, a mail client that follows your https:// URL would have to open it in a browser and rely on the recipient to finish the job on your page. RFC 8058 closes that gap by defining a precise, machine-driven flow. When Google and Yahoo say "one-click unsubscribe", they mean RFC 8058 specifically, which means you need both headers together.

What a compliant set of headers looks like

A correctly configured bulk message carries two headers. Here is the canonical form:

List-Unsubscribe: <https://example.com/unsub?u=abc123&c=newsletter>, <mailto:unsubscribe@example.com?subject=unsub-abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Several details in that example are load-bearing, and each one is a place people get it wrong.

The URIs are wrapped in angle brackets. <...> is required by RFC 2369. A raw URL without brackets is malformed and may be ignored.
You can list more than one URI, comma-separated. Best practice is to provide both an https:// URL and a mailto: address. The https one powers one-click; the mailto is a fallback for clients that prefer or only support email-based opt-out.
The List-Unsubscribe-Post value is fixed. It must be exactly List-Unsubscribe=One-Click. It is not a URL, not a flag you invent; it is a literal token defined by the RFC. Getting the spelling or casing of One-Click wrong means the header does nothing.
The unsubscribe URL should encode who is unsubscribing. Notice the ?u=abc123 parameter. The whole point of one-click is that the POST arrives with no human in the loop, so the URL itself has to identify the subscriber and ideally the list or campaign. A signed or opaque token is far better than a plaintext email address, for reasons we will come to.

When all of this is present and the message also passes DKIM (more on why that matters below), Gmail renders an "Unsubscribe" link beside the sender, and a tap on it fires a background POST. The recipient sees a brief confirmation and never leaves their inbox.

How the one-click flow actually works on the wire

It helps to trace the exact sequence, because understanding it tells you precisely what your server has to handle.

The recipient opens your message in Gmail, Apple Mail, Outlook or another supporting client and taps the provider's built-in unsubscribe control.
The mail client reads the https URI from your List-Unsubscribe header and sees that List-Unsubscribe-Post: List-Unsubscribe=One-Click is present.
The client sends an HTTP POST to that URL. The body is application/x-www-form-urlencoded and contains exactly List-Unsubscribe=One-Click. Critically, it is the mailbox provider's infrastructure that makes this request, not the recipient's browser, and often from the provider's own servers.
Your server receives the POST, parses the subscriber identity out of the URL, records the opt-out, and returns a 200 OK (or another 2xx). You should process the unsubscribe immediately and not redirect to a "are you sure?" page.

A few consequences fall straight out of this flow:

You must accept POST, not just GET. A very common bug is an unsubscribe endpoint that only handles GET because it was built for the old footer-link flow. RFC 8058 one-click is a POST. If your endpoint returns a 404, 405 or a redirect to a login page on POST, you are not compliant, even though the header is present.
No authentication, no confirmation, no CAPTCHA. The request arrives with no cookies and no session. If your page demands a login or a "click here to confirm", the unsubscribe silently fails. The whole requirement exists to remove those friction steps.
It must be idempotent and fast. The same POST may arrive more than once; processing it twice should be harmless. Aim to honour the opt-out well within the providers' expectation, which Google states as no later than two days, though doing it instantly is the right behaviour.

Why the providers enforced this, and what they check

Mailbox providers did not add this rule to be tidy. Unsubscribe friction is one of the strongest predictors of spam complaints. When a recipient cannot easily get off a list, they do the next-easiest thing, which is hit the "Report spam" button. Spam complaints are the single most damaging signal a sender can accumulate, because providers use complaint rate to decide whether your future mail lands in the inbox, the spam folder or nowhere at all. By forcing frictionless unsubscribe, Google and Yahoo are trying to drain the complaint pool: give people an easy exit and they stop reaching for the spam button.

That is also why the requirement is bundled with the wider 2024 bulk-sender rules rather than standing alone. The full package, for anyone sending roughly 5,000 or more messages a day to Gmail or Yahoo, is:

Authenticate your mail. SPF and DKIM must be set up, and a DMARC policy of at least p=none must be published, with alignment. This is the part the rest of this site is about; the requirements page lays out the thresholds and what counts as compliant.
Keep spam complaints low. Google asks senders to stay under a 0.3% complaint rate in Postmaster Tools and ideally below 0.1%.
Offer one-click unsubscribe as described here, and honour opt-outs within two days.

These are checked together. A domain with perfect authentication but a broken unsubscribe will still see delivery suffer, and a domain with flawless unsubscribe but failing DMARC alignment will be filtered regardless. The providers treat the whole set as the price of bulk sending. If you are working through DMARC enforcement, think of one-click unsubscribe as the same project: it is on the same compliance checklist, published by the same companies, enforced by the same filters.

DKIM, alignment and the unsubscribe header

There is a subtle but important connection between one-click unsubscribe and the authentication work you may already be doing, and it is easy to miss.

For a mailbox provider to trust your List-Unsubscribe header enough to surface its own unsubscribe button, it generally wants the message to be authenticated, and in practice that means the relevant headers should be covered by a valid DKIM signature. DKIM signs a chosen set of headers, and if List-Unsubscribe and List-Unsubscribe-Post are inside the signed set, the provider knows they were not injected or tampered with in transit. An unsigned unsubscribe header is far less trustworthy: an attacker could otherwise add a malicious "unsubscribe" URL to a forwarded message.

The practical advice that follows:

Make sure your ESP signs the unsubscribe headers with DKIM. Most reputable platforms include List-Unsubscribe in the DKIM h= header list automatically, but it is worth confirming, especially if you inject the header yourself via your sending API.
Keep DKIM aligned with your From domain. One-click unsubscribe sits on top of authentication; it does not replace it. If you are unsure how DKIM alignment works, DKIM alignment explained and what is DKIM cover the mechanics, and the DKIM checker shows what a domain currently signs.

This is the natural bridge back to DMARC. The same DKIM signature that lets DMARC pass on a forwarded message is the signature that makes your unsubscribe header trustworthy. If you have done the authentication groundwork, you are most of the way there. If you have not, the unsubscribe header alone will not save your deliverability.

The mailto fallback, and why you still want it

It is tempting to provide only the https URL, since that is what powers the headline one-click experience. Do not drop the mailto. Including a mailto: URI in List-Unsubscribe matters for two reasons.

First, not every client implements the RFC 8058 POST flow. Some older or niche mail clients support the original RFC 2369 header and will offer a mailto-based unsubscribe instead. Providing the mailto widens the set of recipients who can opt out cleanly.

Second, the mailto route is a useful belt-and-braces channel. When a client uses it, an email arrives at your nominated address, typically with a subject line you specified that encodes the subscriber. You process that mailbox, automatically, to action the opt-out. The key requirements are the same as for the HTTP route: action it promptly and do not bounce or ignore it.

A robust configuration therefore offers both: https for one-click, mailto as the fallback. The order in the header is up to you, but listing the https URL first is conventional.

Common implementation mistakes

Because two headers, an HTTP endpoint and a mailbox all have to behave correctly, there are several well-trodden ways to get this subtly wrong. These are the ones that show up most often.

Missing List-Unsubscribe-Post entirely. The message has the old header but not the RFC 8058 companion, so there is no true one-click. The provider may not surface its button at all. This is the most common single failure.
An endpoint that only accepts GET. Built for the old footer link, it does not handle the POST that one-click sends. Test with an actual POST, not a browser visit.
Requiring a login or confirmation step. A "click to confirm your unsubscribe" page defeats the entire purpose and is explicitly disallowed for the one-click flow.
A URL that does not identify the subscriber. If the POST arrives with no way to tell who is unsubscribing, you cannot action it. Encode an opaque, ideally signed, token in the URL.
Plaintext email addresses in the URL. Putting the raw address in the link invites abuse: anyone can guess or scrape addresses and POST to unsubscribe other people, or use the endpoint to validate which addresses exist. Use a signed token that you can verify and that does not leak the address.
Putting the header only on some messages. Transactional mail (password resets, receipts) does not need it, but every commercial or bulk message does. Inconsistency looks like a misconfiguration to filters.
Not signing the headers with DKIM. As covered above, unsigned unsubscribe headers are less trusted and easier to spoof.
Honouring the opt-out slowly, or not at all. Continuing to mail someone who used one-click is the fastest route to spam complaints and blocklisting. Suppress immediately.

How to test that it actually works

You cannot tell from the headers alone that the whole flow functions, so test the moving parts directly.

Inspect the raw headers of a real send. In Gmail, "Show original"; in Apple Mail, view the source. Confirm both List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click are present, the URIs are angle-bracketed, and the headers appear in the DKIM h= list.
POST to your endpoint manually. From a terminal, send an application/x-www-form-urlencoded POST with the body List-Unsubscribe=One-Click to your unsubscribe URL, using a real test token. Confirm you get a 2xx and that the subscriber is actually suppressed in your database.
Send yourself a test campaign to a Gmail and a Yahoo address and check that the provider's built-in unsubscribe control appears and works end to end.
Watch your complaint rate in Google Postmaster Tools over the following weeks. A falling complaint rate is the real-world signal that frictionless unsubscribe is doing its job.

Most reputable email service providers handle the headers and the endpoint for you, which is the easiest path. If you send through your own infrastructure or a transactional API, you own all of this and the tests above are essential.

Where this fits in the bigger picture

One-click unsubscribe is a small piece of plumbing with outsized consequences. Two headers, one POST endpoint and a suppression list are all it takes mechanically, but they sit inside the same 2024 bulk-sender framework that made DMARC mandatory, and they are enforced by the same filters that decide whether your mail reaches the inbox. A sender who nails authentication but ignores unsubscribe will still struggle, and the reverse is just as true.

The practical takeaway: treat unsubscribe and authentication as one project, not two. Get SPF, DKIM and DMARC aligned first, because the unsubscribe header is only trusted when the message is authenticated, then add the RFC 8058 headers and a fast, login-free POST endpoint that suppresses opt-outs immediately. Keep an eye on your complaint rate to confirm it is working.

If you are still sorting out the authentication foundation underneath all this, that is exactly what DMARC Engine is built to do: take a domain safely from p=none to p=reject without breaking legitimate mail, with DKIM signing, SPF and DMARC handled for you and continuous monitoring that alerts you when something changes. Start by checking where you stand today with the free tools, and read the requirements guide for the full bulk-sender checklist that one-click unsubscribe is part of.

One-click unsubscribe: the List-Unsubscribe requirement