One-Click Unsubscribe (RFC 8058) Explained

Updated

Short answer: One-click unsubscribe, defined in RFC 8058, uses two message headers: List-Unsubscribe with one HTTPS URL, and List-Unsubscribe-Post: List-Unsubscribe=One-Click. Gmail and Yahoo require it on marketing and subscribed mail from bulk senders, and Yahoo also accepts a mailto address. Microsoft doesn't require it and asks for a clear, working unsubscribe link instead.

How RFC 8058 works

RFC 8058 sets out what Yahoo calls the POST method. When someone unsubscribes, a POST request goes to the HTTPS address in your List-Unsubscribe header, so the unsubscribe can complete automatically. The core rule:

"The List-Unsubscribe header field MUST contain one HTTPS URI. It MAY contain other non-HTTP/S URIs such as MAILTO:. The List-Unsubscribe-Post header MUST contain the single key/value pair "List-Unsubscribe=One-Click"."

So a message with one-click unsubscribe carries a List-Unsubscribe header with one HTTPS URL (and, if you like, a mailto address too), plus this exact header:

List-Unsubscribe-Post: List-Unsubscribe=One-Click

The RFC adds four rules for the sender:

  • DKIM must cover both headers. "The List-Unsubscribe and List-Unsubscribe-Post headers MUST be covered by the signature and included in the "h=" tag of a valid DKIM-Signature header field." Without that, "the mail receiver SHOULD NOT offer a one-click unsubscribe for that message."
  • The URL must identify the person and the list by itself. It "MUST contain enough information to identify the mail recipient and the list from which the recipient is to be removed, so that the unsubscription process can complete automatically."
  • The request carries no context. "The POST request MUST NOT include cookies, HTTP authorization, or any other context information."
  • No redirects. "The mail sender MUST NOT return an HTTPS redirect".

What Gmail requires

For bulk senders, Google says "Marketing messages and subscribed messages must support one-click unsubscribe, and include a clearly visible unsubscribe link in the message body." Its sender guidelines tell you to "include both of these headers in outgoing messages", including List-Unsubscribe-Post: List-Unsubscribe=One-Click.

A mailto address is not enough: "We’ll continue to support mailto links but they don’t meet our one-click unsubscribe requirement. To meet our one-click unsubscribe requirement, you must use List-Unsubscribe email headers in all commercial, promotional messages, as described in RFC 8058 and in our Email sender guidelines, and include one HTTPS URL in the List-unsubscribe: header."

Other points from Google:

  • Scope. "One-click unsubscribe is required only for marketing and promotional messages. Transactional messages are excluded from this requirement."
  • Deadline. Senders that already had an unsubscribe link had "until June 1, 2024 to implement one-click unsubscribe in all commercial, promotional messages."
  • Speed. "we recommend that you fulfill unsubscribe requests within 48 hours". When Google announced the rules in October 2023, it said large senders must "process unsubscription requests within two days."
  • Consequences. "We don’t automatically reject messages or mark messages as spam when they don’t meet the one-click unsubscribe requirements in our Email sender guidelines." But "only bulk senders that meet all the requirements in our Email sender guidelines, including one-click unsubscribe, are eligible for mitigation", and requests not honored within 48 hours leave delivery support or mitigations unavailable.

What Yahoo requires

Yahoo's sender best practices ask bulk senders to:

  • "Implement a functioning list-unsubscribe header, which supports one-click unsubscribe for marketing and subscribed messages"
  • use the POST method if they can: "The Post (RFC 8058) method is highly recommended", though "The mail-to: method is acceptable"
  • "Have a clearly visible unsubscribe link in the email body - this may direct to a preference page"
  • "Honor unsubscribes within 2 days"

A link in the body doesn't count as one-click on its own: "you must implement the list-unsubscribe header (preferably according to RFC 8058) in order to meet the requirement for one-click unsubscribe." And like Google, Yahoo exempts transactional mail: "The requirement does not apply to transactional messages (e.g. order confirmations, password resets)." Yahoo began enforcing its List-Unsubscribe policy in June 2024.

What Microsoft asks for

Microsoft's rules for Outlook.com don't require one-click unsubscribe. The announcement lists unsubscribe links under "Additional Email Hygiene Recommendations": "Functional Unsubscribe Links: Provide an easy, clearly visible way for recipients to opt out of further messages, particularly for marketing or bulk mail." It doesn't mention RFC 8058.

The Outlook.com Postmaster policy page adds: "The mechanism for unsubscribing, either from individual lists or all lists hosted by the sender, must be clearly documented and easy for recipients to find and use."

Side by side

PointGmailYahooOutlook.com
One-click on bulk marketing mailRequiredRequiredNot required
RFC 8058 POST methodRequired, with one HTTPS URLHighly recommendedNot mentioned in the announcement
Mailto address onlyDoesn't meet the requirementAcceptableNot stated
Visible link in the bodyRequiredRequired, may lead to a preference pageRecommended in the announcement
Time to act on a request48 hours recommendedWithin 2 daysNot stated
Transactional mailExcludedExcludedNot stated

Set it up, step by step

  1. Add a List-Unsubscribe header with one HTTPS URL that identifies the recipient and the list on its own.
  2. Add List-Unsubscribe-Post: List-Unsubscribe=One-Click.
  3. Sign the message with DKIM, and make sure both headers are covered by the signature and listed in its h= tag.
  4. Make the URL accept a POST that carries no cookies or login, and respond without redirecting.
  5. Remove the address within 2 days. Google recommends 48 hours.
  6. Keep a clearly visible unsubscribe link in the body as well.
  7. Add the headers to marketing and subscribed mail. Transactional mail, such as order confirmations and password resets, doesn't need them.

SPF, DKIM and DMARC Explained covers the DKIM side, and Gmail and Yahoo Bulk Sender Requirements covers the other rules that come with being a bulk sender.

Common mistakes

  • A mailto address alone. Yahoo accepts it, but Gmail doesn't count it.
  • A link in the body only. Neither Gmail nor Yahoo counts it as one-click.
  • Redirecting the POST to a confirmation page. The RFC says the sender "MUST NOT return an HTTPS redirect".
  • A URL that needs a login or a cookie to know who is unsubscribing. The POST carries neither.
  • Headers outside the DKIM signature. Mail services should then not offer one-click at all.
  • Assuming Outlook.com has the same rule. Microsoft asks for a clear, working way to unsubscribe, not one-click headers. See Outlook.com Rules for High-Volume Email Senders.

Precheckly's free SPF, DKIM and DMARC checker looks up your domain's SPF, DKIM, DMARC and MX records and suggests a fix for each problem. It checks DNS only, not message headers, so check your unsubscribe headers in a message you have sent.

Sources

Not legal advice. Carrier rules and provider documentation change, so check the linked sources before you rely on them.