Form-to-Mail Processing Script Tutorial

This page describes how to access the HTML form-to-mail processing scripts available to CIX Internet subscribers and covers the design of forms to take advantage of these scripts.

HTML Forms Processing

The formmail scripts can be used as universal WWW form -> Email gateways. Each script allows you to receive the data entered in any of your form designs via email, in a choice of three formats.

There are just a few requirements that your HTML form designs must fulfil, in order for them to work properly.

Always be sure to test your form with the post-query script prior to making it publicly accessible.

Undertanding the Basics

There is some sample HTML code further down. Before we plunge into the code, it's important to know how to access the scripts, how to test your form safely, and which field names to use in your own forms, if you plan to use them.

Accessing the Scripts

Most importantly, the action of your form needs to point towards one of these scripts and the method must be POST, so begin your form with one of the following lines depending on whether you are testing or choosing the email format you require:

Testing your form: <FORM ACTION="/cgi-bin/post-query" METHOD="POST">
Verbose format: <FORM ACTION="/cgi-bin/formmail.pl" METHOD="POST">
CSV with field names and corresponding data format: <FORM ACTION="/cgi-bin/formmailcsv.pl" METHOD="POST">
CSV data only format: <FORM ACTION="/cgi-bin/formmailcsvd.pl" METHOD="POST">

Testing your form

Before you go ahead and start using your form to generate email, you should always check that the data actually being sent from it is what you intend it to be.

There is a script provided for this purpose:

<FORM ACTION="/cgi-bin/post-query" METHOD="POST">

which doesn't send any mail anywhere, but merely echoes your defined field names and submitted data back to your browser. While you are testing your form, it is the script you should use to avoid excessive amounts of test email being generated.

The post-query script doesn't care what field names you define, and so can be used to test forms other than those designed to use the formmail scripts.

The sample form further down is set up to use the post-query script, so you can see how it works.

Field Names

In any form that uses one of the formmail scripts, the following field names have special meanings. If you define or use these particular field names other than described below, your form will not work properly, if at all.

recipient*, subject, email, realname, redirect

*this field is required, the other four are optional.

If you use an illegal or incorrect value for recipient - no mail is sent and a warning page is displayed.

You can have your own additional fields in your form as you wish.

Field Definitions

Required Field

recipient: This is who the form's contents will be sent to after they have been decoded, etc. You should use a hidden field type for this field:; <input type=hidden name="recipient" value="someuser@yourhostname">; This field is necessary if you want your form contents to be sent anywhere, without this field the form will not work. Make sure you get the address correct.

Having defined at least this field, you can have any other fields in your form that you wish. Of the 4 optional fields below, the first 3 are recommended and the last is suggested:

Other Fields

subject

This will relay the subject of your form to the script. You should also use a hidden field type for this field:

<input type=hidden name="subject" value="Your Subject Line">

The subject field value will appear as the subject in your mail. You can allow respondents to type in the subject simply by taking out the value="..." section and changing type=hidden to type=text in the above example.

email

This is for the respondent to enter their email address. Use a regular text input for this one.

<input type=text name="email">

This field is helpful if you want to be able to reply.

realname

This one is so the respondent can enter their real name. Use a regular text field for this one also:

<input type=text name="realname">

It's nice to have this in your email message, though not essential.

redirect

This field should only be used if you want to redirect the respondent's browser to a different URL when they are done completing the form. The type should be hidden and the URL should be placed in the value="..." attribute.

<input type=hidden name="redirect" value="URL">

This feature replaces the default response telling them what data they submitted. The email is generated whether or not there is a redirect field.

IMPORTANT - The redirect URL must be fully specified, ie of the form:

http://serveraddress/the/path/to/filename.html

If you are a CIX Internet subscriber, this would therefore need to look something like this:

http://www.compulink.co.uk/~hostname/path/to/filename.html

where hostname is your CIX Internet hostname, and path/to/ is needed only if your form response page filename.html isn't in the top level of your personal www directory.

Of course, you can specify any redirect URL you like - it doesn't have to be to somewhere resident on CIX's Webserver eg:

http://www.yahoo.com/Computers_and_Internet/
http://www.apple.com/documents/aboutapple.html

