The TDL cgiemail user guide

The TDL Generic Form Mailer user guide

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.

Create an e-mail template.
Create the HTML form.
Make sure the ACTION is correct.
Try out your form with cgiecho.
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 favourite colour?  [colour]

The template file consists of two parts. The first part is the message headers. There MUST be a To: line. Put your email 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.

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].
Make sure the address in the To: field is correct.
If there are blank lines among the header lines, remove them.
If there are blank lines before the header lines, remove them.
Make sure all your header lines are valid. Most information should go in the message body.
Make sure there is a blank line between the header lines and the body.
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.)

If a file works with cgiecho, but gives you a server error with cgiemail, that means your mail header is invalid. Common reasons for invalid headers are

Forgetting to put a blank line after the headers.
Indenting the headers. They MUST start in the first column.
Capitalization and/or punctuation errors in the header.
If you put user supplied data in the header, then if the user puts in an invalid e-mail address, this can cause an error.
You did not upload it with CRs translated from your Macintosh and our server thinks it's all one line. Don't count on FTP programs to get this right, even if you upload as text. If you need to, get an editor that can produce msdos style text, which will transfer correctly with a text upload.

Within these guidelines there is a lot of flexibility. You can put From:, X-Face:, or any other header in the headers. You can put things like Cc: [yourname] in the headers. Be creative. Just don't put anything in there you wouldn't want us administrators to see, because that's where bounced messages go.

Now go ahead and upload your e-mail template 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 favourite colour:

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

This is the HTML source:

<FORM METHOD="POST"ACTION="http://www.tdl.com/cgi-bin/cgiecho/~crc/questions3.txt">
Your name: <INPUT NAME="yourname"><p>
Your quest: <INPUT NAME="quest"><p>
Your favourite 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.

Note for virtuals. The correct reference for you will have no ~username in it. Instead, the proper way to call the script is http://www.yourdomain.com/cgi-bin/cgiecho/file.txt, assuming your file is in public_html. Substitute your domain for "yourdomain.com" and the filename of your template for "file.txt".

So if the template file is "test.txt", and it's stored in ~crc/public_html, the URL for the template file is "http://www.tdl.com/~crc/test.txt". You would put type this URL into the action part of your

tag, then move your cursor onto the slash after "www.tdl.com", and type "/cgi-bin/cgiecho". The resulting FORM command would then be

<FORM METHOD=POST
ACTION="http://www.tdl.com/cgi-bin/cgiecho/~crc/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.tdl.com/cgi-bin/cgiecho/~crc/questions3.txt">

4. Try out your form with cgiecho.

Just 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, or you get an Error 500, 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 email 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:

The first character in the format string must be %.
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. 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.

Back to Support Page