Your unsubscribe header needs an HTTPS URL

Your List-Unsubscribe header contains a mailto: address and nothing else, or it contains a URL that starts with http://. Either way, one-click unsubscribe cannot work, and no amount of correcting the other headers will change that.

What the error means

One-click unsubscribe is an HTTPS request. When a recipient presses the unsubscribe control in Gmail, the mail provider sends a POST to the URL in your header, reads the response code, and reports success or failure to the user. That exchange needs a URL it can POST to. A mailto: address is not one.

RFC 8058 §3 is explicit that the URI must be HTTPS. Plain http:// is refused for the obvious reason: the URL contains a token identifying a specific subscriber, and sending it in clear text hands that token to anyone on the network path, who can then unsubscribe that person at will.

A mailto-only header is not useless — it predates one-click by twenty-five years and some clients still surface it — but it satisfies a different, older expectation. Under the Gmail and Yahoo bulk-sender rules it does not count.

Why it happens

The mailto-only version is usually a mailing-list heritage. Software written for discussion lists emitted mailto: unsubscribe addresses long before commercial senders existed, and a configuration inherited from that world will still be doing it.

The http:// version is more often a mismatch between the header and the infrastructure. The site was moved to HTTPS, the edge was configured to redirect plain HTTP upward, everything looked fine in a browser — and the template that builds the header was never updated. A browser follows the redirect silently. A mailbox provider does not.

The fix

Add an HTTPS URI, and keep the mailto as a fallback:

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

Four details matter, and each of them is a real failure when missed:

• Angle brackets, always. RFC 2369 requires each URI to be enclosed in < and >, and a receiver will not use a bare URL. This is easy to lose when the header is assembled by string concatenation.
• The final URL, not a redirecting one. If your header URL answers with a 301 or a 302, the unsubscribe stops there — receivers do not follow redirects.
• A token that stands alone. The POST arrives with no cookie, no session and no referrer. Everything needed to identify the subscription has to be in the URL, and it should not be guessable from an address.
• Change the scheme last. Confirm the endpoint actually answers on HTTPS with a valid certificate chain before you put it in a header — a header pointing at a TLS endpoint that is not ready fails more completely than the http:// version did.

Keep the mailto

RFC 8058 recommends offering both, and there is no downside. It is what clients with no HTTP support fall back to, and what still works when your unsubscribe endpoint is down at the moment someone tries to leave. The one requirement is that the mailbox is actually processed — an unmonitored unsubscribe address is worse than none, because it looks like an option and behaves like a dead end.

Checking it worked

Send a message to an address you control and read the raw header. You should see two URIs, both bracketed, the first starting https://. The checker will confirm the scheme and the brackets, and can optionally send a real POST to the URL so you can see the status code a mailbox provider would get. That test genuinely unsubscribes whoever the token belongs to, so use a message you sent to yourself.