are also valid.

Sample HTML Code

The example of the mail output format for each script name was produced from the following HTML code. You will need to substitute the script name, a suitable someuser@yourhostname for your site, a relevant Subject Line and a redirect URL if you copy this code as an example:

<HTML> 
<HEAD>
<TITLE>
Form to generate sample output
</TITLE>
</HEAD> 
<BODY>
<FORM ACTION="/cgi-bin/post-query" METHOD="POST">
<!--                   ^^^^^^^^^^
                      script name

Substitute the script name accordingly, above
post-query      - for echoing values back while testing
formmail.pl     - verbose email
formmailcsv.pl  - csv field names and data email
formmailcsvd.pl - csv data only email
-->
<INPUT TYPE="hidden" NAME="recipient" VALUE="someuser@yourhostname">
<INPUT TYPE="hidden" NAME="subject" VALUE="Your Subject Line">
<INPUT TYPE="hidden" NAME="redirect" VALUE="URL">
<!--
Substitute for your required values above, for these hidden fields
-->

What's your name?<BR>
<INPUT TYPE="text" NAME="realname" SIZE=40 VALUE="Your Name"><P>

What's your address?<BR>
<INPUT TYPE="text" NAME="email" SIZE=50 VALUE="user@address"><P>

What's your phone number?<BR>
<INPUT TYPE="text" NAME="Phone number" SIZE=20><P>

Do you know?
Yes<INPUT TYPE="radio" NAME="Illuminati?" VALUE="Yes"> No
<INPUT TYPE="radio" NAME="Illuminati?" VALUE="No" CHECKED><P>

You can tell us if you want to<BR>
<TEXTAREA NAME="Comments" ROWS=10 COLS=50></TEXTAREA><P>

<INPUT TYPE="submit" VALUE="Send this information">
<INPUT TYPE="reset" VALUE="Clear Form"></FORM>
</BODY> 
</HTML>

Mail Output Format

There are three formats available. The body of the email (shown between the =========) is sent as unwrapped text. Each of these was generated by the example form.:

Verbose

Use the formmail.pl script:

<FORM ACTION="/cgi-bin/formmail.pl" METHOD="POST">

=========================================================
Date: Wed, 1 Nov 95 21:00:57 GMT
To: someuser@yourhostname
From: nobody@compulink.co.uk (CIX Internet WebForm Response)
Subject: Your Subject Line

Below is the result of your feedback form.

It was submitted by:

Mr. X (mrx@nowhere.com) on
Wed Nov  1 21:00:57 GMT 1995

---------------------------------------------------------

Phone number:
555 2323

Illuminati?:
Yes

Comments:
Maybe I'll tell you tomorrow.

---------------------------------------------------------
=========================================================

CSV with field names and corresponding data

Use the formmailcsv.pl script:

<FORM ACTION="/cgi-bin/formmailcsv.pl" METHOD="POST">

=========================================================
Date: Wed, 1 Nov 95 21:09:22 GMT
To: someuser@yourhostname
From: nobody@compulink.co.uk (CIX Internet WebForm Response)
Subject: Your Subject Line

realname,email,Phone number,Illuminati?,Comments
Mr. X,mrx@nowhere.com,555 2323,Yes,Maybe I'll tell you tomorrow.
=========================================================

CSV data only

Use the formmailcsvd.pl script:

<FORM ACTION="/cgi-bin/formmailcsvd.pl" METHOD="POST">

=========================================================
Date: Wed, 1 Nov 95 21:09:22 GMT
To: someuser@yourhostname
From: nobody@compulink.co.uk (CIX Internet WebForm Response)
Subject: Your Subject Line

Mr. X,mrx@nowhere.com,555 2323,Yes,Maybe I'll tell you tomorrow.
=========================================================

Example Form

This is the form that the sample HTML code produces.

This form is shown for illustrative purposes. It is set up to submit the data to the script post-query. No mail is sent by this script, it is used purely to echo the field names and data back to your browser, for testing purposes. When you're sure you have your own form set up correctly, change the script name to one of the formmail ones to enable it.

Go to the Tutorial Index.