One-Click Unsubscribe: A Working Definition for People Who Have to Ship It

One-click unsubscribe is a mechanism that lets a recipient opt out of a mailing directly from their mail client, without opening a web page or confirming anything, by having the mail client send a single HTTP POST request to a URL the sender published in the message headers. It is specified in RFC 8058, and it works by pairing an existing List-Unsubscribe header with a second header, List-Unsubscribe-Post: List-Unsubscribe=One-Click.

The pair is often referred to collectively as the unsubscribe header, or as the List-Unsubscribe headers, and those names describe the same mechanism from the implementer's side rather than the recipient's.

The name describes the recipient's experience, which is the point. From their side it is an unsubscribe link rendered by Gmail or Outlook next to the sender's name, and pressing it ends the mailing. From the sender's side it is two headers and an endpoint that has to do the right thing when something posts to it unattended.

How it works, and why the POST matters

The List-Unsubscribe header has existed since RFC 2369 and can carry a mailto: address, an HTTPS URL, or both. On its own it gives a mail client somewhere to point an unsubscribe affordance, and following that URL loads a page where the recipient finishes the job by hand.

RFC 8058 adds the second header, which is a declaration by the sender that the URL will accept an unattended POST and act on it immediately. When both headers are present, a supporting mail client can perform the unsubscribe itself, submitting a POST with the body List-Unsubscribe=One-Click, and the recipient never leaves their inbox.

The choice of POST rather than GET is deliberate and worth understanding, because it is where naive implementations break. Anti-malware scanners, link checkers and mail-client previewers routinely fetch URLs found in messages. If unsubscribing happened on a GET, every one of those automated fetches would unsubscribe the recipient without their involvement. Requiring a POST separates a machine looking at a link from a person acting on one.

1. Step 1Headers present

   The message carries List-Unsubscribe with an HTTPS URL and List-Unsubscribe-Post declaring one-click support.

2. Step 2Client renders

   A supporting mail client shows its own unsubscribe control beside the sender.

3. Step 3POST

   On use, the client posts List-Unsubscribe=One-Click to the URL. The recipient stays in their inbox.

4. Step 4Honour it

   The endpoint suppresses the address immediately, with no confirmation step and no login.

Where the definition misleads

It is a header pair plus a working endpoint, and the endpoint is the hard half. Publishing the headers is trivial. Standing up a URL that accepts an unauthenticated POST, identifies which recipient it refers to, suppresses them across the whole programme, and returns success is the actual work. A header advertising an endpoint that does not act is worse than no header, because the recipient believes they have unsubscribed.

Requiring a confirmation step defeats it. The recipient has already acted, in their mail client. An endpoint that responds by presenting a preferences page is not implementing one-click, and the person who pressed the button will reasonably assume they are done. When the next message arrives, the button they press is the junk one.

The obligation is not universal, and the threshold matters. Google's sender guidelines require one-click unsubscribe for marketing and subscribed messages, where a sender exceeds 5,000 daily messages to Gmail accounts. The same guidance asks for a clearly visible unsubscribe link inside the message body. A cold outbound programme spread across many low-volume mailboxes may sit below that threshold, which changes the compliance question and does not change the practical one.

An easy opt-out is separately required by law, whatever the volume. The FTC's CAN-SPAM compliance guide requires a working opt-out mechanism, honoured within 10 business days and functioning for at least 30 days after the message is sent, and states that the law makes no exception for business-to-business email. One-click is a good way to satisfy that. It is not the only way, and being under a provider's threshold is not an exemption from the statute.

A visible link in the body still earns its place. Not every client supports the header, and a recipient who cannot find an obvious way out has one guaranteed alternative available in every client ever made. Every use of it costs more than an unsubscribe would have.

List-Unsubscribe onlyRFC 2369

• Gives the mail client somewhere to point
• The recipient follows a link and finishes by hand
• Vulnerable to automated fetchers acting on the URL
• Widely supported for many years

Plus List-Unsubscribe-PostRFC 8058

• Declares the endpoint accepts an unattended POST
• The client completes the unsubscribe itself
• A POST distinguishes a person from a scanner
• Required by major providers above their volume thresholds

What this means when you are running outbound

