The one-click List-Unsubscribe header for cold email: what it is, how to add it, how to verify it
One header. Two lines of metadata. Gmail and Yahoo render a one-tap unsubscribe button at the top of your message. Required above 5,000 sends per day and a quiet positive signal even below.
Rejwan Nirob·May 21, 2026·5 min readMost cold-email teams know they need an unsubscribe link in the body of the message. Fewer know that since 2024, Gmail and Yahoo also require a List-Unsubscribe header with one-click support for any sender above 5,000 emails per day. Below the threshold the header is not technically mandatory, but its presence is a small positive signal and its absence is a small negative one. There is no upside to leaving it out.
What the header actually looks like
Two header lines per outbound message. The first lists the unsubscribe endpoint - a mailto: address, an HTTPS URL, or both. The second declares that the endpoint accepts a one-click POST. Gmail and Yahoo look for the pair together. Either one alone does not satisfy the rule.
Example: List-Unsubscribe: <https://yourdomain.com/u/abc123>, <mailto:unsubscribe@yourdomain.com> followed by List-Unsubscribe-Post: List-Unsubscribe=One-Click. The endpoint must respond to a POST request and process the unsubscribe within 48 hours.
Why Gmail and Yahoo demand it
The one-click unsubscribe is rendered as a single button at the top of the message, next to the sender name. The friction to opt out drops from "find the tiny link in the footer" to one tap. Inbox providers want this because friction-to-unsubscribe correlates strongly with users marking mail as spam instead of unsubscribing. Spam complaints damage reputation; clean opt-outs do not. Removing friction is a placement win for everyone.
How each sending tool implements it
- Smartlead - automatic on every campaign, no config needed
- Instantly - automatic, with a per-account suppression list that honours one-click POSTs within seconds
- Lemlist - automatic, configurable via the account settings if you need a custom unsubscribe page
- Apollo - automatic, headers populated from your domain settings
- Custom SMTP / API - you implement the header and the endpoint yourself
How to verify it is actually shipping
Send a test campaign to your own Gmail address. Open the message. Look at the top - if Gmail renders a small "Unsubscribe" link next to the sender name, the header is present and being parsed correctly. If you only see "Unsubscribe" in the body but not at the top, the header is missing or malformed.
You can also check the raw headers (Gmail: "Show original") and search for List-Unsubscribe. Confirm both lines are present and the URL endpoint returns a 200 to a test POST.
What happens if it is missing
Below 5,000/day, missing one-click unsubscribe is a small negative signal - your placement is slightly worse than it could be. Above 5,000/day, Gmail and Yahoo treat the missing header as a hard fail and route the message to spam or reject it at SMTP. There is no warning email.
Inboxlee reads the header status back from your connected sending tool via API. The infrastructure health score flags any mailbox where the one-click header is missing on outbound campaigns - so you catch the problem before placement drops.
See infrastructure monitoringFrequently asked
What is the List-Unsubscribe header in cold email?
A header on every commercial message that lists an unsubscribe endpoint (mailto: address, HTTPS URL, or both). Paired with List-Unsubscribe-Post: List-Unsubscribe=One-Click, Gmail and Yahoo render a one-tap unsubscribe button at the top of the message - dramatically lower friction than a body-text link.
Do I need List-Unsubscribe for cold email if I am under 5,000 sends per day?
Not technically required, but always recommended. Below the threshold the header is a small positive placement signal and its absence is a small negative one. There is no upside to leaving it out, and Smartlead/Instantly/Lemlist/Apollo all add it automatically.
How do I verify the List-Unsubscribe header is actually being sent?
Send a test campaign to your own Gmail address and look at the top of the message. If Gmail renders a small "Unsubscribe" link next to the sender name, the header is parsing correctly. You can also check raw headers via "Show original" and confirm both List-Unsubscribe and List-Unsubscribe-Post are present.
What happens if my one-click unsubscribe endpoint is broken?
Receiving providers track the failure rate. A pattern of broken endpoints (404s, timeouts, slow processing beyond 48 hours) gets treated as a negative signal similar to ignoring an unsubscribe entirely. Inboxlee reads endpoint health from the sending tool API and flags failures before they accumulate.
Does Inboxlee handle the List-Unsubscribe header?
The header itself is added by your sending tool (Smartlead, Instantly, Lemlist, Apollo) on every campaign. Inboxlee reads the header status and one-click endpoint health back from the sender via API and surfaces a warning on the infrastructure health score if either is missing or failing - so the gap shows up in monitoring before it shows up in placement.