One-click unsubscribe and why your footer link doesn't count

An unsubscribe link in your footer is not one-click unsubscribe. Gmail’s and Yahoo’s bulk sender rules require a specific mechanism defined in RFC 8058, and Microsoft asks for something looser: two headers, one of them a machine-readable instruction to unsubscribe the recipient with a single POST request and no page to load. A footer link that opens your website is not that, even if the button on that page says “Unsubscribe.”

The two headers

RFC 8058 needs both headers present, and they do different jobs.

The exact form, from the RFC itself:

List-Unsubscribe: <https://example.com/unsubscribe/opaquepart>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe alone is old news: it’s RFC 2369 from 1998, and mail clients have shown some form of unsubscribe button from it for years. What changed with RFC 8058, and what Gmail, Yahoo and Microsoft now build their bulk sender rules around, is the second header. Without List-Unsubscribe-Post, a client has no signal that the URL in List-Unsubscribe is safe to hit with a plain POST and no confirmation screen, so it won’t try.

What the URL has to do

The endpoint named in List-Unsubscribe must accept an HTTPS POST carrying List-Unsubscribe=One-Click in the body, as multipart/form-data or application/x-www-form-urlencoded, and unsubscribe the recipient on that request alone. RFC 8058 is specific that the request “MUST NOT include cookies, HTTP authorization, or any other context information”: the URL itself, usually a per-recipient token, is the entire authorization. No login, no session, no second click.

That also rules out a mailto-only header. A mailto: address can sit in List-Unsubscribe as a fallback, but it doesn’t satisfy the one-click requirement on its own: there’s no POST to make, so List-Unsubscribe-Post has nothing to describe. And it rules out a List-Unsubscribe URL that asks the recipient to confirm anything before it takes effect. The one-click contract ends at the POST: anything requiring a second action after it isn’t one-click, whatever the header claims.

Why POST and not GET

The obvious design would be a link the mail client opens directly. RFC 8058 rejects that because “anti-spam software often fetches all resources in mail header fields automatically, without any action by the user.” A security scanner, a spam filter, or a link-prefetching proxy sitting in front of a mailbox will follow a GET URL the moment the message arrives, before the recipient has read it. If that GET unsubscribed people, scanners would unsubscribe your entire list on your behalf, silently, the day you sent it.

A POST doesn’t have that problem, because nothing routinely issues unsolicited POST requests to URLs found in email headers. Requiring the exact body List-Unsubscribe=One-Click closes the gap further: even a POST has to carry the right payload, not just hit the URL.

The honoring window

Google’s guidance is to fulfill an unsubscribe request “within 48 hours” (Gmail sender guidelines FAQ). Yahoo’s is explicit that senders should “honor unsubscribes within 2 days” (Yahoo Sender Best Practices). Both land in the same place: a recipient who clicks unsubscribe today should be off your list within two days, not at the end of your next send cycle.

If your unsubscribe handling queues the removal for a nightly batch job, or worse, for whoever next opens the suppression list, that queue is the part to check against a two-day bar.

What each provider actually asks for

Gmail requires List-Unsubscribe and List-Unsubscribe-Post on every marketing and subscribed message, for any domain sending more than 5,000 messages a day to Gmail addresses (the same threshold covered in full in Gmail, Yahoo and Microsoft’s bulk sender rules), and names RFC 8058 directly as the standard to follow (Google’s email sender guidelines; Gmail sender guidelines FAQ). Its own consequence language is plain: fall short and “your email might not be delivered as expected, or might be marked as spam.”

Yahoo asks bulk senders to “implement a functioning list-unsubscribe header, which supports one-click unsubscribe,” and calls the RFC 8058 POST method “highly recommended,” while still allowing a mailto: fallback as acceptable (Yahoo Sender Best Practices). The same page’s stated consequence for missing any bulk sender requirement is a “negative impact to the delivery of your mail at Yahoo domains,” with no separate penalty called out for the unsubscribe mechanism specifically. In practice that means Yahoo’s own bar is a notch softer than Gmail’s on paper, but any list that also reaches Gmail addresses needs the POST method regardless, so there’s no real reason to implement a weaker version for Yahoo alone.

Microsoft is the outlier worth knowing about. Its Outlook.com postmaster policy requires domains sending more than 5,000 messages a day to fully authenticate with SPF, DKIM and DMARC, and separately requires “a mechanism for unsubscribing… clearly documented and easy for recipients to find and use” (Outlook.com Postmaster policies). That text doesn’t name RFC 8058. Microsoft’s own guidance for senders using Microsoft 365 to send bulk mail goes further in tone without going further in obligation: “a one-click option to unsubscribe is preferable for a smoother process” (Outbound spam protection, Microsoft Learn), which reads as a strong recommendation rather than a hard requirement the way Gmail’s page does. Since implementing RFC 8058 costs nothing extra once it’s built for Gmail and Yahoo, there’s no reason to leave Outlook on a weaker mechanism.

The footer link is still required, separately

None of this replaces the visible unsubscribe link in the body of the email. List-Unsubscribe is a header, invisible unless the mail client chooses to surface it as a button next to the sender’s name; some clients don’t show it at all. Anti-spam law in most jurisdictions requires a working, visible opt-out in the message itself regardless of what the headers say, and EmailFig blocks sending a campaign whose footer is missing the unsubscribe merge tag; see what every email must include. The header and the footer link are two separate obligations that happen to point at the same outcome, not one satisfying the other.

What this looks like day to day

EmailFig puts both headers on every campaign automatically, and the List-Unsubscribe URL always points at the one-click confirmation page regardless of whether the account uses a simple unsubscribe or a preference center; see customizing the unsubscribe experience and meeting Gmail and Yahoo’s bulk sender requirements. An unsubscribe through either path lands on the same suppression list, immediately, with no confirmation email and no window where the address could still receive another send.

If you’re checking your own setup rather than using a tool that handles this for you, two things to look at. First, send yourself a campaign and view the raw source: List-Unsubscribe with no List-Unsubscribe-Post next to it means you have 1998’s version, not the one Gmail, Yahoo and Microsoft are actually asking for in 2026. Second, test the endpoint itself the way a mail client would, not by clicking it in a browser (a browser GET tells you nothing about whether the POST works):

curl -i -X POST "https://example.com/unsubscribe/opaquepart" \
  -d "List-Unsubscribe=One-Click"

A response that opts the address out on that request, with nothing else in the body and no redirect to a page requiring another click, is a working implementation. Anything that 404s, redirects to a login, or silently no-ops isn’t, no matter how the header reads.

One-click unsubscribe is one requirement among several; see email deliverability for people who aren’t experts for how it fits alongside authentication, bulk sender rules, and bounce and complaint thresholds.