List-Unsubscribe Header and One-Click Unsubscribe: Complete Implementation Guide

Every email marketer knows that an unsubscribe link belongs in the email body. But the List-Unsubscribe header is a separate, often overlooked mechanism that tells mailbox providers how to let subscribers opt out directly from the inbox interface, without ever opening the email. As of 2024, it is no longer optional for bulk senders. Google and Yahoo both require it, and failing to implement it properly can lead to delivery throttling, spam folder placement, or outright blocking.

This guide explains how the List-Unsubscribe header works, what one-click unsubscribe means in practice, and exactly how to implement both correctly.

What Is the List-Unsubscribe Header?

The List-Unsubscribe header is a standard email header field defined in RFC 2369. It provides one or more URLs that mailbox providers can use to process an unsubscribe request on behalf of the recipient. When this header is present and properly formatted, providers like Gmail, Yahoo Mail, and Apple Mail display an "Unsubscribe" link or button in their interface, typically near the sender name or at the top of the message.

This is different from the unsubscribe link in your email body. The body link is visible to the subscriber within the email content. The List-Unsubscribe header is invisible to the subscriber but is read by the mailbox provider, which then presents its own unsubscribe option in the UI.

Why List-Unsubscribe Matters for Deliverability

The primary deliverability benefit is simple: when a subscriber wants to stop receiving your emails, you want them to unsubscribe rather than report your message as spam. Every spam complaint damages your sender reputation. Every unsubscribe, while it reduces your list size, is neutral or even slightly positive for reputation because it demonstrates that your list management is responsive.

Without a visible, easy unsubscribe option provided by the mailbox provider, frustrated subscribers default to the spam button. With the List-Unsubscribe header, the mailbox provider gives them a clean alternative right in the inbox interface, intercepting what would have been a complaint and converting it into a clean opt-out.

Google and Yahoo Bulk Sender Requirements

Starting February 2024, Google and Yahoo implemented new requirements for bulk senders (those sending more than 5,000 messages per day to their users). Among these requirements, one-click unsubscribe via the List-Unsubscribe-Post header is mandatory. Senders who do not comply face increased spam filtering, throttled delivery, or outright rejection of messages.

How the List-Unsubscribe Header Works

The List-Unsubscribe header supports two methods for processing unsubscribe requests, and you can (and should) include both in a single header.

Method 1: HTTPS (One-Click Unsubscribe via RFC 8058)

The preferred method uses an HTTPS URL combined with a companion header called List-Unsubscribe-Post. When the mailbox provider processes the unsubscribe, it sends an HTTP POST request to the URL you specified. The POST body contains the value "List-Unsubscribe=One-Click-Unsubscribe" as defined in RFC 8058. No user interaction beyond the initial click is required, which is why it is called "one-click."

# Required headers for one-click unsubscribe (RFC 8058):
List-Unsubscribe: <https://example.com/unsubscribe?id=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click-Unsubscribe

When the subscriber clicks "Unsubscribe" in Gmail or Yahoo Mail, the provider sends a POST request to your URL. Your server processes it and immediately suppresses that address from future sends.

Method 2: Mailto (Legacy Fallback)

The mailto method specifies an email address that the mailbox provider sends an unsubscribe request to. While functional, this method is slower and less reliable than HTTPS. Some providers still support it as a fallback.

# Mailto method (legacy):
List-Unsubscribe: <mailto:unsubscribe@example.com?subject=Unsubscribe&body=id=abc123>

Combined Header (Recommended)

Best practice is to include both methods in the List-Unsubscribe header, with the HTTPS URL listed first. The mailbox provider will use whichever method it prefers (HTTPS is always preferred by modern providers when available).

# Combined header (best practice):
List-Unsubscribe: <https://example.com/unsubscribe?id=abc123>, <mailto:unsub@example.com?subject=Unsubscribe-abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click-Unsubscribe

Step-by-Step Implementation Guide

Implementing one-click unsubscribe involves three parts: generating the headers, building the endpoint, and processing the requests.

Step 1: Generate the Headers

For every outbound email, your sending system must add both the List-Unsubscribe and List-Unsubscribe-Post headers. The unsubscribe URL must be unique per recipient per message, containing a token that identifies the subscriber and the mailing list.

