One-click unsubscribe and List-Unsubscribe

What the two headers do, when they are required, and why a link in the footer is not enough.

In short

Two headers are involved: List-Unsubscribe gives the address, List-Unsubscribe-Post makes it one click.
Gmail and Yahoo require both on promotional mail, honored within two days.
One click means one click: no login, no confirmation page, no preference center.
Genuine transactional mail does not require it, but carrying the header costs nothing and prevents complaints.

The two headers

List-Unsubscribe (RFC 2369) has existed for decades. It tells the receiving client where to send an unsubscribe request, as a mailto address, an https URL, or both:

List-Unsubscribe: <mailto:unsub-abc123@unsub.example.com>, <https://example.com/u/abc123>

List-Unsubscribe-Post (RFC 8058) is the newer half, and the one that makes unsubscribing a single click:

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

It tells the client that it may issue an HTTP POST to the https URL directly, with no user interaction beyond the click. That is what lets Gmail show its own “Unsubscribe” control next to the sender name instead of making the recipient hunt through your footer.

Both headers together are what “one-click unsubscribe” means. List-Unsubscribe alone is not enough, because without the POST declaration a client has to open the URL in a browser and hope for the best.

Why it protects you

The alternative to an easy unsubscribe is not a retained subscriber. It is a spam complaint, which is the most damaging signal a recipient can send about you. Someone who cannot find your unsubscribe link will use the “report spam” button, because it is right there and it works.

An unsubscribe removes one recipient. A complaint damages delivery to everyone.

That is why Gmail and Yahoo made it a requirement for bulk senders rather than a courtesy: see Gmail and Yahoo sender requirements.

The rules that trip people up

Two days maximum to stop sending after an unsubscribe request. Not “by the next campaign”.
No authentication. Requiring a login to unsubscribe fails the requirement outright.
No confirmation step. “Are you sure?” is not one click.
No preference center as the only option. Offering granular choices is fine as a second step, after the unsubscribe has already taken effect.
Keep the body link too. The headers serve clients that support them; the footer link serves everyone else.
Suppress across streams, not per list. Someone who unsubscribes from your newsletter should not receive your other campaign next week.

In Mailverick

Mailverick sets both headers on every message it sends, with no configuration required:

List-Unsubscribe: <mailto:unsub-<token>@...>, <https://.../<token>>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The token is signed and identifies the tenant, the job, and the recipient, so an unsubscribe is attributed correctly and cannot be forged. Both the mailto and the https route are live, because some clients use one and some the other.

When someone unsubscribes you get an unsubscribed event, and the address is suppressed from then on. Later sends to it come back as dropped with the reason recipient_unsubscribed instead of being delivered, so the two-day window is satisfied immediately and permanently.

Complaints work the same way through spam_reported, and every message carries a Feedback-ID header so providers can report them. The event vocabulary is documented in Email Events.

Common mistakes

Only a footer link. Invisible to the client-level unsubscribe controls, which is where most people now unsubscribe.

List-Unsubscribe without List-Unsubscribe-Post. Half the mechanism. It satisfies RFC 2369 and not the current requirement.

An unsubscribe URL that requires a session. Common when the link points into an authenticated app. The click arrives as an anonymous POST from the mail provider, not from a logged-in browser.

Treating the POST as a page view. The endpoint receives a POST with no browser, no cookies, and no JavaScript. It must act on the request itself, not serve a page containing a button.

Honoring it slowly. A nightly job that syncs unsubscribes is fine. A weekly one is not.

Removing the header from mail you consider critical. If a message is genuinely critical, the recipient will not unsubscribe from it. If they do, they were telling you something.

FAQ

Do transactional emails need an unsubscribe?

Not required, and for security mail arguably wrong. Mailverick includes the header on everything it sends, which covers the requirement wherever it applies without asking you to classify each message. See transactional vs marketing email.

What happens after someone unsubscribes?

In Mailverick, the address is suppressed and further sends to it are dropped before delivery, with the reason visible in the event stream. There is nothing to implement on your side.

Can I ask why they are leaving?

After the unsubscribe has taken effect, yes. As a condition of it, no.

Does an unsubscribe hurt my reputation?

No. It is the outcome you want when someone has lost interest. The complaint you avoided is what would have hurt.

Can a recipient be resubscribed?

Only by the recipient, through an explicit action of theirs. Re-adding an unsubscribed address because a colleague asked is exactly the behavior the requirement exists to stop.

Last updated: July 2026