Basics of MailMerge



Table of Contents

Getting Started








What is Mailmerge?

Mailmerge is a Perl CGI script used for handling simple HTML forms. It does not require any actual scripting. You can use it to create guest books, user comment forms, surveys, software registration pages, and bug reports.

Mailmerge is basically an e-mail gateway where you create the form in HTML and users fill it out and submit it. The contents of the form are then e-mailed to you or to the recipient of your choice. Mailmerge gives you alot of control over the way in which the outgoing mail is formatted. You can have your output information sent to you with plain text, with html formatted commands, and with cchelper formatted commands.

Instead of having the contents of the form sent to you in an e-mail, you may choose to have the data posted to a file in your web account.






Using Mailmerge

To begin using Mailmerge you will need to have access to your user account and password. You will also need to be familiar with creating online forms. Check your html editor - some programs come with easy form-makers that basically do all the work for you.

The first file you will need to create is your input (form) file. This file will contain your html form -- with the appropriate fields that you want your visitors to fill out. Your form can be part of a larger HTML page -- or it can be in a page by itself.

The second file you will need to create is the Mailmerge template file that will contain specific instructions/commands to the Mailmerge script. These commands will tell Mailmerge how to format the data submitted through the input form and whether you want this information e-mailed to you or passed through to an output file.

If you choose to have the data e-mailed to you, you do not need the third file. However, if you wish to write the data to a file in your web account, you will need to create an output file. Writing data to a file would allow you to create a guest book and allow users to see the inputed information, for example.

NOTE: The output file needs to have permissions changed to allow Mailmerge to write to the file. You must have your output file read and writeable by the world for Mailmerge to work properly.






Creating Your Input File

To create your input file, simply make a new html file containing your input form. For help on creating a form, consult an HTML Reference. For accounts on www.rootsweb.com, the FORM tag must look something like this:

<FORM ACTION="/cgi-bin/local/mailmerge.cgi/PathName/public_html/template.file" METHOD=POST>

On homepages.rootsweb.com, the FORM tag is slightly different:

<FORM ACTION="/cgi-bin/mailmerge.cgi/PathName/public_html/template.file" METHOD=POST>

This should be all on one line - without any line breaks.

The form tag invokes out the mailmerge.cgi script that is resident on RootsWeb. The path name is critical -- this is just an example -- so double check your path name to make sure that your home directory path name is written properly. An easy way to verify your path name is to login to RootsWeb via a FTP program and access your user account. Your path name will be written along the top of your FTP client box.

