List-Unsubscribe Header: One-Click Unsubscribe Explained

The List-Unsubscribe header is an email header field that lets mailbox providers render a native “Unsubscribe” button at the top of a message, separate from any unsubscribe link in the body. When paired with the List-Unsubscribe-Post header defined in RFC 8058, that button triggers a true one-click unsubscribe: the mail client sends an HTTP POST to your endpoint with no further interaction from the recipient and no confirmation landing page. Since February 2024, Google and Yahoo require all senders who send more than 5,000 messages per day to support this mechanism for marketing email and subscribed messages, and to process those requests within two days.

Two Headers, Two Standards

The List-Unsubscribe header has existed since RFC 2369 (1998), which defined it as a header that “describes the command to directly unsubscribe the user.” In its original form, it accepts one or more URIs pointing to either a mailto: address or an HTTP URL:

List-Unsubscribe: <https://example.com/unsub?token=abc123>, <mailto:[email protected]?subject=unsubscribe>

The mailto: variant asks the mail client to send an email to that address. The https:// variant links to a web page. Neither of these is one-click in the RFC 8058 sense: they require the mail client to open an email compose window or navigate a browser to a URL, possibly including a confirmation step.

RFC 8058, published in 2017, adds a second header that signals true one-click capability. According to the specification, “this document describes a method for signaling a one-click function for the List-Unsubscribe email header field.” The List-Unsubscribe-Post header must contain exactly one value:

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

Together, the full pair looks like this:

List-Unsubscribe: <https://example.com/unsub?token=abc123>, <mailto:[email protected]?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The List-Unsubscribe-Post header signals to the mail client that it can send a POST request to the HTTPS URI in List-Unsubscribe rather than requiring any user interaction beyond the initial click. The mailto: URI remains optional but does not satisfy the one-click requirement on its own.

How the One-Click POST Works

When a recipient clicks the native “Unsubscribe” button, the mailbox provider (not the recipient’s browser) issues an HTTP POST to the URL in your List-Unsubscribe header. The request body is exactly what the List-Unsubscribe-Post header specified:

POST /unsub?token=abc123 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

List-Unsubscribe=One-Click

RFC 8058 is explicit about what this endpoint must not do: “The POST request MUST NOT include cookies, HTTP authorization, or any other context information.” This means your unsubscribe endpoint cannot require the recipient to log in, cannot set a session cookie, and cannot redirect to a page asking the user to confirm. The unsubscribe must be processed silently and immediately.

Your endpoint should:

• Accept POST only (reject GET requests so bots and pre-fetch scanners cannot trigger accidental unsubscribes)
• Be idempotent (processing the same token twice must not return an error)
• Identify the recipient from a signed token in the URL, not from a guessable ID or an exposed email address
• Return HTTP 200 on success

Do not record the provider’s POST as an open or click event. The provider is acting on the user’s behalf; it is not a sign of engagement.

Gmail and Yahoo 2024 Requirements

Both Google and Yahoo tightened their policies for bulk senders in early 2024. The requirements overlap but are not identical.

Google (Gmail): Senders who send more than 5,000 messages per day to Gmail accounts must support one-click unsubscribe for marketing and subscribed messages. Google’s sender guidelines state that senders must “include a clearly visible unsubscribe link in the message body” alongside the header, and must “keep spam rates reported in Postmaster Tools below 0.10%” to stay in good standing (the hard cutoff before delivery impact is 0.30%). Google’s announcement specified that senders must “process unsubscription requests within two days.”

Yahoo: Yahoo’s Sender Best Practices require bulk senders to “implement a functioning list-unsubscribe header, which supports one-click unsubscribe for marketing and subscribed messages,” “honor unsubscribes within 2 days,” and “keep your spam rate below 0.3%.”

The 2-day processing window appears in both sets of guidelines. It is not simply best practice; both providers treat delayed processing as non-compliance.

One-click unsubscribe applies to marketing and subscribed messages only. Transactional mail (password resets, receipts, shipping confirmations) is out of scope, though it is good practice to include a List-Unsubscribe header there too if users can opt out of that communication type.

Why One-Click Unsubscribe Helps Deliverability

The connection between unsubscribe friction and sender reputation is direct. A recipient who cannot easily unsubscribe does not stop receiving your mail. They mark it as spam. That spam report counts against your complaint rate in both Google’s Postmaster Tools and Yahoo’s feedback systems. A rising complaint rate pushes more of your mail to the junk folder, including mail to people who want it.

A native unsubscribe button in the inbox UI reduces the number of recipients who reach for the “Report Spam” button out of frustration. The easier it is to leave, the less likely a disengaged subscriber takes an action that damages your deliverability. This is the mechanism behind the requirement: providers are incentivizing a practice that benefits everyone, including the sender.

For the same reason, a high-quality list built with double opt-in reduces the proportion of disengaged subscribers who need to unsubscribe in the first place, but one-click unsubscribe remains necessary regardless of list quality.

Common Implementation Mistakes

Adding the List-Unsubscribe-Post header but pointing to a page that requires login. This is the most common error. The RFC prohibits cookies and HTTP authorization on this endpoint. If your unsubscribe page is behind a login wall, the one-click POST will return a redirect or a 401, and the provider will either retry or silently discard the request. The subscriber remains on your list.

Only implementing mailto: in List-Unsubscribe. The mailto: variant alone does not satisfy RFC 8058 or Gmail/Yahoo’s one-click requirement. You need the https:// URI and the List-Unsubscribe-Post header.

Not handling the POST method. Some frameworks default to accepting only GET on route handlers. If your endpoint returns 405 Method Not Allowed on POST, the unsubscribe silently fails.

Using guessable identifiers. A URL like /unsub?user_id=1234 lets anyone unsubscribe anyone else. Use a signed, time-limited token that encodes the recipient identifier and can be verified server-side.

Treating the provider POST as an engagement signal. The mailbox provider is the one sending this request, not the recipient clicking in a browser. Logging it as an open or a click inflates engagement metrics and can confuse your webhook processing pipeline.

Not including a body unsubscribe link. The header and the body link are separate requirements. Gmail’s guidelines specifically call for both. Gmail flagging your emails as going to spam is more likely if the body link is missing even when the header is present.

Most established ESPs add the List-Unsubscribe and List-Unsubscribe-Post headers automatically on bulk sends and manage the unsubscribe endpoint for you. If you are sending through your own infrastructure or a developer-focused platform like Coldletter, you need to implement this at the application layer.

Frequently Asked Questions