Documentation for the mail form

The mail form is interpreted by a Perl script (form-mail.pl) that builds and sends a mail message. It can be built by hand, or by a TCL script (mail-form.tcl) that fills in some of the blanks with application and user-specific values. You may wish to refer to the sample form source.

Building the form

The mail-form.tcl script contains default values for the recipient's name, e-mail address, and the subject. These can be changed by specifying them as a "query" to the script in the URL. I.e., the URL

<http:/cgi-bin/mail-form.tcl?subject=The%20Mail%20Form&name=Bongo>

would request a form to be built that starts with the header

Send mail to Bongo about The Mail Form

The mail would be sent to the default recipient.

The fields that can be set are

name: The "real" name of the recipient of this message. Only appears in the form, not in the eventual mail message.
recipient: The e-mail address of the recipient.
subject: The subject of the message. Appears on the form and in the e-mail message. Any spaces and other special characters must be "escaped" with the %XX notation, where XX is the hexadecimal ASCII value for the character. (E.g., %20=space.)

Note that the field name must be given exactly as above, and must be in lower case.

The values (recipient and subject) that must be "passed on" to the script that sends the mail are encoded in "hidden" fields in the form.

The other thing that the mail-form.tcl script does is to try to guess the identity of the person sending the mail. It does this by examining the "environment" variables HTTP_FROM, REMOTE_HOST, and REMOTE_ADDR, in that order.

If HTTP_FROM is set, and has an "@" sign in it, it is assumed to be the user's e-mail address. This is true of browsers such as MacMosaic, Netscape and Lynx. With some browsers (e.g., MacMosaic) the user (you) must set their e-mail address manually in an "Options" or "Preferences" dialog. With others (e.g., Lynx), the browser tries to figure it out automatically.

If HTTP_FROM is not properly set, then an "@host" address is generated from the REMOTE_HOST or REMOTE_ADDR values. REMOTE_HOST is preferred, if it set.

A final note: if you decide to copy this script, you will need to take out or modify the bit that points to this documentation!

The contents of the form.

The form has several input fields. These are

username: The user fills in his or her e-mail address here. It is initialized by mail-form.tcl as described above, or should be blank in a static form.
realname: The user fills in his or her real name here. It is not initialized.
comments: The user types the text of the message here.
recipient: A hidden field, this is initialized to the e-mail address of the person to receive the mail.
subject: Another hidden field that is initialized to the subject of the message.

There are two copies of the "submit" and "reset" buttons, at the top and bottom of the form, for convenience.

The form is submitted using the POST method, since the comments could conceivably be quite long.

Sending the mail

The form-mail.pl script was adapted from one written by Reuven Lerner at MIT. It receives the form submission and packages it as an e-mail message.

To adapt it for your own use, you may need to change the $mailprog and $recipient values at the beginning of the script (note that $recipient is the default value, and is used only if one is not supplied from the recipient field on the form.) You may also wish to change the confirmation message, and the "wrapper" of the e-mail message, found in print statements further down in the script.

The script first "unpacks" the values from the POSTing into internal variables. If no comments were entered, it outputs a "you submitted a blank message" response. Otherwise, it picks up the recipient e-mail address and opens a pipe to the mail process. It prints a Reply-to header with the the user's e-mail address, and a Subject header. It then prints the comments in a "wrapper" identifying the user and the specifics of the connection.

After sending the mail, it returns a response screen to the user.

Spencer W. Thomas (spencer@umich.edu)