There is a line in some email messages that you will never see in the body. It sits in the header section, above the first paragraph, in the same structural layer as From: and Subject:, and it looks like this:
List-Unsubscribe: <mailto:list@host.com?subject=unsubscribe>
That is the example given in RFC 2369, published in July 1998 and written by G. Neufeld and J. Baer. The document is titled, with the flat earnestness of its era, The Use of URLs as Meta-Syntax for Core Mail List Commands and their Transport through Message Header Fields. It is the artifact I want to read closely here, because it marks the moment when leaving a publication stopped being a sentence you wrote in the footer and became a field the container could carry.
The argument is not that the header is elegant. It is that the header is a design decision about the reader’s exit, made at the level of format rather than copy, and that the history of that decision — from 1998 to the one-click revision of 2017 — shows how much of editorial independence lives in the parts of the message the writer does not compose.
What the header displaced
Before RFC 2369, mailing list commands were prose. To leave a list managed by Majordomo or Listserv, you sent a message to a command address with a line like unsubscribe listname in the body, and you learned this from instructions buried somewhere in a welcome message or a footer. The commands varied by list manager, the addresses varied by list, and the whole apparatus was, in the RFC’s own words, “cryptic and varied.”
RFC 2369 proposed to move the command out of the body and into the header, where a mail client could read it and offer it as a button. The abstract is explicit about the intent: “By including these header fields, list servers can make it possible for mail clients to provide automated tools for users to perform list functions. This could take the form of a menu item, push button, or other user interface element. The intent is to simplify the user experience, providing a common interface to the often cryptic and varied mailing list manager commands.”
That sentence is worth sitting with. The RFC is not primarily about making it easier for senders to manage lists. It is about making it possible for clients to present list functions in a consistent way, so that the reader does not have to learn a different dialect for every publication they subscribe to. The command becomes a property of the message, and the interface becomes a property of the client.
The design choice: URLs as meta-syntax
RFC 2369 defines six header fields. Three are core: List-Help, List-Subscribe, and List-Unsubscribe. Three are secondary: List-Post, List-Owner, and List-Archive. Each field typically contains a URL, usually a mailto: URL, that either locates information or performs the command directly.
The choice of URL syntax was deliberate. The RFC’s appendix explains that a single header field carrying a new meta-syntax was rejected because “every additional layer of complexity and newness reduces the likelihood of actual implementation.” URLs were already widely understood, already supported by clients, and already extensible. The header would inherit that.
The syntax also allowed for fallbacks. A field could contain multiple comma-separated URLs, ordered left to right by preference, and the client would use the leftmost protocol it supported. The RFC’s example for List-Unsubscribe shows this:
List-Unsubscribe: <http://www.host.com/list.cgi?cmd=unsub&lst=list>, <mailto:list-request@host.com?subject=unsubscribe>
The web URL comes first, the mailto second. A client that could open a browser would use the first; a client that could only send mail would use the second. The RFC recommends that senders include a mailto command “in addition to any other protocols used, in order to support users who do not have access to non-mail-based protocols.” The preference order is a bet on universality: the exit should work even for the reader whose only tool is email.
Why the header is a container argument
Here is the part that matters for writers. The List-Unsubscribe field lives in the header section, which RFC 5322 defines as the sequence of fields that precedes the optional body, separated from it by an empty line. The header is not the place where you make your argument or set your tone. It is the place where the message declares what it is and what can be done with it. Putting the unsubscribe command there rather than in the body means the command survives whatever the writer does with the content. You can redesign the footer, change the template, rewrite the closing paragraph, and the exit is still there, in the same structural layer as the sender’s identity.
This is what I mean by the container disciplining the content. The format decides what the reader can do, and it does so before the reader has read a word. A newsletter whose only exit is a link at the bottom of a long issue has made leaving a function of the reader’s patience and scroll position. A newsletter that emits List-Unsubscribe has made leaving a function of the message’s structure, available to the client regardless of what the body says.
There is a further consequence. Because the header is read by the client, the client decides how the exit is presented. The sender supplies the command; the interface supplies the affordance. That is a different distribution of editorial control than a footer link, where the sender controls the placement, the wording, and the surrounding copy. The header cedes some of that control to the container, and in exchange the exit becomes consistent across publications.
The failure mode
For nearly two decades, that was the arrangement. Then the container started reading the URLs.
RFC 8058, published in January 2017 and written by J. Levine and T. Herkula, opens with the problem in plain terms: “The need for this arises out of the actuality that mail software sometimes fetches URLs in mail header fields, and thereby accidentally triggers unsubscriptions in the case of the List-Unsubscribe header field.” Anti-spam software, scanning messages for links, would fetch the unsubscribe URL automatically. The sender could not tell whether the request came from a person or a crawler. So senders added confirmation pages: a live reader would see the page and click through; an automated system would not. The RFC is blunt about the cost: “That makes the unsubscription process more complex than a single click.”
This is a container-side problem that had been patched on the content side. The confirmation page asked the reader to do extra work because the protocol could not distinguish a human from a bot. The better fix, RFC 8058 argues, was not a better landing page but a new header and a narrower contract.
The fix and its cost
RFC 8058 introduces List-Unsubscribe-Post, a second header whose only permitted value is List-Unsubscribe=One-Click. A sender that wants to offer one-click unsubscription places one List-Unsubscribe header containing an HTTPS URI and one List-Unsubscribe-Post header with that single key/value pair. The receiver performs an HTTPS POST to the URI, sending the key/value pair as the request body. The POST is the signal that a human consented; a GET, which is what a crawler would issue, does not complete the unsubscribe.
The contract is tighter than RFC 2369’s, and the tightness is the point. Several requirements are worth naming because they show how much the container now has to guarantee:
- The message must carry a valid DKIM signature covering at least the
List-UnsubscribeandList-Unsubscribe-Postheaders. If the signature is missing, the receiver “SHOULD NOT offer a one-click unsubscribe for that message.” The exit is only trustworthy if the message carrying it is authenticated. - The POST request must not include cookies, HTTP authorization, or any other context information. The unsubscribe operation is “logically unrelated to any previous web activity,” and context information could link the exit to the reader’s browsing history.
- The sender must not return an HTTPS redirect, because redirected POSTs have historically not worked reliably and many browsers have turned them into GETs.
- The URI should contain an opaque or hard-to-forge component, and the server should verify it, to deter attacks that abuse unsubscribe links.
- The receiver must not perform the POST without user consent, though how consent is obtained is outside the specification.
There is also a constraint that reads almost like a design principle: because there is no provision for extra POST arguments, all the information needed to identify the recipient and the list must be encoded in the URI. One-click “has no way to ask the user what address or from what list the user wishes to unsubscribe.” The exit cannot ask a question. It can only act.
RFC 8058 is careful to say that it does not update RFC 2369, so the use of List-Unsubscribe for anything other than one-click is unchanged. The mailto command still works. The web URL with a confirmation page still works. What the new header adds is a way to signal that a particular URI will accept a POST and complete the unsubscribe without further interaction.
What the two documents disagree about
Read together, the two RFCs are a record of a changed bet about what “simple” means. RFC 2369 preferred mailto because it was universal: it worked for readers with no web access, and it did not depend on a browser. RFC 8058 requires an HTTPS URI for one-click because the problem it is solving is not access but automation: a mailto command cannot be accidentally triggered by a crawler fetching a link, but it also cannot be completed without the reader composing and sending a message. The one-click path trades the universality of mail for the immediacy of a POST.
Neither choice is wrong. They are answers to different failure modes. RFC 2369 was optimizing against the reader who could not use the web. RFC 8058 was optimizing against the software that used the web too eagerly. The lesson is not that one protocol superseded the other but that “the simplest exit” is always relative to the failure you are trying to prevent.
The practical test for writers
If the container disciplines the content, then the unsubscribe path is part of the editorial container, and it deserves the same scrutiny as the subject line or the opening paragraph. The test I would propose is not “do I have an unsubscribe link” but a set of questions about format:
- Can a reader leave in one action, from the client, without opening a browser?
- Does the exit work if the reader’s only tool is email?
- Does the exit require the reader to log in, confirm an identity, or explain a reason?
- Is the exit present in the header, where the client can find it, or only in the body, where the reader has to scroll for it?
Consider a clearly hypothetical example. A small newsletter offers only a footer link that leads to a page requiring a login to cancel. The reader who wants to leave must find the link, open a browser, remember or reset a password, and navigate a settings page. The same newsletter adds a List-Unsubscribe header with a mailto command. Nothing in the issue changes. The reader’s cost of leaving drops from several steps to one message. The editorial voice is identical; the format is not.
Or consider the one-click case. A publication that emits List-Unsubscribe with an HTTPS URI but no List-Unsubscribe-Post header is offering a link that, in a client that supports one-click, may still require a confirmation page. Adding the second header and signing both is a format decision that changes what the reader can do without changing a word of the content. It is also a decision that requires the sender to maintain a POST endpoint, verify an opaque token, and keep the DKIM signature valid — infrastructure work that is invisible in the issue but constitutive of the reader’s experience of leaving.
Why this is an editorial question
The inbox is a site of editorial independence, and independence includes the right to leave. A publication that makes leaving easy is making a claim about its own confidence: it expects to be read because the reader chooses to read it, not because the exit is hard to find. That claim is made in the header, not in the footer. It is made by the presence of a field the reader never sees, in a format the reader never inspects, and it is enforced by a client that decides how to present the exit.
This is the sense in which the container disciplines the content. The header does not argue with the reader. It does not persuade. It simply makes a structural commitment: the command to leave is part of the message, available to the client, and not dependent on the writer’s prose. A format that makes leaving easy is a format that makes the writing trustworthy, because it removes the suspicion that the reader is being kept by inconvenience rather than convinced by argument.
The artifact is one line. It has been revised once, in 2017, to add a second line and a POST. It will probably be revised again. What will not change is the principle the two RFCs share: the exit belongs in the container, and the container is where the reader’s autonomy is either respected or quietly eroded. Writers who treat the inbox as a place for deliberate format choices should read their own headers before they read their own footers.
Questions readers ask
Does RFC 8058 replace RFC 2369?
No. RFC 8058 states explicitly that it does not update RFC 2369, so the use of List-Unsubscribe for anything other than one-click is unchanged. The mailto command and the web URL with a confirmation page still work as described in 1998. RFC 8058 adds a way to signal that a particular HTTPS URI will accept a POST and complete the unsubscribe without further interaction.
Can I offer both a mailto and an HTTPS URI?
Yes. RFC 8058 says the List-Unsubscribe header must contain one HTTPS URI and may contain other non-HTTP/S URIs such as MAILTO:. The RFC’s own complex example shows a mailto URI followed by an HTTPS URI. The one-click POST applies to the HTTPS URI; the mailto command remains available for clients that use it.
Why does the message need a DKIM signature?
RFC 8058 requires a valid DKIM signature covering at least the List-Unsubscribe and List-Unsubscribe-Post headers. If the signature is missing, the receiver should not offer one-click unsubscribe. The signature ties the exit to an authenticated message, so a forged header cannot be used to trigger unsubscriptions on someone else’s behalf.
Why can’t the unsubscribe page just ask a confirmation question?
It can, and RFC 2369’s web URL path still allows it. But RFC 8058 was written because confirmation pages made the process more complex than a single click, and because automated systems cannot answer a confirmation question. The one-click path exists for cases where the unsubscribe must complete without a human reading a page — for example, when a mail system processes a junk report or closes an abandoned mailbox.
Sources
- G. Neufeld and J. Baer, RFC 2369: The Use of URLs as Meta-Syntax for Core Mail List Commands and their Transport through Message Header Fields, July 1998.
- J. Levine and T. Herkula, RFC 8058: Signaling One-Click Functionality for List Email Headers, January 2017.
- P. Resnick, ed., RFC 5322: Internet Message Format, October 2008.