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. If your unsubscribe page redirects to a sign-in, it is broken. The token in the URL has to be the entire authorisation.

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. But the threshold is not the point. A working one-click unsubscribe reduces spam complaints from anyone, at any volume, and complaint rate is the tightest deliverability constraint you have.

Transactional mail is exempt in principle. In practice, if you are unsure whether a given message is transactional, it is safer to include the headers than to argue the case with a receiving server that has already made up its mind.