Gmail users started seeing something new in 2014: an unsubscribe link right next to the sender's name, before they even opened the email. No hunting through footers, no tiny gray text, no multi-step processes. One click and done.
This feature is powered by the List-Unsubscribe header—a technical standard that's become essential for email deliverability. Gmail now requires it for bulk senders. Other providers use it to improve user experience. If you're sending marketing or bulk email, understanding and implementing this header is no longer optional.
What the header does
The List-Unsubscribe header provides email clients with a machine-readable way to unsubscribe recipients from your mailing list.
When present in your email headers, email clients can display an unsubscribe option in their interface—typically near the sender name or in a menu. Users can unsubscribe without opening the email, finding your unsubscribe link, or visiting your website.
The header can specify two methods for unsubscribing: a mailto address (send an email to unsubscribe) or an HTTPS URL (visit a page to unsubscribe). Best practice is to include both, giving email clients options.
This isn't a replacement for the unsubscribe link in your email body—you still need that for compliance with CAN-SPAM and other regulations. The header is an additional mechanism that makes unsubscribing easier and more visible.
Why it matters for deliverability
The List-Unsubscribe header has become a deliverability factor, not just a nice-to-have.
Gmail requires it for bulk senders. As of February 2024, senders who send more than 5,000 messages per day to Gmail addresses must include List-Unsubscribe headers with one-click unsubscribe support. Non-compliance can result in delivery problems.
Easy unsubscribe reduces spam complaints. When unsubscribing is hard, frustrated users hit the spam button instead. Spam complaints damage your sender reputation far more than unsubscribes. The header channels departures through the less damaging path.
Email clients favor senders who implement it. While not always explicit, providers like Gmail consider sender behavior in their filtering. Making unsubscribe easy signals that you're a legitimate sender who respects recipients.
It improves user experience, which indirectly helps deliverability. Happy recipients engage more and complain less. Anything that improves their experience with your email benefits your program.
Header syntax
The List-Unsubscribe header follows a specific format.
A basic header with just a mailto address looks like: List-Unsubscribe: <mailto:[email protected]?subject=unsubscribe>
A header with just an HTTPS URL looks like: List-Unsubscribe: <https://example.com/unsubscribe?id=abc123>
Best practice includes both: List-Unsubscribe: <mailto:[email protected]>, <https://example.com/unsubscribe?id=abc123>
The angle brackets are required. Multiple methods are separated by commas. The mailto can include subject and body parameters to help you identify the unsubscribe request.
The URL should be unique per recipient so you know who's unsubscribing. Include a token or identifier that maps to the specific subscriber.
List-Unsubscribe-Post for one-click
The List-Unsubscribe-Post header enables true one-click unsubscribe, which Gmail now requires for bulk senders.
Without this header, clicking unsubscribe in Gmail opens the URL in a browser, requiring the user to confirm on a webpage. With List-Unsubscribe-Post, Gmail sends an HTTP POST request directly to your URL, completing the unsubscribe without any user interaction beyond the initial click.
The header is simple: List-Unsubscribe-Post: List-Unsubscribe=One-Click
When both headers are present, email clients that support one-click will POST to your URL with the body "List-Unsubscribe=One-Click". Your server should process this and unsubscribe the user immediately.
This is the standard Gmail requires. If you're sending bulk email to Gmail users, you need both List-Unsubscribe (with an HTTPS URL) and List-Unsubscribe-Post headers.
Implementation details
Implementing List-Unsubscribe requires both header configuration and backend handling.
Generate unique URLs per recipient. Each email should have an unsubscribe URL that identifies the specific subscriber. This might be a signed token, a database ID, or another identifier that lets you process the unsubscribe correctly.
Handle POST requests for one-click. Your unsubscribe endpoint needs to accept POST requests with the one-click body and process them without requiring any user interaction. Return a 200 status code on success.
Handle GET requests for fallback. Some email clients will open the URL in a browser rather than POSTing. Your endpoint should handle GET requests too, either processing the unsubscribe directly or showing a confirmation page.
Process mailto unsubscribes. If you include a mailto address, you need to monitor that inbox and process unsubscribe emails. This can be automated but requires infrastructure.
Most email service providers handle this automatically. If you're using SendGrid, Mailgun, Postmark, or similar services, they add appropriate headers and handle the backend processing. Check your provider's documentation.
Common implementation mistakes
Several errors commonly cause List-Unsubscribe problems.
Missing the Post header means no one-click support. Gmail will show an unsubscribe option, but it opens a webpage rather than unsubscribing immediately. For bulk senders, this doesn't meet Gmail's requirements.
Broken URLs cause failed unsubscribes. If your unsubscribe URL returns errors, times out, or doesn't actually unsubscribe the user, you've made the experience worse, not better. Test your endpoints.
Non-unique URLs can't identify who to unsubscribe. If every email has the same unsubscribe URL with no recipient identifier, you can't process the request. Each URL must map to a specific subscriber.
Requiring authentication defeats the purpose. If your unsubscribe URL requires login, users can't unsubscribe easily. The URL should work without any authentication.
Slow processing frustrates users and email clients. One-click unsubscribe should be instant. If your endpoint takes seconds to respond, email clients might time out or users might think it didn't work.
Testing your implementation
Verify your List-Unsubscribe implementation works correctly.
Check headers in sent emails. Send a test email and view the raw headers. Verify List-Unsubscribe and List-Unsubscribe-Post are present with correct syntax.
Test the URL directly. Visit your unsubscribe URL in a browser. Does it work? Does it actually unsubscribe the test recipient?
Test the POST endpoint. Use curl or a similar tool to POST to your unsubscribe URL with the one-click body. Verify it returns 200 and processes the unsubscribe.
Test in Gmail. Send to a Gmail address and look for the unsubscribe option near the sender name. Click it and verify the unsubscribe processes correctly.
Monitor for errors. Once in production, monitor your unsubscribe endpoint for errors. Failed unsubscribes are bad for users and potentially for your sender reputation.
When to include the header
The header is appropriate for most bulk and marketing email, but not all email types.
Include it for newsletters, marketing emails, promotional content, and any recurring bulk communication. These are the emails where easy unsubscribe matters most.
Consider including it for notification emails that users might want to stop receiving. Even if they're technically transactional, if users might want to opt out, make it easy.
Don't include it for truly transactional emails like password resets, order confirmations, or security alerts. These aren't subscription-based, and an unsubscribe option doesn't make sense.
Don't include it for one-to-one personal emails. The header is for bulk/automated sending, not individual correspondence.
Frequently asked questions
Is List-Unsubscribe required by law?
Not directly, but CAN-SPAM and similar laws require an unsubscribe mechanism. The header supplements (doesn't replace) the required link in your email body. Gmail's requirement for bulk senders makes it effectively mandatory for that audience.
Does the header replace the unsubscribe link in my email?
No. You still need an unsubscribe link in the email body for legal compliance and for email clients that don't support the header. The header is an additional mechanism, not a replacement.
What if someone unsubscribes via the header but I don't process it?
You're violating their unsubscribe request, which is both a legal problem and a reputation problem. If they try to unsubscribe and keep getting emails, they'll mark you as spam.
Do all email clients support List-Unsubscribe?
Most major clients support it to some degree. Gmail, Apple Mail, Outlook.com, and Yahoo all recognize the header. Support for one-click (List-Unsubscribe-Post) is more limited but growing.