List-Unsubscribe and One-Click Unsubscribe (RFC 2369 & RFC 8058)

If you send bulk or marketing mail, the "Unsubscribe" link that Gmail, Yahoo, Apple Mail and Outlook.com show next to your sender name comes from headers you add to each message. Two RFCs define this standard, machine-readable unsubscribe mechanism:

• RFC 2369 (1998) defines the List-* header fields, including List-Unsubscribe.
• RFC 8058 (2017) adds List-Unsubscribe-Post, which turns the HTTPS version into a one-click action that mail clients can carry out for the user without loading a web page.

RFC 2369: the List-* header fields

RFC 2369 defines six header fields for messages distributed by a mailing list:

Syntax rules

• The content of each field is one or more URLs in angle brackets: <mailto:...> or <http://...>. Whitespace inside the brackets is ignored. Systems that generate the fields must not put whitespace inside brackets, but clients should tolerate badly formatted entries.
• Several alternative URLs MAY be given as a comma-separated list of URLs in angle brackets. The order shows preference, from left to right: a client uses the leftmost protocol it supports (for example, HTTPS first, with mailto: as a fallback).
• Comments in parentheses may follow a URL: List-Post: NO (posting not allowed on this list).
• A message may contain at most one of each field.
• The fields MUST only be generated by the list or sending system, never by end users.
• Fields implemented for a list SHOULD appear on all messages that list distributes.
• Rules for clients parsing the fields: if the field content starts with anything other than <, the field SHOULD be ignored. Characters after a closing > are ignored, unless the next character that is not whitespace or part of a comment is a comma. A comma-separated item that is not a URL in angle brackets causes the rest of the field to be ignored.
• A sublist that redistributes a parent list's mail should replace the parent's List-Help, List-Subscribe, List-Unsubscribe and List-Owner with its own, and keep List-Archive unless it provides its own.

Examples (from the RFC)

List-Unsubscribe: <mailto:list@host.com?subject=unsubscribe>
List-Unsubscribe: <http://www.host.com/list.cgi?cmd=unsub&lst=list>,
    <mailto:list-request@host.com?subject=unsubscribe>
List-Help: <http://www.host.com/list/>, <mailto:list-info@host.com>
List-Subscribe: <http://www.host.com/list.cgi?cmd=sub&lst=list>,
    <mailto:list-manager@host.com?body=subscribe%20list>
List-Post: <mailto:list@host.com>
List-Owner: <mailto:listmom@host.com>
List-Archive: <http://www.host.com/list/archive/> (Web Archive)

For mailto: URLs, clients are expected to show a confirmation dialog (with the destination and the command) before sending.

RFC 8058: one-click unsubscribe (List-Unsubscribe-Post)

A plain HTTPS List-Unsubscribe URL cannot safely be opened automatically. Anti-spam scanners, link prefetchers and security proxies follow GET links, which would unsubscribe users who never asked to leave. RFC 8058 solves this. The signal RFC 8058 defines is based on POST, and only a deliberate action in the mail client produces it.

Header syntax

list-unsubscribe-post = "List-Unsubscribe-Post:" 0*1WSP postarg CRLF
postarg               = "List-Unsubscribe=One-Click"

The header value is exactly List-Unsubscribe=One-Click, and nothing else is valid.

Requirements on the sender

If the required DKIM signature is missing or invalid, the mail receiver SHOULD NOT offer one-click unsubscribe. This is what stops an attacker from injecting forged unsubscribe headers.

POST semantics (what the mailbox provider sends)

When the user clicks the unsubscribe control in the client, the mail receiver sends an HTTPS POST to the URI from List-Unsubscribe, with the key and value from List-Unsubscribe-Post as the body:

• Content-Type: multipart/form-data (SHOULD) or application/x-www-form-urlencoded (MAY).
• Body: the single pair List-Unsubscribe=One-Click.
• The request MUST NOT include cookies, HTTP authorization or any other context information. The endpoint therefore cannot rely on a session, only on the URI itself.
• The receiver MUST NOT send the POST without the user's consent. It sends it only after an explicit action by the user, never in advance.

