This is one of the best form mailer programs we have found. Although it appears very difficult to set up, it has withstood the test of many users who were not familiar with perl programming, and they were able to easily set this program up. Don't be intimidated! Just follow the steps.

This compiled script will allow you to make custom e-mail forms that return nicely formatted output without learning CGI programming. There are basically five steps to follow.

1. Create an e-mail template.
2. Create the HTML form.
3. Make sure the ACTION is correct.
4. Try out your form with cgiecho.
5. Go live with cgiemail.

The following steps are optional.

• Use an alternate success page.
• Make some inputs required.
• Specify formatting for some inputs.

1. Create an e-mail template.

Before you start receiving e-mail messages through the web, you should decide what these messages should look like. Create an ASCII file, called an e-mail template, that looks something like this:

To: strangeman@chasm.big HEADER LINES
Subject: questions three
blank line
What is your name? [yourname]
What is your quest? [quest] BODY
What is your favorite co lour? [color]

The template file consists of two parts, message headers and the message body. The first part is the message headers. There MUST be a To: line. Put your e-mail address there. There should also be a Subject: line. Put the subject you want the replies to have there.

Some guidelines for creating a working template.

1. Wherever you want the user of your form to supply information, use a single word inside square brackets with no spaces, e.g. Your name: [yourname]. Not [Put your name here].
2. Make sure the e-mail address in the To: field is correct.
3. If there are blank lines before the header lines, remove them.
4. Make sure all your header lines are valid. Most information should go in the message body.
5. Make sure there is a blank line between the header lines and the body.
6. If you created the file on a Mac, be sure to upload it as text, i.e. CR's translated. (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.)

Within these guidelines there is a lot of flexibility. You can put From:, [yourname], and in this case the e-mail would show it was from the name the user input in the yourname field. You can put things like Cc: info@tdl.com in the header, and a copy of the e-mail form would be sent to that e-mail address. Be creative. Just don't put anything in there you wouldn't want us administrators to see, because that's where bounced messages go.

Once you create an e-mail template, upload it to the WWW server and look at it with your WWW browser.

2. Create the HTML form.

The next step is to make the form that corresponds with the template. Here is the form that corresponds with the sample template.

Your name:

Your quest:

Your favorite colour:

(This example doesn't actually send e-mail.)

This is the HTML source:

<FORM METHOD="POST" ACTION=
"http://www.yourcompany.com/cgi-bin/cgiecho/questions3.txt">
Your name: <INPUT NAME="yourname"><p>
Your quest: <INPUT NAME="quest"><p>
Your favorite colour: <INPUT NAME="colour"><p>
<INPUT TYPE="submit" value="Send e-mail">
</FORM>

This is a very simple example. To learn to create more complicated forms, read NCSA's guide. For now, simply note that the NAME of each input corresponds to what you previously put in the e-mail template. In this example they are yourname, quest, and colour.

3. Make sure the ACTION is correct.

The trickiest part of the HTML form is getting the ACTION set correctly. To do this, you need to take the full URL of your template file, and insert the string "/cgi-bin/cgiecho" right after the servername.

So if the template file is "test.txt", and it's stored in yourcompany.com/public_html, the URL for the template file is "http://www.yourcompany.com/test.txt". You would put type this URL into the action part of your <FORM> tag, then move your cursor onto the slash after "www.yourcompany.com", and type "/cgi-bin/cgiecho". The resulting FORM command would then be

<FORM METHOD=POST ACTION="http://www.yourcompany.com/cgi-bin/cgiecho/test.txt">

The form tag for our sample questions from the strange old man guarding the bridge would be

<FORM METHOD=POST ACTION="http://www.yourcompany.com/cgi-bin/cgiecho/questions3.txt">

4. Try out your form with cgiecho.

Load your newly created form, and try it out! If it works, you should see your template, with the values you entered filled in. If some of your inputs don't seem to be showing up in the processed template, make sure that the inputs have the exact same names in the HTML form as in the ASCII template. e.g. NAME="yourname" in the HTML form and [yourname] in the e-mail template.

5. Go live with cgiemail.

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

If it works, congratulations!

Note: You will not personally get a bounced message even if you've put a From: line in your headers. All bounces will go to the user id that our web server runs as. It runs as "nobody", so that's why when you receive a message from this script, it will be from "nobody@tdl.com". If there is a mistake in the header, the message will bounce to nobody, who doesn't have a mailbox.

Optional: Use an alternate success page.

If you don't like the default page that comes up when e-mail is successfully sent, you can specify an alternate URL using a hidden variable called ``success'' in your HTML form, e.g.

<INPUT TYPE="hidden" NAME="success" VALUE="http://web.mit.edu/">

There is no way to make this alternate success page contain information the user submitted in the form. You will have to learn cgi programming to do that. :)

Optional: Make some inputs required.

If you would like to automatically reject forms with certain inputs left blank (a very useful thing to be able to do!), add the prefix ``required-'' to the name of the input in both your HTML form and your e-mail template. Here is an example:

In the HTML form:

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

In the e-mail template

Your name: [required-yourname]

Optional: Specify formatting for some inputs.

If, in your e-mail 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 new line just before the comma, even though this looks strange. For example, if Pizza wanted toppings listed one per line, they would put the following in their e-mail template:

   [%s topping]

Script courtesy of CGIEmail at MIT.

Return to support index.

Return to shell4 home.