One-click unsubscribe: what RFC 8058 defines

Why an unsubscribe link needed a confirmation page

A List-Unsubscribe header can carry an HTTPS URI that unsubscribes the recipient. Anti-spam software, though, often fetches the URLs in a message's headers on its own. The sender can't tell that automatic fetch apart from a person who wants out.

So senders put a confirmation page behind the link. A person reads the page and clicks the button. A scanner stops at the page, so nobody loses a subscription by accident. The cost is a second step, which a mail client can't complete for its user without parsing a web page it knows nothing about.

That second step matters to senders. A recipient who finds unsubscribing too hard can report the message as junk, and a stream of spam complaints hurts the sender's deliverability. RFC 8058 one-click unsubscribe removes that step.

What RFC 8058 defines

RFC 8058 defines one header, List-Unsubscribe-Post, with one allowed value: List-Unsubscribe=One-Click. The header tells a mail client that the HTTPS URI in List-Unsubscribe accepts an unsubscribe request as a single POST. The recipient doesn't have to open a page or fill in a form.

The RFC sets requirements on both sides. The sender must sign both headers with DKIM, encode everything it needs to identify the recipient and the list in the URI, and answer the POST without a redirect. The mail receiver must not send the POST without the user's consent, and must send it without cookies or credentials.

RFC 8058 does not update RFC 2369. Uses of List-Unsubscribe other than one-click, such as a mailto: URI or a web link opened in a browser, keep their RFC 2369 meaning.

How one-click unsubscribe works

A sender that wants one-click unsubscribe adds two headers to the message: List-Unsubscribe with one HTTPS URI (a mailto: URI can sit next to it), and List-Unsubscribe-Post: List-Unsubscribe=One-Click. It signs the message with DKIM and lists both headers in the signature.

The receiving mail system checks that signature. If it passes and covers both headers, the mail client can show its own unsubscribe button next to the message. When the recipient uses it, the mail receiver sends an HTTPS POST to the URI, with List-Unsubscribe=One-Click as the request body.

The sender's endpoint reads the recipient and the list from the URI, records the opt-out, and returns a success response. The recipient never leaves the mail client.

The POST may come from the mailbox provider's servers. The RFC lets a receiving system process the request in the background, for example when the user reports a message as junk and chooses to unsubscribe at the same time.

Anatomy of the headers

List-Unsubscribe-Post: one fixed key/value pair. The RFC limits the header to this single value, so a crafted message can't make the POST fill in an arbitrary form on someone else's site.

List-Unsubscribe, as RFC 8058 constrains it:

DKIM-Signature: the h= tag must list both list-unsubscribe and list-unsubscribe-post.

One-click unsubscribe in practice

The headers a sender emits

A newsletter message that supports one-click unsubscribe carries this header block:

List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsubscribe>,
  <https://example.com/u/opaque123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=news;
  h=from:to:subject:date:list-unsubscribe:list-unsubscribe-post;
  bh=...; b=...

The token opaque123 identifies both the recipient and the list. The POST carries no other arguments, so the URI is the only place that information can live.

The POST the mail receiver sends

After the recipient clicks the client's unsubscribe button, the mail receiver sends:

POST /u/opaque123 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

List-Unsubscribe=One-Click

The RFC recommends multipart/form-data and also allows application/x-www-form-urlencoded, the two encodings browsers use for forms. The request must carry no cookies, no HTTP authorization, and no other context, so the sender can't tie the unsubscribe to the recipient's earlier web activity.

How the endpoint handles the POST

The server behind the URI goes through these steps:

1. Accept both form encodings. The body only confirms the one-click intent, and the identity comes from the URI.
2. Check the opaque token. The RFC recommends this check to deter spam that carries links to a victim list, and POSTs sent straight to the unsubscribe server.
3. Record the opt-out for that recipient and that list.
4. Return a success response, such as 200 OK, from the URI itself. The RFC forbids a redirect: redirected POSTs have a history of failing, and many browsers turn them into GETs.
5. Expect no session. The request arrives without cookies or credentials, so the endpoint can't require a login.

