Table of Contents Previous Next Index

Section 3 Communicating with LISTSERV

Section 3 Communicating with LISTSERV
LISTSERV was created before the World Wide Web was in general use. Then, the primary way for most people to communicate with the LISTSERV program was by email, and this method is still widely used today. The most recent versions of LISTSERV include a Web interface to make communication easier and more intuitive. The Web interface is richly populated with on-screen information, tutorials, and wizards to help you use the program quickly and effectively.
When you want to perform actions using LISTSERV, such as adding a subscriber to a list, the action is based on a command LISTSERV receives by email or using the Web interface. Some commands are only available to LISTSERV maintainers and list owners, while other commands are available to subscribers and non-subscribers as well.
3.1 Using Email to Communicate with LISTSERV
There are two main email addresses that are used to work with LISTSERV lists. One is to communicate with the LISTSERV program — a “command address”, and one is used to post mail to the list — the “list address”. Any time the list configuration is changed or a subscription setting is changed, communication takes place with the LISTSERV program using the command address. Whenever a message is posted to the list, it is sent to the list address.
The command address will usually start with “LISTSERV@” and will be followed by the server name where the LISTSERV program has been installed. Messages sent to the command address should contain only commands to LISTSERV, one command per line. Lines containing non-commands will result in an error message being returned.
Tip: If sending commands from an email client that uses a “signature file”, make sure that the first line of the signature file is a line containing only “-- “ (two consecutive hyphens and a space) starting at the very start of the line. Otherwise, LISTSERV will attempt to interpret the signature text as commands and return “Invalid command” errors.
Figure 3-1 Example of an Email Sent to LISTSERV
The email address that communicates with
the LISTSERV program always begins with
“LISTSERV@” because you are contacting
the LISTSERV program.
A command (GET) is followed by specific parameters for that command. In this case, the name of the file to “get” followed by the options: a single parenthesis “(“ and the word “header”, indicating that LISTSERV should send only the header part of the list to the list owner’s email address.
The list address will always start with the name of the list followed by the address of the server where the list resides.
Figure 3-2 Example of an Email Sent to the List
The next meeting of the women’s club will be on January 27th at 8:00 PM. We will meet at the public library, 123 Oak Street.
The agenda is posted on our Web site at www.example.org. Don’t forget to fill out your survey for the new year’s activities.
The email address that sends mail to the list of subscribers always starts with the name of the list.
The body of the email message contains the
information that is sent to the subscribers.
For a list of LISTSERV commands, their descriptions, and how to issue them, see the List Keyword Reference document.
Email Command: You can also get a listing of commands by sending an email message to your LISTSERV server with the following command: INFO REFCARD
3.2 Using the Web Interface to Communicate with LISTSERV
Sending email messages to LISTSERV containing commands and posting messages to the list is sometimes confusing for people new to mailing lists. To simplify this process, the Web interface provides a centralized location for interaction with LISTSERV. As a list owner, you can use the Web interface to issue commands directly to LISTSERV. You can also use the Web interface to post simple messages to the list. An overview of the Web interface for list administration is provided in Section 5 Using the Web Interface.
3.3 Anatomy of a LISTSERV List
A LISTSERV list consists of the list’s configuration (header) and any number of subscriptions. Each subscription includes an email address, a name, and the subscription “settings” or “options”. The list’s configuration regulates list behavior that applies to the entire list, whereas subscription settings regulate behavior that may be different for each subscriber.
A list’s configuration is defined by a set of “keywords” arranged in a format called a “List Header.” The keywords contained in the list header have values associated with them. The values of the keywords determine the behavior of the list. For example, a list header that contains the keyword “Attachments” with the value set to “No” will not allow any messages that include attachments to be sent to the list. Keywords can be added, removed, or have their values changed in a list header by sending a command to LISTSERV to replace the header.
Keywords and their associated values set the behavior of the list. This behavior in turn sets the “style” of the list. For example, the keyword “Send” and its associated value determine who is allowed to post messages to the list. A list that has the keyword “Send” set to “Owner” allows only the owner of the list to post messages to the subscribers. This creates a one-way communication style for the list – the owner can send messages to the subscribers, but the subscribers cannot send messages to the list for distribution.
A list of this type might be used for newsletters or product announcements. A list with the keyword “Send” set to “Private” would allow the list owner and the subscribers to that list to send messages to the list, setting up a two-way communication style list. This type of list could be used for collaboration or discussion among the subscribers. See Section 4 Mailing List Types for detailed descriptions of the three most common types of mailing lists.
At present, there are more than 50 keywords that can set the behavior of mailing lists. Keywords can be added, removed, or have their values changed by using the Web interface or by sending an email message to the LISTSERV program using the command address.
Figure 3-3 Example of a List Header
The “Hide Header” (.HH ON) directive is used so no one but the list owner will see the following header lines.
Keywords in the list header and their respective settings or values determine the behavior of the list. The keyword is followed by an “=” (equal sign). Anything to the right of the “=” denotes the setting or value for that keyword.
When a keyword has several values, they are
separated by commas, or can be continued over several lines by repeating the same keyword.
Any text that is not a keyword definition or a
directive (line starting with a “.”) is considered a comment and ignored by LISTSERV.
A description of the template used to create a
particular type of list may be present. This text is explanatory only. It is not used by LISTSERV, does not affect the behavior of the list in any way, and may be removed by the list owner if desired.
When updating the list header using e mail, each line must start with an asterisk (“*”).
“.HH OFF” turns the Hide Header directive off so that any part of the header that follows is viewable by the public
 
3.4 The “OK” Confirmation Method
For the sake of security, there are a number of actions for which LISTSERV requires confirmation before proceeding. In some cases, LISTSERV will accept a password-based validation. In other cases, email confirmation is required. When this happens, LISTSERV sends an email message with a subject line such as:
Subject: Command confirmation request (787EF897)
The string of “hexadecimal” numbers in parentheses (“787EF897” in the example) is called a “cookie” (sometimes referred to as a “confirmation code”) and is different every time. The text of the message will look something like this:
Figure 3-4 Example of an “OK” Confirmation Message
has been received. For security reasons, you are now required to reply to this message, as explained below, to confirm the execution of your command. Note that the security level of the list is under list owner control, and that is the person you should contact if you have any complaint about security procedures.
Alternatively, if you have no WWW access, you can reply to the present message and type "ok" (without the quotes) as the text of your message. Just the word "ok" - do not retype the command. This procedure will work with any mail program that fully conforms to the Internet standards for electronic mail. If you receive an error message, try sending a new message to LISTSERV@HOME.EASE.LSOFT.COM (without using the "reply" function - this is very important) and type "ok 787EF897" as the text of your message.
Finally, your command will be cancelled automatically if LISTSERV does not receive your confirmation within 48h. After that time, you must start over and resend the command to get a new confirmation code. If you change your mind and decide that you do NOT want to confirm the command, simply discard the present message and let the request expire on its own.
Received: from mail.example.com by home.ease.lsoft.com (Windows v1.1b) with SMTP id <9.FC988C9E@home.ease.lsoft.com>; Tue, 3 Dec 2002 17:16:06 -0500
Received: from yourbox by mail.example.com (Windows v1.1b) with SMTP id <0.000007B9@mail.example.com>; Tue, 3 Dec 2002 17:16:06 -0500
In the figure above, the owner sent an email command to delete all subscribers from a list that is configured such that it requires list-owner commands to be validated (Validate=Yes,Confirm). As the “delete” command did not include the owner’s password, LISTSERV sent an email requesting confirmation of the command.
When you receive a command confirmation request, you must confirm within 48 hours (this time may be configured differently using the Confirm-Delay= keyword) in order for the command to be executed. There are two ways of confirming the command, using the Web interface or using email.
To confirm with the Web interface, simply visit the link included in the message. The link sends the “OK” command to LISTSERV, providing the list name to which it applies and the cookie that was assigned to this command.
To confirm with email, simply reply to the email message, keeping intact the Subject line (“Re:” or other prefixes may be added with no impact), in particular the cookie in parentheses at the end of the subject line. In the text of your reply, simply say “OK” (without the quotes) and nothing more.
Tip: If this method is not successful, then you can send a new message to the LISTSERV command address using the “OK xxxxxxxx” command, where “xxxxxxxx” is the cookie copied from the original confirmation request.
The cookie is the key to the “OK” confirmation method of validation. LISTSERV randomly generates a new cookie for each action that requires validation. Only someone with access to the email address to which LISTSERV sends the cookie knows what the cookie is. All of the privileges within LISTSERV are tied to an email address, so when LISTSERV needs to verify that a command was really initiated by the owner of a particular email address, it uses the “OK” confirmation method.
Caution: Never “OK” a cookie blindly. Make sure that it is for a command that you initiated or for a message that you want to have distributed to the list. Several cases of list “hijackings” or spam sent to well-secured lists have been traced back to a list owner or moderator absent-mindedly clicking an OK link that they should not have clicked.
Examples of actions that require an “OK confirmation”:
Postings from a subscriber with the “REVIEW” subscription setting.
Postings to a list with Send=…,Confirm (sender must confirm that the message came from them – strongly recommended for one-way lists, such as newsletters).
Subscription requests for a list with Subscription=Open,Confirm or Subscription=By_Owner,Confirm. Subscription confirmations are strongly recommended on public lists, to prevent unwanted third-party subscriptions.
DELETE or ADD commands sent over email without a password, on a list with Validate=Yes,Confirm.
All subscription modifying commands, including SET and SIGNOFF commands from subscribers, on a list with Validate=All,Confirm.
As these examples illustrate, the list configuration controls most of the conditions under which confirmations are required. The list owner must decide on the right balance between security and convenience for the list. For more information, see the List Keyword Reference document.