One-Click Unsubscribe (RFC 8058): What Gmail and Yahoo Actually Require

In February 2024, Gmail and Yahoo turned years of "best practice" into enforcement: bulk senders must authenticate, stay under complaint thresholds, and support one-click unsubscribe — or watch their mail get filtered regardless of content. The one-click piece is the most misunderstood requirement, because it's not about the link in your footer. Here's the mechanism, precisely.

The two headers that make one-click work

RFC 8058 one-click unsubscribe is implemented entirely in message headers:

List-Unsubscribe: <https://mail.acme.com/u?token=abc123>, <mailto:unsub@acme.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

• List-Unsubscribe (RFC 2369) advertises where unsubscribes go — an HTTPS URL, a mailto:, or both. This header alone is what makes Gmail show the native Unsubscribe button next to your sender name.
• List-Unsubscribe-Post (RFC 8058) is the one-click upgrade: it promises that a bare POST to the HTTPS URL with body List-Unsubscribe=One-Click completes the unsubscribe — no login, no confirmation page, no "are you sure?" survey.

When a Gmail user clicks that native button, Google's servers send the POST for them. The user never sees your website; the unsubscribe just happens. That's the contract you're implementing.

The endpoint: POST acts, GET never does

This is where implementations go wrong in a way that quietly destroys lists. Security appliances (Outlook Safe Links, Proofpoint, Mimecast) follow GET links in email automatically to scan them. If visiting your unsubscribe URL with GET unsubscribes the recipient, those scanners unsubscribe your users the moment mail arrives — you'll see unsubscribe rates spike with zero human intent.

The correct shape:

GET  /u?token=...   → 200, show a page with an "Unsubscribe" button (no state change)
POST /u?token=...   → 200, unsubscribe immediately (this is what mailbox providers call)

Signed, single-purpose tokens in the URL (no session required — the recipient may open it in any browser), idempotent handling (two POSTs = still unsubscribed, still 200), and completion within RFC 8058's expectations — Google says honor requests within two days; immediately is the only sensible implementation.

What mail gets the headers

Marketing and promotional email: always. Newsletters, product announcements, campaigns, digests. This is also where complaint math matters — every person who can't find unsubscribe finds Report spam instead, and complaints above 0.3% at Gmail are a cliff.

Transactional email: never. Receipts and password resets aren't subscriptions; an unsubscribe header on them confuses recipients and providers alike. The transactional/marketing split is the architecture that keeps this clean.

Notification email: per-topic. "Weekly digest" and "comment replies" deserve separate opt-outs. Topic-scoped subscriptions (MailBlastr calls them topics) let a recipient mute one stream while keeping the rest — which converts would-be full unsubscribes into preference changes.

Beyond the headers: the rest of the bulk-sender bar

One-click is one item on Gmail and Yahoo's checklist. The full set, all covered elsewhere on this blog:

1. SPF and DKIM passing, DMARC published, From: aligned
2. Spam complaint rate below 0.3% (target under 0.1%)
3. One-click unsubscribe on commercial mail, honored within 2 days
4. Valid forward and reverse DNS on sending IPs (your provider's job)

What your email platform should do for you

Hand-rolling this means header injection, a token scheme, a POST endpoint, suppression sync, and per-topic state. A platform should make it disappear: MailBlastr adds the RFC 8058 headers and compliant footer to every campaign automatically, processes the provider-initiated POSTs, applies unsubscribes to suppressions instantly, and exposes per-topic preferences — so compliance is the default, not a project. If your current provider leaves the headers to you, that's a real migration reason; the free tier is enough to verify the whole flow end to end with a Gmail address of your own.