List-Unsubscribe headers

List-Unsubscribe is a header that tells your mail app how to take you off a mailing list. It holds a mailto: address, a web link, or both. When it is paired with List-Unsubscribe-Post: List-Unsubscribe=One-Click and the message is properly DKIM-signed, your mail app can unsubscribe you with a single click, in the background, without you ever visiting the sender's site. Since February 2024, Gmail and Yahoo have required this one-click form from bulk senders. For any email you are unsure about, use your mail app's own unsubscribe button rather than links in the message.

What the headers look like

The original header comes from RFC 2369 (1998), which defined a family of List-* fields for mailing lists. List-Unsubscribe (RFC 2369 §3.2) contains one or more URIs in angle brackets, separated by commas:

List-Unsubscribe: <mailto:unsubscribe@lists.example.com?subject=unsubscribe>
List-Unsubscribe: <https://example.com/unsub?u=8f2a91c4>,
 <mailto:leave-8f2a91c4@lists.example.com>

• mailto: asks your client to send an email (often with a prepared subject or body) to the list's robot. Nothing is opened in a browser, which makes it the more private option, but it does confirm to the sender that your address is live.
• https: is a web address. Under RFC 2369 alone, opening it typically takes you to a page where you confirm the unsubscribe.

The one-click extension, RFC 8058 (2017), adds a second header:

List-Unsubscribe: <https://example.com/unsub/opaque-8f2a91c4e7>,
 <mailto:unsub-8f2a91c4@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The second header may contain only that exact value. When it is present, your mail provider unsubscribes you by sending an HTTPS POST to the link, with List-Unsubscribe=One-Click as the body (RFC 8058 §3.2). The link itself has to identify both you and the list, usually through an opaque token, because the request carries no cookies or login and cannot ask you anything (§3.1).

Why one-click needed a POST

Before RFC 8058, a sender couldn't simply unsubscribe whoever opened the https: link. Spam filters and link scanners fetch URLs in incoming mail automatically, often before you see the message, and a plain GET request from a scanner looks exactly like a person clicking (RFC 8058 §1). Senders that unsubscribed on GET lost subscribers who never asked to leave, so they added confirmation pages, and unsubscribing became several steps again.

A POST with a specific, fixed body is something scanners do not send. When the sender receives List-Unsubscribe=One-Click by POST, it can treat the request as a deliberate unsubscribe and act on it immediately. RFC 8058 also says:

• the message must carry a valid DKIM signature covering both headers (§4), so an attacker cannot forge an unsubscribe header onto someone else's mail stream and trick your provider into posting to it. If that signature is missing, receivers should not offer one-click;
• receivers must not POST without the user's consent (§3.2): the click on your provider's Unsubscribe button is that consent;
• the sender must not redirect the POST (§3.1).

The 2024 Gmail and Yahoo requirements

Both providers announced sender rules that took effect in February 2024. They are company policies, not internet standards, and both companies update their pages.

Gmail (sender guidelines, FAQ), as of October 2026:

• Bulk senders are those sending more than 5,000 messages a day to personal Gmail accounts. Once a sender meets that threshold, the status is permanent.
• Bulk senders must authenticate with SPF and DKIM, publish DMARC (a p=none policy is accepted), and have the From domain aligned with the SPF or DKIM domain.
• Marketing and subscribed messages must support one-click unsubscribe with both List-Unsubscribe-Post: List-Unsubscribe=One-Click and List-Unsubscribe headers, and include a visible unsubscribe link in the body. Senders that already had unsubscribe links had until June 1, 2024 to add one-click.
• Google recommends processing unsubscribes within 48 hours, and asks senders to keep their reported spam rate below 0.3%.
• Google says that from November 2025 it is stepping up enforcement on non-compliant traffic, which may be rejected or sent to spam.

Yahoo (sender best practices):

• Bulk senders must use SPF and DKIM, publish a DMARC policy of at least p=none, and pass DMARC with relaxed alignment acceptable.
• Marketing and subscribed mail must have a working List-Unsubscribe header supporting one-click; Yahoo strongly recommends the POST method and accepts mailto. A visible unsubscribe link in the body is also required.
• Unsubscribes must be honored within 2 days, and the spam complaint rate kept below 0.3%.
• Yahoo said enforcement would start in February 2024 and be rolled out gradually.

For readers, the practical upshot is that legitimate bulk mail to these providers now almost always carries both headers and an aligned DKIM signature. Marketing mail from a large sender without them is unusual.

Unsubscribing safely

Use the Unsubscribe button your mail app shows, not the link inside the message. When your provider offers an Unsubscribe option near the sender's name, it is acting on the header, and for one-click it sends the POST itself without opening the sender's site in your browser. In Gmail the control appears next to the sender's name, and may instead read "Go to website" when the sender only supports a web page (Gmail Help). Other apps place it differently and their layouts change; look for an Unsubscribe link or banner near the sender or at the top of the message.

Treat unsubscribe links in suspicious mail like any other link. An "unsubscribe" link at the bottom of a phishing email can lead to a credential-harvesting page or simply confirm that your address is read. If you never signed up and the message looks off, don't unsubscribe at all: report it as spam or phishing instead. See spotting phishing from headers.

Check the sender first. A dmarc=pass for a domain you recognize suggests the header is genuine. If DMARC fails, or the domain is a look-alike, don't act on any of its links, headers included.

Unsubscribing is not instant. Senders are allowed some time to process requests, so another message or two may still arrive.

To check whether a newsletter's DKIM signature passed and aligns with its From domain before you trust its unsubscribe header, paste its headers into the analyser.