One-click unsubscribe: the List-Unsubscribe-Post header

Gmail and Yahoo require one-click unsubscribe for marketing mail. The two headers you need and the mistakes to avoid.

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.