Operations
List-Unsubscribe (RFC 8058): making one-click unsubscribe work
Gmail and Yahoo require RFC 8058 one-click unsubscribe for any sender above ~5000 messages per day. Implementing it wrong has the same effect as not implementing it.
The two required headers
Bulk senders must include both: List-Unsubscribe: <https://example.com/unsub?id=...>, <mailto:unsub@example.com> and List-Unsubscribe-Post: List-Unsubscribe=One-Click. The Post header signals RFC 8058 support and tells Gmail to POST (not GET) to the URL.
The endpoint must accept POST
When the user clicks the button, Gmail sends a POST request with body 'List-Unsubscribe=One-Click'. Your endpoint must process the request and return 2xx; it must not require login or a confirmation page.
The unsubscribe must take effect
Gmail audits this: if a user clicks unsubscribe and still receives a message within a few days, your reputation suffers fast. Make sure suppression takes effect immediately, not on the next campaign cycle.
Frequently asked questions
- Do transactional emails need List-Unsubscribe?
- Only marketing/bulk traffic. Transactional confirmations and security alerts don't need it, but you must clearly separate the streams.