What is the List-Unsubscribe header?

The header takes two forms. A mailto link has existed for years. The HTTPS form, paired with the Post header, lets the mail client submit the opt-out directly with no page load.

Gmail then shows an unsubscribe link beside your sender name, before the message is opened. That placement is why the feature reduces complaints: leaving becomes easier than reporting.

Your endpoint must act on the POST without asking anything further. A landing page with a confirm button breaks the flow, and Gmail will notice mail that claims one-click and does not deliver it.

The header does not replace the link in your footer. Both are required, and the visible one still carries most of the actual traffic.

Here's what a compliant message carries, following RFC 8058. The first header reads List-Unsubscribe: <https://acme.example/u/9f3kq7>, <mailto:unsub@acme.example?subject=9f3kq7>, and the second reads List-Unsubscribe-Post: List-Unsubscribe=One-Click.

When a reader clicks the unsubscribe control in their mail client, the provider sends an HTTPS POST to your URL with the body List-Unsubscribe=One-Click. There are no cookies and no login, so the token in the URL has to identify the recipient and the list by itself. Make it long and unguessable, or anyone could unsubscribe anyone.

POST is used for a reason: security scanners and link previewers fetch URLs in incoming mail with GET requests, and if a GET unsubscribed people, your list would drain every time a corporate filter inspected a message. Your endpoint should act on the POST and show an ordinary confirmation page on a GET.

You can exercise the endpoint from a terminal: curl -X POST -d 'List-Unsubscribe=One-Click' https://acme.example/u/9f3kq7. A 200 response should come back, and the address should show as suppressed in your platform a moment later. Try it again with a made-up token and check that it fails cleanly.

Then look at the signature. RFC 8058 requires a valid DKIM signature that covers both headers, which means list-unsubscribe and list-unsubscribe-post should appear in the h= tag of your DKIM-Signature. If your platform adds the headers after signing, the control may never appear.

Scope matters here too. Google applies the requirement to senders of roughly 5,000 or more messages a day to personal Gmail accounts, and to marketing mail, so receipts and password resets are outside it. Gmail also doesn't show the control for every sender. It appears once Gmail has some trust in your domain, so a missing link on a brand-new domain isn't proof your headers are wrong.