Missing List-Unsubscribe-Post header

You have a List-Unsubscribe header. You have checked it three times. Gmail still shows no unsubscribe link next to your sender name, and your complaint rate is climbing. Nine times out of ten the missing piece is a second header you have never heard of.

What the error means

List-Unsubscribe is old — RFC 2369, from 1998 — and it only ever meant “here is a URL or address a recipient could use to leave”. It says nothing about how. A receiver seeing that header alone has to assume the URL is an ordinary web page, and the only safe thing to do with an ordinary web page is open it in a browser when the user asks. So no button appears.

RFC 8058 added the missing half in 2016. List-Unsubscribe-Post is a promise: it tells the receiver that the URL will accept an HTTP POST and act on it immediately, with no page to load and no form to fill in. That promise is what lets a mail client put its own unsubscribe control in its own interface — and that control is what a recipient presses instead of the spam button.

Why it happens

Almost always because the advice people find is older than the requirement. Search for “list unsubscribe header” and a great deal of what comes back predates 2024, when Google and Yahoo began enforcing one-click for bulk senders. Those pages are not wrong about List-Unsubscribe; they are simply describing a world where the second header did not matter.

The other common cause is a template that was written once, worked, and was never revisited. If your unsubscribe header is assembled by your own application rather than by your sending platform, nothing will have prompted you to add the second line.

The fix

Add one header, with exactly this value:

List-Unsubscribe-Post: List-Unsubscribe=One-Click

The value is not a template and not an example. RFC 8058 §3.1 defines it literally, receivers match it literally, and List-Unsubscribe=one_click or any added parameter means no one-click support at all. Your complete pair should look like this:

List-Unsubscribe: <https://example.com/unsub?id=TOKEN>, <mailto:unsub@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Then sign it

Adding the header is half the job. RFC 8058 also requires both header names to appear in the h= tag of your DKIM signature, and a receiver that finds them unsigned ignores them exactly as if they were absent. This is the single most common reason a sender who has done everything on this page still sees no button — it has its own guide.

Where to make the change

• On an ESP — look for a one-click or list-unsubscribe setting on the sending domain or campaign. Most added one in 2023 or 2024. If you cannot find it, ask support directly whether they emit List-Unsubscribe-Post; some still do not.
• In your own application — add it wherever you already set List-Unsubscribe, on marketing mail only.
• Never on transactional mail. A receipt or a password reset is not something to unsubscribe from, and adding these headers to it invites a recipient to switch off mail they actually need.

Checking it worked

Send a message to an address you control, open it, and view the raw source. Both headers should be present, and the value of the second should match the line above character for character. Then paste the headers into the checker — it will confirm the value is exact and, more usefully, tell you whether your DKIM signature actually covers them.