Google and Yahoo one-click unsubscribe requirements

Is one-click unsubscribe mandatory?

One-click unsubscribe is mandatory within the scope each mailbox provider defines, and not as a universal rule. It is a mailbox-provider requirement rather than a law, and it applies to specific senders and message types rather than to every email. The matrix below is the applicability test; the sections that follow give each provider's exact wording.

A sender below Google's threshold today can cross it during a campaign, so classify message streams before a volume increase rather than after a bounce. The sender or its email service provider adds the headers and runs the endpoint; the mailbox provider decides whether to show an unsubscribe control. For the legal-versus-policy distinction in more depth, see one-click unsubscribe law.

What are the requirements?

Google requires the RFC 8058 header pair on covered messages

Google says qualifying bulk senders must support one-click unsubscribe with the List-Unsubscribe and List-Unsubscribe-Post headers defined in RFC 8058.

List-Unsubscribe: <https://unsubscribe.yourdomain.com/list/opaque-token>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

RFC 2369 defines List-Unsubscribe as a header containing one or more angle-bracket URLs for list commands. RFC 8058, a Standards Track RFC published in January 2017, requires the header to contain one HTTPS URI and adds the fixed List-Unsubscribe-Post value that tells a receiver it may perform a one-click action. Section 5 defines that value as a fixed string, not a free-text field.

The HTTPS URI should contain an opaque, hard-to-forge identifier rather than a plain recipient address or list name. RFC 8058 does not prescribe the token format; the sender is responsible for making it hard to guess and limiting it to the intended unsubscribe operation.

Google's FAQ says a mailto link can still be supported, but it does not meet Google's one-click requirement. A mailto: entry may still appear as an additional RFC 2369 list command; it does not provide RFC 8058 one-click behavior. For the protocol-level distinction, see one-click unsubscribe and the RFC 8058 header pair.

Both headers must be covered by a valid DKIM signature

RFC 8058 requires at least one valid DKIM signature on the message, and the List-Unsubscribe and List-Unsubscribe-Post headers MUST be covered by that signature, listed in the DKIM-Signature header's h= tag.

DKIM-Signature: v=1; a=rsa-sha256; d=yourdomain.com;
 h=from:to:subject:list-unsubscribe:list-unsubscribe-post;
 ...

This is an illustrative header shape only. Inspect the raw headers of a delivered message to confirm the production signature covers both fields. A platform status that says DKIM is enabled does not prove its signing configuration includes these two headers, and a later relay that adds or rewrites headers after signing breaks the coverage.

The endpoint must complete an HTTPS POST without session context

RFC 8058 says a receiving system can perform an HTTPS POST to the URI in List-Unsubscribe and send the key and value from List-Unsubscribe-Post as the request body. Google publishes this example request shape in its sender guidelines:

POST /unsubscribe/example HTTP/1.1
Host: solarmora.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26
List-Unsubscribe=One-Click

RFC 8058 says the receiver SHOULD send multipart/form-data and MAY send application/x-www-form-urlencoded. An interoperable endpoint accepts both encodings.

The endpoint cannot depend on browser state. RFC 8058 says the POST MUST NOT include cookies, HTTP authorization, or other context, and the sender MUST NOT return an HTTPS redirect, because redirected POSTs have not worked reliably. A preference center, login flow, or confirmation page may sit behind a body link, but it cannot be required to complete the RFC 8058 transaction.

The receiver also MUST NOT make the POST without user consent. The mailbox provider obtains that consent through its own interface. RFC 8058 does not require Gmail, Yahoo, or any other provider to display an unsubscribe control for every message.

Google requires a visible unsubscribe link in the body as well

Google's requirement includes a clearly visible unsubscribe link in the message body in addition to one-click support. The header-based action and the visible link are separate requirements; a List-Unsubscribe header does not replace the visible link, and Google says a preference-center link on its own does not comply with RFC 8058 without the headers.

