Gmail and Yahoo require bulk senders to support one-click unsubscribe (RFC 8058) for marketing and subscription mail. It powers the "Unsubscribe" button that mail apps show next to the sender's name. It takes two headers:
List-Unsubscribe: <https://example.com/unsubscribe?u=8f3a…>, <mailto:unsubscribe@example.com?subject=8f3a…>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
How it works
When a recipient clicks the button, the mailbox provider sends an HTTP POST request to your HTTPS URL, with the body
List-Unsubscribe=One-Click. Your server unsubscribes the address encoded in the URL. The person never visits a page.
Requirements and common mistakes
- The URL must be HTTPS and must identify the recipient and list on its own, typically with a signed token. It can't rely on cookies or a login.
- Answer the POST directly. No confirmation page, no redirect to a preference centre, no "are you sure?". Provide those via the normal link in the email body instead.
- Sign both headers with DKIM. Providers ignore the headers if they are not covered by a valid signature. Most email platforms do this automatically.
- Process it within two days. Sending more marketing after someone unsubscribed generates complaints.
- Still include a visible unsubscribe link in the message body. The header doesn't replace it.
- Don't add it to transactional mail like password resets and order confirmations. It's not required there.
If you use a newsletter or marketing platform, it almost certainly adds these headers for you, but only when you use its own unsubscribe feature. Custom setups and self-built mailers are where they go missing.