One-click unsubscribe: how to implement RFC 8058 and stay compliant

One-click unsubscribe is the button a mailbox provider shows at the top of a message, next to the sender name. It is not your footer link. It works because you told the mailbox how to unsubscribe somebody on their behalf, in headers, and it is now a requirement rather than a nicety for anyone sending bulk mail.

Implementing it is genuinely small. Implementing it wrongly is easy and mostly invisible until complaints rise.

The two headers

Both must be present, on every marketing message:

1. List-Unsubscribe — containing an HTTPS URL, and optionally a mailto. The URL must be unique per recipient and per message.
2. List-Unsubscribe-Post: List-Unsubscribe=One-Click — the header that tells the mailbox it may POST without any further interaction.

Without the second header, a mailbox provider will not show the one-click button, and you are not compliant with the bulk sender requirements even though the first header is there. This is the most common implementation gap.

What the endpoint has to do

• Accept POST and act on it immediately. A GET may be used by some clients for the link, but the one-click flow is a POST.
• Do not show a confirmation page. There is nobody to read it. The unsubscribe must happen from the request alone.
• Do not require a login. The provider is not signed in as your customer.
• Make the token opaque and unguessable, scoped to one recipient and one message, and do not make it reusable to unsubscribe somebody else.
• Return 200 quickly. Do the work synchronously enough that it is genuinely recorded, then answer.
• Be idempotent. The same POST may arrive more than once.

The two-day rule, and why it should be two seconds

Google's sender guidelines require unsubscribe requests to be processed within two days. That is the outer limit, not a target. Anything that arrives in a queue and is processed nightly is technically compliant and practically a complaint generator, because the person who unsubscribed will receive the campaign you sent this afternoon.

Process immediately and apply the suppression at send time rather than at list build time, so a campaign already prepared does not go out to somebody who left an hour ago.

The footer link still has to exist

One-click does not replace the visible unsubscribe link. Not every client renders the header button, and EU law requires a clear means of withdrawing consent in every message.

• Visible, in the footer, in plain language. Not "manage preferences" as the only option.
• Working without a login. Requiring somebody to remember an account password to stop receiving email is a dark pattern and a compliance problem.
• A preference centre is fine as a second step, offered after the unsubscribe has already taken effect, or alongside a plain unsubscribe — never instead of it.
• One click from the email to unsubscribed. Every extra step between the two converts into a spam complaint instead.

Scope: what exactly did they unsubscribe from

The one-click header carries no granularity. Somebody pressing it in a newsletter has told you to stop, and the safe interpretation is all marketing on that channel.

1. Stop all marketing email to that address, not just that one campaign type.
2. Keep transactional mail flowing. Order confirmations are not marketing and must still arrive.
3. Record when, and from which message. This is part of your consent record and you will want it if the person later complains they never unsubscribed.
4. Do not resubscribe on a later purchase. Buying again is not withdrawing the objection.