Gmail and Yahoo require bulk senders to support one-click unsubscribe. Not an unsubscribe link in the footer, which everyone already had, but the machine-readable version defined in RFC 8058 that lets the mail client show its own unsubscribe button.

The two headers

You need both. One without the other does not qualify.

List-Unsubscribe: <https://example.com/u/OPAQUE_TOKEN>, <mailto:unsub@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The second header is the one that signals RFC 8058 support. When the user clicks the client's unsubscribe button, the client sends an HTTP POST to your URL with the body List-Unsubscribe=One-Click. It does not open a browser and it does not ask the user anything else.

The three mistakes

Only handling GET. The spec requires POST. If your endpoint is a GET route, mail clients will call it and get a 405, and the unsubscribe silently fails. Handle both: POST for the client, GET for a human who pastes the link.

Requiring a login. The POST arrives with no session and no cookies, so the token in the URL is the entire authorisation. An unsubscribe page that redirects to a sign-in is broken.

Making the token guessable. The URL is the credential, so it needs to be unguessable and it needs to identify the recipient and the list without being enumerable. Sign it rather than storing a lookup row per message:

const payload = base64url(JSON.stringify({ orgId, email, list }));
const sig = hmacSha256(payload, process.env.UNSUBSCRIBE_SECRET);
const token = payload + "." + sig;

Verify the signature on the way back in and you get stateless, non-enumerable tokens that survive a database restore.

Honour it in seconds, not days

Gmail's guidance is to process the request within two days. Treat that as an outer bound rather than a target. The unsubscribe should take effect before the next send, which in practice means writing to the same suppression table your send path already checks.

An unsubscribe that lands in a queue and gets applied nightly will let one more campaign through, and the person who just told you to stop is the person most likely to hit the spam button when the next one arrives.

Who this applies to

The requirement targets bulk senders, currently defined as roughly 5,000 messages a day to a given receiving provider. Complaint rate is the tightest deliverability constraint you have, and a working one-click unsubscribe reduces spam complaints at any volume, including below that threshold.

Transactional mail is exempt in principle. In practice, a receiving server decides for itself whether a message is transactional, so if you are unsure about a given message, include the headers.