List-Unsubscribe Header

The List-Unsubscribe header is an email header, defined in RFC 2369, that gives mail clients a mailto or web address for opting out. Gmail and Yahoo use it to show a built-in unsubscribe button and, together with RFC 8058, require it from bulk senders.

Deliverability & Email InfrastructureUpdated September 30, 2026

In short

List-Unsubscribe is a header that lets the inbox itself offer an unsubscribe button.

Key points

  1. RFC 2369 defines List-Unsubscribe as one or more URIs in angle brackets, usually a mailto address and an HTTPS link [1].
  2. RFC 8058 adds a companion List-Unsubscribe-Post header that signals One-Click Unsubscribe support [2].
  3. Gmail requires bulk senders' marketing and subscribed messages to include both headers, alongside a visible unsubscribe link in the body [3].
  4. Yahoo's sender requirements also call for a working list-unsubscribe header with one-click support for bulk mail [4].
  5. Mailbox providers surface the header as an unsubscribe control near the sender name, which gives recipients an alternative to reporting spam and helps your Spam Complaint Rate [3].

What the header looks like

The List-Unsubscribe header belongs to a family of list headers standardized in RFC 2369 in 1998, alongside List-Help and List-Subscribe [1]. Its value is a comma-separated list of URIs enclosed in angle brackets, for example a mailto address with a subject line and an HTTPS URL that identifies the recipient. A mail client that understands the header can show its own unsubscribe option without the reader hunting for a link in the footer. RFC 8058 later added List-Unsubscribe-Post with the fixed value List-Unsubscribe=One-Click, which tells the client it may send an HTTPS POST to the URL and complete the opt-out immediately [2]. Both headers sit among the other Email Headers and should be covered by the DKIM (DomainKeys Identified Mail) signature.

Who requires it

Since February 2024, Gmail's sender guidelines require bulk senders, those sending around 5,000 or more messages a day to personal Gmail accounts, to support one-click unsubscribe on marketing and subscribed messages using the List-Unsubscribe and List-Unsubscribe-Post headers [3]. Gmail also asks for a clearly visible unsubscribe link in the message body and recommends processing requests within 48 hours [3]. Yahoo's Sender Hub lists the same expectation for bulk senders and asks that unsubscribes be honored within 2 days [4]. These rules sit on top of legal duties such as the opt-out requirement in the CAN-SPAM Act. Together they form a large part of the Bulk Sender Requirements that took effect in 2024.

Implementing it correctly

A good implementation includes an HTTPS URL unique to each recipient and message, a List-Unsubscribe-Post header, and a DKIM signature that covers both [2]. The endpoint should accept a POST without cookies or login, record the opt-out on a Suppression List and return success. A mailto option is still useful for older clients, but the mailbox receiving those requests must be monitored or processed automatically. For one-to-one Cold Email sent from a normal mailbox, the header is less common, and many senders instead offer a plain-text Opt-Out line and act on reply requests. Whichever approach you use, the outcome must be the same: the person is never contacted again, which protects Sender Reputation.

Sources
  1. RFC 2369: The Use of URLs as Meta-Syntax for Core Mail List Commands — RFC Editor
  2. RFC 8058: Signaling One-Click Functionality for List Email Headers — RFC Editor
  3. Email sender guidelines — Gmail Help
  4. Sender Best Practices — Yahoo Sender Hub
External sources open in a new tab.

Related terms

One-Click Unsubscribe

One-click unsubscribe lets people opt out instantly from the inbox, with no web page or login.

Bulk Sender Requirements

Large mailbox providers now require authentication, low complaints and easy unsubscribes from high-volume senders.

Opt-Out

Every commercial email needs an easy way to say stop, and once someone does, you must stop emailing them within the legal deadline and keep them suppressed.

Suppression List

A suppression list blocks sends to people who opted out, complained or bounced.

Email Headers

Email headers are the metadata fields that describe a message's origin, route and authentication.

CAN-SPAM Act

CAN-SPAM lets you send commercial email in the US without prior consent, as long as you are honest about who you are, include an address, and honor opt-outs quickly.

Mentioned in
Email Service Provider (ESP)Sales Engagement Platform

Outreach without the busywork.

PineLead finds new B2B prospects every day, qualifies them against your criteria and writes the first email in your voice. You approve — PineLead sends.

Start free with 100 credits →