Examples (from the RFC)

List-Unsubscribe: <https://example.com/unsubscribe/opaquepart>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

POST /unsubscribe/opaquepart HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

List-Unsubscribe=One-Click

With a mailto: alternative and multipart/form-data:

List-Unsubscribe:
    <mailto:listrequest@example.com?subject=unsubscribe>,
    <https://example.com/unsubscribe.html/opaque123456789>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

POST /unsubscribe.html/opaque=123456789 HTTP/1.1
Host: example.com
Content-Type: multipart/form-data; boundary=---FormBoundaryjWmhtjORrn
Content-Length: 124

---FormBoundaryjWmhtjORrn
Content-Disposition: form-data; name="List-Unsubscribe"

One-Click
---FormBoundaryjWmhtjORrn--

Security model

• Limiting the POST body to one fixed pair stops the header from being used to trigger arbitrary form submissions.
• Leaving out cookies and authorization prevents the unsubscribe from being linked to the user's other activity on the web.
• As with the classic List-Unsubscribe, anyone with a copy of the message can unsubscribe the recipient. The opaque part of the URI reduces this risk but does not remove it.

Why Gmail and Yahoo mandate it

Since February 2024, Gmail and Yahoo have required bulk senders (Gmail's threshold is ~5,000+ messages a day to its users) to include RFC 8058 one-click unsubscribe on commercial and promotional mail, and to honor unsubscribes within two days. The reasons follow directly from the basics of deliverability (see Foundations of Email Deliverability):

• An unsubscribe with no friction is the alternative to the "report spam" button. Every user who unsubscribes instead of complaining protects your complaint rate (Gmail says to keep the spam rate below 0.10% and never let it go above 0.30%).
• The requirement for DKIM to cover the headers ties the unsubscribe to an authenticated domain, which complements DMARC alignment.
• Because the POST carries no cookies or context, honoring it needs infrastructure on the sender's side that actually maps the opaque token to a real suppression. That makes it a good indicator of whether a sender manages its lists competently.

Sender implementation checklist

1. Add both headers to every commercial or list message, and keep mailto: as a fallback URI next to the HTTPS one.
2. Sign with DKIM, and include both headers in the signature's h= list.
3. Make the endpoint idempotent, free of redirects and instant: suppress the address on the POST, with no login and no "are you sure?" step.
4. Send one-click unsubscribes to the same suppression list as complaints from feedback loops, and process them within 48 hours at the latest (the Gmail and Yahoo requirement above).
5. Keep the unsubscribe link in the message body as well. The headers add to it; they do not replace it.

What M3AAWG's Sender Best Common Practices add

The Messaging, Malware and Mobile Anti-Abuse Working Group (M3AAWG) sets out industry practice for unsubscribes in its Sender Best Common Practices (Version 4.0, August 2026, section 4.6). Version 4.0 makes one-click unsubscribe a requirement in M3AAWG's own guidance, citing the rules of the major mailbox providers:

• One-click is a requirement. To meet the updated requirements of major mailbox providers, senders "must implement one-click unsubscribe (List-Unsubscribe-Post) in the headers as described in RFC 8058" (section 4.6, item 6c). The same item still says senders should adopt the RFC 2369 List-Unsubscribe header itself.
• Keep the address out of the link. The unsubscribe link should not show the subscriber's email address, and should use an encoded reference instead of clear text (item 14). Section 2.8 extends this to every action URL in a message, including tracking and preference links. The address should not appear in clear text or in an encoding that is easy to reverse, such as base64. An encrypted value, or an identifier with no relation to the recipient that only the sender can map, is far better. The opaque part of an RFC 8058 URI already works this way.
• No delay, but no deadline. Senders must process every unsubscribe request without delay (item 2), and should tell recipients during the process how long removal will take and which lists it covers (item 3). M3AAWG gives no number of days. The 48-hour and two-day figures on this page come from Gmail and Yahoo, not from M3AAWG.
• No login. Subscribers must be able to unsubscribe without logging in to a preference center or passing any other security challenge (item 12). This matches the RFC 8058 rule that the endpoint completes the action without further interaction.