One Click Unsubscribe Headers and the Bulk Sender Rules
I send a monthly note to the people who play on the servers I run. It is not marketing. It is maintenance windows, map rotations, who won the last endurance night, and about 4,100 addresses sit on the list.

I send a monthly note to the people who play on the servers I run. It is not marketing. It is maintenance windows, map rotations, who won the last endurance night, and about 4,100 addresses sit on the list. In March 2024 the Gmail half of that list stopped arriving properly. Not bounced, not rejected outright, just quietly sorted into spam for maybe a third of recipients, and the February message had gone through fine.
What changed was not my server. Gmail and Yahoo had both started enforcing requirements they announced the previous October, and one of them was a header pair most self hosted senders had never touched: a working one click unsubscribe. My list was authenticated, aligned, and had a clean complaint rate, and it still slid because the unsubscribe link lived at the bottom of the message as a normal hyperlink. That is the piece I want to take apart here, because the specification is short and almost everybody implements it slightly wrong.
What the two headers actually say
There are two of them, and they do different jobs. The older one, List-Unsubscribe, has existed since the 1990s and holds one or two values in angle brackets: a mailto address, an https URL, or both. On its own it tells a mail client that an unsubscribe route exists, and most clients will offer a link somewhere in the interface.
The second header is the one added by RFC 8058 in 2017: List-Unsubscribe-Post, whose only legal value is the string List-Unsubscribe=One-Click. Its presence is a promise. You are telling the receiving provider that it may send an HTTP POST to your https URL, with that same string as the body, and that you will act on it without asking the user anything else. No confirmation page. No login. No preference centre with nine checkboxes.
Three rules decide whether providers believe the promise. The https URL has to accept POST, not only GET, because a POST is what arrives. Both headers have to fall inside your DKIM signature, since a header a forwarder could forge is worth nothing to a receiver. And the unsubscribe has to take effect within two days, which is the window Gmail states in its own sender guidance.
What each combination produces in a real inbox
I tested my own list against four mailboxes over a couple of send cycles. The table is what I observed rather than what the documentation promises, and provider interfaces do shift.
| Headers present | What the recipient sees | What reaches your server |
|---|---|---|
| Neither header | Nothing but your own footer link | A browser visit, if they bother |
| List-Unsubscribe with mailto only | Unsubscribe link in Gmail header area | An email to your parsing address |
| List-Unsubscribe with https only | Link offered, sometimes with a warning | A GET from the user's own browser |
| Both headers, https first | A plain unsubscribe button, no page load | A POST from the provider, no browser |
| Both headers, DKIM broken | Varies, often back to the footer link | Usually nothing |
The fourth row is the one worth having. The user never leaves the inbox, so they never reach the moment where a slow unsubscribe page makes pressing the spam button look easier. That tradeoff is the whole reason the specification exists, and it connects directly to the sorting behaviour I wrote about in why your newsletter lands in the promotions tab.
The five thousand a day threshold is a bad reason to wait
The common reading of the 2024 rules is that they apply to bulk senders, defined as anyone sending more than 5,000 messages a day to Gmail addresses, so a list of four thousand people is below the line and can carry on as it was. I believed that for a month. I was wrong in a way that cost me real delivery.
The threshold describes what Google will enforce as policy, with rejections and temporary failures attached. It does not describe what the spam classifier considers. Complaint rate is an input either way, and a message with no inbox level unsubscribe collects complaints from people who are not complaining about anything: they want out, the easy button on screen says report spam, and that is the button they press. On my list the complaint rate ran at roughly 0.28 percent before the headers and 0.06 percent in the three sends after, with identical content and the same audience. Nothing else changed.
There is a second argument I hear, which is that making it easier to leave will shrink the list. It did shrink mine, by 94 addresses in the first month. Every one of those people had already stopped opening. A smaller list that gets delivered is worth more than a larger one sorted into a folder nobody opens, and the same logic runs through how deliverability works and why messages land in spam.
Wiring it up without a vendor
The work is smaller than it looks. Generate a token per subscriber per send, store it, and build the URL as $UNSUB_URL plus that token. The token has to be unguessable, because an endpoint that accepts a plain numeric id is an endpoint anyone can walk. I use a random 22 character string tied to a row in a table alongside the list id and an expiry of 90 days.
Your endpoint then needs to accept POST and return a 200 with a short body. Do not redirect, because a POST followed by a 302 is handled inconsistently and a provider that gets a redirect may record the attempt as failed. Mark the address as unsubscribed in the same request if you can, or write it to a queue that drains in minutes rather than hours. Keep accepting GET on the same URL for the people who click the footer link in a mail client that ignores the headers, and show them a one line confirmation page.
Then add both headers to the message, include them in the list of signed headers in your DKIM configuration, and send yourself a test. Open the raw source and check that the signature header lists both names. In Mailman 3 and listmonk this is configuration rather than code; on a hand rolled sender it is two lines where you build the message and one line in the signer. Budget an afternoon, most of it spent on the suppression table.
Where it goes wrong
The failure I see most often is a mailto only header on a system where nothing reads that mailbox. An unsubscribe request sitting unread for five weeks is worse than no header, because you advertised a route and ignored it.
The second is adding the headers to transactional mail. A receipt, a password reset, or a server maintenance alert is not a list, and offering to unsubscribe from a password reset confuses people and sometimes removes them from mail they need. I keep two paths in my sender and only the list path gets the headers.
The third is harder to see. Apple Mail and some Outlook builds do not send the POST at all, so a slice of your audience still arrives at the browser route, and your logs will show far fewer POST requests than you expect. That is normal. Do not read it as a broken implementation until you have confirmed a POST from Gmail itself in your access log.
One honest limit: I have no way to measure how much of my recovery came from the headers alone, because Google does not publish per sender reasoning. The complaint numbers moved, the folder placement moved, and the only change I made was this one. That is evidence, not proof. If you want a measurable view of your own mail instead, the reports described in reading DMARC aggregate reports without a paid tool are the closest thing to a feedback channel most of us get.
FAQ
Do I need both headers or just one?
Both, if you want the inbox level button. List-Unsubscribe-Post is meaningless on its own, and List-Unsubscribe without it only produces a link that behaves like any other link.
What should my endpoint return?
A 200 with a tiny plain text or HTML body. Avoid redirects, avoid 204, and never require a session cookie, because the POST arrives from the provider's infrastructure and carries nothing of the user's.
Does this affect my SPF or DMARC setup?
No, but it depends on DKIM. If your signature does not cover the two headers, a receiver has no way to tell that you set them, and several providers will then treat them as absent.
How fast does the unsubscribe have to apply?
Google asks for two days. I would aim for the same send cycle, because the realistic risk is a person who unsubscribed on Monday getting your Tuesday message and reporting it as spam.
More in Email Infrastructure
Email Infrastructure
Why Email Forwarding Breaks SPF and What ARC Fixes
A reader wrote to me in October about invoices that reached half his list and vanished for the rest.
Email Infrastructure
Warming Up a New Sending Domain Without Hitting Spam
You moved the newsletter to a fresh domain on a Monday, sent 8,000 messages on Tuesday, and by Wednesday Gmail was deferring...
Email Infrastructure
BIMI Record Setup and Whether Your Brand Logo Is Worth It
You have seen the little brand logos next to sender names in Gmail and Apple Mail, and now someone on your team wants one too.