Skip to main content
Relaymetry

One-Click Unsubscribe (RFC 8058): the List-Unsubscribe Headers Gmail and Yahoo Require

Gmail and Yahoo require bulk senders to support one-click unsubscribe on marketing and subscribed mail. You signal it with two headers working together: a `List-Unsubscribe` header carrying an HTTPS URI, and a `List-Unsubscribe-Post: List-Unsubscribe=One-Click` header. When the recipient clicks the provider’s built-in control, the provider sends an HTTPS POST – not a GET – to your URL, and the unsubscribe must complete with no further interaction. Both headers must be covered by your DKIM signature, and you must honor the request within two days.

Quick answer

Gmail and Yahoo require bulk senders to support one-click unsubscribe on marketing and subscribed mail. You signal it with two headers working together: a List-Unsubscribe header carrying an HTTPS URI, and a List-Unsubscribe-Post: List-Unsubscribe=One-Click header. When the recipient clicks the mailbox provider's built-in unsubscribe control, the provider sends an HTTPS POST to your URL and the unsubscribe must complete with no further interaction. Both headers must be covered by your DKIM signature, and you must honor the request within two days.

What one-click unsubscribe is

One-click unsubscribe is a requirement Gmail and Yahoo applied to bulk senders in early 2024. It targets the mail that recipients subscribed to: marketing campaigns, newsletters, and similar subscribed messages. Google's sender guidelines state that, for senders of roughly 5,000 or more messages per day to Gmail, marketing and subscribed messages must support one-click unsubscribe through the List-Unsubscribe and List-Unsubscribe-Post headers. Yahoo published a parallel requirement in February 2024.

The mechanism is not a single new header. It is two headers that work together:

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

The first header is defined by RFC 2369. It carries the unsubscribe URI. For one-click support it must contain an HTTPS URI; you may also list a mailto: URI alongside it. The second header is defined by RFC 8058. Its value is exactly the string List-Unsubscribe=One-Click. The presence of this second header is what tells the mailbox provider that the HTTPS URI accepts a one-click POST.

How the one-click POST works

RFC 8058 defines the runtime behavior. When the recipient clicks the unsubscribe control that Gmail or Yahoo renders next to the sender name, the mail receiver does not open your link in the browser. Instead the receiver performs an HTTPS POST directly to the HTTPS URI in your List-Unsubscribe header. The request body is List-Unsubscribe=One-Click, sent as application/x-www-form-urlencoded or multipart/form-data.

The distinction that trips senders up is the verb. The provider sends a POST, not a GET. A URL that only works when opened in a browser, that returns a landing page, or that asks the user to log in or confirm will fail the requirement. After the click, the unsubscribe must complete with no further manual interaction: no landing page, no login, no confirmation step. The single click is the whole transaction.

This is also why the body string matters. Receiving the POST body List-Unsubscribe=One-Click is your signal that the request came from a genuine one-click action rather than from a link scanner or spam filter prefetching the URL. Your endpoint should act on the POST and treat a bare GET differently.

Why the headers must be DKIM-signed

RFC 8058 makes this a hard requirement: both the List-Unsubscribe and List-Unsubscribe-Post headers MUST be covered by the DKIM signature. In practice that means both header names must appear in the h= tag of your DKIM-Signature header. If the headers are present in the message but excluded from the DKIM signature, the one-click guarantee is not protected against tampering, and a receiver can legitimately ignore it.

This ties one-click unsubscribe directly to a clean DKIM setup. A sender whose DKIM signing is broken, or whose ESP signs only a minimal set of headers, can publish both unsubscribe headers and still fail the requirement because the headers are not inside the signed scope. Verify your DKIM signature first, then confirm the two list headers are in the signed h= list.

Gmail and Yahoo specifics

Gmail's requirement is stated in terms of the two headers. For senders above the bulk threshold, marketing and subscribed messages must support one-click unsubscribe via the List-Unsubscribe and List-Unsubscribe-Post headers, per RFC 2369 and RFC 8058.

Yahoo's requirement is slightly broader in how it is described. Yahoo asks for a functioning list-unsubscribe header that supports one-click; it strongly recommends the RFC 8058 POST method and accepts a mailto: method as well. Yahoo additionally asks that you keep a clearly visible unsubscribe link in the body of the email, not only in the headers. Both Gmail and Yahoo require that you honor unsubscribe requests within two days. See Yahoo's sender best practices for the current text.

