List-Unsubscribe Header: How to Implement Correctly

What List-Unsubscribe Does

The List-Unsubscribe header tells mailbox providers how to unsubscribe someone without them needing to find your unsubscribe link in the email body. Gmail shows it as an "Unsubscribe" link next to the sender name. Yahoo shows it similarly.

This isn't optional anymore. Since the 2024 Gmail/Yahoo bulk sender requirements, bulk senders must support List-Unsubscribe with one-click (RFC 8058).

The Two Headers You Need

List-Unsubscribe

This header provides one or two unsubscribe methods:

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

The HTTPS URL should point to an endpoint that processes the unsubscribe. The mailto address receives an email that triggers unsubscribe processing.

List-Unsubscribe-Post

This is the RFC 8058 one-click header:

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

When both headers are present, the mailbox provider can send a POST request to your HTTPS endpoint with the body List-Unsubscribe=One-Click. Your endpoint must process this without requiring any additional user interaction — no confirmation page, no login, no CAPTCHA.

Practitioner note: The most common implementation mistake I see is requiring authentication on the unsubscribe endpoint. Gmail sends the POST request server-side — there's no user session, no cookies. Your endpoint must process unauthenticated POST requests with just the subscriber identifier in the URL.

Implementation Requirements

Your HTTPS unsubscribe endpoint must:

1. Accept POST requests with the body List-Unsubscribe=One-Click
2. Process immediately — no confirmation step
3. Return HTTP 200 on success
4. Be HTTPS — HTTP won't work
5. Include a unique subscriber identifier in the URL (not the email address in plain text)
6. Actually unsubscribe the person — don't just acknowledge the request

Example endpoint behavior:

POST /unsubscribe?token=abc123def456
Content-Type: application/x-www-form-urlencoded

List-Unsubscribe=One-Click

Your server decodes the token, identifies the subscriber, removes them from the list, and returns 200.

ESP-Specific Configuration

SendGrid — Adds List-Unsubscribe automatically. Enable "Subscription Tracking" in Settings for one-click support. Verify with header inspection.

Mailgun — Automatically includes List-Unsubscribe headers when you use their unsubscribe tracking. One-click support was added in late 2023.

Postmark — Handles it automatically for all messages sent through their API with the MessageStream set to broadcast.

Mailchimp — Adds both headers automatically for all campaigns. No configuration needed.

Amazon SES — Does NOT add List-Unsubscribe automatically. You must add these headers yourself in the raw message or via the Headers parameter.

Custom SMTP — You're responsible for adding both headers to every marketing message.

Practitioner note: Amazon SES users get caught by this constantly. SES is infrastructure — it doesn't add any deliverability headers for you. If you're sending marketing email through SES, you need to add List-Unsubscribe and List-Unsubscribe-Post yourself in your application code.

Verifying Your Headers

Send a test message to yourself and inspect the raw headers:

Gmail: Open the message → three dots → "Show original" Outlook: Open → File → Properties → Internet Headers Apple Mail: View → Message → All Headers

Look for both List-Unsubscribe and List-Unsubscribe-Post headers. If either is missing, fix your implementation.

You can also check Google Postmaster Tools — the spam rate dashboard reflects whether Gmail is seeing proper unsubscribe support.

Common Mistakes

Mistake	Impact	Fix
Missing List-Unsubscribe-Post	No one-click support, violates 2024 requirements	Add the RFC 8058 header
Requiring authentication on endpoint	Gmail's server-side POST fails silently	Use token-based identification
Confirmation page on unsubscribe	Violates one-click requirement	Process POST immediately
HTTP instead of HTTPS	Providers won't use the URL	Switch to HTTPS
Plain-text email in URL	Privacy risk, abuse vector	Use opaque tokens

Practitioner note: After the 2024 requirements rolled out, I saw multiple clients whose "unsubscribe" endpoint was actually a preference center landing page. That doesn't count as one-click. Gmail wants the POST request to fully unsubscribe the person — no intermediate steps.

Relationship to One-Click Unsubscribe

List-Unsubscribe is the mechanism. One-click unsubscribe (RFC 8058) is the specific implementation that Gmail and Yahoo now require. You need both headers working together.

If you need help implementing compliant unsubscribe headers across your sending infrastructure, reach out for a deliverability audit — I'll verify your headers are correct across every sending source.

Sources

• RFC 2369: The Use of URLs as Meta-Syntax for Core Mail List Commands
• RFC 8058: Signaling One-Click Functionality for List Email Headers
• Google: Email Sender Guidelines
• Yahoo: Sender Requirements
• M3AAWG: Best Practices for Managing Unsubscribe Requests

---

v1.0 · April 2026