Skip to content
Thoughtful, detailed coverage of everything Apple for 34 years
and the TidBITS Content Network for Apple professionals

Explaining All Those List Headers

Whenever I explain how email works to novices, I call email headers "the glop at the top," since they aren’t easy for us humans to digest. Headers are lines of text that precede any Internet email message; they carry descriptive information about the message rather than the message itself. You’re probably familiar with the primary human-readable headers, such as Date, From, Subject, and To, but you probably wish you’d never seen some of the more indecipherable headers such as Message-Id, Content-Type, or Received, which together can form an impenetrable snarl. These esoteric headers are meant to be understood by email programs, not humans, so email programs often hide headers that rank high on the gobbledygook scale.

However, you may have noticed that TidBITS and TidBITS Talk have sprouted new and unusual email headers since the beginning of 1999. Most of these headers, which I collectively call the "list headers," are up-and-coming Internet standards. These list headers are human-readable and provide information useful to mailing list subscribers; however, they’re also meant to be understood by email programs so they can help email users better manage their mailing list subscriptions.


< chandhok-listid-03.txt>

Heads Up — Because the list headers are standardized, email programs can start to pay attention to them. Initial support from lazy developers would be to hide the list headers, since they occupy a number of lines in each mailing list message. A better solution might be an Unsubscribe menu item when looking at a message containing list headers. Even more useful would be an interface that would help you track your mailing list subscriptions, let you unsubscribe from one or all lists with a click of a button, and automatically filter mailing list messages. Once that level of functionality was available, the list headers could be hidden, since the email program would have subsumed their utility.

Second, until email programs support list headers directly, the list headers can make it easier for normal people to manage their mailing list subscriptions. I describe each of the headers that we use in TidBITS below; since the list headers include URLs, clicking the appropriate list header URL could unsubscribe you from a list, get help, or send email to the list owner. Plus, if you wanted to send someone instructions for joining a list, you could send that person the List-Subscribe header’s URL.

Listing the Headers — Let’s look now at each of the list headers we’re using in TidBITS and why other lists may or may not want to use them. Note that the order is arbitrary – the order we chose is based purely on line length for an easily understandable visual display.

List-URL: <>
List-Archive: <>
List-Subscribe: <mailto:[email protected]>
List-Unsubscribe: <mailto:[email protected]>
List-Help: <>
List-Owner: <mailto:[email protected]> (TidBITS Editors)
List-Software: "ListSTAR v1.2 by StarNine Technologies, Inc."
List-Id: "TidBITS Setext Distribution List" <>
List-Post: <mailto:[email protected]> (Discussions on TidBITS Talk)

The following header also appears in TidBITS Talk:

