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.

List-Unsubscribe Header Generator

Generate RFC 8058 compliant unsubscribe headers for better deliverability

The HTTPS endpoint that handles unsubscribe requests. Required for one-click unsubscribe.

A mailto address as a fallback unsubscribe method

Gmail & Yahoo Requirements (2024+)

  • • Bulk senders (5,000+ emails/day) must support one-click unsubscribe
  • • The HTTPS URL must accept POST requests with the body List-Unsubscribe=One-Click
  • • Unsubscribe must be processed within 2 days
  • • The unsubscribe link must remain valid for the lifetime of the message
  • • Both headers must be present for one-click to work

How one-click unsubscribe works

  1. Email clients detect the List-Unsubscribe and List-Unsubscribe-Post headers
  2. They show an "Unsubscribe" button at the top of the email
  3. When clicked, the client sends a POST request to your HTTPS URL
  4. Your server processes the request and removes the subscriber
  5. This reduces spam complaints because users have an easy alternative

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

More Free Tools

View all tools

DMARC Record Generator

Create a DMARC policy record to protect your domain from email spoofing and phishing. Configure policy, reporting, alignment, and gradual rollout with our free generator.

Spam Trigger Word Checker

Scan your email content for words and phrases that trigger spam filters. Identify risky language that could send your emails to the spam folder and get suggestions for alternatives.

Email Text-to-Image Ratio Checker

Analyze your email HTML to check the text-to-image ratio. Spam filters flag image-heavy emails with too little text content. Optimize your ratio for better deliverability.

Email Migration Checklist

Step-by-step interactive checklist for migrating between email marketing platforms. Covers pre-migration audit, data export, authentication setup, testing, and go-live monitoring across 6 phases.