The visible link may lead to a broader subscription-management experience. The RFC 8058 endpoint has a narrower job: it must process the POST without a web session or redirect. Keep the two paths separate when testing.

Yahoo requires a functioning list-unsubscribe header for covered mail

Yahoo's sender best practices say bulk senders should "Implement a functioning list-unsubscribe header, which supports one-click unsubscribe for marketing and subscribed messages". The same page says the POST method in RFC 8058 is "highly recommended."

Yahoo's sender FAQ describes the requirement more directly: "You must implement the list-unsubscribe header (preferably according to RFC 8058) in order to meet the requirement for one-click unsubscribe." The FAQ also says an unsubscribe link in the body of the message is not sufficient on its own.

Read those statements together. Yahoo requires a functioning list-unsubscribe header for the covered message types and identifies RFC 8058 as the preferred one-click method. Do not turn Yahoo's "highly recommended" wording for the RFC 8058 POST method into a universal Yahoo mandate.

Yahoo requires unsubscribes within two days

Yahoo's best-practices page requires senders to "Honor unsubscribes within 2 days." Its FAQ confirms: "If the unsubscribe is not honored in 2 days, then it would not meet the requirement."

This is a Yahoo-specific processing deadline. Google's sender-guidelines page states no processing deadline, so two days is not a shared Google and Yahoo requirement.

The deadline concerns the durable suppression outcome. An HTTP response from an unsubscribe endpoint does not establish that every campaign system, ESP, and production sending path will stop sending the covered mail.

What happens to noncompliant mail

Yahoo's FAQ states: "If you do not meet the requirements, your mail may be sent to the spam folder or rejected. If mail is rejected, we will return a specific error code with information about the rejection." "May" is important: Yahoo does not say every noncompliant message will be rejected, and it does not enumerate the strings.

Google's FAQ says messages that do not meet the one-click requirement are not automatically rejected or marked as spam for that reason alone. Its enforcement notice says Gmail began ramping up enforcement on non-compliant traffic in November 2025, and that affected messages can experience disruptions, including temporary and permanent rejections. Unwanted mail without an easy unsubscribe path is also more likely to be reported as spam, which feeds the complaint rate both providers cap at 0.3%.

When does the requirement take effect?

Google's sender guidelines state that the requirements for senders of close to 5,000 messages or more took effect on 1 February 2024 for personal Gmail accounts. The sender-guidelines FAQ adds that senders who already included an unsubscribe link had until June 1, 2024 to implement one-click unsubscribe in all commercial and promotional messages, and that enforcement on non-compliant traffic began ramping up in November 2025.

Yahoo's staged timeline is different. Its FAQ states: "Enforcement will begin in February 2024, and we will continue to gradually roll out enforcement as we monitor compliance metrics. Note: Enforcement of the List-Unsubscribe policy will begin in June 2024."

The February 2024 Yahoo date refers to enforcement beginning for its broader requirements. June 2024 is the source-backed enforcement date for Yahoo's List-Unsubscribe policy specifically. Do not collapse those dates into a single shared deadline.

RFC 8058 itself is not a 2024 policy. It has been a final IETF Standards Track RFC since January 2017 and builds on RFC 2369's older list-command syntax. RFC 2369 alone describes list-command links; RFC 8058 adds the signed header signal and the constrained POST flow that make the action one-click.

How do I implement the requirement?

1. Classify the traffic by recipient and message type

Measure daily volume to personal Gmail accounts, by primary domain, separately from Google Workspace recipients. For Yahoo, identify marketing and subscribed mail separately from transactional mail. Inventory every production system that sends promotional mail: ESPs, CRM campaigns, product-notification systems, and custom mail services.

Keep this classification tied to the actual production sending path. A campaign tool's audience estimate may not match final recipient routing or send volume, and a sender over Google's threshold cannot satisfy the rule by adding headers only to its largest newsletter.