List-Digest: <mailto:[email protected]>

  • List-URL: The List-URL header is not part of the Internet standards. We use it because we want keep our list headers consistent and to make sure that people can easily find our Web site’s home page, from which they should be able to find detailed information about TidBITS and our mailing lists.

  • List-Archive: The List-Archive header points to our searchable article database of every TidBITS article ever published. Many lists may not have archives and thus wouldn’t need this header.

  • List-Subscribe: List-Subscribe is one of the most important headers, because it contains the information necessary to subscribe to TidBITS. List-Subscribe might seem silly – after all, if someone’s received a message with this header, they’ve probably already subscribed to the mailing list. However, List-Subscribe is useful if someone forwards you a message from a mailing list and you decide you’d like to sign up, or if you’ve unsubscribed from a list and later decide you want to sign up again. If an email program were to parse the list headers and provide an interface to their functionality, offering a Subscribe menu item would be helpful. Lists may not use the simple -on and -off addresses we’ve helped popularize, but mailto URLs can include additional information, including Subject-based commands like this: <mailto:[email protected]?subject=subscribe>. List-Subscribe could also point to a Web page with subscription forms or other options.

  • List-Unsubscribe: Like List-Subscribe, List-Unsubscribe is a perfect candidate for instantiating in interface. Considering how many bounces we get from people who couldn’t be bothered to figure out how to unsubscribe to TidBITS (not to mention the number of unsubscribe requests sent to seemingly random addresses), we’d love it if people who don’t want to receive TidBITS anymore could reliably unsubscribe without contacting us individually.

  • List-Help: The RFC that describes the list headers considers List-Help the most important, since it could contain a pointer to the information stored in all the other headers.

  • List-Owner: The List-Owner header points to the human contact for the list. For TidBITS, that’s our general <[email protected]> address, although it could be more specific. On TidBITS Talk, for instance, I list myself as the List-Owner.

  • List-Software: Like List-URL, List-Software isn’t part of the list header standard. It provides a spot to identify the list software that runs the mailing list. Although that’s not necessary, it can be helpful to know precisely what program is handling distribution. For instance, from "ListSTAR v1.2 by StarNine Technologies, Inc.", you can tell that ListSTAR sends out TidBITS from the header above, but LetterRip Pro handles TidBITS Talk, as evidenced by the TidBITS Talk List-Software header’s contents: "LetterRip Pro 3.0.4 by Fog City Software, Inc."

  • List-Id: The List-Id header comes not from the RFC describing the other list headers, but from the separate Internet draft linked above. Its purpose is to provide a unique identifier for every mailing list. Automated tools that would provide mailing list management interfaces in email programs need such markers to identify lists reliably. Also, people setting up filters need some way to tell when a message comes from a list. Other headers usually work, but we’ve all experienced problems with lists that change their headers when they switch to a different distribution program or host. Theoretically, the List-Id header could remain the same through such changes, preventing filters and other automated tools from breaking. List administrators make up the List-Ids for each list, though the Internet draft provides format recommendations along the lines of domain names. So <> identifies the setext distribution of TidBITS emanating from TidBITS Talk uses a slightly shorter List-Id – <> – since it doesn’t have to differentiate between setext and other possible formats.

  • List-Post: We use the List-Post header differently than most mailing lists would, since TidBITS is not itself a discussion group. We want to redirect discussion to TidBITS Talk, so we use that address in the mailto URL. The parenthetical comment (Discussions on TidBITS Talk) explains why we’re sending people to another mailing list. Of course, TidBITS Talk itself uses the same mailto URL, but uses a different parenthetical comment (TidBITS Talk Moderator) to indicate that the list is moderated. The fact that we have two mailing lists that share the same List-Post header shows why we need the List-Id header. If someone decided to filter on the contents of the List-Post header, they would hit both TidBITS and TidBITS Talk.

  • List-Digest: Finally, we come to the List-Digest header, used only with TidBITS Talk. It’s not part of the list header standard, but it provides a necessary URL to tell people how to subscribe to the digest version of TidBITS Talk. It’s a prime candidate for instantiation in interface, along with List-Subscribe and List-Unsubscribe.

Who Should Use List Headers? I’ll be honest: a major reason we adopted the list headers for TidBITS and TidBITS Talk is that we know some of the people involved in the standard process. These folks evangelized us to support the list headers, plus answered questions when I was trying to produce the most appropriate set of headers for TidBITS and TidBITS Talk. But aside from our specific situation, there are four groups of people who should pay attention to the list headers: those who run mailing lists, people who write email programs, developers of mailing list programs, and finally, individuals who subscribe to mailing lists.

I encourage everyone who runs a mailing list to add appropriate list headers. They aren’t hard to create and most mailing list programs let you add custom headers. My hope is that the time and effort I put into creating the list headers will be repaid by less time helping TidBITS and TidBITS Talk subscribers manage their subscriptions.

Developers of email programs should start thinking about the best ways to support the list headers internally. I’ve seen an early version of a tool that provides an interface for managing your mailing list subscriptions based on these list headers and it’s a verifiable Good Thing. Think of it this way, until support for list headers is ubiquitous, any email program that supports them can add it to the feature checklist.

Programmers who create mailing list management programs may not need to do much, since custom header features are already common. However, these programs should make the process of creating the list headers easier, which would encourage list header adoption.

From the standpoint of an individual user, I suggest merely that you take a look at the list headers and remember that they exist. Then, when you want to search for information in a message that you’ve deleted, look for the List-Archive header, or if you want to unsubscribe from a list, try using the URL in the List-Unsubscribe header.

As we’ve all seen over the years, users have trouble interacting with mailing list programs, and anything that improves that process serves the entire Internet community.

Subscribe today so you don’t miss any TidBITS articles!

Every week you’ll get tech tips, in-depth reviews, and insightful news analysis for discerning Apple users. For over 33 years, we’ve published professional, member-supported tech journalism that makes you smarter.

Registration confirmation will be emailed to you.

This site is protected by reCAPTCHA. The Google Privacy Policy and Terms of Service apply.