The template.file is where you will type in your template file name. Examples of template file names are: guestbk.tmp, guestbk.txt, guestbk.htm (the extension doesn't matter - but make sure you upload this file as ascii text only!).

The METHOD=POST is a standard for HTML forms that tells the script how to transmit the information back to the web server.

After this line, you will start to embed your form input commands. Input boxes can include spaces for user names, email addresses, web urls, etc. We'll use this form as an example for further discussion:

<FORM ACTION="/cgi-bin/local/mailmerge.cgi/home0013/home/alcalhou/public_html/query.tmp" METHOD=POST>
<STRONG>Your Name:</STRONG><br>
<INPUT NAME="NAME" VALUE="" TYPE="TEXT" SIZE=20>
<p>
<STRONG>Your E-mail address:</STRONG><br>
<INPUT NAME="email" VALUE="" TYPE="TEXT" SIZE=35>
<p>
<STRONG>Please type your comment:</STRONG><br>
<TEXTAREA ROWS=5 COLS=35 NAME="Query">

</TEXTAREA><BR>
<p>
<INPUT TYPE="reset" VALUE="Clear Form"> <INPUT TYPE="submit" VALUE="Enter Query">
</FORM>

Looks like this:

Your Name:

Your E-mail address:

Please type your query:

Every input variable must be unique -- a good way to keep all your input commands as unique strings is to assign them names that match the information you are collecting. For example: our form above used <INPUT NAME="NAME" VALUE="" TYPE="TEXT" SIZE=20> for the user name field and <INPUT NAME="email" VALUE="" TYPE="TEXT" SIZE=35> for the user email field. You might use URL or www for the user web url, and so forth.

The form we created has three input variables which will be provided to the MailMerge script when the user clicks on the submit button:
     NAME
     email
     Query
Note: all variable names are case sensitive so if you use all CAPS you will need to type the names in the same way in your template file. Our example has one variable that is all upper case, one that is all lower case, and one with mixed case.

You may want to include the following paragraph right after the submit button.

Note: You will be taken to a screen called MailMerge Gateway to view your entry. Simply click on your browser's back key and you will return here.






Creating Your Template File

Once your input file and form are done, you can create your template file. You can call this file anything easy for you to remember - I usually prefer to call it xxxxxxx.tmp (that way, I know that it is the template file).

The template file is a straight text file - so do not include any html header commands in the file.

The template file consists of several sections, each one terminated by a single period as the only character in a line by itself. The first section sets up defaults and variables. Variables defined here are similar to hidden variables transmitted from the form. Every template must have an OUTPUT_FORM section. This describes the output to be placed into an e-mail message or written to a file. When setting up a template for sending e-mail, you'll need to use the MAIL_HEADER section.

An optional section, not discussed here, is used to define the input form in the template instead of using HTML. Since our basic example uses a standard HTML page with <form> tags, the INPUT_FORM section won't be needed.

You can place comments into the template by using a hash (#) as the first character in the line.






Creating Your Template File for Email Use

Here's the way the template file (query.tmp) could be built to send the user's query to you through e-mail:

# template: query.tmp

ACTION=mail

# Set up defaults

SUBJECT=Calhoun County Query
TO=lcompton@onramp.net
WORDWRAP=72
TITLE=Query has been sent.
AUTHOR=Leigh Compton
ADDRESS=<A HREF="http://www.rootsweb.com/~alcalhou/index.html">RETURN to Calhoun County Main Page</a>
.

# This is an e-mail header.
MAIL_HEADER=
To: @TO@
From: @Email@
Reply-to: @Email@
Subject: @SUBJECT@
X-mail-agent: mailmerge v1.0
.

# The output form, ie. the email, that is sent.

OUTPUT_FORM=
@NAME@, < @Email@ > has sent the following query:

@Query@
.

Note the @xxxx@ variables (@NAME@ or @Email@). The input variables used in your form are referenced in the template by placing the @ (at sign) around the variable name. MailMerge will take the information it collected for NAME and use it in this template form and insert where ever you have used the @NAME@ variable. You need to make sure that you spell the tag names the same in your input file and in your template file for mail merge to work properly. Case is important in these variable names.






Creating Your Template File for Html Use

The signal to MailMerge that it is supposed to write its output to a file in your directory is to include ACTION=File: in your template file. The file name specified in the ACTION directive needs to be an absolute path, so make sure you have the correct path name.

Here's another version on the query.tmp file which can be used to create a query page rather than sending the query via e-mail.

# template: query.tmp

ACTION=File: /home0013/home/alcalhou/public_html/newqry.html

# Set up defaults
TITLE=Thank You For Posting Your Query
AUTHOR=Leigh Compton
ADDRESS=<A HREF="http://www.rootsweb.com/~alcalhou/index.html">RETURN to Calhoun County Main Page</a>

ESCAPE_HTML=1
.

# The output form, ie. the html fragment that will be appended to the newqry.html file

OUTPUT_FORM=
<p>
<strong>Name: @NAME@<br></strong>
<strong>Email: <a href="mailto:@email@">@email@</a></strong><br>
<p>
@Query@
<p>
.

Again, we use the three variable names from our input form -- spelled exactly as they appear in the form. Unlike the e-mail example which had simple text output, this example creates text marked up with HTML so that it will display properly in the output web page. To make sure that any HTML the user might type into the query is properly handled by MailMerge, we set the ESCAPE_HTML variable to 1.

This output will appear in your web page (newqry.html) something like this:

Name: Leigh Compton
Email: lcompton@onramp.net

Looking for the burial place of John W. Parker.






Creating Your Output File

When you want to pass information collected from your form directly to a file, you will first need to create a file in your web account and include that file name in your action statement in your template file.

You can simply create an empty file or create one that matches your other files (with headers and gif files). You will need to leave room for MailMerge to write the collected information -- and you should not close your file with </body> and </html> commands.

MailMerge automatically inserts a short line of dashes (----------) between each entry in the file.

Once you have created this file and uploaded it into your web account, you need to set the permissions to allow Mailmerge to write to the file. This is done using the "Use With Mailmerge" button in the RootsWeb File Manager. Use http://www.rootsweb.com/fileman/ to access the File Manager for accounts on the WWW server. For accounts on Homepages or the Virts server, use http://homepages.rootsweb.com/fileman/.






Some Common Problems

The most common problem using Mail Merge is setting your output files incorrectly. If your output file is not set to be writeable then your user will get a "permission denied" error message. If that happens, you will need to use the File Manager to make the file "world writable."

Another common problem is incompatible variable names. For example, @WEB@ and @web@ are considered to be two different names. Make sure you are consistent throughout your forms and template files.

Also, since the form action string is very long - sometimes typos occur. Your action string must be exact or mail merge will not work. Check your path and the path to the mailmerge.cgi script on RootsWeb.




This information was excerpted in part from the original tutorial on Mail Merge by:

Lincoln D. Stein, lstein@genome.wi.mit.edu
Whitehead Institute/MIT Center for Genome Research