# Pseudocode for generating headers:
token = generate_secure_token(subscriber_id, list_id, message_id)
unsub_url = "https://mail.example.com/unsubscribe?token=" + token
unsub_email = "unsub-" + token + "@example.com"

headers["List-Unsubscribe"] = "<" + unsub_url + ">, <mailto:" + unsub_email + ">"
headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click-Unsubscribe"

Step 2: Build the Unsubscribe Endpoint

Create an HTTPS endpoint that accepts POST requests at the URL specified in your header. The endpoint must handle the POST body containing "List-Unsubscribe=One-Click-Unsubscribe" and process the token from the URL to identify the subscriber.

# Requirements for the unsubscribe endpoint:
# - Accept POST requests (not just GET)
# - Validate the token from the query string
# - Add the subscriber to your suppression list
# - Return HTTP 200 on success
# - Do NOT require authentication, CAPTCHA, or confirmation pages
# - Do NOT redirect to a landing page for the POST request
# - Process must complete within seconds

Step 3: Process Unsubscribe Requests Promptly

Google requires that unsubscribe requests be honored within two days. In practice, you should process them immediately, adding the subscriber's address to your suppression list in real time when the POST is received. Any emails sent after the unsubscribe request but before processing will likely generate spam complaints.

Step 4: Handle GET Requests Gracefully

While RFC 8058 specifies POST for one-click unsubscribe, some mailbox providers or subscribers may visit the URL directly via GET (by clicking the raw link). Your endpoint should handle GET requests by displaying a simple confirmation page that allows the subscriber to complete the unsubscribe with a single click. Do not reject GET requests outright.

Testing Your Implementation

After implementing the headers and endpoint, verify that everything works correctly before sending at scale.

Header Verification

Send a test email to a Gmail account and inspect the raw message headers. Confirm that both List-Unsubscribe and List-Unsubscribe-Post are present and correctly formatted. Gmail should display an "Unsubscribe" link next to the sender name. Use the email header analyzer to parse and validate the headers.

Endpoint Testing

Test your endpoint with a manual POST request to confirm it processes correctly.

# Test with curl:
curl -X POST "https://mail.example.com/unsubscribe?token=test123" \
  -d "List-Unsubscribe=One-Click-Unsubscribe" \
  -H "Content-Type: application/x-www-form-urlencoded"

# Expected: HTTP 200 response, subscriber marked as unsubscribed

End-to-End Verification

Send a test campaign to your own addresses at Gmail, Yahoo, and Outlook. Click the provider-displayed unsubscribe option in each. Verify that the unsubscribe is processed, the address is suppressed, and no further emails are sent to those addresses.

Common Implementation Mistakes

Even experienced senders make mistakes with List-Unsubscribe. Here are the most frequent issues and how to avoid them.

• Missing List-Unsubscribe-Post header. Including only List-Unsubscribe without the companion Post header means you do not support RFC 8058 one-click unsubscribe. Google considers this non-compliant for bulk senders.
• Requiring confirmation or login. The one-click unsubscribe endpoint must process the request without any additional user interaction. Redirecting to a login page or a "Are you sure?" confirmation defeats the purpose.
• Using the same URL for all recipients. The unsubscribe URL must uniquely identify the subscriber. A generic URL with no token cannot process the unsubscribe because there is no way to know who to unsubscribe.
• Slow or unreliable endpoint. If your unsubscribe URL returns errors, times out, or is behind a CDN that blocks POST requests, mailbox providers may stop honoring your List-Unsubscribe header and revert to displaying your messages less favorably.
• Not including it on all commercial emails. Every bulk or marketing email must include the header. Transactional emails (order confirmations, password resets) generally should not include it, as these are not subscription-based.

Implementation with Common ESPs

Most major email service providers now handle List-Unsubscribe header generation automatically. However, you should verify that your ESP's implementation meets the current requirements.

If your ESP does not support RFC 8058 one-click unsubscribe natively, you may need to configure custom headers or consider switching to a provider that does. This is no longer optional for senders targeting Gmail and Yahoo users.

Frequently Asked Questions

← Back to Blog