# List-Unsubscribe and One-Click Unsubscribe (RFC 2369 & RFC 8058) > Exact syntax and semantics of the List-* header fields and the one-click List-Unsubscribe-Post mechanism, including DKIM requirements and why major mailbox providers mandate them. Source: emailmarketing.net — https://emailmarketing.net/learn/list-management/list-unsubscribe 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: | Header | Purpose | Notes | |---|---|---| | `List-Help` | Full instructions for the list | Considered the most important field; acceptable as the only field implemented | | `List-Unsubscribe` | Command or URL to leave the list | The field that mailbox providers act on | | `List-Subscribe` | Command or URL to join the list | | | `List-Post` | How to post to the list | Special value `NO` for lists that do not accept posts (announcement lists) | | `List-Owner` | Contact for the list administrator | | | `List-Archive` | How to reach the list archives | | ### Syntax rules - The content of each field is **one or more URLs in angle brackets**: `` or ``. 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: List-Unsubscribe: , List-Help: , List-Subscribe: , List-Post: List-Owner: 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 | Requirement | Level | |---|---| | The message has a `List-Unsubscribe` header that contains **one HTTPS URI** (other URIs, such as `mailto:`, MAY also be present) | MUST | | The HTTPS URI contains enough information to identify the recipient **and** the list, so the unsubscribe completes without any further input | MUST | | The URI includes an opaque part that is hard to forge (for example, an HMAC of the recipient and the list), checked on the server | SHOULD | | The unsubscribe endpoint completes the action **without any further interaction** with the user (no login, no confirmation form) | MUST | | The POST endpoint does not return HTTPS redirects (redirected POST requests have historically been unreliable) | MUST NOT | | The message has at least one **valid DKIM signature** whose `h=` tag covers **both** `List-Unsubscribe` and `List-Unsubscribe-Post` | MUST | 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: 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: , 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](https://emailmarketing.net/learn/foundations/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](https://emailmarketing.net/learn/authentication/dmarc). - 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](https://emailmarketing.net/learn/list-management/complaint-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.