mlm-command Documentation

For the most part, mlm-command is configurable by Web page designers as needed on a per-list and per-page basis. It has a variety of features intended to make it easy to customize the script's behavior for your own purposes, but also includes a number of default values that make it easy to run the script from a minimal HTML form for its most likely purpose (allowing people to easily subscribe to a single list).

Form Input Values

mlm-command will accept the following inputs, which are intended to be the NAMEs of HTML form elements. Only the first two, marked with red asterisks (*), are required 100% of the time; if others are left out, the standard default of subscribing to a list hosted by Majordomo will be assumed.

EmailAddress *

The email address of the user who wishes to change hir subscription. This should be entered in a visible text field. The value of EmailAddress will be checked to insure that it is a valid Internet email address.

ListAddress *

The address of the mailing list to affect. This may be entered in a standard form field such as a drop-down list or even a text field (not recommended due to the risk of mistyping). It may also be contained in a hidden form field, allowing users access only to one mailing list (this would be appropriate on a page devoted to that list alone).

Action

The action to take. This must be one of the following strings (though case is not significant):

subscribe	Attempts to subscribe EmailAddress to the mailing list specified in ListAddress. This command and unsubscribe are the only two guaranteed to be valid for all lists and MLMs.
unsubscribe	Attempts to unsubscribe EmailAddress from the mailing list specified in ListAddress. This command and subscribe are the only two guaranteed to be valid for all lists and MLMs.
get_list_info	Attempts to have the list manager responsible for ListAddress send information about said list (usually a short informational file or welcome message) to EmailAddress.
get_list_members	Attempts to have the list manager responsible for ListAddress send a roster of the list members to EmailAddress.
show_own_messages	Makes the list send the subscriber a copy of hir own messages.
hide_own_messages	Makes the list omit sending of messages to their originators, to reduce mailbox clutter.
suspend_delivery	Suspends delivery of messages, but leaves the user subscribed to the list. This can be useful for going on vacation, or if the list has a Web interface that the subscriber can use as a substitute for normal mail delivery.
digest_delivery	Switches to digest delivery mode, in which messages are in one (typically daily) lump, rather than individually. Although this command is valid for all MLMs, it may not be valid for all lists!
resume_delivery	Resumes normal (individual message) delivery mode, shifting back from digest or suspended mode.

The value may be set by (presumably and most sensibly) a drop-down field, a set of radio buttons, or even a hidden field. The action subscribe is the default, and will be assumed if no action is specified or the Action value does not match one of the above list.

ActionDescription-some_action

This can be used in your form to override the hard-coded plain-English description of the action. The default values are as follows:

subscribe	subscribe
unsubscribe	unsubscribe
get_list_info	get information about the list
get_list_members	find out who's on this list
show_own_messages	see your own messages to the list
hide_own_messages	stop seeing your own messages to the list
suspend_delivery	suspend message delivery (but stay subscribed)
digest_delivery	switch to digest delivery
resume_delivery	resume normal list message delivery

When displaying an HTML response file, as specified in [DisplayFile], below, the appropriate plain-English string will be substituted for the token [ActionDescription]. However, these hard-coded English strings may not be what you want. This input allows you to override one or more of the hard-coded values. For example, if the user selected the Action get_list_info, and the HTML response file contains [ActionDescription], mlm-command will attempt to replace that token with the default text "get information about the list". To alter this text, use the following:

<INPUT TYPE="Hidden" NAME="ActionDescription-get_list_info" VALUE="find out more about the list">

You may use as many ActionDescription-some_action inputs as you desire, specifying customized ActionDescription texts for each of the possible [Action]s.

ListManager

Specifies the mailing list manager (MLM) software used to administer the list referred to by ListAddress. Must be one of the MLMs specified in the @Known_MLMs array, which by default is:

majordomo
listserv
listproc
ezmlm
yahoo
egroups

As with Action, the letter case is not significant; upper, lower and mixed case will all be recognized. If ListManager is omitted or is not one of the above list, majordomo will be assumed as the default. The egroups value is deprecated, simply acts as a synonym for yahoo, and will soon go away.

