List-Unsubscribe and List-Id: what RFC 2369/2919 define
A standards-first look at the List-* headers: how a mail client shows an unsubscribe option and identifies a list without parsing the message body.
Why a mail client used to guess at unsubscribe links
Before these headers existed, a mail client had no reliable way to offer an unsubscribe option or identify which list a message belonged to. It had to parse the message body for an unsubscribe link, one that could sit anywhere in the footer and use any wording the sender chose. Identifying list membership meant guessing from the subject line instead, and subject lines change from message to message.
Both approaches were unreliable. A body parser breaks the moment a sender changes its footer template. A subject-line guess breaks the moment a sender changes its subject wording. Neither gave a mail client a dependable signal to build a feature on.
What RFC 2369 and RFC 2919 define
RFC 2369 defines a family of List-* headers a mail client can read directly, without touching the body: List-Unsubscribe, List-Help, List-Subscribe, List-Owner, List-Archive, and List-Post. Each one maps to a specific list-management action: unsubscribing, getting help, subscribing, reaching the list owner, browsing the archive, or posting to the list.
RFC 2919 defines List-Id specifically: one stable, machine-readable identifier for a list, independent of subject line or display name. The RFC 2369 headers describe actions a recipient can take. List-Id answers a different question: which list is this message even from.
How List-Unsubscribe and List-Id work
A sender adds a List-Unsubscribe header with one or more angle-bracket URIs, typically a mailto: address, an https: link, or both. A mail client reads that header directly and renders its own unsubscribe interface, with no need to open the message or scan its content.
List-Id gives every message from a given list the same stable identifier, so a client can group, filter, or apply rules to list mail without depending on any particular subject line wording. The identifier stays constant across every message the list sends, even as subjects change from one message to the next.
Anatomy of the headers
List-Unsubscribe: a comma-separated list of <uri> entries.
| Form | Example | What it tells the client |
|---|---|---|
mailto: | <mailto:unsubscribe@example.com> | Send an email to this address to unsubscribe |
https: | <https://example.com/unsubscribe?id=123> | Open this page to unsubscribe |
List-Id: a display name followed by a stable identifier string.
| Component | Example | Purpose |
|---|---|---|
| Display name | "Weekly Digest" | Human-readable label, in quotes |
| List identifier | <digest.example.com> | Stable, machine-readable string, in angle brackets |
A later standard extends List-Unsubscribe without replacing it: RFC 8058 adds a List-Unsubscribe-Post header carrying the value List-Unsubscribe=One-Click, which tells a mail client to submit the unsubscribe request as a single POST rather than opening a confirmation page.
Worked example
A message carrying both headers:
List-Unsubscribe: <mailto:unsubscribe@example.com>, <https://example.com/unsubscribe?id=123>List-Id: "Weekly Digest" <digest.example.com>
A mail client reading this header block can render an "Unsubscribe" button next to the message without opening it or looking at anything else in the message.
What these headers don't enforce
Both headers are advisory. RFC 2369 doesn't force a sender to honor an unsubscribe request submitted through List-Unsubscribe, and no rule requires a mail client to display either header at all.
The RFC does not create that requirement. Major mailbox providers do: Gmail and Yahoo now require List-Unsubscribe on bulk senders as a condition of inbox placement, and that provider policy is what drives adoption today.
Check it yourself
Open the raw headers on any bulk email sitting in your inbox. In Gmail, open the message and select "Show original" from the menu, then look for List-Unsubscribe and List-Id in the header block.
Where it fits
List-Unsubscribe, List-Id, and the rest of the List-* family live in the same header block defined by message format, the RFC 5322 syntax every email header follows. They travel to the recipient over SMTP, the same transport carrying every other header on the message.
RFC 8058 extends List-Unsubscribe with one-click POST submission, but it depends on marketing-list mechanics that sit outside what this page covers. For the full standards landscape these headers sit inside, see the reference hub.
FAQ
Is List-Unsubscribe required by the RFC?
No. RFC 2369 defines the header's format, it doesn't require any sender to include it. In practice, major mailbox providers now require it on bulk mail as a deliverability policy, separate from the standard itself.
What's the difference between List-Id and the Subject line?
List-Id is a stable, machine-readable identifier meant to stay constant across every message from a list. A subject line can change message to message, which makes it unreliable for a client trying to group or filter list mail.
Does List-Unsubscribe require a webpage?
Not necessarily. It supports a mailto: URI, an https: URI, or both together. A mail client can pick whichever it supports.
How does List-Unsubscribe relate to one-click unsubscribe?
List-Unsubscribe defines the base header. RFC 8058 adds a companion header that tells a mail client to submit the unsubscribe as a single POST request rather than opening a confirmation page.
RFC reference
RFCs covered: RFC 2369, RFC 2919. Superseded / updated by: None.