One-click unsubscribe and the RFC 8058 header pair

What are the requirements?

The message includes the RFC 8058 header pair

RFC 8058 says List-Unsubscribe MUST contain one HTTPS URI. The field may contain another URI, such as a mailto: URI. List-Unsubscribe-Post MUST contain the single key and value List-Unsubscribe=One-Click.

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

These values are illustrative only. Generate recipient-specific endpoint values in your own sending system. Do not publish live recipient tokens in documentation, tickets, or test messages.

The HTTPS URI needs enough information to identify the recipient and applicable list without another form submission. RFC 8058 does not prescribe a token format. Use an opaque, hard-to-forge value and avoid placing recipient data directly in the URI.

DKIM must cover both headers

RFC 8058 requires List-Unsubscribe and List-Unsubscribe-Post to be covered by a valid DKIM signature and included in the signature's h= tag. A vendor dashboard showing that DKIM is enabled does not prove that the delivered campaign message signed these particular headers.

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

This is an illustrative header fragment, not a complete DKIM signature. Your sending system generates the selector, signature data, and signed-header list.

Inspect the delivered message from the real production path. Message transformations, alternate relays, and separate campaign tools can change headers after a general configuration check. RFC 8058 also recommends an opaque or hard-to-forge component in the HTTPS URI to reduce forged-message and direct-POST risks.

The receiver sends a constrained HTTPS POST

RFC 8058 says a mail receiver can perform a one-click unsubscribe by sending an HTTPS POST to the URI in List-Unsubscribe. The mailbox provider SHOULD send multipart/form-data and MAY send application/x-www-form-urlencoded. The endpoint must accept either encoding.

List-Unsubscribe=One-Click

The POST request MUST NOT include cookies or HTTP authorization. The mail sender MUST NOT return an HTTPS redirect. The endpoint cannot depend on a browser session, login page, confirmation screen, JavaScript, or a redirected POST.

Make successful unsubscribe handling idempotent as implementation guidance. A repeated valid request for an already-suppressed recipient should leave that recipient suppressed and should not create duplicate work. RFC 8058 does not separately require idempotency, but it is appropriate for an endpoint that may receive retries.

When does the requirement take effect?

RFC 8058 was published in January 2017 as an IETF Proposed Standard. It remains the controlling protocol document for the header pair, DKIM coverage, and POST constraints. It does not establish a universal sender deadline or require receivers to render a particular interface.

Google states that its bulk-sender requirements began on February 1, 2024, for senders that send close to 5,000 messages or more to personal Gmail accounts in a 24-hour period. Google's sender guidelines FAQ documented a transition through June 1, 2024 for senders that already had an unsubscribe link and needed to add one-click unsubscribe to commercial and promotional messages.

Yahoo uses its own policy wording. Its current sender guidance says bulk senders must implement a functioning List-Unsubscribe header that supports one-click unsubscribe for marketing and subscribed messages, honor unsubscribe requests within two days, and treat the RFC 8058 POST method as highly recommended. Those are Yahoo policy terms, not amendments to RFC 8058.

For the broader, current provider checklist, use the sender requirements hub. The 2024 Gmail and Yahoo sender update provides the related historical context.

How do I implement the requirement?

1. Identify the exact production sending path

Identify the ESP, CRM, or application that composes the marketing or subscribed message. Determine where it inserts the headers and where the final DKIM signature is applied.

Send a controlled message through the same path used for recipients. A staging application, alternate return path, or separate relay can produce different headers and DKIM signatures.

2. Configure the HTTPS unsubscribe URI

Configure an HTTPS URI that the sender can use to identify the subscription and process the request without a cookie, login, HTTP authorization, or confirmation page.

If a provider operates the endpoint, compare a delivered test message with that provider's current documentation. If your team operates it, test both permitted content encodings and confirm that the endpoint returns a direct response rather than a redirect.

3. Add the one-click signal before DKIM signing

Add List-Unsubscribe-Post: List-Unsubscribe=One-Click with the HTTPS List-Unsubscribe URI. Confirm that the final valid DKIM signature includes both header names in h=.

A DKIM pass alone is incomplete evidence. The relevant question is whether the valid signature on the delivered message covers the exact one-click headers.

4. Keep the visible unsubscribe path and suppression process

Keep a visible unsubscribe link in the message body where applicable provider rules require one. Ensure the one-click endpoint updates the suppression source used by every relevant production sender, not only one campaign system.

Do not make the one-click endpoint a general account-management route. Limit it to the recipient and list represented by its opaque identifier.

How do I validate compliance?

Validate RFC 8058 at the message and endpoint layers.

• Send a real test campaign through the production path and inspect its raw headers.
• Confirm List-Unsubscribe includes an HTTPS URI and List-Unsubscribe-Post has the exact one-click value.
• Check a valid DKIM-Signature header and confirm its h= tag covers both one-click headers.
• Send controlled POST requests using multipart/form-data and application/x-www-form-urlencoded.
• Confirm neither request needs cookies or HTTP authorization and neither receives an HTTPS redirect.
• Use a safely testable recipient, then verify that the source-of-truth suppression system records the removal.
• Repeat a valid request to test idempotent handling, then test an invalid or expired token without exposing recipient data in logs.

Confirm the rest of your bulk sender setup

After you have validated the delivered message and endpoint behavior, review the wider Gmail and Yahoo requirements that apply to your sending program.

See the full Gmail and Yahoo bulk sender checklist

That checklist and public authentication checks do not prove that a delivered message includes the RFC 8058 header pair or that its unsubscribe endpoint accepts the required POST.