What is RFC 8058?
Still have a question, spotted an error, or have a better explanation or a source we should cite?
RFC 8058 is the technical standard that defines how one-click unsubscribe works in email. It was published in January 2017 by the IETF, and for years it was optional. Then Gmail and Yahoo Mail made it a requirement for bulk senders in 2024, and suddenly everyone started paying attention.
The spec defines two email headers that work together. The List-Unsubscribe header carries a URL where the unsubscribe request gets sent. The List-Unsubscribe-Post header contains the value List-Unsubscribe=One-Click, which signals to mailbox providers that your endpoint supports a direct HTTP POST request. When both headers are present, the inbox can show a one-click unsubscribe option without sending the user to a landing page first.
Here's what that looks like in practice:
- List-Unsubscribe:
<https://yourdomain.com/unsubscribe?token=abc123> - List-Unsubscribe-Post:
List-Unsubscribe=One-Click
The URL in List-Unsubscribe needs to be unique per recipient, so you know exactly who to remove. When the mailbox provider hits that endpoint with a POST request, your system should process the unsubscribe immediately, no confirmation page, no extra clicks. That's the whole point.
A few things RFC 8058 requires on your side. The endpoint must accept HTTP POST (not just GET). It must act on the request without asking the user to do anything else. And the unsubscribe needs to be processed promptly. Gmail's guidance says within two days, though faster is always better for your compliance with their bulk sender rules.
But the body unsubscribe link you've always had is still required separately. RFC 8058 doesn't replace it. It adds a machine-readable layer on top so inboxes can surface the option more prominently. Think of the header as the fast lane, and the body link as the fallback for email clients that don't support one-click.
Most modern ESPs handle this for you automatically. If you're sending through Mailchimp, Klaviyo, or similar platforms, the headers are likely already being added. What's worth checking is whether your endpoint actually processes those POST requests correctly, because a misconfigured endpoint that ignores them is technically non-compliant even if the headers look right.
If you want to understand the full technical implementation, the technical breakdown of how one-click unsubscribe works goes deeper on the request flow.
Contributors
Who worked on this answer
Every name links to their profile. Every company links to their site. Real people, real accountability.
