List-Unsubscribe header setup and testing

Since February 2024, Gmail and Yahoo require bulk senders to honor one-click unsubscribe under RFC 8058. The header is two lines, the endpoint is one POST, and yet a remarkable number of senders still get it wrong — usually by treating it like a mailto link with extra steps. If you are fixing a campaign now, run a deliverability test and compare the result with the Gmail and Yahoo sender requirements checklist.

The two headers

List-Unsubscribe: <mailto:[email protected]>, <https://example.com/u/abc123xyz>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

• First header lists two methods: a mailto fallback and an HTTPS endpoint.
• Second header signals RFC 8058 compliance — receivers will POST to the HTTPS URL automatically.
• The mailto address is a fallback for clients that don't support one-click.

The POST endpoint contract

When a Gmail or Yahoo user clicks the native 'Unsubscribe' link, the receiver's server (not the user's browser) sends a POST request to your URL. There is no human in the loop and no chance to show a confirmation page. If you need to inspect a live header block first, use the free header analyzer.

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

List-Unsubscribe=One-Click

Implementation checklist

1. Generate a per-recipient HMAC token at send time. Never reuse tokens.
2. Store the token mapped to the recipient address in your database.
3. POST handler validates the token, suppresses the address, and returns 200 OK.
4. Suppression must be effective within 2 days — same campaign already in flight should be aborted for that address.
5. GET on the same URL should show a friendly confirmation page for users who paste the URL.

import { createHmac } from "node:crypto";

function unsubToken(recipient: string, secret: string): string {
  return createHmac("sha256", secret)
    .update(`unsub:${recipient}`)
    .digest("base64url")
    .slice(0, 32);
}

const url = `https://example.com/u/${unsubToken(to, process.env.UNSUB_SECRET!)}`;
// Add to headers:
// List-Unsubscribe: <mailbox fallback>, <${url}>
// List-Unsubscribe-Post: List-Unsubscribe=One-Click