How do I implement the List-Unsubscribe header correctly?

Implementing the List-Unsubscribe header correctly requires including both List-Unsubscribe and List-Unsubscribe-Post headers in your message headers. These headers enable the "unsubscribe" button that appears in Gmail, Yahoo, and other major email clients, making it easier for recipients to opt out.

Basic Header Format

The List-Unsubscribe header should contain an HTTPS URL (and optionally a mailto address) formatted as:

List-Unsubscribe: <https://example.com/unsubscribe?id=12345>

The URL must be unique per recipient and message to identify who is unsubscribing. Many senders include encrypted tokens or subscriber IDs in the URL parameters.

One-Click Unsubscribe Support

To comply with RFC 8058 and enable one-click unsubscribe functionality, you must also include:

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

This signals to mailbox providers that your endpoint accepts POST requests for instant unsubscription without requiring the user to visit a webpage.

How It Works

When a recipient clicks the unsubscribe button in their email client, the system sends a POST request to your URL. Your server must process this request, unsubscribe the user immediately, and return an HTTP 200 response. No confirmation page or additional steps should be required for one-click unsubscribe to work properly.

Most email service providers (ESPs) handle this implementation automatically, but if you're sending emails directly or through custom systems, you'll need to ensure your unsubscribe endpoint processes both GET requests (for manual clicks) and POST requests (for one-click functionality).