What is One-Click Unsubscribe? (RFC 8058)

The two headers

List-Unsubscribe (RFC 2369) lists one or more ways to unsubscribe — a mailto: address, an HTTPS URL, or both. RFC 8058 adds a second header that tells the mailbox provider the HTTPS URL can be called directly, with no page for the user to visit:

List-Unsubscribe: <https://example.com/u/abc123>, <mailto:unsub+abc123@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

When the recipient clicks the provider’s own “Unsubscribe” button, the provider sends an HTTPS POST to that URL with the body List-Unsubscribe=One-Click. Your endpoint must unsubscribe the recipient on that request alone — no login, no confirmation page, no redirect that needs a second click.

Rules that are easy to miss

• Both headers must be covered by a valid DKIM signature, so a forwarder cannot insert its own URL.
• The URL has to identify the recipient and list by itself, typically with a signed token, because the POST carries no cookies or other context.
• Handle POST, not just GET. Link scanners and security gateways fetch URLs with GET, so unsubscribing on GET alone can remove people who never clicked anything.

Who requires it

Since 2024, Gmail and Yahoo require one-click unsubscribe on marketing and subscribed mail from bulk senders (more than about 5,000 messages a day to their users), and expect unsubscribes to be honoured within two days. Transactional mail such as receipts and password resets is exempt.

In PostStack

PostStack adds both headers to every broadcast, and to any other message whose body contains the {{unsubscribe_url}} tag. The link is signed per recipient, and an unsubscribe fires an email.unsubscribed webhook event.