What is RFC 8058 (List-Unsubscribe)?
Still have a question, spotted an error, or have a better explanation or a source we should cite?
If you've ever clicked "Unsubscribe" directly inside Gmail without leaving your inbox, that's RFC 8058 doing its job.
RFC 8058 is the technical standard that defines one-click unsubscribe for email. It specifies two email headers that senders can include in their messages: List-Unsubscribe and List-Unsubscribe-Post. Together, they let mailbox providers surface a visible "Unsubscribe" button right in the email client, and process the unsubscribe automatically behind the scenes.
Here's how the two headers divide the work. The older List-Unsubscribe header (which predates RFC 8058) carries either a mailto address or an HTTPS URL. The newer List-Unsubscribe-Post header is what RFC 8058 actually adds. It tells the receiving client to send an HTTP POST request to that URL when the reader clicks unsubscribe, rather than requiring them to click through to a webpage. That's the "one click" part. The subscriber never leaves their inbox.
Why does this matter for deliverability? When someone can't easily unsubscribe, they hit "Spam" instead. Spam complaints hurt your sender reputation far more than unsubscribes do. Making the exit door easy to find is genuinely good for your deliverability.
RFC 8058 was published in 2017 but was largely optional for years. That changed in 2024. Yahoo Mail and Gmail both announced new requirements for bulk senders, and one-click unsubscribe was on the list. If you send over 5,000 messages a day to Gmail addresses, you need these headers. It's not optional anymore.
Most major ESPs now handle this automatically. If you're using Mailchimp, Klaviyo, or a similar platform, the headers are likely already being added for you. If you're sending via a custom setup or API, you'll need to add them manually. A valid implementation looks something like this:
List-Unsubscribe: <https://yourdomain.com/unsubscribe?uid=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickStill the URL in your List-Unsubscribe header needs to handle POST requests, process the unsubscribe immediately, and return a 200 response. If your endpoint only handles GET requests, the one-click POST will fail silently (which is worse than it sounds).
If you're not sure whether your emails are sending these headers correctly, our free Email Header Analyzer can parse a raw email and show you exactly what's there. Or if something's broken and you need a second set of eyes, our SOS hotline is free.
Contributors
Who worked on this answer
Every name links to their profile. Every company links to their site. Real people, real accountability.
