One-click unsubscribe: List-Unsubscribe-Post headers explained

One-click unsubscribe means adding two headers to a marketing message: List-Unsubscribe with an HTTPS URL, and List-Unsubscribe-Post with the value List-Unsubscribe=One-Click. The message must also carry a valid DKIM signature covering both headers. Gmail and Yahoo expect this from bulk senders of marketing mail.

The problem it solves

RFC 8058 explains it well. Anti-spam software often fetches every URL in message headers automatically. A plain link would unsubscribe people who never clicked. Senders therefore added confirmation pages, which a person can use but a robot cannot, so unsubscribing took several steps. People who find it too hard mark the mail as spam, which hurts the sender.

The one-click design lets the receiving mail system send an HTTP POST to the URL on the user's behalf only when the user asks, with no confirmation page.

The headers

A compliant message has exactly one of each:

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

The List-Unsubscribe header holds the HTTPS URL wrapped in angle brackets, and may also include a mailto form. The RFC requires the HTTPS URI to contain enough information to identify the recipient and list without extra input, and says it SHOULD include an opaque, hard-to-forge identifier.

Google's documentation shows the same two headers, and says the POST body is List-Unsubscribe=One-Click with a form content type.

Rules the sender must follow

• Sign with DKIM. The message must have a valid DKIM signature that covers at least the List-Unsubscribe and List-Unsubscribe-Post headers. This is how receivers know the headers were not added by someone else.
• No redirects. The sender's endpoint MUST NOT return an HTTPS redirect for the POST.
• No cookies or authentication. The POST request must not need cookies, HTTP authorization or other credentials.
• Identify the recipient from the URL alone. There is no way to ask the user which address or list, so the URL must carry enough to complete the request.

Receivers, for their part, must not POST without a user's action.

What Gmail and Yahoo say

Google requires one-click unsubscribe for marketing and subscribed messages from senders of more than 5,000 messages a day, plus a visible link in the body. Yahoo asks for the same, calls the RFC 8058 POST method highly recommended, accepts mailto, and wants unsubscribes honored within two days.

Implementation checklist

1. Generate a unique, opaque unsubscribe token per recipient and list.
2. Expose an HTTPS endpoint accepting POST with no authentication and no redirect.
3. Add both headers to every marketing message, including the DKIM signing configuration so those headers are in the h= list.
4. Test by sending to a mailbox at a major provider and using its unsubscribe control.
5. Process the unsubscribe quickly and confirm the recipient is removed from the next send.
6. Keep a visible link in the body for people who look there.

Quick check

Sources

• RFC 8058, Signaling One-Click Functionality for List Email Headers
• Google, email sender guidelines
• Yahoo Sender Hub, sender requirements

Last reviewed: 19 October 2026.