Nisto Products Cree Mac WWW FAQ Standards Mail Lists Nisto

Guidelines to the List- Header Fields for Client Application Authors

By Grant Neufeld

Last update: August 2, 1998

The List- header fields provide you with a standard method by which you can consistently determine electronic mailing list command syntax and implement an interface to make list access easier for your users.


Header Field Handling Requirements

There are presently six header fields which should be supported.

When implementing support for the headers you should handle both "X-List-" and "List-" prefixes (treating them identically). Supporting both formats is important so that you can handle message from servers that implemented support for the "X-List-" header fields before the "List-" fields were approved for RFC status.

Currently, each header field is defined to contain a comma-separated list of URLs. The individual URLs are enclosed in angle brackets <>.
There may be the keyword "URL:" immediately following the open angle bracket '<' and preceding the beginning of the URL. The "URL:" keyword should be ignored.
Also note that round-bracket comments (RFC822) are permitted within the List- header fields.

When the user asks your application to perform a particular command from a list header field, you should pick the first URL that you know how to handle, from the comma-separated list. This may mean passing the URL to another application (such as a web browser), or creating a mail message.

Any List Header field whose content does not begin with a valid, angle bracket enclosed, URL (skipping over any comments) should be ignored; and you may want to display an error message if the user attempts to use the corresponding command. Do not attempt to handle URLs that are not enclosed in angle brackets.

If an URL (properly enclosed in angle-brackets) is not immediately followed by a comma (excepting whitespace), you should ignore any characters following the closing angle bracket '>'. In future, the syntax of the headers may be extended to include additional information following the URL.

You will need to support the mailto URL scheme which provides for URLs to describe the content of the Subject field and the body of the message.

There may be RFC822 comments in the field (although, not within the angle brackets the enclose an URL). As with other header fields, the comments (enclosed in round brackets "(comment)") should be treated as whitespace.

If the user has multiple email addresses supported by the mail client, the client application should prompt the user for which address to use when subscribing or performing some other action where the address to use cannot be specifically determined. When unsubscribing or such, just use the address that is subscribed, unless that cannot be determined from the message headers or a record kept by the client application.

The List Header Fields

All of the current List Header fields use the comma-separated, angle-bracket-enclosed-URL format for describing commands (see above).

If you implement support for any or all of these fields, you should probably recognize them with the "X-" prefix as well.

List-Unsubscribe:

Unsubscribe (remove, off) from the list.

List-Help:

A general purpose URL for the user to get information and help with the list, and possibly for web-controlled subscription management.

List-Subscribe:

Subscribe (join, on) to the list.

List-Post:

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

There is a special case for the List-Post field where the content of the field is the single word "NO". When the List-Post field contains "NO", it means that posting is not allowed on that list.

List-Owner:

Contact address for a human list administrator (list-manager, list-mom). If the List-Owner field is not present, you can assume postmaster@same.domain.as.the.list (but should confirm with the user).

List-Archive:

Access to archive of past list messages.

The Experimental Header Fields

These fields are experimental - their format may change in future, and they eventually may be deemed innappropriate. The should only be used with the "X-" prefix.

X-List-Software:

Provides information about the list software used to manage the mailing list. This field should generally be hidden from the user as it will usually not be of interest to them.
Handle as plain text.

X-List-ID:

Provides a unique identifier for the list. You may wish to use this in your own tracking of mailing lists subscribed to by the user. It may also be of use in the generation of filters.
Handle as plain text.

X-List-Digest:

Switch to digest subscription format.
Uses the same command URL format as described for the List Header Fields above.

X-List-Digest-Off:

Switch from digest to non-digest subscription format.
Uses the same command URL format as described for the List Header Fields above.


Examples

List-Unsubscribe: <mailto:listcontrol@host.com?Body=unsubscribe%20somelist>
  List-Subscribe: <mailto:somelist@host.com?Subject=subscribe>
       List-Help: <http://www.host.com/lists/somelist.html>, <mailto:listcontrol@host.com?Body=help%20somelist>
       List-Post: <mailto:moderator@host.com?subject=list%20posting>
      List-Owner: <mailto:listmom@host.com> (contact for administrative questions)
    List-Archive: <ftp://ftp.host.com/pub/list/archive/>

Note that any valid URL can be used in the fields, so you may need to pass the URL to some other client application (such as a web browser) if your application does not handle it directly.


Security

The user should have a chance to confirm any action before it is executed. In the case of mailto, it may be appropriate to create the correctly formatted message without sending it, allowing the user to see exactly what is happening and giving the user the ability to stop the message before it is sent.

Mail client applications should not support list header field URLs which could compromise the security of the user's system. This includes the "file://" URL type which could potentially be used to trigger the execution of a local application on some user systems.

If there is any question as to the validity of an URL or its content, the user should be asked to verify the operation, or it should not be performed.


User Interface Guidelines

Handling Multiple User Addresses

If the user has multiple email addresses supported by the mail client, your application should prompt the user for which address to use when subscribing or performing some other action where the address to use cannot be specifically determined. When unsubscribing or such, just use the address that is subscribed, unless that cannot be determined from the message headers.

Feedback

You may wish to provide some specialized feedback/dialog rather than displaying the command messages generated from mailto URLs found the List Header fields.

This feedback can be used for the user to provide command confirmation while 'shielding' them from the raw command message. Such feedback should provide a means for the user to directly review - and perhaps modify - the message before it is sent, but only if they choose to do so (perhaps through a "review" option, or through a general application preference they have set).

For example, if a GUI client application has provided an "Unsubscribe" button, which is mapped to the command url "<mailto:control@server.com?Body=unsubscribe%20maillist>", it could present an alert of the form:

Are you sure you want to unsubscribe from the "maillist" mailing list by sending the command "unsubscribe maillist" to <control@server.com>?
You will no longer receive copies of messages submitted to the list.
|Cancel| |Review Message| |Unsubscribe|

Sample Feedback Messages

Subscribe

Do you want to subscribe to a mail list by sending the command "subscribe SomeList" to <requests@mail.server.foo>?
Every message posted to the list will be forwarded to your mailbox. (<username> <<useraddress>>)
|Review Message| _ _ _ |Cancel| |Subscribe|

Unsubscribe

Are you sure you want to unsubscribe by sending the command "unsubscribe" to <SomeList-request@mail.server.foo>?
You should no longer receive copies of messages posted to the list.
|Review Message| _ _ _ |Cancel| |Unsubscribe|

This document is intended for redistribution on the internet.
Permission is granted to redistribute in whole or in part on the internet provided this complete copyright notice remains intact.
All other reproduction requires prior authorization from the author.



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