[back to the mail form handler home page]

Mail Form Handler - mail_form.pl

Mail Form Handler Help

Overview

The Mail Form Handler (mail_form.pl) is a generic CGI script designed to email HTML form input to a specified user or users. All your forms can point to a single instance of the script because the script can support any number of HTML forms while providing customizable output for each.

To use the script, all you need is an HTML form. The script uses the "name" and "value" attributes of special form <input> tags to collect variable data. Many of these fields are of type="hidden", such as the "Recipient Address". This means that users don't see the field in their browser but the name/value pair for the field is passed to the script when they submit the form.

Other fields can be hidden or can be filled in by the form submitter as desired, such as the "Email Subject Line".

None of the special name/value pairs are returned in the generated email/results page (except the Full Name special field). However, all of the special fields are used to generate the email and to return the results page properly. (Note: To exclude the Full Name field from the results table as well, prepend the string "exclude;" to the specified Full Name value. See below.)

The <form> tag in your HTML form should point to the script location and should use the POST method. For example:

<form method="post" action="http://www.someserver.com/cgi-bin/mail_form.pl">

Server Requirements

    unix servers:

    • http server (eg, Apache server) that allows cgi execution, either in arbitrary directories or in a special cgi-bin directory (if cgi scripts can only be executed in cgi-bin, you must install the script in that directory)
    • perl installation (script assumes /usr/local/bin/perl -- if perl is installed elsewhere on your server, you must change the first line of the script to point to the correct location)
    • sendmail installation (script assumes /usr/lib/sendmail -- if sendmail is installed elsewhere on your server, or you are using an equivalent program, you must change the line in the script that points to the sendmail binary)

    windows 2000 iis servers:

    • http server (typically, IIS) that allows cgi execution, either in arbitrary directories or in a special scripts directory (if cgi scripts can only be executed in the scripts directory, you must install the script in that directory)
    • some flavor of perl for windows (the windows version of the Mail Form Handler was tested using a default installation of 32-bit ActivePerl from ActiveState)
    • sendmail for windows installation (script assumes c:/inetpub/scripts/sendmail.exe -- if sendmail is installed elsewhere on your server, or you are using an equivalent program, you must change the line in the script that points to the sendmail executable)

    Note on sendmail: The Mail Form Handler script points to the sendmail binary/executable in two places - both must be modified if your sendmail is in a non-default location. Point your browser at the HTTP location of the script to see if the script has found an installation of sendmail on your server and to see whether you need to change the two lines in the script that point to it.

Installing the Script

To install the script, first download the script and save it as a file on your hard drive. What you should have is just a text file on your disk.

Copy this text file to your HTTP server and place it in the cgi-bin, scripts, or an arbitrary directory. Where you put the file depends on the server setup with regard to executing scripts. See the troubleshooting section below for more information.

Once the script is in the correct location, make sure the permissions are set to world read and world executable.

Make sure that the perl installation and sendmail installation are correct and that the script points to the right locations to access these components.

Lastly, make sure your HTML form "action" tag points to the absolute or relative HTTP location of the mail_form.pl or mail_form_win.pl script.

Troubleshooting

Here are some common problems with implementing the script:
  • Your server must be configured to allow CGI execution - contact your sysadmin.
  • Some servers let you execute CGIs anywhere; others require that you install your CGIs in specific locations (such as a cgi-bin directory) - contact your sysadmin.
  • Some servers only let you execute scripts that end with certain extensions. For example, one server might only allow execution of files with the ".cgi" extension. Others might permit .pl, .cgi, .exe, etc. Check with your sysadmin.
  • The script must be world-executable. On a unix machine, use chmod. On NTFS disks, go File>Properties>Permissions. In addition, you might need to go into IIS and configure the containing directory to allow script execution.
  • Make sure the HTML form "action" points to the HTTP location of the script. Point your browser at the HTTP location of the script -- if you get the basic help page, that's a good sign. Otherwise the script is not where you think it is, it is not set up to be executable (either the file or the directory permissions are wrong), or the script cannot execute due to a syntax error or other problem. Try running the script from the command line. It should print out the HTML of the help page. If it does not, it should tell you what and where the problem is.
  • The script points to the perl interpreter and to sendmail - make sure these executables are located in the directory specified in the script, or alter the script to point to the location of these executables on your server.

