Is one-click unsubscribe a law?

No, it is a mailbox-provider requirement and a technical standard (RFC 8058), not a statute. In the United States, the CAN-SPAM Act separately requires a clear in-message opt-out mechanism that you honor within 10 business days, but it does not name RFC 8058. Treat CAN-SPAM compliance as a separate legal requirement rather than assuming that the header alone satisfies it.

What is the List-Unsubscribe-Post header?

It is the header that turns a List-Unsubscribe URL into a one-click action. RFC 8058 says it must contain the single key/value pair List-Unsubscribe=One-Click, and it must be covered by the DKIM signature. Without it, a mailbox treats List-Unsubscribe as the older, multi-step method from RFC 2369 instead of offering one-click.

Do I need one-click unsubscribe if I send low volume?

Not always. Google applies the RFC 8058 requirement to senders of more than 5,000 messages per day to Gmail, while Yahoo describes its scope as bulk senders and calls the RFC 8058 POST method highly recommended. Check the provider and message type that apply to your campaign, and keep a visible unsubscribe link regardless.

Does one-click unsubscribe replace the unsubscribe link in the email body?

No, they are separate requirements. Google requires both the RFC 8058 header pair and a clearly visible unsubscribe link inside the message for the covered bulk senders. Yahoo also requires an easy unsubscribe mechanism and a visible link, while describing the RFC 8058 POST method as highly recommended. The header can drive a mailbox's built-in Unsubscribe control; the in-body link still serves recipients whose client does not render that control.

What should I test after configuring one-click unsubscribe?

Send a real test message through the same platform and campaign path, then inspect the raw source. For RFC 8058, confirm the exact header pair, HTTPS URL, and DKIM h= coverage described above. Test the endpoint's POST behavior without cookies, sign-in, or redirect, and compare the result with the current Gmail or Yahoo guidance that applies to your send.

One-click unsubscribe and the RFC 8058 header pair

One-click unsubscribe is the method defined in RFC 8058 that adds a List-Unsubscribe and List-Unsubscribe-Post header pair to bulk mail, so a supported mailbox can show an Unsubscribe control that removes the recipient with a single action. Google requires that RFC 8058 implementation from senders of more than 5,000 messages a day to Gmail. Yahoo expects bulk senders to provide a functioning List-Unsubscribe mechanism that supports one-click, and calls the RFC 8058 POST method highly recommended. It is a mailbox-provider requirement and a technical standard, not a law.

At a glance

Quick takeaways

One-click unsubscribe is defined by RFC 8058 (2017), which signals one-click support for the older List-Unsubscribe header from RFC 2369 (1998).
It needs a header pair: List-Unsubscribe with an HTTPS URL, plus List-Unsubscribe-Post: List-Unsubscribe=One-Click.
The action is an HTTPS POST from the mailbox provider to the sender's endpoint, not a click on the sender's website.
Google requires RFC 8058 one-click unsubscribe for senders of more than 5,000 messages per day to Gmail. Yahoo expects bulk senders to provide a functioning List-Unsubscribe mechanism that supports one-click, calls the RFC 8058 POST method highly recommended, and says to honor requests within 2 days.
It does not replace the visible unsubscribe link that Google and Yahoo also require in the message body.
It is a provider requirement and a technical standard, not a statute, so it sits alongside laws such as CAN-SPAM rather than replacing them.

Who is affected?

This requirement targets sending operators, not recipients. If your team runs bulk campaigns to consumer mailboxes through an ESP, CRM, or marketing platform, check the recipient provider's current guidance for your marketing and subscribed messages. The recipient never configures anything; your sending platform composes the headers, and a supporting mailbox can render the control.

One-click unsubscribe is the automated half of "let people opt out easily." The List-Unsubscribe header itself is older: RFC 2369 defined it in 1998 so mail clients could offer a built-in unsubscribe command for mailing lists. RFC 8058 added the one-click signal on top of it in 2017, so a mailbox can complete the opt-out without opening a web page or sending a message.

Keep this rule separate from the authentication rule. Gmail and Yahoo require bulk senders to pass SPF, DKIM, and DMARC as well, which is a different pillar of the same ruleset. If you are still mapping those, start with what email authentication is and why it matters and the full Gmail and Yahoo sender requirements. One-click unsubscribe is about list hygiene and opt-out plumbing; authentication is about proving who sent the message.

What are the requirements?

The `List-Unsubscribe` and `List-Unsubscribe-Post` header pair

RFC 8058 requires two header fields in each message. The List-Unsubscribe header must contain one HTTPS URI and may also contain a mailto: URI. The List-Unsubscribe-Post header must contain the single key/value pair List-Unsubscribe=One-Click. The presence of both is what tells a mailbox that one-click is available.

Technical exampletext

List-Unsubscribe: <https://example.com/unsubscribe?token=EXAMPLE>, <mailto:unsubscribe@example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Vertical RFC 8058 header-pair diagram: List-Unsubscribe and List-Unsubscribe-Post need valid DKIM coverage, while an opaque URI separately protects the endpoint. — Source: Original Palisade diagram based on RFC 8058. It separates the required header pair, valid DKIM coverage, and opaque-URI endpoint hardening. Open the full-size diagram.

