List-Unsubscribe Checker

🛡 Deliverability & security

Paste an email’s headers to confirm your one-click unsubscribe is set up correctly for Gmail and Yahoo.

No sign-up required Runs on our own infrastructure Also available via API

Runs in your browser — headers are not uploaded.

The List-Unsubscribe header has been around since the late 1990s, but it went from optional courtesy to hard requirement in February 2024, when Gmail and Yahoo began mandating one-click unsubscribe for bulk senders. If you send newsletters or marketing mail at volume and this header is missing or malformed, you’re not just being impolite — you’re out of compliance, and it drags down your deliverability. The good news is it’s a small, well-defined piece of plumbing. This page explains exactly what the header does, the difference between the old and new versions, and how to add it.

What the List-Unsubscribe header actually does

The original List-Unsubscribe header, defined in RFC 2369, lets a message tell the mail client how a recipient can unsubscribe without hunting through the email body. It carries one or two methods inside angle brackets — a mailto: address, an https:// URL, or both:

List-Unsubscribe: <https://example.com/u/abc123>, <mailto:unsub@example.com?subject=unsubscribe>

When a mailbox provider sees this, it can surface a native “Unsubscribe” control in its own interface — the link that appears next to the sender name at the top of a Gmail or Apple Mail message. The recipient never has to scroll to the footer or find the tiny grey link. That’s the whole idea: make leaving easy so people unsubscribe instead of hitting “report spam,” which is far more damaging to your reputation.

The one-click version — and why it’s now required

Here’s the catch with the old header: when a recipient clicked the provider’s unsubscribe link for an https:// method, the provider would just open the URL in a browser. That often dumped the user on a landing page asking them to log in, pick preferences, or confirm — friction that defeats the purpose. To fix it, RFC 8058 added a second header:

List-Unsubscribe: <https://example.com/u/abc123> List-Unsubscribe-Post: List-Unsubscribe=One-Click

With both headers present, the provider stops opening a browser window and instead sends a single automated HTTP POST directly to your URL, carrying the exact body List-Unsubscribe=One-Click. Your server reads that POST and unsubscribes the recipient — no login, no confirmation page, no extra clicks. This is what Gmail and Yahoo mean by “one-click,” and for bulk senders it is now mandatory, not optional. A plain List-Unsubscribe without the -Post companion does not satisfy the requirement.

mailto: vs https: — you want both, but https is the one that counts

The two method types behave differently and serve different purposes:

  • https: is the method that powers one-click. It’s the one Gmail and Yahoo POST to, and the one that must be paired with List-Unsubscribe-Post. This is non-negotiable for bulk-sender compliance.
  • mailto: is a robust fallback. Some clients and privacy-conscious setups prefer it, and it works even when your web endpoint is briefly down. But on its own it does not satisfy the one-click requirement, because there’s no POST mechanism behind it.

Best practice is to include both, with the HTTPS URL present and backed by List-Unsubscribe-Post. That gives you the compliant one-click path plus a graceful fallback.

How to add it correctly

  1. Build an unsubscribe endpoint at an HTTPS URL that accepts a POST and immediately unsubscribes the recipient. Encode who’s unsubscribing in the URL itself (a signed token per recipient) so the POST needs no login or lookup form.
  2. Emit both headers on every bulk message: List-Unsubscribe with your HTTPS URL (and a mailto: fallback), plus List-Unsubscribe-Post: List-Unsubscribe=One-Click.
  3. Handle the POST idempotently. Providers may retry, and the same recipient shouldn’t break anything by being unsubscribed twice. Return a 200 and process quietly.
  4. Honor it within two days. Gmail and Yahoo require the unsubscribe to take effect within two days — in practice, process it immediately.
  5. Keep the visible footer link too. The header powers the native button, but a clear unsubscribe link in the body is still expected and, in many jurisdictions, legally required.

Most ESPs add these headers automatically once you enable the feature — but verify it on a real message rather than assuming, because a subtle misconfiguration (missing -Post, a URL that requires login, an endpoint that only accepts GET) fails silently. Paste your headers into the tool below to confirm.

Where this fits in the bigger compliance picture

One-click unsubscribe is one item on a longer list. To reach the inbox as a bulk sender you also need aligned SPF, DKIM and DMARC, valid reverse DNS, and a spam complaint rate under 0.3%. Run the full bulk sender compliance check to see where you stand, and the guide to why newsletters fail if your mail has started landing in spam.

Frequently asked questions

Do I still need a visible unsubscribe link in the message body?
Yes — the headers power the native button, but a visible unsubscribe link in the body is still expected and, in many jurisdictions, legally required. Keep both.
Is a mailto: unsubscribe enough on its own?
No — one-click needs the HTTPS URL plus List-Unsubscribe-Post, which enables the automated POST. mailto: is a useful fallback but doesn’t satisfy one-click on its own.
What is the difference between List-Unsubscribe and List-Unsubscribe-Post?
The first (RFC 2369) advertises the methods; the second (RFC 8058) tells the provider to POST automatically. You need both for one-click compliance.
How fast must I honor an unsubscribe?
Within two days per Gmail and Yahoo — but process the POST immediately so the recipient stops receiving mail right away.