Form-to-mail script

Netwood provides an ASP script for mailing the contents of Web Forms. It includes HTML call-able input checking routines that allow you to require the submitted data meet certain requirements - all through hidden form elements. All configuration for the script is taken from the form input. This makes it highly portable and extremely useful for applications that would otherwise require multiple scripts. The fundamental power of aspmail.asp is that it lets each form specify error-checking routine calls from within the HTML and each form can completely control the format of the email message from directives in the HTML. Below are the different configuration options for the script. You don't have to use all of them to get the script to run with your form. In fact, only one variable is required which is RECIPIENT. You run the script from your form with the following HTML tag:

<form method=POST action="http://www2.netwood.net/cgi-bin/aspmail.asp">
<input type=hidden name=RECIPIENT value="username@mydomain.com">

The above is the minimum configuration needed to run the script.

Additional configuration

The script has 5 types of configuration options. They are: mailer, info, email-formatting, error-checking, and confirmation message directives. NOTE: All directives are CASE SENSITIVE. That means that "SUBJECT" and "Subject" are NOT the same. Once you have added the necessary configuration directives (between the opening <FORM> tag and the closing </FORM> tag) build your web form just as you normally would. The format and a basic description for each type is displayed below:

MAILER DIRECTIVES:

The following directives control the mailer: (RECIPIENT, THANKURL, SUBJECT, FROMADDRESS). Only RECIPIENT is required. All others SHOULD be used, since otherwise the code uses internal defaults that may not be what you desire. The format for these directives is below:

<input type="hidden" name=RECIPIENT value="">
<input type="hidden" name=THANKURL value="">
<input type="hidden" name=SUBJECT value="">
<input type="hidden" name=FROMADDRESS value="">

The FROMADDRESS directive will be processed specially if it contains a dollar sign('$'). You can refer to the contents of another field by setting the value of FROMADDRESS to be a dollar sign followed by the name of another field. Caveats on the format of the field names are discussed below in the section on email formatting directives.

The following chart shows the type of data that must be used for each directive:

RECIPIENT = email address
THANKURL = URL
SUBJECT = Text
FROMADDRESS = email address or $field_name

INFO DIRECTIVES

The following directive controls whether or not to send additional information regarding the browser used when the form was submitted:(BROWSER_INFO). The format for this directive is below:

<input type="hidden" name="BROWSER_INFO" value="optional variable list">

This directive behaves like an advanced on/off switch. If the directive is not present, then the information about the visitors browser and IP address information (basically, the environment variables available to the aspmail.asp script) will not be sent. If you simply specify the BROWSER_INFO directive without any variable names, then all the information about the visitors browser will be sent. You can choose which values you wish to get in the email by specifying them as a comma separated list in the value portion of the BROWSER_INFO directive. The example below will only report the name of the remote host, and the official browser type they are using:

<input type="hidden" name="BROWSER_INFO" value="REMOTE_HOST,HTTP_USER_AGENT">

EMAIL-FORMATTING DIRECTIVES

The following directives control the formatting of the email message generated:
(SEPARATOR, ALPHA_SORT, SUPPRESS_EMPTY, FORMAT).
The SEPARATOR directive is used to define the Text which separates the Field Name from the Field Value in the generated email message. The format for this directive is below:

<input type="hidden" name=SEPARATOR value=" = ">

Where the value is a Text string to use as the new separator. If this directive is not defined in the form, then the script defaults to ": " as the delimiter. Output using the default would appear as: Field_Name: Data from form

The ALPHA_SORT directive controls the order of the Fields in the generated email message. The format for this directive is below:

<input type="hidden" name=ALPHA_SORT value= "">

If this directive is not used, the fields will be in the order in which they appear in the form. If this directive is used, the sorting will be done alpha-numerically. The SUPPRESS_EMPTY directive causes the script to omit any empty fields from the generated email message. The format for this directive is below:

<input type="hidden" name=SUPPRESS_EMPTY>

It also behaves as a switch. If you wish to receive all fields including empty ones, do not use this directive.

