How do I implement the List-Unsubscribe header correctly?

If you send bulk email to Gmail or Yahoo Mail addresses, you've probably noticed the "Unsubscribe" link that appears at the top of messages in those inboxes. That link comes from the List-Unsubscribe header. Getting it right matters, because both Gmail and Yahoo now require one-click unsubscribe for bulk senders.

Here's what you need to add to your outgoing email headers.

The two headers you need

You need both of these, not just one.

Header 1:

List-Unsubscribe: <https://yoursite.com/unsubscribe?id=UNIQUE_TOKEN>

Header 2:

List-Unsubscribe-Post: List-Unsubscribe=One-Click

The first header points to your unsubscribe endpoint. The second tells the inbox that your endpoint accepts a POST request and can remove the subscriber instantly, no confirmation page needed. That combination is what makes it one-click compliant under RFC 8058.

The URL must be unique per recipient

Still your unsubscribe URL needs to identify exactly who is clicking. That means including a subscriber-specific token or encrypted ID in the URL parameters. A shared URL that doesn't know who's on the other end won't work. Most senders use something like ?id=abc123xyz where that token maps back to the subscriber in your database.

What your endpoint needs to do

When someone clicks the unsubscribe button in Gmail or Yahoo, the inbox sends a POST request to your URL with the body List-Unsubscribe=One-Click. Your server needs to do three things.

• Read the token from the URL to identify the subscriber.
• Remove them from your list immediately.
• Return an HTTP 200 response.

No redirect. No confirmation form. No "are you sure?" page. Just unsubscribe them and respond with 200. If your endpoint returns anything else, inbox providers may treat your header as broken.

Still you should also handle GET requests on the same URL. That covers cases where a real human clicks your in-email unsubscribe link and lands on your page directly (rather than the inbox triggering the automated POST).

If you use an ESP, you probably don't need to do this manually

Most modern ESPs handle List-Unsubscribe headers automatically. Mailchimp, Klaviyo, Brevo, Twilio SendGrid, and Postmark all inject these headers for you and manage the POST endpoint on the backend. Check your ESP's documentation to confirm it's including the List-Unsubscribe-Post header too, not just the basic List-Unsubscribe one. Some older setups only add the mailto version, which doesn't satisfy the one-click requirement.

If you're sending through a custom mail setup or building your own integration, you'll need to wire this up yourself. The good news is it's a few lines of server-side code once you understand what the inbox expects.

Not sure if your headers are set up right? You can use our free Email Header Analyzer to check a real message, or drop us a line at the SOS hotline if something's broken and you need a second pair of eyes.