The compliance framing is the less interesting half. The operational case for making opting out easy is that the alternative is worse in every measurable way.

A recipient who wants out has two buttons available. One removes them from your list and tells you nothing beyond that. The other reports the message as spam, and that signal feeds directly into the reputation that governs whether your next campaign reaches anybody. Making the first button easy to find is the cheapest protection available against the second, and it converts a reputational cost into a routine list update.

That reframes the trade people worry about. A visible, frictionless opt-out will be used slightly more often than a buried one, and the marginal person it loses is a person who was not going to reply. What it prevents is a complaint, and complaints are weighed heavily by every mailbox provider. Google's guidelines ask senders to keep the spam rate reported in Postmaster Tools below 0.3%, which is a small budget to spend on people who could have unsubscribed instead.

The mailto variant, and when it is the pragmatic answer

List-Unsubscribe also accepts a mailto: address, and for a small programme that is a legitimate implementation rather than a lesser one. The client sends a message to the nominated address, something reads that mailbox, and the address is suppressed. No web endpoint, no tokens, no unauthenticated POST to secure.

It has two costs worth naming. It does not qualify as one-click under RFC 8058, which requires the HTTPS POST form, so it does not satisfy the providers that require one-click above their volume thresholds. And it moves the work to a mailbox that has to be processed reliably, which is the same failure mode as unprocessed bounces: an address exists, mail arrives, nothing happens, and nobody notices until somebody who opted out weeks ago receives another message.

Where a programme sends from many mailboxes at low individual volume, publishing both forms is the sensible position. The mailto covers clients that use it, the HTTPS POST covers the providers that require it, and both feed the same suppression store.

Getting the endpoint right

Three properties separate a working implementation from a decorative one.

It has to act without authentication, because the POST arrives from a mail client with no session and no login. That means the URL itself has to identify the recipient, usually through an unguessable token generated per message, and the token has to remain valid long enough to be useful. It has to suppress across the whole programme rather than the campaign that generated the request, since an opt-out honoured in one tool and not another is an opt-out that fails at the next send. And it has to be permanent, written to the suppression list every future campaign consults rather than to a per-campaign flag.

The way to check is to use it. Send yourself a message, press the button your mail client renders, and confirm that a suppression entry now exists and that a subsequent campaign build excludes the address. Reading the code is not the same test, because the failure mode here is an endpoint that returns success and does nothing.

A one-click unsubscribe that actually works

• ✓Yes: Both List-Unsubscribe and List-Unsubscribe-Post headers are present
• ✓Yes: The URL accepts an unauthenticated POST and acts on it immediately
• ✓Yes: No confirmation page, login, or preference step stands in the way
• ✓Yes: Suppression applies across every campaign and every sending tool
• ✓Yes: A visible unsubscribe line remains in the message body
• ✕No: Publishing the headers before the endpoint has been tested end to end

One warning about the token in the URL. Because the endpoint accepts an unauthenticated request, the token is the only thing identifying the recipient, and a guessable one lets anybody unsubscribe anybody. Generating it from something predictable, an incrementing identifier or a hash of the address, is the mistake to avoid. A random value stored against the send is the whole fix, and it costs nothing at build time.

The short version

One-click unsubscribe is two headers and a URL that honours a POST without argument. The specification is short, the implementation is a morning's work, and the failure mode is an endpoint that advertises more than it delivers, which is invisible from the sending side and obvious to the person who pressed the button.

Beyond the compliance requirements, which depend on volume and jurisdiction, the case for it is straightforward: every person who unsubscribes cleanly is a person who did not report you as spam, and complaint rate is one of the few signals that damages a sending programme quickly and heals slowly. Make the exit obvious, make it work in one action, and enforce it everywhere. The rest of the sending-side work, authentication, domain reputation and monitoring what actually moves placement, assumes you are not spending reputation on people who asked to leave.

RevenueFlow runs cold email and LinkedIn outreach for B2B teams, one message per campaign, with opt-outs honoured across the whole programme. See how the campaigns work.

Standards and platform requirements verified as of August 2026 against RFC 8058, RFC 2369, Google's published sender guidelines and the FTC's CAN-SPAM guidance. Verify current obligations with counsel and with the source before relying on them.