Where you saw it: A mail tester reporting the header as missing, no unsubscribe control shown next to your sender name in Gmail, or a Google bulk sender warning.
Why it happens
- The sending platform does not add it by default, which is still common on transactional and API-driven sending.
- Mail is being sent through an API or a script that builds headers by hand and omits it.
- The header is present with a mailto link only, while one-click support needs an HTTPS URL and the companion post header.
- The List-Unsubscribe-Post header is missing, which is what actually enables one-click.
The fix, in order
Look at the raw headers of a real message
Open a message you sent, view the original source, and search for List-Unsubscribe. Trust the message rather than the platform's settings page.
Add both headers together
List-Unsubscribe with an HTTPS URL and a mailto fallback, and List-Unsubscribe-Post with the value List-Unsubscribe=One-Click. One without the other does not satisfy the requirement.
Make the URL work with no login and no confirmation
One-click means one click. A page asking the person to sign in or confirm a preference fails the requirement and irritates someone who is already leaving.
Process the unsubscribe within two days
Google's guidelines say 48 hours. Your endpoint should suppress the address immediately rather than queueing it for a weekly job.
Keep the visible footer link as well
The header serves the mail client. Some people still look for the link, and having both costs nothing.
List-Unsubscribe: <https://example.com/u/abc123>, <mailto:unsub@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickBoth headers, HTTPS first. This is what enables the inbox control.
How to know it worked
The short version
- Raw headers show both List-Unsubscribe and List-Unsubscribe-Post.
- Gmail displays an unsubscribe control next to your sender name.
- Clicking it suppresses the address immediately in your platform.
Questions people ask
Does this apply to transactional mail?
The bulk sender requirements target marketing mail. Adding the header to genuinely transactional messages is usually unnecessary and occasionally confusing for the recipient.
Will an easy unsubscribe shrink my list?
Yes, and that is the point. Someone who unsubscribes costs you nothing. The same person pressing the spam button damages your reputation with every other recipient at that provider.
Is a footer link enough on its own?
Not for bulk senders to Gmail and Yahoo. They require the headers, because the header is what lets the mail client offer its own control.