The values above are illustrative. Your sending platform generates the real endpoint and token for each recipient.

The one-click POST request

One-click unsubscribe is an action the mailbox provider performs, not the recipient. When someone selects the Unsubscribe control, the provider sends an HTTPS POST to the HTTPS URL in the List-Unsubscribe header. RFC 8058 says the mailbox provider should send the one-click POST as multipart/form-data and may send application/x-www-form-urlencoded instead, so an interoperable unsubscribe endpoint accepts either encoding. The POST must not carry cookies or HTTP authorization, and the sender must not answer it with an HTTPS redirect.

DKIM must cover both headers

RFC 8058 requires the List-Unsubscribe and List-Unsubscribe-Post headers to be covered by a valid DKIM signature and listed in its h= tag. That lets a receiving mailbox verify that the associated domain signed those header fields. RFC 8058 also recommends an opaque, hard-to-forge component in the HTTPS URI, because DKIM coverage does not by itself stop someone from sending a direct unsubscribe request.

The figure below traces the exchange, from the headers a sender adds to the POST that reaches the receiving endpoint.

Vertical RFC 8058 flow: sender adds both headers, an eligible mailbox provider offers Unsubscribe, the provider sends a POST, and the sender endpoint suppresses the address. — Source: Original Palisade diagram of the RFC 8058 one-click unsubscribe flow. It shows the header-driven exchange and does not depict a specific mailbox interface or a real endpoint.

View the full-size diagram

When does the requirement take effect?

Google's Email sender guidelines set February 1, 2024 as the date these requirements took effect for senders of more than 5,000 messages per day to personal Gmail accounts. Marketing and subscribed messages from those senders must support one-click unsubscribe and still include a visible unsubscribe link in the body. Google's sender-guidelines FAQ documented a transition exception: senders that already included an unsubscribe link in their messages had until June 1, 2024 to add one-click unsubscribe to commercial and promotional messages. That historical exception did not create an alternate current scope. Treat the live guidelines and FAQ as the source of truth for the current threshold and dates.

Yahoo's Sender Hub best practices set a related expectation: bulk senders must implement a functioning List-Unsubscribe header that supports one-click for marketing and subscribed messages, and honor unsubscribe requests within 2 days. Yahoo calls the RFC 8058 POST method highly recommended rather than mandatory, and says a mailto: option is acceptable.

For the wider context of the 2024 change, including spam-rate and authentication rules, see our companion guide to the Gmail and Yahoo 2024 sender update. The header standard itself is stable: RFC 8058 has been a Proposed Standard since January 2017.

How do I implement the requirement?

1. Add the header pair in your sending platform

Find the unsubscribe or subscription-management setting in your sending platform, then check its current documentation and a delivered test message. For an RFC 8058 implementation, the message must contain both headers rather than only the older List-Unsubscribe field. The List-Unsubscribe URL must be HTTPS.

2. Serve a one-click POST endpoint

The HTTPS URL in List-Unsubscribe must accept an HTTPS POST and unsubscribe the recipient without asking them to sign in or confirm on a web page. If you host the endpoint yourself, accept both multipart/form-data and application/x-www-form-urlencoded bodies, do not require cookies or HTTP authorization, and do not respond with a redirect. If a vendor hosts the endpoint, verify the same behavior in a delivered-message test.

3. Honor opt-outs and keep the visible link

Process each opt-out on your side quickly. Yahoo tells bulk senders to honor unsubscribes within 2 days, and you must keep the clearly visible unsubscribe link in the message body, which Google and Yahoo both still require. One-click unsubscribe supplements that link; it does not replace it.

How do I validate compliance?

Validate at the message level, because this rule lives in the mail headers rather than in DNS. Send a test campaign to a Gmail address and a Yahoo address, then open the raw message source in each. To confirm RFC 8058, check that List-Unsubscribe carries an HTTPS URL, List-Unsubscribe-Post: List-Unsubscribe=One-Click is present, and a valid DKIM signature covers both headers in its h= tag. For Yahoo, also compare the result with its current guidance, which says a mailto: option is acceptable. Check whether the mailbox shows its built-in Unsubscribe control next to the sender name.

Public authentication checks are a different layer. A tool such as the email security score reviews your SPF, DKIM, and DMARC posture, which is another pillar of the Gmail and Yahoo rules, but it does not read the List-Unsubscribe header or prove one-click works. DNS lookups and DMARC aggregate reports also say nothing about the unsubscribe header, so do not treat a clean authentication result as unsubscribe compliance.

Confirm the rest of your bulk sender setup

One-click support is one part of the current Gmail and Yahoo bulk-sender guidance. The providers also specify authentication, spam-rate, TLS, formatting, and other requirements. If you are working through a bulk-sender warning, confirm the whole checklist rather than treating the header as the only requirement.

See the full Gmail and Yahoo bulk sender checklist

The List-Unsubscribe header is configured in the platform that sends your mail. Keep the result of this message-level check separate from your SPF, DKIM, and DMARC review: authentication can affect deliverability, but it does not prove that one-click unsubscribe works.

Evidence