Generate the headers
How it works
Point at your endpoint
An https URL that carries a per-recipient token. Merge tags are kept as-is so your sending tool can fill them at send time.
Add a mailbox fallback
A real mailbox with a fixed subject. Old clients and some corporate gateways only act on the mailto form, and it costs nothing to include.
Test before you send
Copy the generated curl command and run it. If it does not come back 2xx without a redirect to a confirmation page, one-click is not working no matter what the header says.
Validate what you already send
Paste a live header into the second box to check bracket syntax, the exact Post value, http vs https and duplicate URIs.
What the two headers do
List-Unsubscribe comes from RFC 2369 and is just a list of URIs in angle brackets, comma separated. It has existed for decades and on its own it does very little: a client might expose a small link, or might not. RFC 8058 added the second header, List-Unsubscribe-Post: List-Unsubscribe=One-Click, and with it a contract. When both are present and one of the URIs is https, the mailbox provider may render its own unsubscribe control — the grey link Gmail shows next to the sender name — and, when the recipient clicks it, POST List-Unsubscribe=One-Click to your endpoint. The recipient never leaves their inbox.
The value of the second header is exact. List-Unsubscribe=One-Click, nothing else, no quotes, no extra parameters. Receivers that do not find that precise string fall back to treating the message as having no one-click support, which is the same as not sending the header at all.
Why it matters for cold email
Since the Gmail and Yahoo bulk sender rules landed, one-click unsubscribe is a requirement for anyone sending at volume to their users, alongside authenticated mail and a spam complaint rate under 0.3%. The rules were written for marketing lists, but the enforcement does not read your intent — it reads your headers and your complaint rate. Cold email that offers no easy way out gets marked as spam instead, and a spam complaint costs far more than an unsubscribe: it feeds straight into the domain and IP reputation that decides where the next thousand messages land.
That is the practical argument. Someone who wants out of your sequence is not a prospect. Giving them a one-tap route out of it converts a complaint into a quiet removal, and the difference between those two outcomes is measurable in placement within a few weeks.
Where it goes wrong
Almost never in the header. In order of how often I see it: the endpoint only accepts GET and returns 405 to the receiver's POST; the endpoint redirects to a confirmation page, so the POST returns a 302 and the receiver logs a failure; the URL is identical for every recipient because the merge tag was never inserted, so unsubscribes cannot be attributed; the token is a sequential database id, so anyone can unsubscribe anyone; the http scheme is used and one-click is silently ignored. Run the curl command this tool generates before you trust any of it.
Sending platforms and SMTP
If you send through a sequencer, check what it already injects before adding your own. Most cold email platforms add a List-Unsubscribe header pointing at their own endpoint when their unsubscribe feature is on, and a second header from you creates two competing URIs. Decide which one owns the suppression list. If you send over raw SMTP or through a transactional provider, the headers are yours to set, and this is the pair to set. Either way the footer still needs a visible link with a physical address next to it — the CAN-SPAM checker checks that side, and the List-Unsubscribe checker validates the headers on a message you have already received.
Frequently asked questions
Can I send only the mailto form?
You can, and it is better than nothing, but it does not satisfy the one-click requirement and Gmail will not show its own unsubscribe control. Send both.
Does the https URL need a merge tag?
Functionally no, practically yes. Without a per-recipient token you learn that someone unsubscribed but not who, so you cannot suppress them.
What should the endpoint return?
Any 2xx, with no redirect. Return it fast and process the suppression asynchronously if you need to — receivers time out.
Is a confirmation page allowed?
Not for the one-click POST. You may show a confirmation page to someone who clicks the footer link in a browser; the POST from the mailbox provider must act immediately.
How quickly do I have to stop sending?
Within two days under the Gmail and Yahoo bulk sender rules, and under ten business days for CAN-SPAM. In practice, suppress on receipt.
My sequencer already adds this header. Should I add mine too?
No. Two List-Unsubscribe headers, or two URIs owned by different systems, means one of them records a suppression the other never sees. Pick one.
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.