How to set up one-click unsubscribe (RFC 8058)

What one-click unsubscribe is#

One-click unsubscribe is a way for a mail app to take someone off your list without sending them to your website. It is defined by RFC 8058, published by the IETF in January 2017, and it builds on a much older header: List-Unsubscribe, from RFC 2369 (1998), which lets a message say where to send an unsubscribe request.^[1][2]

The older header had a problem the new one exists to fix. RFC 8058 explains that “anti-spam software often fetches all resources in mail header fields automatically”, so a sender cannot tell a real click from a scanner, and senders protected themselves with a confirmation page — which makes the process “more complex than a single click”. One-click replaces that with an HTTPS POST that only a mail app sends, and only with the reader’s consent.^[1]

The standard is also frank about why senders should want this. Mailbox providers know “their users do not make a clear distinction between unsubscription and junk”, and if unsubscribing is too difficult, “the recipient’s alternative is to report mail from the sender as junk”.^[1] Every unsubscribe that one click makes easy is, very often, a spam complaint that never happens. The companion guide on lowering your spam complaint rate picks up from there.

Who requires one-click unsubscribe#

Gmail requires anyone sending 5,000 or more messages a day to personal Gmail accounts to support one-click unsubscribe on marketing and subscribed messages, and to include “a clearly visible unsubscribe link in the message body”.^[3] The bulk-sender rules took effect in February 2024; senders who already had an unsubscribe link were given until June 1, 2024 for one-click.^[4] Yahoo requires a working list-unsubscribe header with one-click for the same kinds of mail.^[5] Microsoft’s rules for Outlook.com recommend a functional, clearly visible unsubscribe link and do not name RFC 8058.^[6]

Gmail’s FAQ settles the questions senders ask most. One-click is required “only for marketing and promotional messages” — password resets, reservation confirmations and form confirmations are excluded — and mailto or plain unsubscribe links “don’t meet our one-click unsubscribe requirement”. You must “include one HTTPS URL in the List-unsubscribe: header”.^[4] The line between the two kinds of mail is drawn in transactional vs marketing email, and the rest of the bulk-sender rules in the Gmail and Yahoo sender requirements.

Missing the requirement does not bounce your mail. Google says it does not automatically reject or spam-folder messages for it — but “unwanted messages that don’t use one-click unsubscribe are more likely to be reported as spam by recipients”, and reports decide where your future mail goes.^[4]

The List-Unsubscribe and List-Unsubscribe-Post headers#

RFC 8058 asks for exactly two header fields. List-Unsubscribe “MUST contain one HTTPS URI” and may also carry a non-HTTP one such as mailto:; List-Unsubscribe-Post “MUST contain the single key/value pair ‘List-Unsubscribe=One-Click’”.^[1]

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

List-Unsubscribe#

• Angle brackets, comma-separated. Each URL sits inside < and >; several are separated by commas, in order of preference from left to right.^[2]
• One HTTPS URL that identifies the person and the list. There is no way to pass extra fields with the POST, so the URL “MUST contain enough information to identify the mail recipient and the list”.^[1]
• An opaque, hard-to-forge token. The URL “SHOULD include an opaque identifier or another hard-to-forge component”, and your server should check it. The point is to stop someone who knows your URL pattern from unsubscribing other people.^[1] A signed token (an HMAC over the list and subscriber ids) does this without a database lookup to reject a forgery.
• A mailto is optional. Keep one if you can process it: Yahoo accepts mailto,^[5] and some older clients only speak mail. It does not satisfy Gmail on its own.^[4]

List-Unsubscribe-Post#

The value is fixed. The standard limits it to one known key and value on purpose, so a malicious message cannot use it to make a mail app fill in an arbitrary form on someone else’s website.^[1] Copy it byte for byte: List-Unsubscribe=One-Click.

Sign both headers with DKIM#

This is the requirement most often missed. The message “MUST have a valid DomainKeys Identified Mail (DKIM) signature that covers at least the List-Unsubscribe and List-Unsubscribe-Post headers”, which means both names appear in the h= tag of the DKIM-Signature. Without it, the mail receiver “SHOULD NOT offer a one-click unsubscribe for that message”.^[1]

DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=mail;
 h=from:to:subject:date:message-id:list-unsubscribe:list-unsubscribe-post;
 bh=...; b=...

