The cgiemail user guide
This guide will help you write a WWW form that sends an e-mail message
to you. The following steps are required:
- Create an e-mail template.
- Put a link to the template on your page.
- Decide if a mailto: link will do.
- Create the HTML form.
- Create more advanced HTML forms.
- Make sure the ACTION is correct.
- Try out your form with cgiecho.
- Go live with cgiemail.
- Debug if you don't get mail
The following steps are optional.
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: someone@FoxValley.net HEADER LINES
Subject: questions three
blank line
What is your name? [yourname]
What is your quest? [quest] BODY
What is your favourite colour? [colour]
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:
- 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. 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.
- Make sure there is a blank line between the header lines and the
body.
- 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."
- 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 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 <someone@FoxValley.net>.
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:
- You will get a lot of frivolous e-mail from people who are merely
``surfing the web.''
- 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.
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.
This is the HTML source:
<FORM METHOD="POST" ACTION="/shared-cgi/cgiecho/home/someone/public_html/questions3.txt">
Your e-mail address: <INPUT NAME="email"><p>
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. 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 colour.
This is the key concept in using cgiemail. Be careful to make them
exactly the same; if you put NAME="colour" 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.
On Fox Valley's servers, the URL which you specify as the FORM tag ACTION
value is
/shared-cgi/cgiemail/TEMPLATEFILE
for virtual web host sites (www.yourdomain.com) and
/shared-cgi/cgiemail/home/USERNAME/public_html/TEMPLATEFILE
for user web sites (users.FoxValley.net/~USERNAME) where USERNAME is your
username in lowercase letters and TEMPLATEFILE in the name of your template
file.
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 remove this 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 Lynx 2.6 or
Netscape 3.0, then you may put HTML markup into this variable using the
appropriate character
entities. For example, if you wanted to add
Thank you!
then the HTML markup would be
<em>Thank you!</em>
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://web.mit.edu/">
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.3, there is no way to make this alternate success page
contain information the user submitted in the form. This feature is
likely to be added in a future
release.
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]
Note: With release 1.4, the prefix cgiemail uses to
recognize a required field is ``required'' without the hyphen. You
should still add a hyphen for readability, but you have the option of
using an underscore (better for interaction with JavaScript) or nothing
at all.
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 Godzilla's
Pizza wanted toppings listed one per line, they would put the
following in their e-mail template:
[%s
,topping]
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,
[$HTTP_USER_AGENT]
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.
cgiemail
Last modified: Thu Feb 5 13:09:39 EST 1998
