RFC 2369: List-Unsubscribe and List-* Headers

Current Standard Mailing Lists & Header Fields Mailing ListsUnsubscribeHeader Fields

ELI5: When you get a letter from a magazine subscription, there is usually a phone number and address to cancel. RFC 2369 adds the same thing to email — standardized headers that tell email clients how to unsubscribe, get help, subscribe, or reach the list owner.

Why This Exists

Before RFC 2369, there was no standard way for mailing list messages to advertise unsubscribe or management URLs. Users had to hunt through message footers for an unsubscribe link — if one existed at all. This RFC defined a family of List-* header fields that email clients can parse and present as UI elements (like Gmail's "Unsubscribe" link next to the sender name).

Today, these headers are essential for commercial email. Gmail, Yahoo, and Apple Mail all use List-Unsubscribe to display one-click unsubscribe buttons. RFC 8058 later extended this with a true one-click POST mechanism.

How It Works

Each List-* header contains one or more URIs (in angle brackets, comma-separated) that email clients can use for list management. The most important is List-Unsubscribe, but the RFC defines a full set:

The Complete List-* Header Family

Header	Purpose
`List-Unsubscribe`	URL(s) to unsubscribe from the list
`List-Subscribe`	URL(s) to subscribe to the list
`List-Help`	URL(s) for list documentation or help
`List-Post`	Address to send messages to the list (or `NO` if posting is not allowed)
`List-Owner`	Contact address for the list administrator
`List-Archive`	URL to the list's message archive

Header Examples

; HTTPS URL and mailto fallback
List-Unsubscribe: <https://example.com/unsub?id=abc123>,
    <mailto:unsub-abc123@example.com>

; One-click unsubscribe (RFC 8058 addition)
List-Unsubscribe-Post: List-Unsubscribe=One-Click

; Other List-* headers
List-Subscribe: <https://example.com/subscribe>
List-Help: <https://example.com/list-help>
List-Post: <mailto:discussion@example.com>
List-Owner: <mailto:listadmin@example.com>
List-Archive: <https://example.com/archive>

URI Schemes

The RFC allows any URI scheme, but in practice two are used:

mailto: — the client sends an email to the specified address to trigger the action. This is the original mechanism and still serves as a fallback.
https: — the client opens a web URL. Combined with RFC 8058's List-Unsubscribe-Post, this enables true one-click unsubscribe via an HTTP POST.

When multiple URIs are provided, the email client chooses which to use. Most modern clients prefer HTTPS over mailto when List-Unsubscribe-Post is present.

Key Technical Details

Correct Header Format

URIs must be enclosed in angle brackets. Multiple URIs are comma-separated. Whitespace and line folding are permitted per standard header folding rules (RFC 5322).

Correct:
List-Unsubscribe: <https://example.com/unsub?id=abc>, <mailto:unsub@example.com>

Incorrect (missing angle brackets):
List-Unsubscribe: https://example.com/unsub?id=abc

The mailto URI

A mailto URI for unsubscribe can include a subject or body:

List-Unsubscribe: <mailto:unsub@example.com?subject=unsubscribe-abc123>

The receiving system processes the incoming email to trigger the unsubscribe. This works even when the recipient's email client does not support HTTPS-based unsubscribe.

List-Post: NO

For announcement-only lists where recipients cannot post, use the special value:

List-Post: NO

Common Mistakes

Missing angle brackets. The URIs must be wrapped in < >. Without them, email clients will not parse the header correctly.
HTTPS URL without List-Unsubscribe-Post. If you provide an HTTPS URL but omit the List-Unsubscribe-Post header (RFC 8058), Gmail and Yahoo will not show the one-click unsubscribe button. They require both headers together.
Unsubscribe URL that requires login. The unsubscribe endpoint must work without requiring the user to log in. It should identify the subscriber from the URL parameters alone.
Broken or expired URLs. If the unsubscribe URL returns an error or redirects to a generic page, mailbox providers may penalize your sender reputation. These URLs must work reliably.
Adding List-Unsubscribe to transactional email. List-* headers are for bulk/commercial email. Adding them to password resets, order confirmations, or other transactional messages confuses recipients and is semantically wrong.
Not including a mailto fallback. While HTTPS is preferred for one-click, a mailto URI ensures compatibility with older email clients that do not support HTTP-based unsubscribe.

Deliverability Impact

Gmail and Yahoo require it. Since February 2024, Gmail and Yahoo require List-Unsubscribe (with RFC 8058 one-click support) for bulk senders. Messages without these headers are more likely to be filtered.
Reduces spam complaints. When users can easily unsubscribe via the email client UI, they are far less likely to hit "Report Spam." Lower complaint rates directly improve inbox placement.
Signals legitimate sending. The presence of properly formatted List-* headers is a positive signal to spam filters. It indicates the sender follows best practices and provides a way out for recipients.
Apple Mail integration. Apple Mail uses List-Unsubscribe to show an unsubscribe banner at the top of messages. Missing headers mean missing functionality for a significant portion of your audience.