Two practical consequences. First, the headers have to exist before the message is signed: a tool that adds them afterwards produces headers the signature does not cover. Second, the signing domain should be yours and aligned with your From domain, which is what Gmail’s bulk-sender rules ask for anyway.^[3] The background is in DKIM, SPF and DMARC explained and the DKIM glossary entry.

Handling the one-click POST request#

When a reader presses unsubscribe, the mailbox provider sends your URL a POST whose body is the header’s value. Gmail’s guidelines show the request you receive:^[3]

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

List-Unsubscribe=One-Click

RFC 8058 says the body “SHOULD” be sent as multipart/form-data and “MAY” be sent urlencoded, so parse both. The POST goes to the same URL a person would open by hand, which is deliberate: one route can serve the confirmation page on GET and the one-click on POST. And the rules for the response are strict:^[1]

1. No redirect. “The mail sender MUST NOT return an HTTPS redirect,” because redirected POSTs have historically not worked reliably.^[1] Answer with a 200 directly.
2. No login, no cookies, no confirmation. The request “MUST NOT include cookies, HTTP authorization, or any other context information”.^[1] Anything that waits for a person to click a button never completes, because no person is looking.
3. Never unsubscribe on GET. Link scanners fetch URLs in headers automatically;^[1] a GET that unsubscribes will take people off your list who never asked.
4. Make it idempotent. A provider may retry, and a reader may press twice. Unsubscribing an address that is already off the list should still answer 200.

A minimal handler, written against the standard Request and Response:

import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.UNSUBSCRIBE_SECRET!; // a long random key

// token = base64url(JSON [listId, subscriberId]) + "." + HMAC of that part
function verify(token: string): { listId: string; subscriberId: string } | null {
  const [payload, mac] = token.split(".");
  if (!payload || !mac) return null;
  const expected = createHmac("sha256", SECRET).update(payload).digest();
  const given = Buffer.from(mac, "base64url");
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return null;
  const [listId, subscriberId] = JSON.parse(Buffer.from(payload, "base64url").toString());
  return { listId, subscriberId };
}

export async function POST(request: Request, ctx: { params: Promise<{ token: string }> }) {
  const who = verify((await ctx.params).token);
  if (who === null) return new Response(null, { status: 404 });

  const form = await request.formData(); // urlencoded or multipart/form-data
  if (form.get("List-Unsubscribe") !== "One-Click") return new Response(null, { status: 400 });

  await unsubscribe(who.listId, who.subscriberId); // idempotent; records when and how
  return new Response(null, { status: 200 }); // no page, no redirect
}

// GET shows a page with a button that POSTs back here. It never unsubscribes by itself.

Keep the endpoint working for as long as the mail is in someone’s inbox. In the US, CAN-SPAM sets a legal floor for that:^[8]

Step by step: set up one-click unsubscribe#

The order matters: the headers are useless without the signature, and the signature is useless without an endpoint that answers.

1. 1

   Decide which mail gets the headers

   Add one-click unsubscribe to marketing and subscribed mail: newsletters, promotions, digests. Leave it off transactional mail such as receipts, password resets and account alerts, which Gmail excludes from the requirement.

2. 2

   Mint a signed unsubscribe URL per recipient and list

   Build an HTTPS URL that carries an opaque, hard-to-forge token identifying the subscriber and the list, such as an HMAC over their ids. Never put a bare email address in it, and keep it valid for at least 30 days.

3. 3

   Add both headers before signing

   Write List-Unsubscribe with the HTTPS URL in angle brackets (optionally followed by a mailto) and List-Unsubscribe-Post: List-Unsubscribe=One-Click, then DKIM-sign the message so both header names appear in the signature's h= tag.

4. 4

   Handle the POST at that URL

   Accept urlencoded and multipart bodies, verify the token, check for List-Unsubscribe=One-Click, remove the subscriber from that list and answer 200. No redirect, no login, no confirmation step, and never unsubscribe on a GET.

5. 5

   Keep a visible link in the body

   Add an unsubscribe link people can see in every marketing email. It may lead to a preference page where readers choose fewer topics or leave everything, as long as the headers still offer one click.