The practical reading of both sets of requirements is the same: ship the two headers, point the HTTPS URL at an endpoint that accepts a POST and unsubscribes immediately, sign the headers with DKIM, keep a visible in-body link, and process opt-outs within two days.

Common mistakes

Several recurring errors cause senders to fail the requirement even when they believe they support unsubscribe:

  • Only a mailto: method, no HTTPS one-click. A mailto: URI is acceptable as an additional method, but on its own it does not satisfy the HTTPS one-click POST behavior that the providers look for. Include an HTTPS URI and the List-Unsubscribe-Post header.
  • A URL that needs a GET, shows a landing page, or requires login. The provider sends a POST and expects the unsubscribe to complete with no further interaction. Any page that asks the user to click again, confirm, or sign in breaks the one-click contract.
  • Headers not covered by DKIM. Both list headers must be in the DKIM h= tag. Headers present but unsigned do not meet RFC 8058.
  • Not honoring requests within two days. A working header that does not actually suppress the address within the two-day window still fails the requirement.
  • Putting the headers on transactional mail that does not need them. The requirement is for marketing and subscribed bulk mail. Adding one-click unsubscribe to password resets, receipts, and other transactional messages is unnecessary and can let recipients opt out of mail they need.

What this does not prove

Confirming that your message carries both headers, that the HTTPS URL accepts a POST, and that the headers are inside the DKIM signature tells you the message is correctly formed for one-click unsubscribe. It does not tell you whether your suppression list actually removes the address, whether your sending reputation is healthy, or whether a given campaign reached the inbox. One-click unsubscribe is one of several bulk-sender requirements; it sits alongside DMARC, a low spam-complaint rate, and clean authentication. A public check can verify your DNS and authentication baseline, but it cannot see what your unsubscribe endpoint does after the POST arrives, or whether opt-outs are processed within the two-day window.

Frequently asked questions

Is a mailto: unsubscribe enough, or do I need the HTTPS one-click method?

A mailto: URI is acceptable as an additional method, and Yahoo lists it as acceptable, but on its own it does not satisfy the HTTPS one-click behavior the providers look for. One-click unsubscribe requires a List-Unsubscribe header carrying an HTTPS URI plus the List-Unsubscribe-Post: List-Unsubscribe=One-Click header. When the recipient clicks, the provider performs an HTTPS POST to that URL — not a GET, and not an email to a mailbox. List the mailto: URI if you like, but the HTTPS method is what meets the bulk-sender requirement.

Do the List-Unsubscribe headers need to be covered by my DKIM signature?

Yes. RFC 8058 requires that both the List-Unsubscribe and List-Unsubscribe-Post headers be covered by the DKIM signature — meaning both header names must appear in the h= tag of your DKIM-Signature header. Headers that are present in the message but excluded from the signed scope do not meet the requirement, and a receiver can legitimately ignore the one-click guarantee. This is why a clean, correctly scoped DKIM setup is a prerequisite, not an optional extra.

Do transactional emails (receipts, password resets) need one-click unsubscribe?

No. The requirement is for marketing and subscribed bulk mail, not transactional messages. Receipts, password resets, and other transactional mail do not need the one-click unsubscribe headers, and adding them is unnecessary. It can also be counterproductive, because it lets recipients opt out of mail they actually need to receive. Scope the headers to the marketing and subscribed streams the providers are asking about.

What exactly does the mailbox provider send when the recipient clicks unsubscribe?

The provider performs an HTTPS POST to the HTTPS URI in your List-Unsubscribe header, with the request body List-Unsubscribe=One-Click sent as application/x-www-form-urlencoded or multipart/form-data. It does not open the URL in a browser and does not send a GET. After that single POST, the unsubscribe must complete with no further manual interaction — no landing page, no login, and no confirmation step. Your endpoint should act on the POST and process the opt-out immediately.

How quickly do I have to process an unsubscribe request?

Gmail and Yahoo both require that you honor unsubscribe requests within two days. A working header that does not actually suppress the address within that window still fails the requirement. Make sure the endpoint behind your HTTPS URL writes to your suppression list synchronously, or at least within the two-day bound, and that the suppression is honored across every system that sends as your domain.

Other bulk sender requirements

References