RealName

Specifies the user's real name, to be used with some installations of LISTSERV and ListProc. If omitted or left blank, mlm-command will set the value to a default of Anonymous. This value will be ignored if used with a ListManager setting of majordomo, ezmlm or yahoo, as those MLMs pay no attention to such a field.

ReturnURL

The URL to return people to after signup is complete. It is assumed this will be a URL on the same server as the original HTML form, but that's not necessary. If not supplied, this will default to the root of the system with the HTML form. If this is either of the special values "REFERRER" or "REFERER", the script will return the user to the referring page (the form which called mlm-command in the first place).

DisplayFile

This allows for some customization of return messages (the Web pages that say things like "You have been subscribed to the list" or "An error of type such-and-so occurred"). This works by allowing the calling form to specify a file path on the server where the script resides (starting from the server's DocumentRoot). This will be taken as the base for any messages, with the following extensions appended for the following occurrences:

.success-[Action name]		Operation completed successfully. Note: When a "success" message is generated, mlm-command will append a hyphen and the name of the Action performed to .success, yielding constructs such as .success-subscribe, .success-get_list_info, and so on. It will first check for a specific .success file for that action; if it does not find one, it will default to the generic .success file. Failing that, it will use its own hard-coded (very generic) HTML for the appropriate action.
.err-mail		Error sending mail.
.err-other		Other (unspecified) error.
.no-email		No email address was specified in the calling form.
.no-list		No mailing list was specified in the calling form.
.invalid-email		The email address specified is not a valid Internet email address.
.invalid-list		The list address specified is not a valid Internet email address (including host name!). Note that host name is required even if ForceLocalList is set (see below).
.invalid-action		The Action requested is not valid for the MLM specified by ListManager.
.unknown-mlm		The MLM specified by ListManager is not one this script can handle.
.non-local-list		The mailing list address specified does not reside on the local host (see ForceLocalList, below).
.non-local-referrer		The calling form does not reside on the local host (see ForceLocalReferrer, below).

Thus, if you specify "DisplayFile=/stuff/gothic", and mlm-command carries out the action hide_own_messages successfully, the file /stuff/gothic.success-hide_own_messages will be displayed if it exists. (If not, then /stuff/gothic.success will be tried.) This file can have very different formatting from, for example, the /stuff/techno.success-hide_own_messages or /stuff/corporate.success-hide_own_messages files.

It is assumed that these files will be standard HTML files, though they are assumed not to have .html extensions.

When these files are displayed, tokens in [brackets] will be expanded as follows: any environment variable name will be replaced with its value, and any parameter name for this script will be replaced with its value as well. Consider the following example:

<P>Error! I could not [ActionDescription] the email address [EmailAddress] [to/from] the list [ListAddress].
</p>
<P>You can <A HREF="[ReturnURL]">click this link</a> to return back to the [HTTP_REFERER] host.
</p>

The token [ActionDescription] will be replaced with "subscribe", "get information about the list", or whatever else is appropriate, and the other tokens will similarly be expanded to their proper values. However, the phrase "[to/from]" will be left alone (unless you have a parameter or environment variable named "to/from", which seems unlikely).

A complete listing of tokens for use in display files can be found in the DisplayFiles Tokens Guide.

If DisplayFile is not specified, or the file specified by DisplayFile is not found, the script will display some very generic, hard-coded HTML.

UserConfirmMail

The system administrator can set up mlm-command to send an extra, confirming email to EmailAddress, to reduce the chance of people changing other people's list subscriptions behind their backs. (Or, the system administrator can set it not to do so.) However, if you don't like whichever default behavior the system administrator has chosen, you can also set this variable in your Web form to override the default.

To send a confirmation, set UserConfirmMail to 1. To avoid sending a confirmation, set it to 0 (zero).

(Note that the system administrator can also set mlm-command to always send a confirmation, overriding whatever you chose in your form. So if you've set UserConfirmMail to zero, but confirmations are still being sent, this is probably why.)

Examples of Use

Here are some HTML code examples showing various uses of mlm-command, from the minimal to the rather complex. All these examples assume you have mlm-command installed in the root /cgi-bin directory of your server; if this is not the case, you'll need to change the path in the FORM ACTION attribute accordingly.

Minimal Use: Auto-Subscribe a Majordomo List

The simplest use for mlm-command is to allow people to easily subscribe to a single list -- presumably one you administer, and presumably from a Web page describing or advertising that list. For such purposes, you can hard-code the ListAddress and Action values, and ListManager if you use something other than Majordomo.

To set up a minimal form that allows anyone to subscribe to the list somelist@somehost.tld, assuming that list is managed by Majordomo, use the following HTML:

   <FORM ACTION="/cgi-bin/mlm-command" METHOD="POST">
   <INPUT TYPE="Hidden" NAME="ListAddress" VALUE="somelist@somehost.tld">
   <P>Enter your email address:<BR>
   <INPUT TYPE="Text" NAME="EmailAddress">
   </p>
   <INPUT TYPE="Submit">
   </form>

The default values will be used for Action (subscribe) and ListManager (majordomo), allowing a standard signup. Then the script will use its own hard-coded HTML to return a results page, and offer an exit link to the default ReturnURL of the front page of whatever server it is running on.

Minimal Use for Another MLM

To extend the above example for lists managed by other MLMs, simply include another hidden field setting the appropriate value for ListManager, as follows. This example assumes your list is managed by LISTSERV.

   <FORM ACTION="/cgi-bin/mlm-command" METHOD="POST">
   <INPUT TYPE="Hidden" NAME="ListAddress" VALUE="somelist@somehost.tld">
   <INPUT TYPE="Hidden" NAME="ListManager" VALUE="listserv">
   <P>Enter your email address:<BR>
   <INPUT TYPE="Text" NAME="EmailAddress">
   </p>
   <INPUT TYPE="Submit">
   </form>

Here is an example demonstrating a minimal signup for for the list nonexistent-list@yahoogroups.com. Note that this HTML is presumed not to be emplaced on Yahoo! Groups' own server -- that is irrelevant; the script will do its thing just fine anyway (as long as ForceLocalList is zero).

   <FORM ACTION="/cgi-bin/mlm-command" METHOD="POST">
   <INPUT TYPE="Hidden" NAME="ListAddress" VALUE="nonexistent-list@yahoogroups.com">
   <INPUT TYPE="Hidden" NAME="ListManager" VALUE="yahoo">
   <P>Enter your email address:<BR>
   <INPUT TYPE="Text" NAME="EmailAddress">
   </p>
   <INPUT TYPE="Submit">
   </form>

Minimal Use With Custom Display Files

Presuming your system administrator, webmaster, or other knowledgeable person has given you the path /some/random/path to find display files, and told you that there are files prefixed "english", "spanish", "french" and "german", you might use the following HTML to give people Spanish error messages when trying to deal with a Spanish-language list:

   <FORM ACTION="/cgi-bin/mlm-command" METHOD="POST">
   <INPUT TYPE="Hidden" NAME="ListAddress" VALUE="unalista@myhost.tld">
   <INPUT TYPE="Hidden" NAME="DisplayFile" VALUE="/some/random/path/spanish">
   <P>Entra su correo electrónico:<BR>
   <INPUT TYPE="Text" NAME="EmailAddress">
   </p>
   <INPUT TYPE="Submit" VALUE="Somete la forma">
   </form>

This will cause the script to display the file /some/random/path/spanish.success if the operation completes successfully, or such files as /some/random/path/spanish.no-email or /some/random/path/spanish.invalid-command for the various error possibilities.

More Complex Use: Multiple Lists

Many sites host more than one list, and it's easy to use mlm-command to allow people to interact with all your lists at their own leisure from a single, central location (such as http://www.your-domain.tld/lists). For such a use, the site administrator may well want to set ForceLocalList to 1 (see below). Here is some example HTML for a site using LISTSERV as their MLM, hosting a variety of sports-oriented lists:

   <FORM ACTION="/cgi-bin/mlm-command" METHOD="POST">
   <INPUT TYPE="Hidden" NAME="ListManager" VALUE="listserv">
   <P>Enter your email address:<BR>
   <INPUT TYPE="Text" NAME="EmailAddress">
   </p>
   <P>And what list do you want to join?<BR>
   <SELECT SIZE=1 NAME="ListAddress">
       <OPTION VALUE="baseball@thisdomain.tld">Baseball
       <OPTION VALUE="basketball@thisdomain.tld">Basketball
       <OPTION VALUE="football@thisdomain.tld">Football
       <OPTION VALUE="ice-hockey@thisdomain.tld">Ice Hockey
       <OPTION VALUE="soccer@thisdomain.tld">Soccer
       <OPTION VALUE="yachting@thisdomain.tld">Yachting
   </select>
   </p>
   <INPUT TYPE="Submit">
   </form>

The user should see a text field for the email address, then a drop-down box listing just the names of the various sports. Since there's no way to set the [Action] value, this form will only allow people to subscribe.

Subscribing and Unsubscribing

To allow people to unsubscribe from lists as well as subscribing to them, simply include a pair of radio buttons in your form, like so:

   <FORM ACTION="/cgi-bin/mlm-command" METHOD="POST">
   <INPUT TYPE="Hidden" NAME="ListAddress" VALUE="somelist@somehost.tld">
   <P>Enter your email address:<BR>
   <INPUT TYPE="Text" NAME="EmailAddress">
   </p>
   <P>And what would you like to do?<BR>
   <INPUT TYPE="Radio" NAME="Action" VALUE="subscribe"> Subscribe<BR>
   <INPUT TYPE="Radio" NAME="Action" VALUE="unsubscribe"> Unsubscribe
   </p>
   <INPUT TYPE="Submit">
   </form>

Multiple Actions

To allow users to pick whatever actions they want, you might use a large group of radio buttons, or simply go with a drop-down box. Here's an example of just the controls for the radio buttons, which could easily be interpolated into the previous example:

<P>And what would you like to do?<BR>
<INPUT TYPE="Radio" NAME="Action" VALUE="subscribe"> Subscribe<BR>
<INPUT TYPE="Radio" NAME="Action" VALUE="unsubscribe"> Unsubscribe<BR>
<INPUT TYPE="Radio" NAME="Action" VALUE="get_list_info"> Find out more about the list<BR>
<INPUT TYPE="Radio" NAME="Action" VALUE="show_own_messages"> Get copies of your own messages to the list<BR>
<INPUT TYPE="Radio" NAME="Action" VALUE="hide_own_messages"> Don't get copies of your own messages; just the ones from other people<BR>
<INPUT TYPE="Radio" NAME="Action" VALUE="suspend_delivery"> Temporarily stop getting messages from the list (but remain subscribed)<BR>
<INPUT TYPE="Radio" NAME="Action" VALUE="digest_delivery"> Get messages daily in one big email, instead of individually<BR>
<INPUT TYPE="Radio" NAME="Action" VALUE="resume_delivery"> Go back to getting messages normally.
</p>

You will rarely want to allow all actions, unless you allow your form to target multiple MLMs. This could be done by making the ListManager value be set by a visible control, but that's probably a very bad idea, unless your users know what MLM runs each list. If your users are that good, they probably don't need to use this script in the first place.

More likely, you will only want to target lists run by one MLM, and only include controls for the Actions that are valid for that MLM. One alternative would be to include some JavaScript in your form that determines the proper MLM for each list, but that's outside the scope of this documentation. (If you wish to do this, consult a good book on JavaScript, such as the excellent JavaScript: The Definitive Guide, from O'Reilly and Associates.)

Questions? Comments? Suggestions for future features? Send 'em all to kmactane@GothPunk.com.

Home  |  DisplayFile Tokens  |  Sysadmin Docs  |  User Installation