InboxRatio
Check your domain

Glossary term

List-Unsubscribe header: the machine-readable exit

What the List-Unsubscribe header is

List-Unsubscribe is a message header, defined in RFC 2369, that declares in machine-readable form where an opt-out request for this mailing should go. It is invisible to the reader but fully visible to the mailbox provider, which is the point: the header powers the native unsubscribe controls Gmail, Yahoo and Outlook display near the sender name, outside your message body entirely.

The header carries one or two URIs — an HTTPS endpoint, a mailto: address, or both:

List-Unsubscribe: <mailto:unsub@example.com>, <https://example.com/u/opaque-token>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The second header shown, List-Unsubscribe-Post, comes from RFC 8058 and upgrades the HTTPS variant to one-click: its fixed value promises the provider that a bare HTTPS POST to the URL completes the opt-out with no landing page, login or confirmation step. Together the pair is what the Gmail and Yahoo bulk-sender requirements mandate for marketing and subscribed mail.

RFC 2369 actually defines a family of List-* headers (List-Help, List-Subscribe, List-Post and others) dating to 1998. List-Unsubscribe is the member that graduated from mailing-list convention to compliance requirement, because it sits directly upstream of the complaint rate that providers score.

How the header differs from the footer link

Both lead out of your list. They serve different actors through different surfaces.

The body link is content: HTML in your footer, rendered wherever the reader scrolls, leading to whatever page you built. Its quality is a human-experience question (visibility, trust, steps to completion), and the unsubscribe entry covers that side in full.

The header is metadata: parsed by the receiving system, surfaced in the provider's own chrome, and executed by the provider on the user's behalf under RFC 8058. You control the endpoint; the provider controls the interface. The recipient may complete the entire opt-out without ever opening your message body.

The compliance consequence is that neither substitutes for the other. Gmail and Yahoo require the header mechanism and a clearly visible link in the message. A sender with an immaculate preference center but no header fails the requirement; so does a header-compliant sender whose footer link is hidden. Different doors, both load-bearing.

How the List-Unsubscribe header works

Declaration. Your sending platform injects the header pair at send time. The HTTPS URL must identify the recipient and list by itself, through an opaque token rather than a readable email address — RFC 8058 is explicit that the URI carries its own context.

Authentication. RFC 8058 requires the message to be authenticated, and the two List-Unsubscribe headers to be covered by a valid DKIM signature. This is what stops a forger from injecting opt-out headers pointing at malicious endpoints: a provider only honors the mechanism on mail whose signed headers vouch for it. Your DKIM alignment work is therefore a prerequisite, not a separate track.

Execution. When the recipient uses the provider's unsubscribe control, your endpoint receives an HTTPS POST with the body List-Unsubscribe=One-Click. The RFC forbids redirects on this path and forbids requiring any further human step. Your server confirms with a 2xx response, and the opt-out lands in your suppression list.

The mailto fallback. A mailto: URI in the header remains valid RFC 2369 and some providers still use it, generating an opt-out email to the address given. It is the compatibility layer, not the compliance layer: one-click as the requirements define it is the HTTPS POST mechanism.

Verifying your own stream takes one delivered message in the email header analyzer — confirm both headers are present, the URL is HTTPS, and the DKIM signature's h= list includes them.

The List-Unsubscribe header and your deliverability

The direct stake is binary compliance: bulk senders without functioning one-click unsubscribe fail the Gmail and Yahoo requirements, in the same tier of mandate as SPF, DKIM and DMARC. Enforcement began in 2024 and is not grandfathered away by list age or opt-in quality.

The indirect stake is complaint arithmetic. The provider's unsubscribe control sits next to the spam button, and every recipient it satisfies is a complaint that never reaches your sender reputation. Providers built the native control precisely because footer links historically underperformed; routing exits through your header instead of the spam button is the cheapest complaint-rate reduction available. The spam-rate ceilings those complaints count against are documented in the Gmail requirements page.

There is also a signal-quality reading. A well-formed, signed, functioning header pair is weak evidence of a legitimate operation; its absence on bulk marketing mail is a mark filters have learned to weigh. Postmaster dashboards will show you the complaint consequences either way.

Limitations and failure modes

Header present, endpoint dead. The pair ships, the endpoint 404s or times out, the provider's interface offered an exit that did nothing. The recipient's next click is the spam button, now with evidence. The POST path is production infrastructure; monitor it like one.

Unsigned headers. The platform emits the pair but the DKIM signature does not cover them, or the message fails authentication outright. RFC 8058's guarantee dissolves, and providers may decline to show the control at all. This failure is invisible in your dashboard and obvious in a raw header inspection.

GET-only endpoints. An endpoint that unsubscribes on GET, built for the footer link, wired into the header URL. Link-scanning security software fetches URLs in delivered mail, and every scan becomes an opt-out. RFC 8058 chose POST specifically to survive scanners; honor the method distinction.

Redirect chains. The RFC forbids redirects on the one-click POST. Tracking-domain hops that are harmless on the body link break the header path at providers that enforce the rule strictly.

Mailto-only in a one-click world. A header carrying only a mailto: URI predates the requirement and leaves the mandated HTTPS mechanism unimplemented. Ship the HTTPS pair; keep mailto as a companion if you like.

Slow honoring. The click succeeded, but the suppression sync runs weekly and two more campaigns land first. Both providers' published windows are days, not weeks, and the recipient who already left is the likeliest complainant on your list. Wire the POST straight into suppression, then let list hygiene handle the rest.

Related terms

Unsubscribe, complaint rate, suppression list, feedback loop, DKIM, DMARC, sender reputation, Postmaster Tools, list hygiene.

Frequently asked questions

Is the List-Unsubscribe header required? For bulk senders of marketing and subscribed mail at Gmail and Yahoo, yes — specifically the RFC 8058 one-click pair, alongside a visible unsubscribe link in the body. Purely transactional mail sits outside the mandate.

What is the difference between List-Unsubscribe and List-Unsubscribe-Post? The first (RFC 2369) says where opt-outs go. The second (RFC 8058) promises that a bare HTTPS POST to that URL completes the opt-out in one step. One-click compliance requires both, with the URL being HTTPS.

Should the header use mailto or HTTPS? HTTPS is the mechanism the requirements define; include it always. A mailto: alongside it is legitimate and helps older clients, but a mailto-only header does not satisfy one-click.

Why does Gmail not show an unsubscribe option on my mail? Usual causes: the header pair is missing or malformed, the message fails authentication, the DKIM signature does not cover the headers, or the provider has not yet built confidence in the sender. Check a delivered message's raw headers rather than your platform's settings screen.

Can the header be abused to unsubscribe people maliciously? The design defends against it: the URL carries an opaque per-recipient token, the headers must arrive under a valid DKIM signature, and the one-click POST comes from the mailbox provider. A forged message without your signature does not get the control rendered.

Do unsubscribes through the header hurt my reputation? No — opt-outs are not complaints. They are the reputationally free exit, and every one of them through the header is a spam-button click you did not receive.

Send yourself one live campaign message and read it in the email header analyzer: both headers present, HTTPS URL, covered by your DKIM signature. Then POST to your own endpoint the way a provider would and watch the suppression record appear. Ten minutes, and the most heavily mandated header in email is verified end to end.

Sources