![[Mail merge icon]](mailmerge.gif)
Mailmerge CGI Script, v1.1
Mailmerge CGI Script, v1.1It's basically an e-mail gateway: you write the form in HTML, users fill it out and submit it, and the contents of the form are then e-mailed to you or to the recipient of your choice. However, unlike other scripts of this sort, Mailmerge gives you control over the way in which the outgoing mail is formatted by letting you supply printmerge-style templates that specify the appearance of both the input form and the outgoing message.
As of version 1.1, mailmerge can also be used to write messages out to a file, so that you can create voting scripts, guestbooks, and so on.
sendmail-compatible e-mail agent (this
requirement limits this script to servers running
on Unix systems by and large).
Otherwise you can download the various components individually. After the text of the scripts appear on your screen, save them to disk.
#!/usr/local/bin/perl
This defines the path to the perl interpreter. Adjust this as
necessary and make sure that it points to perl version 5.001
or higher.
The other configuration parameters are at the bottom of mailmerge.cgi
following a line that reads __END__.
They define default values for the input and output forms, the e-mail
headers to use, and such things as the title of the input page,
the contact address for the form's author, and formatting preferences.
Any of these values can be changed on the fly in the template file
(see Using Mailmerge)
but you will probably want to set some reasonable defaults here.
Specific values you will probably want to change include:
AUTHOR=Your Name Here
ADDRESS=<A HREF="/">Your affiliation here</A>
TO=webmaster
You usually invoke mailmerge by creating hypertext links that look like this:
<A HREF="/cgi-bin/mailmerge.cgi/path/to/template">
Fill out the user comment form
</A>
To understand how this link works, you need to understand a bizarre
but very useful feature of links that involve CGI scripts. The
first part of the HREF, /cgi-bin/mailmerge.cgi is the
path to the mailmerge script on your server. The second part,
/path/to/template, is actually additional "path information"
that is passed to mailmerge to tell it where it can find the
template file to use for formatting an e-mail message.
The additional path information can be interpreted in several ways, allowing you a bit of flexibility when referring to the template. Mailmerge tries all the various interpretations till it finds the template file. For example, let's say you call mailmerge this way:
<A HREF="/cgi-bin/mailmerge.cgi/templates/templ1">Mailmerge will try to find the template in the following ways:
ACTION=Mail
OUTPUT_FORM=
* MEMO *
Subject: @SUBJECT@
To: @TO@
From: @FROM@
Date: @DATE@
Priority: @PRIORITY@
@BODY@
.
There are two instructions in this template file. The first instruction,
ACTION= tells mailmerge that the message is to
be sent out by e-mail. The second instruction defines the output
form. The form definition
starts with the line OUTPUT_FORM= and ends with a period
(.) alone on a line.
The text of the output form consists of normal text interspersed
with special variables that have the form
@VARIABLE@. A variable name is surrounded by "@" signs and
can contain any combination of letters, numbers and the underscore (_)
character. Case is significant, so @SUBJECT@
and @Subject@ are
two different variables.
When mailmerge formats an e-mail message it substitutes appropriate values for the variables:
* MEMO *
Subject: Release date is close!
To: jwilmer@capricorn.org
From: abs@zoo.com
Date: Sat Aug 5 18:48:14 EDT 1995
Priority: High
John,
The release date is perilously close and marketing is getting
antsy. Isn't it time to get the product out of beta test and
start planning the party?
-Agatha
Where do the values for the variables come from? They can come from
several sources, but the most important source is from named fields
in the fill-out form presented to the remote user. One of the ways
to specify this form is to define it with a
INPUT_FORM=
instruction in the template file. Here's an input form that
will go well with the memo example:
INPUT_FORM=
<H2>Memo</H2>
To: <INPUT TYPE="text" NAME="TO"><BR>
From: <INPUT TYPE="text" NAME="FROM"><BR>
Subject: <INPUT TYPE="text" NAME="SUBJECT">
Priority: <INPUT TYPE="radio" NAME="PRIORITY" VALUE="High">High
<INPUT TYPE="radio" NAME="PRIORITY" VALUE="Normal" CHECKED>Normal
<P>
<TEXTAREA ROWS=20 COLS=60 NAME="BODY">
</TEXTAREA>
<INPUT TYPE="submit" VALUE="Send">
.
This form defines three one-line text input fields named
"TO", "FROM", and "SUBJECT", plus a large 20-line input field
named "BODY" and a pair of radio buttons named "PRIORITY".
When this form is submitted, mailmerge uses the various named
fields to fill in the variables in the output form. Thus the
contents of the "TO" field is substituted for the variable @TO@
the contents of the "SUBJECT" field is substituted for the
variable @SUBJECT@, and so on.
The INPUT_FORM= definition is written in HTML, using
the fill-out form tags. For information on using these tags, see
NCSA's tutorial, or my book,
How to Set Up and
Maintain a World Wide Web Site. Note that should not
surround the definition with the <FORM> and </FORM>
tags. Mailmerge does this for you. You can also embed a form
directly in a larger HTML document and use mailmerge to process
it, bypassing the INPUT_FORM= definition. See
Embedding mailmerge forms in your own pages
for details.
What about the @DATE@ variable? It isn't defined in the input
form, so where does its value come from? Many variables are
predefined by mailmerge, either as defaults
that you can adjust, or calculated by mailmerge on the fly.
@DATE@ is one of
the predefined variables, and always contains the date and time
at which the message was submitted. A full list of the predefined
variables is given in Predefined variables.
ACTION definition tells mailmerge what to do with
the formatted output form. Three different values are possible:
definition.
Things are arranged so by default this address will be found
in the TO variable.
TO variable and using the indicated address
for the recipient. This is useful if you don't want the remote user to
be able to change the recipient.
~bob/public_html.
It's important to know that in the interests of security, the file must already be created in order for the script to append new entries to it. It must also be writable by the user ID that the Web server runs under (usually an unprivileged user named "nobody"). You can create an empty starting file and make it writable by the Web server in this way:
$ touch log_file
$ chmod o+w log_file
ACTION in your template,
is to assume ACTION=Mail. This can be changed by modifying
the like-named variable in mailmerge.cgi.
INPUT_FORM= and
OUTPUT_FORM= definitions, you can make a
MAIL_HEADER= definition. This is the
e-mail header that is used on all outgoing messages.
By default the definition looks like this:
MAIL_HEADER= To: @TO@ From: @FROM@ Reply-to: @REPLY_TO@ Cc: @CC@ Bcc: @BCC@ Subject: @SUBJECT@ X-mail-agent: mailmerge v1.0 .This header definition assigns special meaning to the following variables:
MAIL_HEADER= definition. In fact,
the working example at the top of this documentation uses this trick
in order to set both the sender and recipient of the message to
the same address (see example 3).
INPUT_FORM, OUTPUT_FORM
and
MAIL_HEADER), you can define default values for variables.
These values
will be used unless the variables are overridden by the contents of
the submitted form. Variable default definitions are single lines
in the form
VARIABLE=VALUEYou can define defaults for variables that have special meaning in the mail header, or create variables of your own choosing to use in the input, output forms and mail headers. For example:
TO=webmaster@capricorn.org FROM=nobody@capricorn.org SUBJECT=Feedback on the Web Site BCC=fred@zoo.com PRIORITY=NormalThese lines define defaults for the
@TO@, @FROM@, @SUBJECT@, @BCC@
and
@PRIORITY@ variables, and ensure reasonable
behavior even when the input
form isn't filled out completely. For example, if the "TO" field isn't
filled out (or if a "TO" field isn't even provided in the input form), then
the default value of
webmaster@capricorn.org will be used for the recipient
of the e-mail. This is one way to force the e-mail to go to the
recipient of your choice.
Mailmerge doesn't yet support multiline variable definitions.
VARIABLE=VALUE
lines in the template file.
{value1,value2,value3}. This is the default.
There is a particular order in which mailmerge tries to assign values to the variables. You can take advantage of this order in order to create global defaults, and then override the defaults in individual template files.
Mailmerge first reads its own defaults from the bottom of the
mailmerge.cgi file itself. Everything following the line
__DATA__ is actually a template that follows all the
rules for template files described above. This default template
defines reasonably generic values for INPUT_FORM, OUTPUT_FORM and
MAIL_HEADER. (If you make a link to mailmerge without specifying any
template file, these defaults will be used to give you a "plain vanilla"
e-mail gateway.) Mailmerge also calculates many of its built-in variables,
such as @DATE@, at this point.
After reading its built-in defaults, mailmerge reads the template file you provide it. Any variables and forms that you redefine in this file replace the defaults.
Finally, if mailmerge is being called to process a fill-out form, the contents of each named field is substituted for the like-named variables.
<A HREF="@REFERER@">Back</A>This is only supported by a subset of browsers.
INPUT_FORM
definition in the template file, you can place the form directly into your
own HTML page and arrange to have mailmerge process it when the submit
button is pressed. You should point the <FORM> tag's ACTION
attribute to the mailmerge script, and set METHOD to
POST (this is very important). Follow
this example:
<FORM ACTION="/cgi-bin/mailmerge.cgi/path/to/template" METHOD=POST>
(your form here)
</FORM>
Remember to specify a template file to use. Although the
INPUT_FORM definition, if any, will be ignored,
mailmerge still needs to read the OUTPUT_FORM definition
to format the contents of the fields you
declare in the fill-out form.
INPUT_FORM
by incorporating a variable directly into the field definition.
For example, if you define COUNTRY=USA in the template,
then the string "USA" will appear by default if this line appears
in the INPUT_FORM definition:
<INPUT TYPE="text" NAME="COUNTRY" VALUE="@COUNTRY@">
TO field. You can do so with lines like these
in the INPUT_FORM definition:
<SELECT NAME="TO">
<OPTION>fred@bedrock.com
<OPTION>wilma@bedrock.com
<OPTION>webmaster@capricorn.org
</SELECT>
TO=
variable
in your template file and avoid creating any TO fields in the
INPUT_FORM. To be absolutely certain that the e-mail can
only be sent to the recipient(s) of your choice, you can
redefine the MAIL_HEADER in this way:
MAIL_HEADER=
To: fred@bedrock.com (Fred Flintstone)
From: @FROM@
Subject: @SUBJECT@
Date: @DATE@
.
FROM variable is
@REMOTE_USER@@@REMOTE_HOST@. This allows you to create forms
that incorporate the user's name and host in the return address
field (e.g. fred@bedrock.com). See
example 4 (try it).
INPUT_FORM just by
placing a <SRC> there. In fact, you are free to incorporate
any HTML tags you choose, including hypertext links and Netscape/HTML3
tables.
mailmerge.cgi read
"#!/usr/local/bin/perl", and does this path point to version
5 of the perl interpreter?
CGI.pm installed in the perl library directory,
usually /usr/local/lib/perl5?
sendmail, and is this program
located in the usual location of /usr/lib/sendmail?
sendmail installed.
Mailmerge can be modified easily to handle other mail agents, but I
didn't have any handy to test out. See your system or network
administrator for help with this one. E-mail problems can be hard
to sort out, but here's one hint: it usually pays to examine the
e-mail log files.
©1995, Lincoln D. Stein, All Rights Reserved
You're encouraged to send me questions and bug reports. My address is given at the bottom of this documentat.
You'll find pointers to other CGI scripts on my home page and at How to Setup and Maintain a World Wide Web Site.