The FORMAT directive allows you to completely control the email. Using the FORMAT directive requires you to name your fields with only letters, numbers, and underscores in the name. Also, the first character in the field name must be a letter or an underscore. If your fields are named properly then you can use the FORMAT directive. The value for the FORMAT directive is the entire body of the email message you wish to send. The data from each of the fields in your form is available in the FORMAT as '$<fieldname>'. For example: if you have a field named 'first_name', to use the data from the 'first_name' field in the email, use '$first_name' in the FORMAT. Below is a sample FORMAT for a form that has 3 fields, 'your_name', 'your_addr', 'comments'.

<input type="hidden" name=FORMAT value=$your_name, at $your_addr wrote us some comments. Their comments are: $comments.

We need to make sure that we take care of this for them.>

The references to '$your_name', '$your_addr', and '$comments' will be replaced in the email sent by the values entered by the visitor into the fields, 'your_name', 'your_addr', and 'comments', respectively.

ERROR-CHECKING DIRECTIVES

The following directives control the error-checking activities of aspmail.asp: (EMAIL, ZIP, SELECT, NONUM, NUMONLY, LETTERONLY, NOTBLANK).

The general format for all but the SELECT directive is:

<input type="hidden" name="CHECK:DIRECTIVE:FIELD_NAME">

Where 'DIRECTIVE' is one of the directives listed above (with the exception of the SELECT directive). The format for the SELECT directive is:

<input type="hidden" name="CHECK:SELECT:FIELD_NAME" value="...">

Where the contents of the value field is the select option you do not wish to allow.

Examples of error-checking directives:

<input type="hidden" name="CHECK:NOTBLANK:name">
<input type="hidden" name="CHECK:EMAIL:email_address">
<input type="hidden" name="CHECK:NUMONLY:age">
<input type="hidden" name="CHECK:NONUM:color">
<input type="hidden" name="CHECK:NOTBLANK:color">
<input type="hidden" name="CHECK:LETTERONLY:state">
<input type="hidden" name="CHECK:NOTBLANK:state">
<input type="hidden" name="CHECK:ZIP:zipcode">
<input type="hidden" name="CHECK:NOTBLANK:zipcode">
<input type="hidden" name="CHECK:SELECT:types_avail" value="Choose one">

Where "name", "email_address", "age", "color", "state", "zipcode", "types_avail", are fields that you wish to have the user fill out.

Fields can have multiple error-checking directives applied to them, as the above example illustrates. One excellent example is the "age" field referenced. In the directives above, we won't require that the user tell us their age, but we will require them to give us their age in numbers only if they choose to tell us.

CONFIRMATION MESSAGE DIRECTIVES

The following directives control whether or not a confirmation message is to be set automatically to the visitor who filled out the form: (CONFIRM_RECIPIENT, CONFIRM_MESSAGE, CONFIRM_FROMADDRESS, CONFIRM_SUBJECT). These directives behave much like their MAILER directive counterparts, with a few notable exceptions. Each of the CONFIRMATION directives is parsed to check for references to other field names (see the section on the FORMAT directive). This allows you to have an automatically generated response go straight to the email address submitted by the visitor. The CONFIRM_RECIPIENT directive defines the address that will receive the confirmation email. The CONFIRM_FROMADDRESS directive defines the address the confirmation email will come from (the From: <address> in the recipients email client). The CONFIRM_SUBJECT directive defines the subject of the confirmation email. And, the CONFIRM_MESSAGE directive is the message which will be sent as a confirmation. The value of CONFIRM_MESSAGE is processed in exactly the same way that the FORMAT directive's value is.

This example sends a brief "your order was received" type reply to the visitor of a mythical form.

<input type=hidden name=CONFIRM_RECIPIENT value="$email_address">
<input type=hidden name=CONFIRM_SUBJECT value="Your order received">
<input type=hidden name=CONFIRM_FROMADDRESS value="bob@what.orgt ">
<input type=hidden name=CONFIRM_MESSAGE value="$name, thank you for your order, of $quantity gadgets. We value your business.">