Validate unsubscribe headers
Or build a pair from scratch
How it works
Find the headers
Paste just the two lines, or the whole block from Gmail's “Show original”. Folded continuation lines are unfolded and every List-Unsubscribe header is collected.
Parse each target
Each angle-bracketed URI is checked: https or mailto, well-formed, no spaces, no http. A mailto target is checked for a subject that identifies the recipient.
Check the Post header
The value must be exactly List-Unsubscribe=One-Click and there must be an https target for the POST to land on. Anything else fails one-click.
Copy the fix
A corrected pair is generated from whatever you gave it, with a curl command that sends the same POST a receiver would so you can confirm the endpoint really unsubscribes.
Two headers, one rule
RFC 2369 defined List-Unsubscribe in 1998 as a list of angle-bracketed URIs — a mailto, an http URL, or both — that a mail client could show as an unsubscribe control. RFC 8058 added List-Unsubscribe-Post in 2017 so that a receiver could unsubscribe without loading a web page: it POSTs the body List-Unsubscribe=One-Click to the https URL from the first header and expects the sender to act on it with no further confirmation. Since 2024 Google and Yahoo require both headers on marketing mail from anyone sending five thousand or more messages a day, the unsubscribe must be processed within two days, and Microsoft followed for Outlook.com. Gmail's “Unsubscribe” button next to the sender name only appears when the pair parses cleanly, and its presence is a small positive signal in its own right.
How senders get it wrong
The failures are almost always syntax. A mailto with no https alongside it, so there is nowhere to POST. An http:// target, which receivers refuse for one-click. Brackets missing on one URI. A Post header with a value like One-Click or List-Unsubscribe=one-click — the string is matched exactly. Two List-Unsubscribe headers on one message because both the sending tool and a relay added one. An https target that returns a confirmation page and ignores the POST, which passes every syntax check and fails the two-day rule. And, specific to cold email: tools that append the header only when a campaign has an unsubscribe link in the body, so half the sequence carries it and half does not. The bulk sender compliance checker reads these headers alongside the DNS requirements if you want the whole picture at once.
Does cold email need it?
Strictly, the one-click rule covers marketing and promotional mail from bulk senders; a genuine one-to-one message is exempt. In practice Gmail decides what is bulk by looking at your sending pattern, not your intent, and a domain sending the same templated message to hundreds of strangers is scored as a bulk sender whether or not it crosses 5,000 a day. Carrying a valid header pair costs nothing, makes the unsubscribe path visible to people who would otherwise hit “Report spam”, and lowers the complaint rate that actually decides placement. Every serious cold email platform can add it; this page tells you whether yours does it correctly.
Testing the endpoint, not just the header
The curl command the tool produces sends the exact request Google sends: an HTTP POST with Content-Type: application/x-www-form-urlencoded and the body List-Unsubscribe=One-Click. Run it against a test contact's URL, then check that the contact is suppressed in your platform. If the URL requires a GET first, redirects to a form, or returns anything other than 200 to the POST, the one-click path is broken even though the header looks perfect.
Frequently asked questions
Do I need both mailto and https?
For one-click you need the https URL; the mailto is optional but recommended because some desktop clients only understand it. Having both is the safe answer.
Can the https URL carry a query string?
Yes — it usually must, to identify the recipient. The whole URL should be under about 1,000 characters and must not contain spaces. Percent-encode anything unusual.
What must the endpoint return?
A 200 to the POST, after which the recipient is unsubscribed with no further action. Redirects, login walls or confirmation pages break one-click. Answering a GET to the same URL with a normal page is fine and expected.
Does the mailto need a subject?
Not by the RFC, but without one you cannot tell who is unsubscribing unless the address itself is unique. The tool warns when a mailto has neither a subject parameter nor a per-recipient local part.
Is anything I paste uploaded?
No. Parsing runs in your browser and nothing is stored. The curl command is for you to run; the tool does not call your endpoint.
Last reviewed
What to run next
The checks that most often follow this one.
More in this category
Guides that go deeper
When the tools tell you something is wrong
The diagnostics here are free and always will be. When the fix is bigger than a DNS record, this is the work I do.
Deliverability rescue
Mail landing in spam, replies gone quiet, or a domain suddenly blocked. I find the actual cause rather than guessing, and fix it.
- Authentication and alignment failures
- Blocklist delistings and reputation repair
- Gateway and filter-level blocks
- A written report on what broke and why
Email & sending infrastructure
Sending domains, inboxes, authentication and warmup, built to survive volume instead of burning down in a month.
- Domain and inbox fleets at any scale
- SPF, DKIM, DMARC and tracking domains
- Google Workspace and Microsoft 365 inboxes
- Handover documentation you actually own
Domain, DNS & migration
Changing registrar, mail provider or host without a day of downtime or a week of mail silently failing.
- Registrar and nameserver moves
- Workspace and Microsoft 365 migrations
- MX, SSL and subdomain cutover
- Staged rollout with rollback at every step
Monitoring & retainer
Infrastructure drifts. Records get edited, certificates expire, domains get listed. Ongoing eyes on the fleet.
- Scheduled checks across every domain
- Alerts before your clients notice
- Monthly reporting
- Priority response when something breaks
Start with a call
Bring a domain and the symptom. I will tell you what is actually wrong and whether you need me at all — plenty of people leave that call able to fix it themselves.
Thirty minutes, no pitch
We will run the checks together on your actual domains, and you will leave knowing what is broken, what it takes to fix, and what it should cost. If that is a job you can do in-house, I will say so.