Nisto Products Cree Mac WWW FAQ Standards Mail Lists Nisto

Mail List Command Specification:
Header Fields

Last update: November 22, 1997
Grant Neufeld - <grant@acm.org>

This sub-document discusses the use of message header fields to transport mail list commands (in the form of a meta-syntax).


General Notes

Note that client software should recognize and support both the "List-" and "X-List-" prefixes as the same thing. Servers should format outgoing header fields that have not been standardized (currently none have been) with the "X-List-" prefix.

Use of URLs

Where the content of a header field is specified as an URL, it must be properly encoded and enclosed in angle brackets <>. Any such header field whose content does not begin with the open angle bracket '<', as well as any characters following the closing angle bracket '>', should be ignored by client applications (for now). This will allow for the implementation of non-URL based and/or multi-URL syntaxes without confusing existing clients.

Any List Header based URL missing one or both of the angle brackets must be considered invalid by client applications.

RFC822 format comments (text between round brackets "()") should be treated as whitespace - ignored.


The Standard Header Fields

It is strongly recommended that mailing list servers and mail client applications implement full support for the following 'core' header fields. These provide the basic functionality to cover most user's needs.

Each of these fields must consist of one or more angle-bracket-enclosed URLs (separated by commas). The client is to choose from one of the available URLs (with the first having precedence). There may be RFC822 format comments - "()" bracket enclosed text - which should be treated as whitespace, but comments may not be placed within the angle-bracket enclosed URLs.

Whenever possible, one URL for every field should be a mailto URL.

List-Unsubscribe:

Unsubscribe (remove, off) from the list.

List-Help:

List-Help is just a general purpose URL for the user to get information and help with the list, and possibly for web-controlled subscription management. It should point to a central spot from which the user can access all the information available about the list (description, command instructions, archives, human admin, etc.).

List-Subscribe:

Subscribe (join, on) to the list.
Private or hidden lists will probably not want to include this header.

List-Post:

The address to send messages to be posted/forwarded to the list.

List-Owner:

Contact address for a human list administrator (list-manager, list-mom). Don't need to include it if it's the same as the postmaster.
This field must specify a mailto URL (other protocols may be used, but only when a mailto URL is included in the field).

List-Archive:

Access to archive of past list messages. Often an ftp or http site, although some servers may support the mailto "Get Index" type commands.


Debatable Headers

These header fields have not been submitted for formal standardization, but may still have some value. Discussion remains open on them, so their names and values are still under flux (we can virtually guarantee that some of them will not be adopted).

Unless otherwise specified, the following header fields take the same content format (URLs) as the "core" header fields described above.

<token> are required elements.
[token] are optional elements.

List-Digest:

Switch, or subscribe, to digest mode (default digest mode for the server).
The List-Digest field could almost count as a core header. Its use is recommended for lists that support digests.

List-Digest-MIME:

Switch, or subscribe, to MIME format digest mode.
This field is almost the same as List-Digest, except that the digest format is specified to be MIME digests.

List-Digest-Off:

Switch from digest mode to individual messages.
The List-Digest-Off header could almost count as a core header. Its use is recommended for lists that support digests.

List-Sequence:

<message sequence number>

Sequence numbers can be used by mailing lists to ensure the order of the messages can be properly tracked.

List-Control:

<<list server control address URL>>

Server's address for control (command)messages. Must include "?Body=" or "?Subject=" to identify where command messages go. For example: "<mailto:control@server.com?Body=>" would indicate that messages are to be sent to control@server.com with the commands to be put in the body of the message.

List-Attributes:

[comma separated list of list attributes]

Information about the list such as whether it's moderated, announcements-only, archivable, etc.

Changed from List-Info to List-Attributes.

List-Settings:

[comma separated list of command abbreviations]

The subscriber's particular settings.

List-Software:

<SoftwareName>/<Version> <<CommercialURL>>

Name and version of the mailing list management software in use. (and optional URL to the software's developer). Note that this is strictly an optional tag and provides no functional use. As Joshua D. Baer put it, this is one for the marketing folks, although it may also prove to be of use for those tracking down problems with the software.


Additional Headers

X-URL:

X-URL should be reserved for the user and preserved or dropped by the mailing list software. The user's X-URL can point to their own home page or such.

List-Address:

"<list name>" <<list email address>>

Some possible uses for this field (from Clarence C. Wong):

  1. As part of the confirmation dialog, informing the user that the intended action is to subscribe (or unsubscribe) from this list. (e.g. Are you sure you want to subscribe to "some-list@host.com?")
  2. When subscribing to lists, the MUA could automatically (as an option) create filters and mailboxes for the user.
  3. MUAs could keep track of lists users have subscribed to or unsubscribed from. People who go on vacation often unsubscribe to a bunch of lists and then resubscribe later on.

Alternative labels for this field: List-Identity, List-Description, List-Name, List-ID.

Perhaps only a plain text description (and not the address) should be used for this field.

We may need a header to identify the list name and address. I'm not satisfied that this is the correct way to do it.

List-See-Also:

Information (usually a website) related to the list; but not about the list.

E.g. for the list-header list:

List-See-Also: <http://www.nisto.com/listspec/>

Use of Plain Text (Discussion Only!)

Header fields could be used to provide a plain text message to users. For example, a list which does not allow posting (announcements only) might use the List-Post header field with a plain text message stating "You cannot post to this list. It is only for announcements." instead of providing a mailto URL for an address to post to.

Plain text could be identified in the List- header fields by enclosing it in parentheses: (plain text).

This method presents problems in terms of multi-lingual support and non-standard messages. Formal specification of list attributes may be a more appropriate method of identifying restrictions and features of mailing lists (as currently discussed in the form of a possible List-Attributes header field and the List Attributes identifier meta-syntax).

However, the inclusion of plain text in the List headers provides directly human-readable description without the intervention of the client application. Additionally, the allowance for plain text in the header fields would provide greater flexibility for describing specific conditions of a mailing list that may not be covered through formal list attribute identification.

It may also be useful to combine plain text with the use of meta-syntax (currently URLs) in the header fields. A really bad example of how this might be used:

List-Post: <http://a.com/listpost.cgi> (Post only through the web form)

Client applications may want to display the plain text to the user in the form of a dialog or alert when the user initiates the associated action. For example, a no-posting list might have the header:

List-Post: (No posting on this list - announcements only.)

So that when the user clicks on the "Post to List" button (or whatever), the client application pops up an alert like:

Cannot post to this list:
(No posting on this list - announcements only.)

A Single List Header Field

This alternative method for transporting list meta-info in message headers was proposed by Roger Fajman and is included here for discussion purposes - hiliting alternatives to the current proposal.

List-Function:

<function name> <<command URL>> [; ...]

where function name is one of "help", "unsubscribe", "subscribe", ...

This may address a couple issues:

"One is that firewalls need look for only one header instead of many. If a new function is added, firewalls that look at headers don't need to be changed unless they look inside the header. The other advantage is that only one header name is defined, which may address the concern of some about defining a large number of headers."


Not all of the protocols described here are intended for actual use at this time. Only those portions which undergo some form of peer-review or standards formalization should be deployed.
This document may be redistributed provided this copyright notice remains intact.



Copyright ©1997-1998 Grant Neufeld.
Nisto and nisto.com are trademarks of Grant Neufeld.