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 shows an Unsubscribe control that removes the recipient with a single action and no extra clicks. Google requires it for senders of more than 5,000 messages a day to Gmail, and Yahoo requires it for bulk senders. It is a mailbox-provider requirement and a technical standard, not a law.

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 it for senders of more than 5,000 messages per day to Gmail; Yahoo requires it for bulk senders and says to honor unsubscribes 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, the mailbox provider expects one-click unsubscribe on your marketing and subscribed messages. The recipient never configures anything; your sending platform composes the headers, and the mailbox renders 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 Google's stricter sender rules. 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.

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

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 the DKIM signature and listed in its h= tag. That coverage lets a receiving mailbox confirm the sender, not an attacker, authorized the one-click endpoint, so a forged header cannot silently opt people out.

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

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 has revised the page since the 2024 rollout, so treat the live guidelines as the source of truth for the current threshold and dates.

Yahoo's Sender Hub best practices set a parallel 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 highlights the RFC 8058 POST method as the recommended way to meet it.

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

Most ESPs and marketing platforms add the List-Unsubscribe and List-Unsubscribe-Post headers when you enable their unsubscribe or subscription-management feature. Confirm your platform advertises RFC 8058 support rather than only the older List-Unsubscribe header, then enable it on the campaigns you send at bulk volume. 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. Managed ESPs handle this endpoint for you.

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. Confirm that List-Unsubscribe carries an HTTPS URL, that List-Unsubscribe-Post: List-Unsubscribe=One-Click is present, and that both headers appear inside the h= tag of the DKIM-Signature. Check that 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 the other half 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 unsubscribe is one of three pillars in the Gmail and Yahoo rules, alongside low spam rates and SPF, DKIM, and DMARC authentication. If you are working through a bulk-sender warning, the next unresolved task is usually confirming the whole checklist, not just the header.

See Google's full sender requirements

Palisade helps manage the authentication pillar of these requirements: its documentation describes how it turns DMARC report data into prioritized SPF, DKIM, and DMARC fixes, with a human reviewing each policy change. It does not add the List-Unsubscribe header, which is configured in your sending platform, and stronger authentication supports better deliverability rather than guaranteeing inbox placement.

Sources and further reading

• RFC 8058: Signaling One-Click Functionality for List-Unsubscribe Email Header Fields
• RFC 2369: URLs as Meta-Syntax for Core Mail List Commands
• Google Email sender guidelines
• Yahoo Sender Hub best practices
• FTC CAN-SPAM Act compliance guide for business