6. 6

   Test it and watch Postmaster Tools

   Read the raw headers of a test send, replay the POST with curl, tamper with the token to confirm it fails, and check the compliance dashboard in Postmaster Tools for one-click unsubscribe and honouring unsubscribes.

The body link and the preference page#

The headers do not replace the link in the email. Gmail requires a visible unsubscribe link in the body for bulk marketing mail,^[3] and Yahoo says that link “may direct to a preference page”.^[5] The body link does not have to be one-click itself; Google says it “can link to a preferences web page that you specify”.^[4]

That split is what lets you offer choice without breaking the rule. The header removes someone from “the mailing list associated with the message”, not from everything you send,^[4] and the preference page lets a reader who only wants less mail pick fewer topics instead of leaving entirely. Google’s guidelines suggest exactly this — let people unsubscribe from lists individually or all at once — alongside one-click, never instead of it.^[3]

How to test your List-Unsubscribe-Post setup#

1. Read the raw headers. Send a campaign to yourself and open the original message (in Gmail, “Show original”). Confirm both headers are present, the URL is HTTPS, DKIM passes, and both names are in the signature’s h= list.
2. Replay the POST yourself. Send exactly what a mailbox provider sends and check you get a 200 with no Location header, then that the subscriber is actually off the list.
3. Tamper with the token. Change one character and send it again. It should fail, and it should not unsubscribe anyone.
4. Watch Postmaster Tools. Its compliance dashboard reports one-click unsubscribe and honouring unsubscribes for your domain.^[7]

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

# expect: HTTP/2 200, no Location header, and the subscriber gone

Do not use the button’s appearance as your test. Gmail shows its unsubscribe link next to the sender name “only for messages that pass Google’s automated eligibility checks”, which include meeting the sender requirements and building volume gradually — so a correct setup can still show no button on a new domain.^[4]

Common one-click unsubscribe mistakes#

Myths about one-click unsubscribe#

• Documented by Google “A mailto: in List-Unsubscribe is enough for Gmail.” False: Gmail supports mailto links but says they do not meet its one-click requirement.^[4]
• Documented by Google “Missing one-click gets your mail rejected.” Not directly: Google says it does not reject or spam-folder mail for this alone. It costs you through complaints and through losing eligibility for mitigation.^[4]
• Documented by Google “The unsubscribe link in the body must be one-click too.” False, when the headers are in place; the body link can go to a preference page.^[4]
• Documented by Google “One-click removes people from everything you send.” Not by itself: the header unsubscribes from the list the message belongs to.^[4] Gmail’s own subscription manager does remove people from every list of a sender, though.^[10]
• Documented by Google “Keep sending after an unsubscribe until the list syncs.” Costly: when someone who unsubscribed receives more mail from you, Gmail sends it straight to Spam.^[11]
• Unproven “Making it easy to leave shrinks your list for nothing.” The people leaving were not going to read. RFC 8058 notes their alternative is the spam button,^[1] and a 2008 survey by Q Interactive and MarketingSherpa found many people reached for it on purpose (below).

What the law adds to one-click unsubscribe#

Mailbox providers set the technical rules; the law sets its own, and one-click does not replace them. In the US, CAN-SPAM requires a clear and conspicuous way to opt out of all marketing mail from you, honoured within 10 business days, and forbids charging a fee or asking for anything beyond an email address and a single page visit or reply.^[8] In the UK, PECR requires a valid contact address for opting out in every marketing message, solicited or not.^[13] Record every opt-out with when and how it happened; you may need to prove you honoured it.

One-click unsubscribe in Rasket#

If you send marketing mail with Rasket’s Campaigns (the API resource is broadcasts), none of the above is yours to build. Every campaign message carries List-Unsubscribe with a signed HTTPS URL and List-Unsubscribe-Post: List-Unsubscribe=One-Click, both written before the message is DKIM-signed with your verified domain. Transactional sends never carry the headers.

The URL points at a preference page we host. It needs no login; a GET only shows the page, a one-click POST unsubscribes the contact at once and answers 200 with no redirect, and the page lets a contact opt out of everything or change individual topics. A campaign body without an unsubscribe link gets a footer with one and your postal address, and every change is written to a consent record. See marketing email for the rest of the picture, and the Gmail Promotions tab guide for what these headers do and do not do for placement.