Back to Tools

List-Unsubscribe Header Generator

Generate RFC 8058 compliant List-Unsubscribe and List-Unsubscribe-Post headers. Required by Gmail and Yahoo for bulk senders since 2024. Get ready-to-use headers and code snippets.

About this tool

In February 2024, Gmail and Yahoo drew a hard line: bulk senders who don't support one-click unsubscribe get filtered to spam. If you send more than 5,000 emails per day to Gmail or Yahoo addresses, you need RFC 8058 compliant List-Unsubscribe and List-Unsubscribe-Post headers on every marketing email. This isn't optional anymore—it's table stakes for inbox placement.

How the Headers Work

Two headers work together to enable one-click unsubscribe. The List-Unsubscribe header provides the unsubscribe URL (and optionally a mailto fallback): List-Unsubscribe: <https://yourapp.com/unsubscribe?id=abc123>, <mailto:unsub@yourapp.com?subject=unsubscribe>. The List-Unsubscribe-Post header tells the mail client to use HTTP POST instead of GET: List-Unsubscribe-Post: List-Unsubscribe=One-Click. When a recipient clicks "Unsubscribe" in Gmail or Yahoo Mail, their client sends a POST request to your HTTPS URL with the body List-Unsubscribe=One-Click. Your server processes it and returns a 200 status. No confirmation page, no extra clicks.

Why This Matters for Deliverability

Before these requirements, users who couldn't find the unsubscribe link would hit the spam button instead. Every spam complaint hurts your sender reputation—Gmail's threshold is 0.3% complaint rate before they start throttling. By making unsubscribes frictionless, you trade a lost subscriber (who was leaving anyway) for a clean reputation. Senders who implemented one-click unsubscribe early saw spam complaint rates drop by 30-40% on average.

Common Implementation Mistakes

The most common mistake is using a GET endpoint instead of POST—RFC 8058 specifically requires POST to prevent accidental unsubscribes from link prefetchers. Another pitfall is requiring authentication on the unsubscribe endpoint; the request comes from the mail provider's servers, not the user's browser, so cookie-based auth won't work. Use a signed token in the URL instead. Also, make sure your endpoint responds quickly—Gmail expects a response within 10 seconds.

Complete Your Compliance Setup

One-click unsubscribe is just one piece of Gmail and Yahoo's 2024 sender requirements. You also need proper SPF, DKIM, and DMARC authentication. Run a CAN-SPAM compliance check to make sure your footer and opt-out mechanisms are legally compliant. Use the unsubscribe rate calculator to monitor whether your unsubscribe implementation is actually reducing complaints.

Frequently Asked Questions

What is one-click unsubscribe and why is it required now?

One-click unsubscribe (RFC 8058) lets email clients like Gmail show an 'Unsubscribe' button right at the top of your email. Since February 2024, Gmail and Yahoo require it for anyone sending 5,000+ emails per day. Without it, your emails are increasingly likely to land in spam. It's the single biggest compliance change for email marketers in years.

What exactly do the List-Unsubscribe headers look like?

You need two headers. The first is List-Unsubscribe containing an HTTPS URL (and optionally a mailto): List-Unsubscribe: <https://yourapp.com/unsub?token=abc>. The second is List-Unsubscribe-Post with the exact value: List-Unsubscribe-Post: List-Unsubscribe=One-Click. Both headers are required for one-click to work in Gmail and Yahoo.

Do I need both List-Unsubscribe and List-Unsubscribe-Post?

Yes, you need both. List-Unsubscribe alone only gives you the old-style unsubscribe (opens a browser window). Adding List-Unsubscribe-Post is what enables the one-click behavior where Gmail handles the unsubscribe inline without opening a browser. Missing either header means one-click won't activate.

How should my server handle the POST request?

Your HTTPS endpoint receives a POST with the body 'List-Unsubscribe=One-Click'. Immediately unsubscribe the user identified by the token in your URL and return HTTP 200. Don't require cookies or login—the request comes from Google's or Yahoo's servers, not the user's browser. Process within 10 seconds or the client may retry.

Does this apply to transactional emails too?

No, one-click unsubscribe is only required for marketing and promotional emails. Transactional emails like password resets, order confirmations, and account notifications are exempt. However, if your transactional emails include any promotional content, Gmail may classify them as marketing and expect the headers.

What's the mailto fallback for?

The mailto fallback (e.g., mailto:unsub@yourapp.com?subject=unsubscribe) is a legacy mechanism for email clients that don't support the HTTPS POST method. It's optional but recommended for maximum compatibility. When a client uses mailto, it generates an email to your address that you process server-side to unsubscribe the user.

Will adding unsubscribe headers increase my unsubscribe rate?

You might see a small initial increase, but these are people who would have hit the spam button instead. A spam complaint is 10x worse for your reputation than an unsubscribe. Most senders see their overall complaint rate drop significantly after implementing one-click, which improves deliverability for everyone else on your list.

How do I test that my one-click unsubscribe works?

Send a test email to a Gmail account and look for the 'Unsubscribe' link next to the sender name. Click it and verify your server receives the POST request and processes the unsubscribe. Check your server logs for the incoming request. You can also use tools like Postman to send a POST with body 'List-Unsubscribe=One-Click' to your endpoint directly.

More Free Tools

View all tools

CAN-SPAM Compliance Checker

Verify your email campaigns meet CAN-SPAM Act requirements. Check for required elements like physical address, unsubscribe links, and proper sender identification to avoid penalties.

Email Accessibility Checker

Check your email HTML for accessibility issues. Analyze alt text, color contrast, font sizes, heading structure, link text, and more against WCAG guidelines.

Email Color Contrast Checker

Check WCAG color contrast compliance for your email designs. Enter foreground and background colors to get instant accessibility ratings for normal text, large text, and UI components with real-time preview.

GDPR Email Compliance Checker

Audit your email marketing practices against GDPR requirements with this interactive checklist. Check consent collection, subscriber rights, data processing, and more.