List-Unsubscribe is an email header (RFC 2369) that provides mailbox providers with a URL or mailto address for processing unsubscribe requests outside of your email body. Gmail and Yahoo require it for senders sending 5,000+ messages per day. It enables the 'Unsubscribe' link shown next to the sender name in Gmail and the unsubscribe button in Yahoo, making it easier for recipients to opt out without hitting the spam button.
What Is the List-Unsubscribe Header?
List-Unsubscribe: The Header That Protects Your Reputation
List-Unsubscribe adds a machine-readable unsubscribe mechanism to your email headers. Mailbox providers use it to display native unsubscribe options — the "Unsubscribe" link next to your sender name in Gmail.
This isn't optional anymore. Gmail and Yahoo made it mandatory for bulk senders in February 2024. This is part of the broader email authentication and compliance requirements that all senders must follow.
The Headers
Two headers work together:
List-Unsubscribe: <https://example.com/unsub?id=abc123>, <mailto:[email protected]?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
The first header provides the unsubscribe endpoints (URL and/or mailto). The second header tells providers to process one-click unsubscribe via HTTP POST — no user confirmation required.
Why Both Headers Matter
| Header | Purpose | Required By |
|---|---|---|
List-Unsubscribe | Provides unsub URL/mailto | Gmail, Yahoo (bulk senders) |
List-Unsubscribe-Post | Enables one-click processing | Gmail (mandatory), Yahoo |
Gmail won't show the unsubscribe link unless both headers are present and properly formatted. The POST endpoint must accept the request and process the unsubscribe within a reasonable time (Gmail expects action within 2 days).
Implementation
If your ESP handles this automatically, verify it's working by checking raw email headers. Look for both List-Unsubscribe and List-Unsubscribe-Post.
For self-hosted setups, add the headers in your MTA configuration. In Postfix:
header_checks = regexp:/etc/postfix/header_checks
Or inject them at the application level when constructing the email.
Your one-click endpoint must:
- Accept POST requests
- Process the unsubscribe immediately
- Return a 200 status code
- Not require authentication or a confirmation page
Practitioner note: I audit email headers regularly, and about 20% of senders I check have List-Unsubscribe but are missing List-Unsubscribe-Post. Gmail treats this as non-compliant. Check your raw headers — both must be present.
Practitioner note: The fear that List-Unsubscribe "makes it too easy to unsubscribe" is backwards. Every unsubscribe that happens via header is a spam complaint that didn't happen. Spam complaints hurt your reputation. Unsubscribes don't.
For the related implementation requirement, see one-click unsubscribe. If your List-Unsubscribe headers aren't configured correctly, schedule a consultation — I'll audit your headers and fix compliance gaps.
Sources
- RFC 2369: List-Unsubscribe Header
- RFC 8058: One-Click Unsubscribe
- Google: Email Sender Guidelines
- Yahoo: Sender Requirements
v1.0 · April 2026
Frequently Asked Questions
Is List-Unsubscribe required?
Yes, for bulk senders. Gmail and Yahoo require List-Unsubscribe (and specifically List-Unsubscribe-Post for one-click) for senders exceeding 5,000 messages/day. Without it, you risk throttling and spam placement.
Does List-Unsubscribe increase unsubscribes?
Slightly — but it significantly decreases spam complaints. Unsubscribes don't hurt your reputation. Spam complaints do. A subscriber who unsubscribes via header is one who would have otherwise hit 'Report Spam.' See [what is complaint rate](/definitions/what-is-complaint-rate) for more.
What's the difference between List-Unsubscribe and one-click unsubscribe?
List-Unsubscribe provides the mechanism (URL or mailto). One-click unsubscribe (List-Unsubscribe-Post) tells the provider to process the unsubscribe with a single POST request, no confirmation page needed. Gmail requires both headers together.
Do ESPs add List-Unsubscribe automatically?
Most major ESPs (Mailgun, SendGrid, Mailchimp, Postmark) add both List-Unsubscribe and List-Unsubscribe-Post headers automatically to marketing emails. If you're self-hosting, you need to implement it yourself.
Want this handled for you?
Free 30-minute strategy call. Walk away with a plan either way.