This article is training support material provided by L-Soft during Course 3042 training.
Last Update: Jan 2008
This document provides a brief overview and examples detailing the necessary steps to set up a List Signup CGI-bin form on your Web site so that people can simply “click a button” to join or leave list(s) hosted on a LISTSERV® Version 14.x, 15.x or later server (at L-Soft or anywhere).
There are two basic ways to set up a List Signup CGI bin form on a Web site: write your own CGI-bin script or use the existing LISTSERV® CGI-bin script. There are advantages and disadvantages to using either method, and these will be described below.
Your own CGI-bin script must be written so that it sends a regular e-mail message to the LISTSERV® server with a properly formatted command string. The script can act as a user sending the “subscribe” command by e-mail or as an authorized list owner sending the “add” command. The difference between each approach will be described, followed by examples. A custom written CGI- bin script will work with any version of LISTSERV®.
The Web interface of LISTSERV® Version 14.x runs its own CGI script that already provides these capabilities. Simply “call” this CGI script with the proper parameters and the subscriber will be able to join or leave the list(s). This method requires the user to “confirm” joining or leaving the list.
Many LISTSERV® administrators do not want to inconvenience users by making them confirm subscription signons and signoffs. Confirmations do have important advantages for both the list owner and the subscriber.
Confirmations test the e-mail address the user entered for validity, ensuring the address reaches the intended subscribers.
According to L- Soft Support statistics, approximately 35% of subscribers make an error entering their e-mail address.
In addition, some corporate e-mail systems have been configured to reject list e-mail. Confirmation can test for such rejection.
2002 - 2008 L-Soft international, Inc.
L-Soft international Inc. www.lsoft.com ● info@lsoft.com
8100 Corporate Drive, Suite 350 ● Landover, MD 20785
1 800 399 5449 ● +1 301 731 0440 ● fax +1 301 731 6302
Confirmations prevent malicious third parties from subscribing a user to a list without that user's consent. This is known as “spoofing”.
Confirmation is an overt positive act that acknowledges the user does want to receive e-mail messages generated by your list(s). In these days of “spam” and unwanted commercial e-mail, mail which has been specifically requested (Confirmed, Opt-In) can never be considered “spam”.
LISTSERV® 's confirmation message can be responded to either with e-mail by replying to the message with the simple word “OK” (detailed instructions are in the message), or with a clickable URL also found in the message. The actual message text is configurable in the CONFIRM1 template of *.MAILTPL.
Write your own CGI script so that the e-mail message impersonates the subscribing user and is formatted as though the user was issuing a normal SUBSCRIBE command by e-mail. The advantage of this method is that it requires no special privileges or security. The user will receive a welcome or signoff message as appropriate, which can be customized with specific information about your list. The user may be required to confirm their subscription depending on certain list header settings (Subscription= Open,Confirm). User confirmation is not needed to signoff by e-mail command.
[Both the e-mail headers and the message text (command strings) must always be flush-left.]
Date:(Today date in RFC822 format) From:user@address To:LISTSERV@demo.lsoft.com
SUBSCRIBE listname Fname Lname
Note as always, the LISTSERV command(s) is (are) in the message body, never in the Subject: line.
If the user may subscribe to several lists at one time, the command form in the message body is similar:
SUBSCRIBE listname1 Fname Lname SUBSCRIBE listname2 Fname Lname SUBSCRIBE listname3 Fname Lname
To leave the list the command is:
SIGNOFF listname
No name is used for the signoff; it will produce an error if present. To leave several lists:
SIGNOFF listname1 SIGNOFF listname2 SIGNOFF listname3
It is also possible to signoff all lists on the server:
SIGNOFF *
The user@address comes from the user's Web form input on your site. The Fname and Lname are the user's first name and last name if known. Substitute the phrase “No Name” if you do not want this option. It is also possible to configure LISTSERV® so that no name is required. (Default-Options= CONCEAL)
Lists hosted on an instance of LISTSERV® may also use an alternate single-line special-action address format to subscribe to one-list-at-a-time only. Multiple lists are not supported by this method.
Date: (current date in RFC822 format) From: Fname Lname <user@address>
To: listname-SUBSCRIBE-REQUEST@demo.lsoft.com (any message text is ignored so none is needed) To leave the list the special action address is
To: listname-SIGNOFF-REQUEST@demo.lsoft.com
In this case the CGI script acts as an authorized list owner (a pre-authorized From: address), and sends the message as an ADD command. This requires use of a plain text password to verify the From: address. No user confirmation is possible using this method. As a result, L-Soft hosted lists cannot use this method unless you provide your own form of positive identification and confirmation (such as a login to a private Web site).
This method is more customizable than the first method where the script acts as a user. Welcome and/or signoff messages can be sent to the user or not, depending on the form of the command string. To have your Web site script submit an ADD command for getting people to join your list, it must be able to issue a multi-line e-mail command string.
Date: (Today date in RFC822 format) From: webserver123@hostname
//x JOB REPLY-TO=NONE
[QUIET] ADD listname user@address Fname Lname PW=??????
Normally LISTSERV® always acknowledges every command back to the user issuing the command. The //x JOB REPLY-TO=NONE in the command string was added to prevent LISTSERV® from sending back an e-mail response that your Web server will not be able to decipher. If the user has selected several lists, repeat the line as many times as necessary:
//x JOB REPLY-TO=NONE
[QUIET] ADD listname1 user@address Fname Lname PW=?????? [QUIET] ADD listname2 user@address Fname Lname PW=?????? [QUIET] ADD listname3 user@address Fname Lname PW=??????
To leave the list, the command string is:
//x JOB REPLY-TO=NONE
[QUIET] DELETE listname user@address PW=???????
For multiple lists repeat as necessary:
//x JOB REPLY-TO=NONE
[QUIET] DELETE listname1 user@address PW=??????? [QUIET] DELETE listname2 user@address PW=??????? [QUIET] DELETE listname3 user@address PW=???????
Note: You cannot use the “*” character to do this for ALL lists like the example below:
//x JOB REPLY-TO=NONE
[QUIET] DELETE * user@address PW=???????
In this instance your Web script will not be able to respond appropriately because LISTSERV® will ask for and expect to receive a separate confirmation of this action.
Again, the user@address comes from the user's form input on the site. The Fname and Lname are the user's first name and last name if known. Substitute the single character “*” or the phrase “No Name” if you do not want this option.
The PW=????? is a password assigned to the From: address of the e-mail that you determine, but will usually be something like “webserver123@host_name.” The QUIET modifier is optional. If used, do not use the “[ ]” brackets. QUIET will prevent LISTSERV® from sending any acknowledgement, welcome, or signoff message to the user. As noted, the ADD or DELETE command does not require any confirmation from the user.
For this method to be successful, your LISTSERV® server must know the e-mail From: address that will be used by your CGI script so that this address can be installed as a valid list owner with power to issue commands. Your LISTSERV® Site Administrator will also have to assign a password (of your choice) to this special address to enable its privileges to work.
CAUTION: For either method described above, it is advisable that you incorporate some processing in your CGI script to validate the user's e-mail address, at least as syntactically valid per RFC822. If your script acts as a user, the request may simply be sent off and never reach a valid e-mail address. If your script acts as an authorized list owner, it is extremely important that the “*” character, if entered as an address, is trapped. LISTSERV® will recognize the “*” as a wildcard matching any address. Thus it is possible for a valid and authorized command to be issued that can delete all subscribers from the list, unless you perform validation on the submitted address before sending it to LISTSERV®. The L-Soft CGI script (see below) does trap and prevent this occurrence.
This is the Web equivalent of the script acting like a user. The user will be required to confirm their subscription and signoff. The user will receive the appropriate Welcome or Signoff message. This is to protect users from accidental clicking and unintended consequences.
Below is the minimum code sequence for calling the WA.EXE CGI script that you would add to your Web page. You can embellish this with add-ons and collect additional information for your own use. However, this is the minimum needed by the L-Soft CGI script.
Test this minimum interface, which is intentionally made as simple as possible, by going to: http://demo.lsoft.com/signupdemo.html. The information in the examples displayed in this paper is based on lists hosted on the L-Soft server DEMO.LSOFT.COM. To use the examples, simply substitute your server's name wherever you see DEMO.LSOFT.COM in the command strings, and in other places. The working CGI demo exists only on the DEMO server.
In order to be fully successful, you also need to make certain modifications to the *.WWWTPL dynamic Web templates so that the default site pages normally created by LISTSERV® are not accessible and instead include the necessary references to re-direct users to your site for signup.
This is the signupdemo.HTML file:
<!-- Begin LISTSERV(R) wa.exe example calling demo-->
<!-- Below is the basic code you will need to add to your site-->
<form action="HTTP://DEMO.LSOFT.COM/SCRIPTS/WA.EXE">
<!-- Note above URL for calling CGI script must be customized to your host-->
<!-- below parameters SUBED2 and A must be declared first and in this order. Other parameters are not sensitive to declaration order.-->
<input type=hidden name=SUBED2 value="SIGNUPDEMO"><!default LISTNAME to join>
<input type=hidden name="A" value=1><!required low security parameter>
<!Other Variables needed: (all variable NAMES below are case sensitive.)>
<!s= email address>
<!L= listname>
<!p= username phrase: Fname Lname>
<!9= topics list (if used) else "" empty>
<table>
<tr>
<td nowrap>
<b> Your e-mail address:</b>
</td>
[Continued from previous page]
<td>
<input name=s size=30 value="">
</td></tr>
<tr><td>
<b>Your name:</b>
</td>
<td>
<input name=p size=30 value="">
</td></tr>
<tr><td>
<b>Select a list:</b>
</td>
<td>
<select name=L>
<option value="SIGNUPDEMO" selected>SIGNUPDEMO
<!other listnames follow here>
<option value="SIGNUPDEMO2">SIGNUPDEMO2
</select>
</td></tr>
<!-- cut here to remove topics section below -->
<tr>
<td>
<b>Delivery Style:</b>
</td>
<td>
<! checked one is the default choice>
<input type=radio name=9 value="HTML">HTML
<input type=radio checked name=9 value="text">Text
<input type=radio name=9 value="AOL">AOL
</td></tr>
<!-- cut here to remove topics section above -->
<tr>
<td></td>
<td>
<input type=submit name="b" value="Join this list">
<input type=submit name="a" value="Leave this list">
<INPUT type="reset" name="Reset" value="Reset">
</td></tr>
</table>
</form>
<!end of LISTSERV(R) example CGI calling code>
Please note that the calling order of the above parameters is significant. The SUBED2=listname and A=1 must be listed first, in this order. The other parameters may follow in any order.
To customize the example script, replace instances of “signupdemo” with your own List Name where necessary, and replace “demo.lsoft.com” with your own server address. If you do not want people to enter a name, then you can hard code the "p" parameter to "no name" like this:
<tr valign=top>
<td><!Your Name:></td>
<td><input type=hidden name=p value="No Name"></td>
</tr>
You may also want to change the SIGNUP WWW template. See below.
All the LISTSERV® related *.HTML pages are re-generated at least once daily from template files. Since they are dynamic you should never make changes to the *.HTML pages themselves, but only to the templates used to generate the final HTML pages. This is a complex process and you should tread carefully. Before modifying any templates, you should study the default .*TPL template files (mailtpl is mostly text messages with some HTML, wwwtpl is all HTML) to be sure you understand the existing functions before modifying them.
Below is the minimum code necessary to change the default templates on your own
LISTSERV® host site to work just like the example. Before using this code, read Chapter 9 of the Owners Manual, or the Site Manager manual (http://www.lsoft.com/manuals/1.8e/owners/index.html) that discusses template files and how to GET the DEFAULT.*TPL files and modify the desired portions. If activated, you can use the LISTSERV® WWW List Management interface to modify these templates.
You must customize the JOIN_URL to your own site (URL below is for the working Demo only) The LAYOUT-data template is not editable via the WWW interface (you have to do it by e-mail), but SUBEDIT-MAIN is editable. Modifying the LAYOUT-data template in this way disables the user from later modifying their Subscription Options (such as MAIL/NOMAIL, DIGEST/INDEX, and others) with the WWW interface. (They can always modify them by e-mail commands or you do not have to modify this template.) Since this simplified signup procedure is normally used only for one-way lists where all subscriber options are preset anyway and not intended to be changed this is not a serious limitation.
PUT L-LIST WWWTPL PW=?????
>>> LAYOUT-data all layout customization variables go here
+SE JOIN_URL http://demo.lsoft.com/signupdemo.html
>>> SUBEDIT-MAIN Authenticated subscribe/leave, main page
<title>Join or Leave the &+LISTNAME; list</title>
<center><h1>Join or Leave the &+LISTNAME; list</h1></center>
<p>
+BB &+MSG;
<hr><p><b>&+MSG;</b><p>
+EB
<hr>
<p>Thank you! Your Request has been Processed.
<p>To confirm your identity and prevent third parties from tampering with the list, an e-mail message with a confirmation code will be sent to the address you specified in the form. Simply wait for this message to arrive, then follow the instructions to confirm the operation.
<hr>
If you prefer, you can replace the above SUBEDIT-MAIN template with a simple redirect to another page on your site: <meta http-equiv="refresh" content="0; URL=http://totally.other.page">. This completely prevents the user from editing their own subscriber options, but this is not usually a problem for one-way lists.
Please let us know at manuals@lsoft.com if you found this document helpful, or not, or if you have any suggestions for improvement.