One-click unsubscribe is now mandatory. Here is how it works
Gmail and Yahoo require RFC 8058 one-click unsubscribe from bulk senders. It takes two headers and an endpoint that must not ask questions.
Since February 2024, anyone sending more than 5,000 messages a day to Gmail or Yahoo must support one-click unsubscribe. Not a link to a preferences page — a single action that opts the recipient out immediately.
The two headers
List-Unsubscribe: <https://yourdomain.com/api/unsubscribe?token=SIGNED>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
The first has existed since 1998 and was widely ignored. The second is what makes it one-click: it tells the mailbox provider it may POST to that URL directly, without the recipient ever visiting your site.
Both must be present. List-Unsubscribe alone gets you the old behaviour.
What your endpoint must do
When Gmail POSTs List-Unsubscribe=One-Click to your URL, you must:
- Unsubscribe the recipient immediately
- Return a 2xx status
- Not redirect, not show a page, not ask for confirmation
That last point trips people up. The recipient never sees your endpoint's response. Any confirmation step means the unsubscribe silently fails, and the next step for that person is the spam button.
Processing must complete within a couple of days at most. Gmail's guidance says two; treating it as immediate is simpler and safer.
Sign the token
The URL is in every copy of the email, sitting in inboxes and forwarded threads indefinitely. If it encodes a plain user ID, anyone can unsubscribe anyone.
Sign it:
token = base64(userId:email:timestamp:hmac(userId:email:timestamp, secret))
Verify the HMAC before acting, and derive the address from the token, never from a query parameter the caller supplied. Otherwise your unsubscribe endpoint becomes a way to remove arbitrary people from arbitrary lists.
Keep the visible link too
The header is not a replacement for the unsubscribe link in your footer. Plenty of clients do not surface the native control, and regulations require a visible mechanism regardless.
Point both at the same signed URL so they cannot drift apart — a footer link that 404s while the header works is a compliance problem that looks fine in testing.
Why this is worth doing well
Every unsubscribe you make difficult becomes a complaint. A complaint costs vastly more: 0.1% is the threshold at which Gmail starts filtering everything you send.
Making it easy to leave is what keeps you in the inbox for everyone who stays.