RFC 8058 says nothing about retries. In practice, if a mail receiver retries the POST, answer a repeated request for an address already unsubscribed with the same success response.

The same URI also receives GET requests: from the recipient who opens it in a browser, and from scanners that fetch it on their own. The RFC sets the same target for the manual GET and the one-click POST, so one server can handle both. A GET can still show a confirmation page.

Limits

One-click needs an HTTPS URI. A List-Unsubscribe header with only a mailto: address can't offer it.

It also needs DKIM. If the signature is missing, fails, or leaves out either header, the receiver should not offer the one-click option. A forwarder or mailing list that rewrites a signed header breaks the signature, and the option goes with it.

The RFC leaves the interface to the mail client. It requires the user's consent before the POST, but how and when the client asks for that consent is outside the specification. No rule in the RFC forces a client to show an unsubscribe button at all.

Anyone who holds the message can unsubscribe its recipient, since the URI carries everything the server needs. The RFC accepts this trade-off: a plain List-Unsubscribe link already allowed it, with more steps.

The push to adopt the RFC comes from mailbox providers. Google's email sender guidelines require bulk senders to support one-click unsubscribe on marketing and subscribed messages, with the RFC 8058 headers. Yahoo's sender best practices require one-click unsubscribe from bulk senders and highly recommend the RFC 8058 POST method.

Check it yourself

Open the raw source of a newsletter in your inbox. In Gmail, open the message and select "Show original" from the menu. Look for List-Unsubscribe-Post: List-Unsubscribe=One-Click, then find the h= tag of the DKIM-Signature header and confirm it lists list-unsubscribe and list-unsubscribe-post.

To test your own endpoint, send the POST a mail receiver would send, to a URI issued for a test address you control:

curl -i -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'List-Unsubscribe=One-Click' \
  'https://example.com/u/opaque123'

Repeat with the multipart/form-data encoding the RFC recommends:

curl -i -F 'List-Unsubscribe=One-Click' 'https://example.com/u/opaque123'

The response should carry a 2xx status and no Location header. Send it a second time: a repeat-safe endpoint returns the same answer.

Where it fits

RFC 8058 extends the List-Unsubscribe header that RFC 2369 defines, along with List-Id and the rest of the List-* family. It depends on the DKIM signature described in SPF, DKIM, and DMARC, the only authentication mechanism RFC 8058 accepts. An easy unsubscribe gives a recipient a way out besides the junk button, whose clicks come back to the sender as ARF complaint reports where the mailbox provider runs a feedback loop.

For a sending API that adds both headers to every broadcast message and serves the POST endpoint, see Broadcast and the broadcast unsubscribe guide. For the full set of email standards, see the reference hub.

FAQ

Does one-click unsubscribe work with a mailto: address?

No. RFC 8058 requires an HTTPS URI in List-Unsubscribe. A mailto: URI can sit next to it, for clients that use the RFC 2369 behavior. Mailbox provider policies can differ: Yahoo also accepts a mailto: method for its own one-click requirement.

Why can't the unsubscribe endpoint redirect the POST?

RFC 8058 forbids it. Redirected POSTs have a history of failing, and many browsers turn a redirected POST into a GET, which loses the one-click request.

Why must DKIM cover the List-Unsubscribe headers?

The signature shows that the signing domain vouches for both headers and that nobody changed them in transit. Without a valid DKIM signature over both, the receiver should not offer one-click unsubscribe.

Can a GET request on the unsubscribe URL unsubscribe the recipient?

Not under RFC 8058. It defines one-click only as a POST and leaves GET under RFC 2369. Anti-spam software fetches header URLs on its own, so a GET that unsubscribed would remove recipients who never asked. A GET can show a confirmation page.

Is one-click unsubscribe required?

The RFC makes it optional for senders. Google and Yahoo require one-click unsubscribe from bulk senders on marketing and subscribed messages.

RFC reference

RFCs covered: RFC 8058. Superseded / updated by: None.