2. Generate an opaque HTTPS unsubscribe URI

Configure the sending platform or list system to create a recipient-specific, hard-to-forge HTTPS URI. The endpoint needs enough information to identify the applicable subscription without asking the receiver to sign in, accept cookies, or submit another form.

Do not use a raw recipient address or reusable account identifier in the unsubscribe URI. Treat the URI as sensitive operational data and avoid exposing full values in routine logs or support tickets. Do not copy another tenant's unsubscribe URLs or identifiers.

3. Add both headers before DKIM signing

Add List-Unsubscribe with the HTTPS URI and List-Unsubscribe-Post: List-Unsubscribe=One-Click to each covered message before its DKIM signature is generated. Inspect the generated DKIM-Signature header to confirm its h= list includes both header names.

If another mail relay modifies or adds headers after signing, test the message after the final production hop. The right configuration in an upstream service can still fail if a later hop changes the signed header set.

4. Accept the one-click POST directly

Configure the endpoint to accept the exact List-Unsubscribe=One-Click body with either permitted form encoding. Process a valid request without a redirect, cookie, authorization challenge, or browser JavaScript.

Do not make the endpoint redirect to a login page, confirmation page, consent screen, or preference page. RFC 8058 says an HTTPS redirect is not part of the one-click transaction.

Make repeated valid requests safe to handle. A recipient who is already removed should remain removed after a second request, without a duplicate removal event or an error that obscures the result.

5. Keep a visible unsubscribe link in the template, and connect it to suppression

Place a clearly visible unsubscribe link in the body of every affected marketing and subscribed message. Check the rendered message, not only the template editor, because layout or content conditions can hide the link in a specific campaign.

When either path receives a valid request, remove the recipient from the list covered by that message, and make sure the suppression update reaches every production sender that can send that list's traffic. For Yahoo-covered mail, confirm the recipient is suppressed within two days. The endpoint is not a substitute for consent records or list governance across brands and systems.

For platform-specific patterns, see Mailchimp one-click unsubscribe, SendGrid one-click unsubscribe, or Braze one-click unsubscribe if one of those is part of the sending path.

How do I validate compliance?

Validate one-click unsubscribe compliance by checking four layers in order: the published DNS records, the sending platform's configuration, a delivered production message, and the unsubscribe endpoint together with the suppression list it updates. Each layer proves something the others cannot, and a green result at one layer is not evidence for the next. The message and endpoint layers are the ones that decide whether Google and Yahoo treat the mail as compliant.

• DNS: Confirm the domain's DMARC and DKIM records resolve through the authoritative DNS service and a public resolver. This confirms published DNS, not delivered-message behavior.
• Vendor: Check the sending platform's current authentication and unsubscribe configuration. A green platform status does not prove the production path adds the headers.
• Message: Send a real test message through the exact production path and inspect its raw headers. Confirm List-Unsubscribe contains an HTTPS URI, List-Unsubscribe-Post contains the exact fixed value, and a valid DKIM signature includes both header fields in its h= list. Check the rendered body for the visible link.
• Endpoint and suppression: With a safe test recipient, send the fixed POST using both multipart/form-data and application/x-www-form-urlencoded. Confirm the endpoint completes without a cookie, login, authorization header, redirect, or browser-only dependency, then verify the recipient's suppression status in the source-of-truth list system and confirm the next applicable send excludes them.

A successful unsubscribe test proves the tested path. It does not prove that every future message, recipient system, or mailbox interface will behave the same way.

Check the wider sender posture behind the unsubscribe requirement

One-click unsubscribe is one provider expectation among several. The same covered sending stream also needs authentication, alignment, transport, and spam-rate controls. Use the email security score to inspect the domain's public authentication posture, and the Gmail sender requirements guide to track the rest of Google's policy.

The score cannot verify a list-unsubscribe header, test an unsubscribe endpoint, monitor future sender changes, or prove how Gmail or Yahoo will place an individual message.