Supported Special Form Fields

Note: ALL names (and where indicated, values) are CASE SENSITIVE!

    Recipient Address - The email address(es) to send the form submission results to. Multiple addresses can be specified as a comma-separated list. THIS IS THE MOST IMPORTANT FIELD. IF YOU DON'T SPECIFY YOUR EMAIL ADDRESS HERE, THE EMAIL WILL BE SENT TO THE DEFAULT ADDRESS. This field is usually type=hidden.

      Example (one address): <input type="hidden" name="Recipient Address" value="nobody@example.com">
      Example (multiple addresses): <input type="hidden" name="Recipient Address" value="address1@example.com, address2@example.com">

    Email Address - Used as the return address in the email. This is usually a user-entered value.

      Example: <input type="text" name="Email Address" size=15>

    Cc Address - Specifies address(es) to include on the Cc: line of the email. Multiple addresses should be specified as a comma-separated list. This can be a user-entered or predefined address or comma-separated list of addresses.

      Example: <input type="text" name="Cc Address" size=15>

    Auto Cc - Allows you to Cc the user (as defined by the Email Address "special" field) on the generated email. Value (case sensitive) should be either "Yes" (Cc user) or "No" (don't). This field is usually type=hidden.

      Example: <input type="hidden" name="Auto Cc" value="Yes">

    Full Name - Used as the parenthetical full name in the return address of the email. This is the only special field that is returned in the results table. To exclude it (useful if you're using a predefined generic string), prepend the string "exclude;" (case sensitive, include the semicolon but not the quotes) to the value. This can be a user-entered value or a predefined generic string (e.g., "Feedback Results").

      Example (with result returned): <input type="text" name="Full Name" size=15>
      Example (with result hidden): <input type="hidden" name="Full Name" value="exclude;Form Submission">

    Email Subject Line - Specifies the subject line of the generated email message. This can be a user-entered value or a predefined generic string.

      Example: <input type="hidden" name="Email Subject Line" value="Important Feedback">

    Email HTML - Specifies whether the generated email should be sent using plain text or HTML format. Value (case sensitive) should be either "Yes" (send HTML) or "No" (don't). This field is usually type=hidden.

      Example: <input type="hidden" name="Email HTML" value="Yes">

    Background Color - Defines the background color for all pages generated by the Mail Form Handler. Any valid color name or #RRGGBB value is acceptable (for example, "white" and "#FFFFFF" both produce a white background). This field is usually type=hidden.

      Example: <input type="hidden" name="Background Color" value="blue">

    Link Color - Defines the link color for all pages generated by the Mail Form Handler. Any valid color name or #RRGGBB value is acceptable. This field is usually type=hidden.

      Example: <input type="hidden" name="Link Color" value="blue">

    ActiveLink Color - Defines the active link color for all pages generated by the Mail Form Handler. Any valid color name or #RRGGBB value is acceptable. This field is usually type=hidden.

      Example: <input type="hidden" name="ActiveLink Color" value="blue">

    VisitedLink Color - Defines the visited link color for all pages generated by the Mail Form Handler. Any valid color name or #RRGGBB value is acceptable. This field is usually type=hidden.

      Example: <input type="hidden" name="VisitedLink Color" value="blue">

    Text Color - Defines the color of the text on all pages generated by the Mail Form Handler. Any valid color name or #RRGGBB value is acceptable. This field is usually type=hidden.

      Example: <input type="hidden" name="Text Color" value="black">

    Toggle Graphics - Toggles graphics usage (Required Graphic and Graphic special fields). Value should be either "On" (graphics are used) or "Off" (graphics are not used). This field is usually type=hidden.

      Example: <input type="hidden" name="Toggle Graphics" value="Off">

    Required Graphic - Full or relative URL of the desired "required fields" graphic (generated when any required fields are not filled in). This graphic inherits any alignment properties specified by the Response Page Title special field. This graphic is only shown if the Toggle Graphics special field is set to On. This field is usually type=hidden.

      Example: <input type="hidden" name="Required Graphic" value="http://www.servername.com/imglib/some_graphic.gif">

    Graphic - Full or relative URL of the desired header graphic. Use a full URL if the Email HTML option is set to Yes. This graphic is only shown if the Toggle Graphics special field is set to On. This field is usually type=hidden.

      Example: <input type="hidden" name="Graphic" value="http://www.servername.com/imglib/some_graphic.gif">

    Magic Word - Specifying a magic word allows you to make input type=Select fields required while still having text as the first element in the drop down list (for example, "Select One"). This field is usually type=hidden.

      Example: <input type="hidden" name="Magic Word" value="Select One">

    Response Page Title - Text used for the title and heading of the results page. To center the heading elements on the page (graphic and heading text), prepend the string "center;" (case sensitive, include the semicolon but not the quotes) to the title value. Default is left aligned. This field is usually type=hidden.

      Example (default): <input type="hidden" name="Response Page Title" value="Submission Received">
      Example (centered): <input type="hidden" name="Response Page Title" value="center;Submission Received">

    Greeting - Short blurb of thanks. Use "*" in the value to denote a new paragraph (<p>) This field is usually type=hidden.

      Example: <input type="hidden" name="Greeting" value="Thanks very much for sending us your comments. We appreciate it.*Press the Back button to return to my page.">

    Return URL - Full URL to use for the link to be displayed on the results page. Note that you can include a target specification at the end of this URL (see example). You'll be disappointed if you don't use the Return Link Text special field in conjunction with this one. This field is usually type=hidden.

      Example: <input type="hidden" name="Return URL" value="http://www.servername.com/home/index.html">
      Example (with target spec): <input type="hidden" name="Return URL" value="http://www.servername.com/home/index.html target=_top">

    Return Link Text - Text to use for the link to be displayed on the results page. You'll be disappointed if you don't use the Return URL special field in conjunction with this one. This field is usually type=hidden.

      Example: <input type="hidden" name="Return Link Text" value="Return to the home page">

    Show Results - Tells the script whether to display the form values onscreen for the user when the form is submitted. Value (case sensitive) should be either "Yes" (show them) or "No" (don't). This field is usually type=hidden.

      Example: <input type="hidden" name="Show Results" value="Yes">

    Show Blanks - Tells the script whether to display form name/value pairs in the results if the value is null (blank). Value for Show Blanks (case sensitive) should be either "Yes" (show them) or "No" (don't). This field is usually type=hidden.

      Example: <input type="hidden" name="Show Blanks" value="Yes">

    Debug Flag - Tells the script to print debug information to the generated HTML response page. Value (case sensitive) should be either "Yes" (show debugs) or "No" (don't). This field is usually type=hidden and is only used for troubleshooting purposes.

      Example: <input type="hidden" name="Debug Flag" value="Yes">

Default Special Form Field Values

Default values for a particular instance of the script can be viewed by pointing at the script itself using your browser.

For example, on a server www.example.com, if the script is in a directory called /cgi-bin and the filename is mail_form_handler.cgi, you would point at http://www.example.com/cgi-bin/mail_form_handler.cgi to view the built-in help file, which includes the default values for each field.

Try it out (mail_form.pl.cgi on server www.employees.org): mail form handler built-in help file

HTTP Referer Checking

In version 4.0 and later, the script can limit form data submission to a user-specified list of domain names, IP addresses, or URLs, based on the HTTP_REFERER environment variable passed from the submitting form.

While not foolproof, this feature provides basic protection against unauthorized use of an instance of the script on your server by some third party.

HTTP referer checking is disabled by default. YOU MUST MODIFY THE SCRIPT ITSELF TO ENABLE THIS FEATURE AND MODIFY THE ALLOWED HTTP REFERER LIST. In other words, this is not a setting that is passed from the HTML form to the script. The process is pretty straightforward, and the script is well-commented to help you make the proper changes.

To enable this feature:

  1. Open the script in a text editor
  2. Find the "HTTP Referer Control Block" (it is right near the top, and pretty obviously labelled)
  3. Change the Ignore Flag value from the default value of 1 (that's the number one) to 0 (that's zero).
  4. Replace the Allowed List with the domain names, IP addresses, and/or URLs that you want to be able to submit form data to the script.
  5. Save the file.

Only referring URLs that match one of the strings you enter in the Allowed List will be permitted to submit form data to the script. Any others will receive an error message.

Make sure you include any possible alternate domain names you might want to use, and be sure to remove the "dummy" domain names and IP addresses in the script by default.

The following examples illustrate how the Allowed List might look after you modify it :

@httpAllowedList = ("host.example.com", "http://host", "example.com", "http://10.99.113.4", "http://another-host.example.com", "http://another-host/", "www.example.net", "http://example.net", "http://www.example.org/~user/files/forms/my_html_form.html");

Sending HTML Email

In version 4.0 and later, the script supports the option to send the generated email message in HTML format rather than in plain text. This is done using the HTML Email special form field.

This is pretty self-explanatory. Obviously, there are probably some security concerns about sending & receiving HTML in your email (I suggest making sure you have a virus checker on your system that detects malicious ActiveScript, Java, JavaScript, and so on).

The one gotcha with sending HTML email is that if you are using the "Graphic" special form field, make sure you specify the complete URL of the image file, not a relative location, otherwise you will see a broken image in the HTML email.

Checking Email Address Validity

In version 3.0 and later, the script checks the email address format for the Recipient Address, Email Address, and Cc Address fields. An email address is rejected if any of the following applies:

  • No @ symbol is present in the address (although in v4.0, "at" is an acceptable substitute for @)
  • More than one @ symbol is present in the address
  • The address begins or ends with the @ symbol
  • The address contains any of the following characters:
    [ ] { } < > ( ) \\ / : ; ! # \$ % ^ & * ` <space>

Anti-Spam Email Fixup

In version 4.0 and later, the script accomodates email addresses using "anti-Spam" format, that is, with the word "at" instead of the symbol "@" between the username and the domain name. This prevents email harvesters from gleaning your email address from the "Recipient Address" or "Cc Address" fields in your HTML forms.

As an example, suppose your email address is "nobody@example.com". You can use the following HTML for the "Recipient Address" field to protect your email address:

<input type="text" name="Recipient Address" value="nobody at example.com">

Specifying Required Fields

To specify a required field, use a "*" after the input tag "name" attribute -- this denotes a field that must be completed before the form will be processed. In the following example, users must fill in their phone number before the form is accepted.

    Example: <input type="text" name="Phone*" size=10>

If you are using required "select" lists (that is, <select name="some_name*"> elements where you want to force the user to make a choice), use the "*" to identify the select list as required and use the "Magic Word" hidden field to have a text line (for example, "Select One") as the default option ("option selected"). If you do not specify a Magic Word, the default option must be blank. This field would in most cases be type=hidden.

Here is an example:

    <input type="hidden" name="Magic Word" value="Select One">
    <select name="Select List*">
      <option selected>Select One
      <option>Choice One
      <option>Choice Two
      <option>Choice Three
    </select>

It is important that you specify the "Magic Word" input field ONLY ONCE in your HTML form. Specifying multiple Magic Word elements (whether using the same or different Magic Words) will return unexpected results. This means that you must use the same Magic Word throughout a given form, regardless of how many "select" lists or other multiple choice fields (radio buttons, etc) you have.

Making Radio Button input fields required is a bit kludgy, because no value is passed to the script if no radio button is selected, and if you use the "checked" attribute on one of the buttons, then the requirement for a response is satisfied! The workaround is to include a radio button that utilizes the "Magic Word" as its value. Note that you must include an asterisk (*) after the name for each radio button. Here is an example:

    <input type="hidden" name="Magic Word" value="Select One">
    <input type="radio" name="Required Radios*" value="Select One" checked>
    <input type="radio" name="Required Radios*" value="Option 1">
    <input type="radio" name="Required Radios*" value="Option 2">

Unfortunately, making Checkboxes required using the same method is even kludgier, because the user has to uncheck the Magic Word checkbox as well as check one or more other checkboxes (as opposed to the radio buttons, where only one choice is possible at any given time).

Credits

Mail Form Handler (mail_form.pl) by Tim Stevenson
Generic HTML form-processing CGI script
Send bug reports, feature requests, and other correspondence to tstevens at employees.org
Visit the Mail Form Handler home page.

ReadParse subroutine by Steven E. Brenner

This script may be distributed freely as long as this message remains intact.

Disclaimer

The Mail Form Handler is provided as-is. I shall not be held responsible for its performance, nor the manner of its use by another party, in any respect.

In addition, use of this script is subject to the Privacy & Usage Policy.

Visitor Number:

[Reset August 17, 2004]

Updated: 08/17/2004
Tim Stevenson, tstevens-at-employees.org
Privacy & Usage Policy