Honest Intros Sign in

Guide

RFC 8058 explained: one-click unsubscribe in plain English

Two email headers and one HTTPS request. Here is what the standard says, line by line, and who now requires it.

Updated · By Otman Ounana · How we research

Short answer

RFC 8058 is the standard behind one-click unsubscribe. An email carries a List-Unsubscribe header with one HTTPS address and a List-Unsubscribe-Post: List-Unsubscribe=One-Click header; the mail client unsubscribes the reader by sending an HTTPS POST to that address [1]. Gmail requires it for marketing email from bulk senders [2].

The problem it solves

Unsubscribe links used to be ordinary links. The trouble is that security scanners open links by themselves. As the RFC puts it, "anti-spam software often fetches all resources in mail header fields automatically, without any action by the user" [3]. A link that unsubscribed on a simple visit could be triggered by a scanner, so senders added a confirmation page, and unsubscribing stopped being one click. RFC 8058 fixes this with a different kind of request, a POST, that the mail client sends only when the person asks.

The two headers

List-Unsubscribe: <https://example.com/u/7f3a9c>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The address should identify both the person and the list, so the unsubscribe can complete with no further step. In practice that means a signed token in the URL, not an email address in plain text.

What your server has to do

  1. Accept an HTTPS POST to the address, whose body is List-Unsubscribe=One-Click [1].
  2. Unsubscribe the person straight away. The request carries no cookies and no login: "The POST request MUST NOT include cookies, HTTP authorization, or any other context information" [6]. Everything you need must be in the URL.
  3. Answer the request itself. Do not redirect it to a confirmation page.
  4. Keep a page for people who click the link in a browser (a GET), with a button that confirms. Scanners load that page too, so loading it must not unsubscribe anyone.

The DKIM rule

Both headers must be covered by the message's DKIM signature, listed in its h= tag [7]. Otherwise anyone could add an unsubscribe header to your mail. If you send through a provider, check that its signature includes these two headers.

Who requires it

WhoWhat they require
Google (Gmail)Marketing and subscribed messages must support one-click unsubscribe and show a visible unsubscribe link [2]. The requirements in that section apply to senders of more than 5,000 messages a day to Gmail accounts [8]. Google recommends honouring unsubscribes within 48 hours [9].
YahooBulk senders need a working one-click list-unsubscribe header and must honour unsubscribes within 2 days [10].
The lawLaws ask for a working way to opt out and set deadlines, but do not name RFC 8058. In the US, "You must honor a recipient's opt-out request within 10 business days" [11]. See the law by country.

Does a low-volume cold email need it?

If you send a few dozen emails a day from your own mailbox, Google's bulk sender rules do not apply to you, and the law only asks for a working opt-out. One-click unsubscribe is still worth having: it is the easiest way for someone to say no without marking you as spam, and a spam report costs you far more than an unsubscribe.

A checklist

How Honest Intros does it

Every email Honest Intros sends carries both headers, with a signed token that names the recipient. A POST to that address stops all further email to the person straight away, with no login; opening the link in a browser shows a button and changes nothing until it is pressed.

Questions

Is RFC 8058 required by law?

No. It is a technical standard. The law asks for a working opt-out; Gmail and Yahoo require one-click unsubscribe from bulk senders.

Why does one-click unsubscribe use POST and not a normal link?

Because security scanners open normal links by themselves. A POST is only sent by the mail client when the reader asks to unsubscribe, so a scanner cannot unsubscribe anyone by accident.

Is a mailto unsubscribe address enough?

Not for one-click. RFC 8058 requires one HTTPS address in the List-Unsubscribe header. A mailto address can sit alongside it for older mail clients.

How fast must I honour an unsubscribe?

Google recommends within 48 hours and Yahoo asks for within 2 days. Laws set their own limits, such as 10 business days under the US CAN-SPAM Act.

See what it would write for you

Type your website. Honest Intros reads it and shows the kind of first email it writes, quoting your own pages.

Free to start. Nothing is sent until you approve it.

Read next

  • Send cold email from your own Gmail, safelyHow to send cold email from your own Gmail without hurting your reputation: daily limits, warm-up, working hours, unsubscribe and bounce brakes.
  • "Where did you get my email?"What GDPR requires when someone asks where you got their email address after a cold email, with three replies you can send and what to do if they object.
  • UK: is it a sole trader?Under PECR you may email UK companies and LLPs, but sole traders and some partnerships count as individuals. How to check a business in three minutes, with a decision table.

Sources

  1. IETF, RFC 8058, section 3.2. “A mail receiver can do a one-click unsubscription by performing an HTTPS POST to the HTTPS URI in the List-Unsubscribe header. It sends the key/value pair in the List-Unsubscribe-Post header as the request body.” Read on 1 October 2026.
  2. Google, Email sender guidelines. “Marketing messages and subscribed messages must support one-click unsubscribe, and include a clearly visible unsubscribe link in the message body.” Read on 1 October 2026.
  3. IETF, RFC 8058, section 1. “But anti-spam software often fetches all resources in mail header fields automatically, without any action by the user, and there is no mechanical way for a sender to tell whether a request was made automatically by anti-spam software or manually requested by a user.” Read on 1 October 2026.
  4. IETF, RFC 8058, section 3.1. “The List-Unsubscribe header field MUST contain one HTTPS URI.” Read on 1 October 2026.
  5. IETF, RFC 2369: The Use of URLs as Meta-Syntax for Core Mail List Commands. “The List-Unsubscribe field describes the command (preferably using mail) to directly unsubscribe the user (removing them from the list).” Read on 1 October 2026.
  6. IETF, RFC 8058, section 3.2. “The POST request MUST NOT include cookies, HTTP authorization, or any other context information.” Read on 1 October 2026.
  7. IETF, RFC 8058, section 4. “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.” Read on 1 October 2026.
  8. Google, Email sender guidelines. “Starting February 1, 2024, email senders who send more than 5,000 messages per day to Gmail accounts must meet the requirements in this section.” Read on 1 October 2026.
  9. Google, Email sender guidelines FAQ. “To reduce spam reports, protect your sending reputation, and keep your email lists healthy, we recommend that you fulfill unsubscribe requests within 48 hours, a reasonable timeline for removing recipients from a mailing list.” Read on 1 October 2026.
  10. Yahoo, Sender best practices. “Honor unsubscribes within 2 days.” Read on 1 October 2026.
  11. US Federal Trade Commission, CAN-SPAM Act: A Compliance Guide for Business. “You must honor a recipient's opt-out request within 10 business days.” Read on 1 October 2026.