If you only remember one thing: one-click unsubscribe is two headers plus a POST endpoint that suppresses the address without asking the user anything. The mailbox provider — not the recipient’s browser — sends the request, so there is no human on the other end to click a confirm button. Your endpoint must act on the request itself. Get that wrong and you either fail the requirement or, worse, present a confirmation page the provider can’t complete.
Why Gmail and Yahoo now require it
As part of their bulk-sender rules (roughly 5,000+ messages a day to their users), Gmail and Yahoo require marketing and promotional mail to include RFC 8058 one-click unsubscribe and to honour requests within two days. The goal is to make leaving a list frictionless, which reduces the number of people who instead hit “report spam” — and your spam-complaint rate is one of the hardest signals to recover once it climbs. Making unsubscribing easy is, counter-intuitively, one of the best protections for your deliverability. See the full bulk sender requirements for how this fits alongside SPF, DKIM, DMARC and the complaint-rate threshold.
The two headers
One-click builds on the older List-Unsubscribe header (RFC 2369) and adds the List-Unsubscribe-Post header from RFC 8058. Add both to every marketing message:
List-Unsubscribe: <https://example.com/unsub?u=abc123&c=456>, <mailto:unsubscribe@example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickWhat each part does:
List-Unsubscribelists one or more unsubscribe methods in angle brackets. Include both anhttps://URL (for one-click) and amailto:— the mailto is a required fallback and helps some clients.List-Unsubscribe-Post: List-Unsubscribe=One-Clickis the flag that says “the https URL above accepts a POST and will unsubscribe without any further interaction.” Its value is fixed — it must be exactlyList-Unsubscribe=One-Click.- Both headers must be covered by your DKIM signature so they can’t be tampered with. Most ESPs sign them for you; if you build your own, include them in the signed header list.
Put a unique, signed token in the URL (a subscriber id and campaign id, protected by an HMAC or signature) so the request identifies exactly who to unsubscribe and can’t be forged or guessed.
What the provider actually sends
When the recipient taps Unsubscribe, the mailbox provider makes an HTTP POST to your https URL with a specific form body. It looks like this:
POST /unsub?u=abc123&c=456 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26
List-Unsubscribe=One-ClickNote the crucial details: it is a POST, not a GET (so mail-scanning bots that pre-fetch links can’t accidentally unsubscribe people), the content type is application/x-www-form-urlencoded, and the body is the literal string List-Unsubscribe=One-Click. There is no session, no cookie, no logged-in user — just the request.
Building the endpoint
Your endpoint must verify the request, suppress the address, and return success — all server-side, with no page for a human to interact with. A minimal Express handler:
// Express: honour a one-click unsubscribe POST (RFC 8058)
app.post('/unsub', async (req, res) => {
// The mailbox provider POSTs this exact body; no user is present.
if (req.body['List-Unsubscribe'] !== 'One-Click') {
return res.status(400).send('Bad request');
}
const { u, c } = req.query; // signed subscriber + campaign ids
if (!isValidToken(u, c)) { // verify your signature/HMAC
return res.status(400).send('Invalid token');
}
await suppress(u); // suppress immediately — no confirm page
// Respond 200 so the provider records success. Do NOT redirect,
// do NOT render a "click to confirm" page — the request is the confirmation.
res.status(200).send('Unsubscribed');
});The rules that make this compliant:
- Act on the POST itself. The unsubscribe must complete from this single request. Do not render a “click here to confirm” page and do not require a login — there is no user to click or log in.
- Return 2xx. Respond with a success status so the provider records the unsubscribe as done. A redirect or error can be treated as a failure.
- Verify the token. Because anyone could POST to the URL, sign the identifiers and reject anything that doesn’t validate — otherwise the endpoint is a tool for mass-unsubscribing your list.
- Be idempotent. Providers may retry; unsubscribing an already-suppressed address should still return success, not an error.
Honour it within two days
Both Gmail and Yahoo require that you stop sending to an unsubscribed address within two days. In practice, suppress immediately — write the address to your suppression list the moment the POST arrives, before returning 200 — and make sure your sending pipeline checks that suppression list before every send. Don’t queue unsubscribes for a nightly batch that might miss the window, and never route an unsubscribe into a “we’ll process this soon” flow. The link at the bottom of your email (your normal preference-centre unsubscribe) should feed the same suppression list, so the two paths never disagree.
Common mistakes
- Only a mailto, no https. The mailto alone doesn’t satisfy one-click; you need the https URL plus the
List-Unsubscribe-Postheader. - Using GET instead of POST. A GET endpoint gets triggered by link-scanning security appliances, unsubscribing engaged recipients who never asked to leave.
- Headers not DKIM-signed. Unsigned unsubscribe headers may be ignored or stripped; ensure they’re inside your DKIM signature.
- A confirmation page. One-click means one click — an interstitial defeats the purpose and fails the standard.
- Sending after unsubscribe. If your suppression check runs too late, you’ll mail people who left, spiking complaints.
Verify it
Once your headers are live, send a test campaign and confirm the headers are present, correctly formed and DKIM-signed with the List-Unsubscribe Checker. The authoritative specs are RFC 8058 (one-click) and RFC 2369 (List-Unsubscribe), and the requirement itself is spelled out in Google’s sender guidelines and Yahoo’s best practices.