Technical Support: FormMail.asp

ASP Form Mail

FormMail.asp uses control values taken from hidden form fields to set parameters such as the email address to send the data to, the subject text for the email, which fields are required, what order to list the fields, etc.

You can try it out on the form below. Required fields are marked with an asterisk ('*'). Leaving them blank results in an error message. When filled out correctly, the submitted form data is emailed to the address you supply below.

You might notice that the form above uses a bit of JavaScript code to copy the value you enter in the 'Email Address' field to the hidden '_recipients' field. Normally you would hard code a value for that field, but here it allows you to send the form data to yourself to see the results. See below for details on the '_recipients' field.

Using the Script

The script can be used with most forms just by adding a few hidden fields. Also, it can only be run on our NT based servers - if you unsure if your site is on our NT servers, contact us and we will advise. If you are on our Linux servers you must use FormMail.cgi. Regardless, you'll need ask xcelNet to add you to the Referrers - this is facility reserved for xcelNet Clients only.

The Post command is:

Form Setup

With the script set up on your host, you can set your forms to use it by pointing them to the script and adding some hidden fields to pass control data. The control fields are:

Field Name Description

_recipients Required. The email address to send the form to. Multiple recipients can be specified by separating addresses with commas (',').

<input name="_recipients" type="hidden" value="webmaster@abc.net"> OR <input name="_recipients" type="hidden" value="sales@xyz.com, orders@xyz.com">

_replyTo An email address that will be used in the Reply To header of the email.

<input name="_replyTo" type="hidden" value="techsupt@xyz.com">

_replyToField Like _replyTo except that you specify the name of another field on the form. Generally, you'd use the name of a field that asks for the user's email address. Then, the email would have a Reply To header set to the user's address and you could easily reply to whoever submitted the form.

<input name="_replyToField" type="hidden" value="Email"> ... Your email address: <input name="Email" type="text" size=20>

Email The field Email must be used to capture the Email Address of whoever submitted the form. The _replyToField will use this field. If you use a different field other than Email (ie a different syntax; e.g. EmailAddress or emailaddr etc) then the script will assume that Email=guest@xcelnet.com.au
Your email address: <input name="Email" type="text" size=20>

_subject Specifies the text to use in the email subject line.

<input name="_subject" type="hidden" value="Site Feedback">

_requiredFields A comma-deliminated list of field names that should be checked for a value. Any missing values causes an error message to be displayed and the form will not be submitted.

<input name="_requiredFields" type="hidden" value="Name, Address, City, State, Zip Code, Email">

_fieldOrder A comma-deliminated list of field names. When building the email, the fields and values will be displayed in the order specified here. Note, if you use this option, you must specify the names for all form fields you want sent.

<input name="_fieldOrder" type="hidden" value="Name, Email, Phone, Address, City, State, Zip Code">

If no order is specified, the fields will be displayed in the same order as they appear in the form request. Usually, this is the same order that they appear in on the page.

_envars A comma-deliminated list of environment variable names. All server-side scripts have access to a set of variables set either by the host or in the request from the user. These describe various host settings and information about the client browser.

<input name="_envars" type="hidden" value="HTTP_REFERER, HTTP_USER_AGENT, REMOTE_ADDR">

These can be useful for diagnostic information by telling you where the user came from or what browser he or she is using. You can use any of the names in this list.

_redirect Normally when the form has been submitted and the email sent without any errors the script will display a thank you message along with the form data. You can change this by specifying the URL of another page in this field and the user will be sent there instead.

<input name="_redirect" type="hidden" value="termsofservice.html">

You should note that, except for the above, any field name starting with an underscore ('_') character is ignored. This allows you to customize the script by adding your own control fields.

Also, although you can use spaces within a field name, you should avoid using them at the start or end of any name. The script tends to strip leading and trailing spaces when processing field names. Also avoid using commas (',') as these are used to deliminate multiple values in control fields.

How it Works

The script is really fairly simple, it's the number of options that add to the length of the code.

Basically, it follows this outline to check for errors. Anytime an error is found, a message is added to a list.

Check the referring URL against the referer list.

Make sure a recipient or recipients are specified.

If any required fields are defined, check each one to make sure a value was given.

Process the other control fields to set the field display order and email parameters.

If no errors were found, build and send the email. Otherwise, display a list of the accumulated error messages.

If the email was successfully sent, display a page showing the form data received (or redirect to another page if one was specified).

To help prevent errors in sending the email, all email addresses are checked for proper syntax. Likewise, if an error occurs in sending the email, a message is generated and the resulting page informs the user of the problem.

Note that possible errors in sending email will vary depending on the component used and on individual host settings. For example, the default CDONTS component included with IIS never returns an error, it simply acts as though the process succeeded normally. ASPMail and JMail, however, do return an error code along with a descriptive text message. Check the documentation for your specific component and with your host provider to diagnose any problems.

Some points of interest in the code are described below.

Parsing Multiple Values

For control fields that allow multiple values such as _recipients or _requiredFields, the script uses the built in Split() function to create an array of values from a single string. These arrays can then be used in loops to check or process each individual value.

Getting the Field Order

Also of note, when no specific field order is given, we want to display the fields in the order they arrive at in the form request header. This is usually the order in which the individual form tags appear in the HTML page.

All fields and values are taken from the Request.Form collection. So you would think that a simple 'for each' loop like this

  for each name in Request.Form
    Response.Write(name & ": " & Request.Form(name) & vbCrLf)
  next

would display them in that order. However, looping through a collection in ASP with this method does not necessarily keep the order. But accessing the collection as an array like this

  for i = 1 to Request.Form.Count
    Response.Write(Request.Form(i) & vbCrLf)
  next

will keep the proper order. The problem is, the field name is lost. The FormFieldOrder() function fixes that by looping through the collection as an array, and in an inner loop, uses the 'for each' method to match the name to the array index.

In the end, it returns an array of field names in the proper order. This array is then used to loop through the form field collection and retrieve the names and values in order.

Creating and Sending the Email

The email note generated uses HTML tags for formatting to make it look better. Most email clients support this as do the three email components the script is designed to use. It's just a matter of setting an option or two to create the proper email header.

To ensure you have the Latest Information, Click Here to Refresh this Page