John Doe’s Email Form

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:

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

• Add text to the success page.
• Use an alternate success page.
• Make some inputs required.
• Specify formatting for some inputs.
• Use CGI environment variables.

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]

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.)

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

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

3. Decide if a mailto: link will do.

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:

Your e-mail address:

Your name:

Your quest:

Your favourite colour:

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.

5. Create more advanced HTML forms.

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.

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.

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 », but it depends on how your server is configured. On web.mit.edu it happens to be « /bin/cgiecho », thus my ACTION looks like this:

http://web.mit.edu/bin/cgiecho/wwwdev/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.

7. Try out your form with cgiecho.

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.

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 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.

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.

Optional: Add text to the success page.

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:

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

Note that besides being difficult to write, this feature won’t work for people using older browser software.

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.

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.

Optional: Make some inputs required.

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:

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.

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:

Optional: Use CGI environment variables.

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: Tue Oct 31 09:24:21 EST 2000

Источник

CGI Email

Note: These instructions assume you are familiar with basic HTML and fill-out forms. You should also note that all file names and form fields are case sensitive. XMission uses a CGI tool called cgi-email to generate email from a fill-out form page without the need for a separate email client (which would be needed with a tag). To configure your own email form, you need to create a form with the appropriate «action» URL and create a template email message. These steps are outlined in detail below.

For more details about CGI Email, or to learn how to set it up on your own server, refer to MIT’s CGI Email help pages.

Creating the Form

When you create your form, there are two main things you will need to do. The first is to be certain that all the form fields have a unique name. The second is to properly set the tag. Any standard form entries may be used (such as radio buttons, check boxes, pull-down select menus, etc.). Below is a short example of a proper form, but you may also review your mail.html.

Please fill out the form below.

---

Your Name:
E-Mail Address:
Subject: Message / Request:

In red, you will see the tag. The method will be post, and the action will be your template message through our cgi-email script. The syntax shown in the form tag above should be followed exactly. You will, of course, replace «acctname» with your XMission account name, and mail.txt with the location and name of your template message. Your template message must be located in your public_html directory or a sub-directory within it. To show an example of a variation, the XMission username will be «web», the template message will be located in the public_html/contact/ directory, and it will be named «order.txt».

A notable bonus of using cgi-email is shown above in green. You can make a field required by preceding its name with «required-«. XMission recommends that you make the email address a required field. The reason being, if you reply to your form and there is no email address present, your reply will automatically be sent to XMission’s webmaster instead of the intended recipient.

Creating the Template Message

The template message is the email message that will be sent to you when the form is submitted. It’s a simple text file in the format of an email message. Because cgi-email sends this text file as an email message, it must have the proper header fields to work properly and must not have any blank lines before the first field.

The format of the template after the header lines is up to you. The only thing you must have is the names of the form fields in brackets. Below is an example of a text template to go with the form above. You may also review your mail.txt file.

To: John Doe From: [name] Reply-to: [required-email] Subject: [subject] Sender's Name: [name] Email Address: [required-email] Comments or Request: [content]

You would, of course, replace «John Doe» with the name of the person or department that the email message is being sent to, and «username@xmission.com» with the destination email address.

Adding a «success» Page

By default, there is a text confirmation page that notifies the sender that the email message was sent successfully. However, some XMission subscribers would like to replace it with a nicer HTML success page. This is easy with cgi-email.

You will need to open the HTML form and add a hidden form field. The syntax will look like the following example

Unlike the other form fields, you cannot change the name of the «success» field. It must be named «success» for it to work properly. The value is the URL of the success page that you want to appear after the sender has successfully completed and submitted the form. The example above will show the file named «successpage.html» in acctname’s public_html directory. The success page value must be a fully-qualified URL, so you may want to be sure it works in a browser first. tag cgiemail

Источник