How does one-click unsubscribe work technically? (List-Unsubscribe header)

When someone clicks the unsubscribe link inside Gmail or Apple Mail, they're not clicking a link inside your email body. They're triggering a header your sending system adds to every message. That header is the List-Unsubscribe header, and understanding what it does (and what it expects back from you) is worth a few minutes of your time.

Here's what actually happens, step by step.

Step 1: Your ESP adds the headers at send time. Every outgoing email should carry two headers. The first is List-Unsubscribe, which contains a URL and optionally a mailto address. The second is List-Unsubscribe-Post, which simply signals that your server accepts POST requests. That second header is what makes it one-click. Without it, the mailbox provider can't confirm you support the modern method, so it may fall back to the older mailto approach instead.

A real header pair looks like this:

List-Unsubscribe: <https://unsubscribe.harborpost.net/unsub?token=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Step 2: The reader clicks unsubscribe in their inbox UI. Gmail, Apple Mail, and Outlook all display an unsubscribe button or link above your email. When the reader taps it, the mailbox provider itself fires an HTTP POST request to your URL. The reader doesn't get redirected anywhere. They don't fill out a form. It's one tap and done, which is the whole point of RFC 8058.

Step 3: Your server processes the POST. The POST body contains the string List-Unsubscribe=One-Click. Your server needs to receive that, identify the subscriber from the token in the URL, suppress them from future sends, and return an HTTP 200 status. If you return anything else, or if the endpoint doesn't exist, the unsubscribe silently fails. That subscriber stays on your list and may eventually report you as spam instead.

But the token in the URL is doing a lot of work here. It encodes who the subscriber is, which list they're on, and sometimes which campaign triggered the request. Your ESP should be generating these tokens automatically. Most modern ESPs (Mailchimp, Klaviyo, Postmark, Twilio SendGrid) handle the full flow for you. If you're sending through a custom setup or a lower-level API, you'll need to build the endpoint yourself.

One thing worth knowing: this doesn't replace the unsubscribe link inside your email body. The header-based method and the in-body link serve different audiences. The body link is still required, and you want it visible. Hiding it doesn't reduce unsubscribes, it just turns them into spam reports (which hurt a lot more).

Not sure if your current setup is handling this correctly? Check your email headers with our free Email Header Analyzer to see if both headers are present and formatted right. Or if something's actively broken, the SOS hotline is free and we actually pick up.