Here are some nifty options for the advanced user:

• Use an alternate success and failure pages.
• Make some inputs required.
• Specify formatting for some inputs.
• Secure server.

1. Create an email template.

Before you start receiving email messages through a web form, you should decide what these messages should look like. Create an ASCII/text file, called an email template, that looks something like this:

To: webhelp@earthlink.net From: mymailform@earthlink.net Subject: Form Response Your name: [yourname] Your email address: [youremail] Your favorite color: [color]

We will call this file results.txt in our example. In one sense, this template is free-form. People who want to send you e-mail can download this template, fill it out, and mail it to you. However, the template will be used by the cgiemail program in this case, so be careful to follow these guidelines:

• Wherever you want the user of your form to supply information, use a single word inside square brackets with no spaces; for example, Your name: [yourname]. Not [Put your name here.].
• In our example results.txt, the first three lines are the header. For security reasons, do not include any variables (bracketed words) in any of header items, which should consist of nothing other than the following items:
  • To:
  • From:
  • Subject:
• Make sure the e-mail address in the To: field is correct. This is the e-mail address where you want the users to send the form submissions.
• Make sure the e-mail address in the From: field is correct. This is the e-mail address that you want the email to be from. You may wish to use this address to filter incoming emails that originated from your form. For security reasons, do not use a variable name for the "From:" header.
• Remove any blank lines before or among the header lines.
• Make sure there is one blank line between the header and the body.
• If you created the file on a Mac, be sure to upload it as text. (Unix computers have different codes denoting the end of a line than Mac's do, so your file might look like one long line to the Unix computer if you do not upload it as a text file.)

Now upload your email template to your web hosting account somewhere in the "www/" directory and look at it with your web browser to check that it was uploaded.

You do not need to locate your template file in your "cgi-bin/" directory!

2. Create the HTML form.

Here is an example:

Your name:
Your email address:
Your favorite color:

(This example doesn't actually send email.)

This is the HTML source:

<FORM method="post" ACTION="/cgi-bin/cgiecho/webhelp/features/cgiemail/emailresults.txt"> Your name: <input NAME="yourname"><br> Your email address: <input NAME="youremail"><br> Your favorite color: <input NAME="color"><p> <input type="submit" value="Send email"> </FORM>

This is a very simple example. For more information about creating forms in HTML, see http://help.mindspring.com/webhelp/features/cgiemail/forms.htm

Note that the NAME of each input corresponds to what you previously put in the email template. In this example they are yourname, youremail, and color.

3. Make sure the ACTION is correct.

We will first test the form with a program called cgiecho. cgiecho does exactly the same thing as cgiemail, except it will not send the actual email. When the form works with cgiecho, we will move on to cgiemail.

In our example, the template file results.txt is located in our "www/features/emailforms/" directory. Therefore, our action line is:

ACTION="/cgi-bin/cgiecho/features/emailforms/results.txt".

If we were to relocate our results.txt to our "www/" directory, the action line would be:

ACTION="/cgi-bin/cgiecho/results.txt"

So, if you placed your template file in your "www/" directory, you would use the following FORM tag:

<FORM method="post" ACTION="/cgi-bin/cgiecho/template file">

Don't forget to replace template file with your template file name!

4. Upload the proper cgi's

You already have files called "cgiecho" and "cgiemail" in your cgi-bin directory - these were installed for you when your account was created. If for some reason they are not there, please install them using the directions below:

• Download cgiecho and cgiemail from our ftp site *in binary mode*.
• Upload them to your cgi-bin directory *in binary mode*.
• Change the permissions on these files to 755.

5. Try out your form with cgiecho.

After you uploaded your HTML form to your web hosting account, view it in your web browser, fill in all the fields, and submit it. You should see what the processed form looks like. If instead you see an error with a number near 500, your ACTION may be incorrect. Go back to the previous step. Also, you may have written or uploaded your template file incorrectly. Go back to step 1.

If some of your inputs don't seem to be showing up in the processed form, make sure that the inputs have the exact same names in the HTML form as in the ASCII/text template file. For example, NAME="yourname" in the HTML form and [yourname] in the email template.

6. Go live with cgiemail.

Now change cgiecho to cgiemail in the ACTION of your HTML form. Try it out. You should receive an email message with the processed form. If not, go back and make sure you correctly followed the instructions in step 1.

If it works, congratulations!

Here is our example in action:

Your name:
Your email address:
Your favorite color:

(This example will send the email to you.)

This is the HTML source:

<FORM method="post" ACTION="/cgi-bin/cgiemail/features/emailforms/emailresults.txt"> Your name: <input NAME="yourname"><br> Your email address: <input NAME="required-youremail"><br> Your favorite color: <input NAME="color"><p> <input type="submit" value="Send email"> </FORM>

For more info on cgiemail look at the official cgiemail home page.

To access the cgiemail tool

The Email Form tool will appear in the lower frame of your web browser window. Click the Install button, then fill out the form that appears in your browser window to put a generic email form on your site.

Advanced Cgiemail Options

Optional: Use alternate success and failure pages.

If you don't like the default page that comes up when email is successfully sent, or if there is a problem when sending email, you can specify an alternate URL using hidden variables called "success'' and "failure" in your HTML form.

Note: The URL must be a full URL, starting with ``http://''
Examples:

<INPUT TYPE="hidden" NAME="success" VALUE="http://www.mydomain.com/success_yay.htm">

<INPUT TYPE="hidden" NAME="failure" VALUE="http://www.mydomain.com/failure_boo.htm">

Optional: Make some inputs required.

If you would like to automatically reject forms with certain inputs left blank, add the prefix ``required-'' to the name of the input in both your HTML form and your email template. Here is an example:

In the HTML form:

Your name: <INPUT NAME="required-yourname">

In the email template

Your name:      [required-yourname]

Optional: Specify formatting for some inputs.

If, in your email template, the text inside square brackets begins with %, cgiemail will use the printf() function in C on the field name after the comma. If you're not familiar with this function, look in a book on C. If you are familiar with it, please note these two differences:

1. The first character in the format string must be %.
2. Characters like \n and \t must be literal. If you want a newline, you have to put a newline just before the comma, even though this looks strange.

Optional: Use cgiemail on the secure server.

You can use cgiemail to send the input of a secure form to you, but please note that the email is unencrypted once it leaves the secure server.