The One-Click List-Unsubscribe Header: What Gmail and Yahoo Actually Require

If you send marketing or bulk email to Gmail or Yahoo addresses, there is a small piece of plumbing that now decides whether your campaigns reach the inbox or get filtered: the List-Unsubscribe header. It is invisible to most marketers because it lives in the message headers, not the body, but the mailbox providers read it on every send. Get it right and you give recipients a frictionless exit that protects your reputation. Get it wrong, or skip it, and you tell Gmail you do not want to play by the rules.

This post explains what the header is, why one-click unsubscribe became mandatory, what the header should actually look like, and how it fits alongside the rest of the deliverability checklist.

Why This Header Suddenly Matters

In February 2024, Gmail and Yahoo rolled out their bulk sender requirements. If you send roughly 5,000 or more messages a day to their users, you now have to meet a short list of conditions or watch your delivery rates fall off a cliff. Three of those conditions get most of the attention: authenticate your mail with SPF, DKIM, and DMARC, keep your spam complaint rate below 0.3 percent, and support one-click unsubscribe.

That last one is where the List-Unsubscribe header comes in. The providers decided that hunting for a tiny “unsubscribe” link buried in the footer was too much friction. When unsubscribing is hard, frustrated recipients reach for the “report spam” button instead, and spam complaints are one of the fastest ways to torch your sender reputation. Making the exit effortless is, counterintuitively, one of the best things you can do for deliverability.

The Two Headers You Need

There are actually two related headers, and you want both.

The first is List-Unsubscribe. It has been around for years and tells the mailbox client where to send an unsubscribe request. It can point to a URL, a mailto address, or both:

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

The second is List-Unsubscribe-Post, defined in RFC 8058. This is the header that makes one-click work:

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

When both headers are present, Gmail and Yahoo can show a native “Unsubscribe” link next to the sender name at the top of the message. When a recipient taps it, the mail client sends a single HTTP POST to your unsubscribe URL. No landing page, no “are you sure” form, no login. The user is out, and crucially, they did not file a spam complaint to get there.

A Common Mistake: One-Click That Is Not Actually One-Click

The detail that trips people up is the difference between a List-Unsubscribe URL that opens a web page and one that accepts a POST request. RFC 8058 requires that the unsubscribe URL accept an HTTP POST and process the unsubscribe without any further user interaction. If your URL only works as a GET that loads a confirmation page, you are not compliant, even though you technically have the header.

Here is the practical checklist for the URL behind a one-click header:

• It must accept an HTTP POST request.
• It must unsubscribe the recipient immediately, with no confirmation step and no required sign-in.
• It must use HTTPS, not plain HTTP.
• It should respond reasonably quickly so the mail client registers success.

Many email service providers handle all of this for you automatically once you enable the feature. If you send through your own infrastructure or a transactional API, you own the implementation and need to test it deliberately.

How To Verify Your Header Is Working

You do not have to guess. Send a test campaign to a Gmail and a Yahoo account you control, open the message, and click “Show original” (Gmail) or “View raw message” (Yahoo). Search the raw headers for List-Unsubscribe and List-Unsubscribe-Post. Both should be present, the URL should be HTTPS, and the post header should read exactly List-Unsubscribe=One-Click.

Then actually click the native unsubscribe link in the client and confirm the recipient is suppressed on your side. A header that exists but does not remove anyone is worse than no header at all, because the provider will notice the gap between what you advertise and what you do.

The Header Is Not Enough On Its Own

Supporting one-click unsubscribe is one requirement out of several, and it sits on top of a more fundamental need: a clean, deliverable list. The whole point of the bulk sender rules is to reward senders whose recipients actually want their mail. You can have a flawless List-Unsubscribe header and still get buried if a chunk of your list is dead addresses, spam traps, or catch-all mailboxes that quietly bounce.

This is where list hygiene does the heavy lifting. Before a campaign goes out, running your list through a validation service like Scrubby removes the invalid and risky addresses that drive up bounces and complaint rates. Scrubby is built to handle the cases generic validators skip, including catch-all and risky addresses that other tools mark as “unknown,” so you are not flying blind on a meaningful slice of your list. Pairing one-click unsubscribe with a validated list is the combination that keeps your complaint rate under the 0.3 percent threshold the providers care about.

The same logic applies before you ever hit send on cold outreach. If your outbound is going to prospects rather than an opted-in list, the deliverability math is even less forgiving, and tooling matters. Teams running calendar-based outreach through Kali still benefit from validating recipients first, because a bounce on a cold send costs you reputation you cannot easily rebuild. And for any high-volume program, Scrubby gives you the pre-send confidence that the addresses behind your carefully built headers are real.

Quick Implementation Summary

To bring it together, a compliant bulk sender setup includes:

1. Authentication. SPF, DKIM, and a published DMARC policy on your sending domain.
2. Both unsubscribe headers. List-Unsubscribe with an HTTPS URL plus List-Unsubscribe-Post: List-Unsubscribe=One-Click.
3. A real POST endpoint. It unsubscribes instantly, no confirmation, no login.
4. A low complaint rate. Stay under 0.3 percent by mailing people who want your mail.
5. A validated list. Clean out invalid, risky, and catch-all addresses before every major send.

The List-Unsubscribe header is small, but it is a signal. It tells Gmail and Yahoo that you respect the recipient’s choice to leave, and that respect is exactly what these rules are designed to reward. Get the header right, keep your list clean, and the inbox stays open.