Configuring and Using CGIEmail

Configuring and Using CGIEmail

What is CGIEmail?

CGIEmail is another form processing script, totally different than FormMail. It is a program written in the C language that takes the contents of fill-in boxes on a form and emails them to a specified location. In addition to the form specification in the .html file, a mail specification in a .txt file is required to format the resulting email message.

How do I use it?

Cgiemail is usually in the cgi-bin directory of your server. You need to have an action in your order.htm file to call it. It should look like this:

<form method=post action=”http://www.yourdomain.com/cgi-bin/cgiemail/order.txt”>

Note: If you wish to use CGIEMAIL on a secure server please see the special instructions.

order.htm

Look for a file in your www directory called order.htm. This is our example form we put on your site that shows how a form should be configured to work with CGIEmail. Look at it in a browser, and download it to your hard drive using FTP so you can see how it works. If you’ve never dealt with HTML forms before, don’t worry, they’re easy to create and understand.

The form prompts the user for data which is sent to the server as simple key-value pairs. Each <INPUT> tag specifies a record. The key is given by thename attribute, and the value is given by the value attribute. The type attribute tells the browser what kind of data to expect. Now, try looking at the example.

Please note that the hidden items are used to transmit critical info to CGIEmail. They provide the location of the success file, the name of the person the results should be sent to, and the subject of the form. When making your own forms, you may want to change the email address in the required-tofield, and likely the subject in the subject field. The first item tells CGIEmail what to show the user after successfully completing the form. You can, but don’t need to customize this.

After that come the items that are actually presented to the user. You’ll want to use type=text input items with cgiemail: it’s a simple tool. The size=60tells the browser how big to make the box. The name=something is required in each input tag, otherwise the browser wouldn’t know how to send the data to the server. The value=”” attribute is correct in most cases, unless you want a default value in the form.

Note that if a field begins with required-, cgiemail will require that the user enter a value for this field. This is particularly useful if you want to require a user to submit their email address.

When the user presses the Submit button, the data goes to our machine where cgiemail starts doing something with it. What is does is controlled by the order.txt file discussed below.

By the way, you can name your HTML form anything you want to.

order.txt

Now that we have all this data, what do we do with it? Mail it, of course! But for flexibility, cgiemail requires that you create a mail file to show it what to send. (If you didn’t want flexibility you’d use a mailto link.) The program will read this file, perform substitutions, and pass it to the mail system. In our example, the mail file is named order.txt, but you can name it anything you want.

Make sure that you upload your mail file in ASCII mode. Failure to upload in ASCII mode will generate the message: “Server Error: The server encountered an internal error or misconfiguration and was unable to complete your request.” There is already an example order.txt document in the forms directory in your www directory ( http://yourdomain.com/forms/order.txt).

Note that the first several lines are mail headers. You probably shouldn’t change that part, or the corresponding parts in your form. In particular, there must be a To: header or the mail won’t go anywhere!

What cgiemail does is simply replace every string that looks like [key] with the value the user typed into the field with name=key. That’s all. You can lay out your form as is best for your users, but lay out your mail file as is best for you to read. You can even insert gobs of text to help format the output. Only the [key] parts will be replaced by CGIEmail.

CGIEmail does not report environmental variables like FormMail will, but other than that, it is an excellent program, allowing you more flexibility in the way you want your data returned by the form.

The CGIEMAIL User Guide

For a more detailed explanation of cgiemail’s capabilities and syntax, visit the cgiemail user guide published at MIT.

Calling CGIEmail Through the Secure Server

If you want to call your cgiemail form through the secure server, use the following ACTION tag:

<FORM METHOD=POST ACTION=”https://machine.safe-order.net/cgi-username/cgiemail/forms/order.txt”>

where machine is the name of the server on which your domain resides, and username is your domain name without the top-level domain extension (e.g., for hostingmanual.net, the username is hostingmanual.)

If you’re specifying a success page, the appropriate tag would be:

<INPUT TYPE=HIDDEN VALUE=”https://machine.safe-order.net/username/pagename.html name=”success”>