This guide will help you write a WWW form that sends an e-mail message to you. The following steps are required:
The following steps are optional.
|Add text to the success page.|
|Use an alternate success page.|
|Make some inputs required.|
|Specify formatting for some inputs.|
|Use CGI environment variables.|
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: email@example.com HEADER LINES Subject: questions three blank line What is your name? [yourname] What is your quest? [quest] BODY What is your favorite color? [color]
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 your WWW
server, be careful to follow these guidelines:
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 WWW server and look at it with your WWW browser.
Here's an example:
Would you like to cross the bridge? Download my "questions three" form and send it to <firstname.lastname@example.org>.
Even after you create your WWW form, you will want to leave this link in to increase accessibility to users with disabilities.
Already, without any complicated HTML, you have a way for people on the WWW 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 WWW have two particular disadvantages:
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:
Here is an example HTML form.
This is the HTML source:
<FORM METHOD="POST" ACTION="http://support.esosoft.net/cgi-sys/cgiecho/cgi/cgiemail/questions3.txt"> Your e-mail address: <INPUT NAME="email"><p> Your name: <INPUT NAME="yourname"><p> Your quest: <INPUT NAME="quest"><p> Your favorite color: <INPUT NAME="color"><p> <INPUT TYPE="submit" value="Send e-mail"> </FORM>
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.
To learn to create more complicated forms, read NCSA's guide and/or 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. To get more ideas, see the cgiemail example page.
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://support.esosoft.net/cgi/cgiemail/questions3.txt \ /\ / `------- Part 1 --------' ` ------- Part 2 --------'
Then you put the script name in the middle. Usually this is "/cgi-sys/cgiecho'', thus my ACTION looks like this:
http://support.esosoft.net/cgi-sys/cgiecho/cgi/cgiemail/questions3.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.
Pop your form into your favorite WWW 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.
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!
Normally, mail gets sent asynchronously, meaning it goes into a queue to be sent at 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 removethis variable when you are done debugging, because it slows things down for the end user and possibly for the mail system.
Note: For release 1.1 and prior, this won't work. Ask your webmaster to install a newer release. Some mailers have a nonstandard extension that sends bounces to an address in an Errors-To: header, so you might try using that header in your template if you're stuck with an old version of cgiemail. However, some errors make this header line unreadable, so there's no way to make absolutely sure the bounce will go to you.
When mail is sent, a page titled ``Success'' appears with the text of the e-mail message. You may use a hidden variable called "addendum'' to add your own text. Here is a simple example:
<INPUT TYPE="hidden" NAME="addendum" VALUE="Thank you!">
If you are willing to assume that readers of your form are using recent browser software like Microsoft Internet Explorer or Netscape Navigator or Lynx, then you may put HTML markup into this variable using the appropriate character entities. For example, if you wanted to add
then the HTML markup would be
meaning you would need the following in your form:
<INPUT TYPE="hidden" NAME="addendum" VALUE="<em>Thank you!</em>">
Note that besides being difficult to write, this feature won't work for people using older browser software.
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://support.esosoft.net/">
Note: Start your URL with / or with http://. Otherwise cgiemail will direct your browser to a second invocation of cgiemail, resulting in the error No variable substitutions.
As of release 1.4, you can make this alternate success page contain information the user submitted in the form.
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 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]
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:
This feature may or may not work, depending on whether or not your webmaster enabled it when configuring cgiemail.
In addition to form inputs, your e-mail template can include CGI environment variables simply by preceding the variable's name with a dollar sign. For example,
will put the name of the user's browser and/or gateway in your e-mail message. In order to be respectful of privacy, your HTML form should warn users about any information about them that will be included in the e-mail, e.g. HTTP_USER_AGENT, REMOTE_ADDR.
Last Updated: 13 May 2001
Copyright © by Esosoft Corporation 1996-2001
All Rights Reserved.