One-click unsubscribe law: what RFC 8058 actually requires

There is no statute called the "one-click unsubscribe law." The term people search for usually points to RFC 8058, an IETF technical standard, which Gmail and Yahoo have each turned into a bulk-sender requirement. Gmail requires it for senders of more than 5,000 messages a day to Gmail accounts, effective February 1, 2024. Yahoo lists it as a requirement for bulk senders without publishing a numeric threshold on the same page.

Who is affected?

RFC 8058 itself does not name a sending volume or a specific mailbox provider. It defines a signal that any list sender can add to outgoing mail, and a behavior any mail receiver can implement when it sees that signal.

Mailbox providers decide who has to use it. Google's Email sender guidelines state that starting February 1, 2024, senders of more than 5,000 messages per day to Gmail accounts must meet its bulk-sender requirements, which include: "Marketing messages and subscribed messages must support one-click unsubscribe, and include a clearly visible unsubscribe link in the message body." Google's page does not give a separate processing-time window for one-click compliance beyond that threshold, so nothing here should be read into it.

Yahoo's Sender Best Practices require bulk senders to "Implement a functioning list-unsubscribe header, which supports one-click unsubscribe," and describes the RFC 8058 POST method as highly recommended. Yahoo also instructs senders to "Honor unsubscribes within 2 days" and keep spam complaint rates below 0.3%. The page does not define a specific numeric bulk-sender threshold, unlike Gmail's stated 5,000-message figure.

Transactional-only senders with no marketing or subscribed messages are outside the scope both providers describe, since the requirement is written around "marketing messages and subscribed messages." A sender that only sends receipts or password resets, with no list mail, is not the audience this requirement targets, based on how Google phrases its own rule.

What are the requirements?

The message carries two headers

RFC 8058 requires a List-Unsubscribe header containing an HTTPS URI, and a List-Unsubscribe-Post header with a fixed value. Google's page shows this same header pair and links both RFC 2369 and RFC 8058 as the underlying references.

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

The URI shown here is illustrative only. The real value is generated by the sending platform or ESP for each recipient, and it should not be published or shared outside that system.

The DKIM signature has to cover both headers

RFC 8058 Section 4 requires a valid DKIM signature whose h= tag covers both List-Unsubscribe and List-Unsubscribe-Post. Without that coverage, receivers should not offer the one-click action at all. This is the point where one-click unsubscribe stops being a mail-client feature and becomes a DKIM configuration question: a signature that exists but does not list these two headers in its h= tag does not satisfy the standard, even if DKIM otherwise passes.

The receiver's POST has no cookies, login, or redirect

When a recipient clicks unsubscribe in their mail client, RFC 8058 says the mail receiver sends an HTTPS POST to the URI with List-Unsubscribe=One-Click as the body. The mailbox provider should send the POST as multipart/form-data and may send application/x-www-form-urlencoded. The endpoint must accept either encoding and complete the unsubscription from that request alone. The standard bans cookies, HTTP authorization, and redirects on that response, and recommends the URI carry an opaque, hard-to-forge token that the server verifies. A confirmation page or login wall on the other end breaks the one-click behavior, even if the headers themselves are correctly formatted.

The visible unsubscribe link stays in the message body

Google's requirement pairs one-click support with keeping "a clearly visible unsubscribe link in the message body." The header-based mechanism and the body link are not substitutes for each other under Google's stated rule. A sender that removes the visible link because the headers are present has not met the requirement as Google describes it.

When does the requirement take effect?

RFC 8058 itself was published as an IETF Standards Track document in January 2017. Publication of the RFC did not create an enforcement date on its own; that came later, from individual mailbox providers.

Google's bulk-sender requirements, including the one-click and visible-link provisions, took effect February 1, 2024, for senders of more than 5,000 messages a day to Gmail accounts. Yahoo's Sender Best Practices page states the one-click requirement for bulk senders but does not publish a specific effective date or numeric threshold on that page, so treat it as an ongoing best-practice expectation rather than a dated rollout.

How do I implement the requirement?

1. Confirm your sending platform supports RFC 8058 headers

Most major ESPs add List-Unsubscribe and List-Unsubscribe-Post automatically for list mail. Check your platform's documentation for whether it sets both headers, or only the older List-Unsubscribe field without the POST companion header, since the single-header form does not satisfy RFC 8058 on its own.

2. Verify DKIM signs both headers

Check the h= tag on your DKIM signature. If your platform signs a fixed set of headers that predates your one-click setup, List-Unsubscribe and List-Unsubscribe-Post may not be included, which means receivers should not treat the message as one-click eligible even though the headers are present.

3. Keep the visible body link

Do not remove the in-message unsubscribe link when you add header-based one-click support. Google's rule asks for both.

4. Honor unsubscribe requests promptly

Yahoo's page asks senders to honor unsubscribes within two days. Update suppression lists across every system that can still send to that recipient, not only the platform that received the POST.

5. Watch your complaint rate

Google's guidance sets 0.3% as the spam-rate ceiling in Postmaster Tools, and its separate monitoring guidance recommends staying below 0.10% rather than approaching that ceiling. A working one-click flow tends to lower complaint rates, since recipients who can unsubscribe in one step are less likely to click "report spam" instead.

How do I validate compliance?

Send a real message through your production list-sending path and inspect the raw headers, not a preview or test-mode copy. Confirm List-Unsubscribe contains an HTTPS URI and List-Unsubscribe-Post contains exactly List-Unsubscribe=One-Click. Confirm the DKIM signature's h= tag lists both header names.

Trigger the unsubscribe action from a real or test mail client where possible, and confirm the recipient is actually suppressed in your source-of-truth list system afterward, not just that the request returned a success response. A green DKIM status in your sending platform is not the same check as a delivered message with both headers correctly signed; verify the delivered message itself.

Public DNS and authentication checkers can confirm that your domain publishes valid SPF, DKIM, and DMARC records, which is the foundation DKIM signing depends on. The email security score tool checks that authentication posture from public DNS. It does not read message headers from a delivered email, and it cannot confirm whether your List-Unsubscribe headers exist, whether DKIM's h= tag covers them, or whether your unsubscribe endpoint behaves the way RFC 8058 requires. Those checks need a real delivered message and a test against your own endpoint.

Check your domain's authentication posture

A correctly signed one-click header pair depends on working DKIM in the first place. If you have not confirmed your domain's SPF, DKIM, and DMARC records are published correctly, that is worth checking before troubleshooting header coverage.

Check your domain's authentication setup

This check reads public DNS records. It cannot confirm that a specific delivered message carries the List-Unsubscribe and List-Unsubscribe-Post headers, or that your DKIM signature's h= tag covers them; that requires inspecting the message itself. For the fuller picture of what Gmail, Yahoo, and other mailbox providers currently require from bulk senders, see the sender requirements guide, and for background on the header pair itself, see one-click unsubscribe and RFC 8058.