CGIemail is a script that allows you to send the contents of a form to an email address. While it can make the results look a little bit nicer than Formmail, it is considerably more difficult to set up than Formmail.

You can learn more about CGI E-mail in the CGI E-mail User Guide .

This guide will help you write a WWW form that sends an e-mail message to you. The following steps are required:

1. Create an e-mail template.
2. Put a link to the template on your page.
3. Decide if a mailto: link will do.
4. Create the HTML form.
5. Create more advanced HTML forms.
6. Make sure the ACTION is correct.
7. Try out your form with cgiecho.
8. Go live with cgiemail.
9. Debug if you don't get mail

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 a plain text file, called an e-mail template, that looks something like this:

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 also be used by the cgiemail program, so before you upload the file to the server, be careful to follow these guidelines:

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 address in the To: field is correct.
3. If there are blank lines among the header lines, remove them.
4. If there are blank lines before the header lines, remove them.
5. Make sure all your header lines are valid. The first character on the line must be a letter. Most information should go in the message body; don't make up your own headers.
6. Make sure there is a blank line between the header lines and the body.
7. Make sure you save it as ASCII text. For example, if you are using Microsoft Word, use "Save As" and choose "Text Only with Line Breaks."
8. 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 Bcc:, 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 your webmaster to see, because that's where bounced messages go.

Now go ahead and upload your e-mail template to the server and look at it with your browser.

2. Put a link to the template on your page.

Here's an example:

3. Decide if a mailto: link will do.

Already, without any complicated HTML, you have a way for people on the Web to send you the information you want. Before you go to the effort of making an HTML form, decide if it's really worth it. Forms on the Web have two particular disadvantages:

1. You will get a lot of frivolous e-mail from people who are merely ``surfing the web.''
2. The user's e-mail address is typed manually, and is often mistyped, so that you have no way to reply. This is less of a problem with mailto: links.

4. Create the HTML form.

If you've decided to create an HTML form, you need to give people a way to supply an e-mail address. With the mailto: link, their mailer would supply the From: address for them. But now you need to add a line to the top of your e-mail template like this:

From: [email]

Here is an example HTML form.

Your e-mail address:
Your name:
Your quest:
Your favorite color:

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

This is a very simple example. Note that the NAME of each input corresponds to what you previously put in the e-mail template. In this example they are email, yourname, quest, and color. This is the key concept in using cgiemail. Be careful to make them exactly the same; if you put NAME="color" in your HTML form and [color] (note the spelling difference) in your e-mail template, the input will not show up in the e-mail.

5. Create more advanced HTML forms.

To learn to create more complicated forms, read an HTML book. All of their example forms can be converted to cgiemail forms merely by changing the ACTION. Unlike other forms-to-email programs, you are not required to use hidden inputs with special names.

All types of inputs (radio buttons, etc.) work the same way. Each input needs a NAME, and that name must appear within square brackets in your e-mail template. It's that simple.

6. Make sure the ACTION is correct.

The trickiest part of the HTML form is getting the ACTION set correctly. Start with the URL of your e-mail template, then split it into two parts, e.g.

http://www.yourdomain.com/questions.txt
`----- Part 1 ------------------------'`---Part 2---'

First type the URL of your e-mail template into a web browser and make sure it's correct. Then put the script name in the middle. Usually this is ``/cgi-bin/cgiecho'' Thus, ACTION looks like this:

http://www.yourdomain.com/cgi-bin/cgiecho/questions.txt
`------- Part 1 ---------------------'----script name------`-- Part 2 --'

For simplicity, you may leave out part 1, but you must include it if you want to test your form as a local file. If you don't know what that means, just feel free to omit part 1.

7. Try out your form with cgiecho.

Put your form into your favorite browser, fill in the inputs, 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 is probably set wrong. Go back to the previous step.

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 template. E.g. NAME="yourname" in the HTML form and [yourname] in the e-mail template.

8. 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 you get a success page but don't receive mail, there is some problem with your template file. Go back and make sure you correctly followed the guidelines in step 1.

If it works, congratulations!

9. Debug if you don't get mail

Normally, mail gets sent asynchronously, meaning it goes into a queue to be sent at a convenient time. Asynchronous mail is sent more efficiently and reliably, but has the disadvantage that problems can only be reported by mailing an error message back to the sender. To the mail system, it appears that the sender of the mail is the web server, so the error message won't get to you.

If you are getting a success message but aren't getting mail, you can temporarily use synchronous mail delivery by creating a hidden input named cgiemail-mailopt and giving it a value containing "sync", e.g.

<INPUT TYPE="hidden" NAME="cgiemail-mailopt" VALUE="sync">

Be sure to remove this variable when you are done debugging, because it slows things down for the end user and possibly for the mail system.

Add to Favourites

Print this Article