The List-Unsubscribe header is a hidden email header that tells a mailbox provider where to send an unsubscribe request, so Gmail, Yahoo, and Apple Mail can show a native "Unsubscribe" link next to your sender name. Paired with the List-Unsubscribe-Post header defined in RFC 8058, it enables one-click unsubscribe: the recipient clicks once, the provider sends an automated request to your server, and you remove that address without the person ever loading a landing page. If you send bulk email to Gmail or Yahoo accounts, both headers are mandatory and unsubscribe requests must be honored within two days.
Reads public DNS only. Nothing is stored unless you save the domain to an account.
What the List-Unsubscribe header does
List-Unsubscribe predates the one-click standard. It has existed since RFC 2369 (1998) as a way for mailing lists to advertise an unsubscribe method to mail clients. The header holds one or more URIs, each wrapped in angle brackets, that a client can use to remove the recipient from the list.
Two URI schemes are allowed:
- A
mailto:link, which triggers an unsubscribe email to a mailbox you monitor. - An
https:link, which points to a web endpoint that processes the removal.
A minimal header with both looks like this:
List-Unsubscribe: <mailto:unsub@example.com?subject=unsubscribe>, <https://example.com/u/abc123>
On its own, this header still requires interpretation. A mailbox provider cannot be sure that following the URL will avoid signing the user up for something, exposing them to tracking, or requiring a login. So historically many clients either ignored it or, at best, prompted the user before acting. That is the gap RFC 8058 closes.
How RFC 8058 adds one-click
RFC 8058, published in January 2018, defines a companion header named List-Unsubscribe-Post. Its only valid value is:
List-Unsubscribe-Post: List-Unsubscribe=One-Click
The presence of this header signals from the sender that the https: URL in List-Unsubscribe is safe to call automatically, and that the correct action is an HTTP POST to that URL with the body List-Unsubscribe=One-Click. No GET, no page load, no confirmation step. The mailbox provider performs the POST on the user's behalf the instant they click the native Unsubscribe control.
For a message to qualify, three conditions must hold:
- Both
List-Unsubscribe(with anhttps:URI) andList-Unsubscribe-Postare present. - The message carries a valid DKIM signature, and that signature covers at least the
List-UnsubscribeandList-Unsubscribe-Postheader fields. This stops an attacker from forging or stripping the headers in transit. If DKIM is new to you, see how to set up DKIM. - The unsubscribe URL is unique per recipient and per list, so the POST carries enough information to identify exactly who to remove and from what.
The endpoint must accept the POST without cookies, HTTP authentication, or any other credential. The provider strips identifying data on purpose; all the context lives in the opaque token embedded in the URL. When your server receives the request, it looks up the token, removes the address, and returns a 200 response.
The request your server receives
A one-click POST from a provider looks roughly like this:
POST /u/abc123 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26
List-Unsubscribe=One-Click
Your handler should treat any well-formed POST to that URL as a valid unsubscribe. Do not require the body to match beyond the List-Unsubscribe=One-Click field, and do not redirect to a confirmation page. The person is done.
mailto vs https
Both URI types can appear in List-Unsubscribe, and including both is good practice. They serve different clients and failure modes.
| Aspect | mailto: | https: |
|---|---|---|
| One-click (RFC 8058) | Not eligible | Eligible when paired with List-Unsubscribe-Post |
| How it is triggered | Client sends an email | Provider sends an HTTP POST |
| Processing speed | Depends on how fast you read the mailbox | Immediate, machine to machine |
| Failure risk | Message can be delayed, filtered, or blocked | Endpoint downtime returns an error |
| Best used as | Fallback for older clients | Primary path for Gmail and Yahoo |
The https: URL is what Gmail and Yahoo act on for their one-click button, so it must be present for a bulk sender to comply. The mailto: entry is a sensible fallback for mail clients that predate RFC 8058 or that prefer the email method. Provide both, and make sure the mailbox behind any mailto: is actually monitored, because an unattended unsubscribe inbox is a compliance failure that both regulators and providers notice.
The two-day processing requirement
Google and Yahoo both require that you process an unsubscribe request within two days (48 hours). This is stricter than the ten-business-day window that CAN-SPAM has historically allowed in the United States, so the provider rule is the one to design around.
Two days is the outer limit, not a target. For a one-click POST the removal should be effectively immediate, since your endpoint receives the request in real time. The 48-hour window mainly exists to cover asynchronous processing, queued jobs, and mailto: requests that land in a mailbox you poll. If a recipient keeps receiving promotional mail after they unsubscribed, that drives spam complaints, and a high complaint rate damages your ability to reach the inbox at all. Related reading on that feedback loop lives in what is sender reputation and why emails go to spam.
Who has to add these headers
The one-click requirement applies to bulk senders, which Google and Yahoo define as anyone sending 5,000 or more messages per day to personal accounts at their domains. Once you cross that threshold, one-click unsubscribe joins authenticated mail (SPF, DKIM, and a DMARC policy), a spam complaint rate kept under 0.3 percent (and ideally under 0.1 percent), and other rules. The full checklist is covered in the 2026 bulk email sender requirements and the provider-specific Google and Yahoo sender requirements.
Two important scope limits:
- The requirement covers promotional and commercial mail. Transactional messages such as password resets, receipts, shipping notices, and security alerts are exempt, because there is nothing to unsubscribe from. Adding the header to transactional mail is harmless but not required.
- The 5,000 per day figure is a floor for enforcement, not a reason to skip the header below it. One-click unsubscribe is now expected practice for any marketing program, and adding it early protects reputation before you scale.
How to implement it
Most email service providers add both headers for you. Platforms such as Mailchimp, SendGrid, Postmark, Mailgun, Brevo, and Klaviyo generate per-recipient tokens, sign the message with DKIM, and run the unsubscribe endpoint on their infrastructure. In that case your job is to keep your list synced with their suppression list and confirm the header is present in a real send.
If you send mail yourself, from an application server or your own SMTP setup, you own the full implementation:
- Generate a unique, unguessable token for each recipient and campaign, and store the mapping from token to subscriber.
- Add
List-Unsubscribewith anhttps:URI containing that token, plus amailto:fallback. - Add
List-Unsubscribe-Post: List-Unsubscribe=One-Click. - Ensure your DKIM signing includes both headers in the signed set (
h=). This is the step self-senders most often miss. If neither header is signed, providers will not honor the one-click path. - Build an endpoint that accepts an unauthenticated POST, removes the subscriber, returns
200, and never redirects. - Poll the
mailto:mailbox and process those requests too.
After deploying, send a test message to a Gmail and a Yahoo account and confirm the native Unsubscribe link appears near the sender name. You can also inspect the raw source; the guide on how to read email headers walks through finding these fields. Fold the whole thing into your broader email deliverability best practices so it does not drift out of sync.
Frequently asked questions
Does the List-Unsubscribe header replace the unsubscribe link in my email body?
No. Providers still require a clearly visible unsubscribe link inside the message body. The header adds a second, faster path that the mailbox provider surfaces as a native button; it does not remove the obligation to offer a visible link that anyone can find and use.
Why is my one-click unsubscribe button not showing in Gmail?
The most common cause is DKIM. Gmail only honors one-click when a valid DKIM signature covers both the List-Unsubscribe and List-Unsubscribe-Post headers. Check that both header names are listed in your DKIM h= tag, that the List-Unsubscribe value includes an https: URI, and that List-Unsubscribe-Post reads exactly List-Unsubscribe=One-Click.
Do transactional emails need a List-Unsubscribe header?
No. The requirement applies to promotional and marketing mail. Transactional messages such as receipts, password resets, and shipping updates are exempt because the recipient cannot opt out of mail tied to an action they took. Adding the header does no harm, but it is not required for these messages.
What HTTP response should my unsubscribe endpoint return?
Return a 200 status after processing the removal. Do not require authentication, do not set cookies, and do not redirect the request to a confirmation page. The mailbox provider sends the POST on the user's behalf and expects a clean success response with no further interaction.
Adding both headers correctly depends on DKIM signing that actually covers them, and a broken or missing signature is the usual reason one-click fails silently. Run a free scan with SPFWise to check your SPF, DKIM, and DMARC setup and confirm the authentication your one-click unsubscribe relies on is in place.