One-click unsubscribe and the List-Unsubscribe header (RFC 8058)

List-Unsubscribeis an email header that gives mailbox providers a machine-readable way to unsubscribe a recipient. Clients surface it as a prominent “Unsubscribe” control at the top of the message — separate from whatever link is in your email body — which both improves trust and reduces the odds people hit “Report spam” instead.

It can point to an HTTPS URL, a mailto: address, or both. Providing both is best practice.

On its own, List-Unsubscribe just links the user somewhere. RFC 8058 upgrades it to true one-click by adding a second header:

List-Unsubscribe: <https://example.com/unsubscribe?id=abc123>, <mailto:unsubscribe@example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The presence of List-Unsubscribe-Post: List-Unsubscribe=One-Click tells the provider to POST to the HTTPS URL directly — unsubscribing the user without them leaving the inbox or loading a page. This is what the mailbox sends:

POST /unsubscribe?id=abc123 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

List-Unsubscribe=One-Click

Your endpoint should accept that POST, unsubscribe the address, and return 200. Don’t require auth or a confirmation click on it — the whole point is that it happens in one step.

As of February 2024, Gmail and Yahoo require bulk senders (roughly 5,000+ messages a day to their users) to include one-click unsubscribe via RFC 8058 and to process unsubscribe requests within two days. Falling short gets commercial mail filtered or rejected. It’s a deliverability requirement now, not a nicety.

• Include both the HTTPS URL and a mailto: in List-Unsubscribe.
• Add List-Unsubscribe-Post only when the HTTPS URL accepts a POST — they must match.
• Make the URL unique per recipient (a signed token), so a POST unambiguously identifies who to unsubscribe.
• Honor the request immediately and return 200 — no login, no landing page, no extra click.
• Keep the headers off purely transactional mail (password resets, receipts) that recipients can’t meaningfully opt out of.

SenderKit adds compliant List-Unsubscribe and List-Unsubscribe-Postheaders, hosts the one-click endpoint, and records the opt-out so the address is suppressed on future sends — per workspace, automatically. You don’t build or host any of it. Transactional messages stay exempt.