From version 3.00, FormMail provides a feature where you can format the plain text email it sends you.

If you've got FormMail working, then you will have seen the email it sends you. Typically, the email contains the field names and their values, listed down the page. The email is formatted in plain text.

This HOW-TO guide explains how you can change the wording, order, and format of the plain text emails FormMail sends to you.

If you want it to send you HTML email, there's a specific How-To guide that explains how to do that.

In overview, here are the steps you need to perform:

1. Create a directory on your server to hold templates.
2. Configure FormMail for a template directory (or URL prefix).
3. Create a plain text template.
4. Configure your form to tell FormMail to use the template.

Your template files can be placed anywhere on your server, however we strongly recommend creating a separate directory (folder) to hold template files.

It's much more secure. FormMail won't load templates outside the directory you specify - this means that a hacker cannot use FormMail to access files on your server that are to be kept secret.

By creating a directory that only holds template files, you can be sure that a hacker cannot use FormMail to compromise your server.

We recommend that you create a directory called "fmtemplates" at the top of your web server document root.

Edit formmail.php and look for $TEMPLATEDIR in the configuration section. In version 3.00 this is near line 1350. The line you're looking for looks like this:

$TEMPLATEDIR = ""; // directory for template files; ...

It's a good idea to review the documentation above this line.

Now, alter $TEMPLATEDIR to specify the full path to your template directory:

$TEMPLATEDIR = "/path/to/fmtemplates"; // directory for template files; ...

Use your favourite text editor and write the text you want FormMail to send to you.

To tell FormMail to include a field value, simply put the name of the field where you want and prefix it with '$'. Here's an example:

This is the latest form submission:

Email: $email
Name:  $realname

Now upload this file to the directory you created in Step 1. Let's assume you've called this file "plain.txt".

Finally, edit your HTML form and add a hidden field to tell FormMail to use the template:

<input type="hidden" name="mail_options" value="PlainTemplate=plain.txt" />

If you already have a mail_options field in your form, simply append "PlainTemplate=plain.txt" to the value and precede it with a comma.

Upload your modified form and test!

By default, FormMail will send you an alert and fail the form submission if your template specifies a field that the user hasn't entered.

Therefore, you must only include required fields in your templates or tell FormMail to allow missing fields.

You can tell FormMail to insert a specific value when a field is missing. Simply add the "TemplateMissing" option to mail_options:

<input type="hidden" name="mail_options" value="PlainTemplate=plain.txt,TemplateMissing=n/a" />

The above tells FormMail to write "n/a" in place of missing fields. You can use any value (except comma and double-quote). To replace missing fields with no value:

<input type="hidden" name="mail_options" value="PlainTemplate=plain.txt,TemplateMissing=" />

Some users have requested that FormMail send a CSV format email to them. This is easy with the PlainTemplate feature. Just create a template that lists the form values with commas:

$email,$realname,$yourfield1,$yourfield2,....