support

Unofficial Guide to FormMail.pl (Customization Features)

Requirements
Any text or HTML editor

First things first you need to tell Formmail who is going to receive the resulting e-mail that is sent from your online form. We do this by inserting a hidden field in the HTML of your online form; this is NOT set in the Formmail script itself. The HTML line should look like this:

Be sure that this line is contained within the <form> and </form> tags or else it won't work.

Here's a short list of the things you can do to customize Formmail:

You can send the results of the online form to more than one recipient
You can specify required fields for your form
You can automatically check the syntax of an e-mail field
You can set up a customized error page
You can set up a custom thank you page
You can give each form its own subject
You can force the printing of blank fields
You can set up the order of fields in the resulting e-mail
You can find out certain environmental variables (like the type of browser being used)
Print header values in the body of the e-mail

All customization from this point forward is done via hidden form fields in the HTML of your web page that contains your online form.

Multiple Recipients
To send the results to more than one e-mail recipient, you will need to contact Web Hosting in order
to set up a "group" email address.

Required Fields
To specify required fields (these are fields that must be filled in by a user before the form can be submitted) for your form, simply list them in the values attribute of a hidden field called "required":

Use commas to separate the required field names. Caution: Be sure to list the names of the required fields EXACTLY as they are named on your form. Formmail is case-sensitive.

** As a side note, The usual convention for naming fields with multiple words is in the form of (for example): "First_Name" or "FirstName".

It's probably a good idea to let your users know which fields are required. Nothing is more frustrating for site visitors than having to fill out a form multiple times because they have no clue what minimum information they are required to provide. Most webmasters use a red asterisk or similar visual aid with a small note to communicate this information to the users.

Check E-mail Syntax
To automatically check the syntax of an e-mail address that a user inputs in a text field, simply name the text field "email" and make it a required field. If you look closely, you'll notice there is special code in the Formmail script that checks for the correct syntax... like ensuring the inclusion of an @ symbol in an e-mail address, for instance. An example of this might look like:

The syntax of the e-mail address will only be checked if the "email" field is required.

Make a Custom Error Page
You don't have to create a custom error page to let the user know he/she did not fill in all the required fields on your form. Matt's Formmail script already includes a generic error page that informs the user of any missing fields when the submit button is clicked. Once your form is up and working properly, you can easily see what this generic error page looks like by leaving some required fields blank and then submitting the form.

Optionally, you can use Java Script to do "client side" form validation. Check out these resources.
http://www.echoecho.com/jsforms.htm
http://www.spoono.com/tutorials/javascript/validation/
http://javascript.about.com/library/weekly/aa070901a.htm

Most people refer to create a customized error page, simply because you have total control over how the page looks when you create it yourself. That way, your error page has the same look and feel of the rest of pages on your site.

I would suggest making a standard error page that communicates these things:

The form was not submitted because all required fields were not filled in.
Here is a list of the required fields (at this point, you could gently remind them "all required fields have a red asterisk beside them" or something similar).
The user needs to go back to the form, add the missing information, and resubmit the form. You can provide a link to go back (like <a href="javascript:history.go(-1);">Go back</a> for instance) to the form, or ask them to push their browser's "Back" button.

Once you have made the error page, remember the file name because you need to enter it as the value in the hidden field called "missing_fields_redirect":

In the above code example, you'll notice how the error page URL is in the form of an absolute URL. We do this because Matt's script looks for a string that begins with http: and, unless you change the code of the script, a relative URL like "../form_error.html" won't work.

Because of case sensitivity issues when dealing with web servers, be sure that the URL is correct. A URL of http://www.yoursite.com/Form_Error.html will not work if the filename of the error page is actually http://www.yoursite.com/form_error.html.

Make a Custom Thank You Page
Similar to the customized error page, you can just as easily create a custom "thank you" page to let your site visitors know you received their information. Matt's script also provides similar confirmation by default, but as stated before, many web designers prefer to create their own for aesthetic reasons.

The name of this particular hidden field is called "redirect"; again, make sure you use an absolute URL like

unless you change the code in formmail.pl as mentioned above. Again, remember that URL's are case sensitive!

Create a Subject for your Form
You can easily control the subject of the e-mail which is sent to you from the form. Just add a hidden field called "subject" to your online form:

Adding a subject to your form responses can help you rapidly determine if you got any mail from your web site; it can even help automate your business. Let's say you have multiple online forms on your web site: one form for requesting a brochure, one to join an online newsletter list, another for an online order, etc. You could easily set up filtering in your e-mail client (Outlook Express, Eudora, etc.) so that when an e-mail of a particular subject arrives, it automatically goes into the appropriate folder.

Unless you add this hidden field to your form, the default subject will be a generic
"WWW Form Submission".

Force the Printing of Blank Fields
"OK," you ask, "why in the world would I want to know the contents of a form field if the user didn't fill in a value?" Truth is, most people won't. But, if you're one of those enterprising developers who has written a macro (or similar functionality) that depends on always finding the contents - blank or not - of all the fields, this option can be very helpful indeed.

If you want to print the value of all fields in the resulting e-mail, simply add this hidden field to your form:

Without this code, Formmail defaults to turning this option off.

Sort the Fields in the Resulting E-Mail
Sorting fields can really streamline your reading and responding to emails. Here's how to do it with a hidden field called "sort":

Just be sure the phrase order: is at the head of the list.

Otherwise, you can sort the fields alphabetically by name with a hidden field like:

Discovering Environmental Variables
Wanna find out what type of browser your site visitors use to surf your site? You can do this by adding a hidden field called "env_report":

Using this code snippet will allow you to find out the hostname making the request as well as the type of browser. You can find other environmental variables to exploit by going to CGI Resources.

Print Header Values in the Body of the E-mail
Two fields that are normally shown only in the header of the resulting e-mail (namely, the e-mail address and the subject of the e-mail) can be forced to print within the body of the e-mail. This hidden field is called "print_config":

Note: For this to work for the e-mail address, the name of the text field MUST be "email". By adding it as a required field, the script will automatically check the syntax of the text.

If you need additional help with FormMail, just let us know.
WebHosting@nethere.com

This Guide originally entitled:
"The Defiitely Unofficial Guide to FORMMAIL"
Was written by Brant Burgiss.
(Some content has been edited.)