Using Form Mail

CCIT provides Mines students, faculty, and staff with an email processing script that allows your site to accept HTML form data and submit the results to you (or a member or your group) via email. This script can be easily implemented by adding a simple HTML form to your site, and configuring the form according to the instructions below.

Intended Audience

FormMail requires basic knowledge of HTML forms and access to a web site hosted under a Mines domain. While the FormMail script is written in Perl, the nature of the script is such that no specific Perl training is required to use it. Site owners and administrators who are unable to create an HTML form are encouraged to contact the Mines Help Center and submit a help request for FormMail assistance.

Contents

About FormMail

FormMail is a configurable Perl script that converts an HTML form submission into an email. The FormMail script can be called by anyone using Mines web services. It allows site owners to create an HTML form to gather user data, send the results to a designated email address, and direct the user to a "thank you" page, as follows:

FormMail version 3.14c1 was created by London Perl Mongers as a drop-in replacement for Matt Wright's FormMail script, with minor changes made for Mines. The FormMail README is available here.

Using FormMail on a Web Page

In order for the FormMail script to properly process HTML form data, you must create an HTML form that refers to the central FormMail script located at http://inside.mines.edu/csm-cgi-bin/FormMail.pl and, at a minimum, specify the destination email address by adding a hidden <input> form field. The example below sends an email to the address 'yourmail@mines.edu' when a user completes and submits the form:

<form method="post" action="http://inside.mines.edu/csm-cgi-bin/FormMail.pl">
  <input type="hidden" name="recipient" value="yourmail@mines.edu" />
  <input type="text" name="feedback" /><br />
  Please enter your comments<br />
  <input type="submit" />
</form>

Note that the hidden 'recipient' input field in the code above allows the page owner to indicate the desired email recipient to the FormMail script. Most of FormMail's configuration options work in the same manner. A complete account of FormMail configuration options can be found in the README file. Key configuration options (both required and optional) are listed below.

Notes:

  • Type="hidden" attributes: this information is sent to FormMail.pl and is included in the form results, but the person filling out the form will not see this information.
  • Other type attributes (eg, text, textarea, radio, etc): this information is collected from the person filling out the form and is included in the results.

Required FormMail Configuration Tags

The following tags must be present in your HTML form and properly configured in order for form data to be successfully emailed to the recipient.

  • The opening form tag must be written as follows: <form method="post" action="http://inside.mines.edu/csm-cgi-bin/FormMail.pl">
  • The following hidden input field must be present between the <form> and </form> tags: <input type="hidden" name="recipient" value="yourmail@mines.edu">. Be sure to change "yourmail@mines.edu" to the email address to which the form results should be sent.

Note that the recipient email address must be an address under the mines.edu domain (i.e.: username@mines.edu or user.name@is.mines.edu). If the recipient address is not a mines.edu address, you must open a ticket at Mines Help Center and request that your recipient email address be added to FormMail's "@recipients" array (you will need to include information about the intended URL of your web form, the purpose of your web form and information about to whom the form results are to be sent.)

Optional FormMail Configuration Tags

A few useful (but optional) FormMail configuration tags are listed below. Field names must be written in lowercase as shown. For a full list of predefined input fields, see the FormMail README file.

  • subject: Specifies the subject for the email message. For example: <input type="hidden" name="subject" value="Your Subject">
  • required: Set the value of this hidden field to the name(s) of any other form field that you would like to be required input from the person filling out the form. Separate the value names with commas. Example: <input type="hidden" name="required" value="email,realname">
  • redirect: If this value is present, the user will be redirected to the URL specified in the value attribute after a successful form submission. For example: <input type="hidden" name="redirect" value="http://www.your.domain/foo.html" /> will redirect users to http://www.your.domain/foo.html. If you don't specify a redirect URL, FormMail will automatically generate a page to indicate that the submission was successful.

In addition to the optional hidden input fields listed above, there are two non-hidden fields supported by FormMail that are also useful:

  • email: If one of the things you're asking the user to fill in is their email address and you call that input 'email', FormMail will automatically use it as the address part of the sender's email address in the email. Usage: <input type="text" name="email" value="">
  • realname: If one of the things you're asking the user to fill in is their full name and you call that input 'realname', formmail will use it as the name part of the sender's email address in the email. Usage: <input type="text" name="realname" value="">

Also note that code has been added so that the web address (URL) of the web page that calls FormMail.pl is included in the email message that is sent and on the "thank you" page that is displayed after the form has been submitted.

Sample Form

The HTML code below creates a form that uses the FormMail script to collect the following user data:

  • the user's full name
  • the user's email address
  • the user's relationship with Mines
  • a brief message

In addition, this sample form offers the following functionality:

  • an automatic redirect to a custom "thank you" page
  • a hidden field that specifies "My Form Results" as the email subject

Mines site owners and administrators may use this code to create simple forms as needed. Note that the destination email address in line two must be changed to the site owner's email address, and the correct path to your customized "thank you" page should be specified in line four.

Sample HTML form code

<form method="post" action="http://inside.mines.edu/csm-cgi-bin/FormMail.pl">
  <input type="hidden" name="recipient" value="yourmail@mines.edu" />
  <input type="hidden" name="subject" value="My Form Results" />
  <input type="hidden" name="redirect" value="thankYou.html" />

  <label>Your name:</label>
  <input type="text" name="realname" value="" /><br />

  <label>Your email address:</label>
  <input type="text" name="email" value="" /><br />

  <label>Your Mines affiliation:</label>
  <select name="affiliation">
    <option>Faculty</option>
    <option>Staff</option>
    <option>Student</option>
    <option>Other</option>
  </select><br />

  <textarea name="comment" rows="10" cols="50" wrap="virtual">
  Enter your comments here.
  </textarea><br />

  <input type="submit" value="SUBMIT" />
</form>

Sample HTML form code output

The code above yields a simple HTML form that looks like this:





Remember: In order for this sample form to function properly on your web page, the recipient address must be an address under the mines.edu domain.

EXAMPLES

Some useful non-predefined INPUT statements are:

  • <INPUT TYPE="HIDDEN" NAME="html_reference_page" VALUE="http://www.mines.edu/blah/feedback.html">
    If you set VALUE to the URL of the page that is calling FormMail.pl, you will have a reference to the calling page in the FORM results that are sent to you.