htmail

home / how-to / cgi-scripts / htmail

About htmail

htmail is a generic forms-to-email gateway. With it, you can implement feedback forms and simple surveys that will be e-mailed to you.

FAQ:

How do I enable my address for HTMail?
Can I use htmail for non-UM email addresses?
Can you enable another person's email address for htmail?

How to use htmail

This document assumes some familiarity with Navigating the World Wide Web and Creating and editing html documents in the U-M environment. This document further assumes that you have an IFS home directory and access to both a World Wide Web browser and a simple text editor.

• Step 1 - enable your address
  As a security measure, htmail can only send e-mail to pre-enabled e-mail addresses. If you wish to use htmail, you must first register your email address(es). This registration should be instantaneous.
  
  Note: htmail service is available only to U-M facutly, staff, students, and affiliates.
• Step 2 - view generic form
  Use your favorite web browser to open the URL:

  http://cgi.www.umich.edu/cgi-bin/htmail/email@address

  where email@address is replaced with the email address you have just had enabled for use with htmail.
• Step 3 - create your own form
  Save the source of that document into an html form in your Public/html directory. Procedures for doing this vary from browser to browser, but typically there will be a "Document Source" choice under the "view" menu or something similar.
  
  Once you view the source of this page, save it as a new file in your Public/html directory.

Please note: When editing the source of your htmail form, you will note the email address field is titled "from" (lowercase). This field is required for htmail to function; if you remove or change this field, your form will generate an error. See the "customization" section of this document for additional information.

How to customize htmail

It is possible to make rather complex fill-in forms for use with htmail. Here is an example of a form which incorporates a number of more advanced features. To make complex forms such as this one, you need to know two things: how to create html forms, and what fields are available for use in the htmail cgi application.

For a good description of the tags used to create html forms, please see the HTML Code Tutorial.

The fields that you may use in your htmail forms include:

• body - Usually a TEXTAREA that is used as the main body of your e-mail message.
• ccme - If this is set to "yes" a copy of the message will be sent to the person using htmail.
• from - The e-mail address of the person filling out the htmail form. Must be lowercase.
• apparently-from - The same as the "from" field, but it will also be included in the list of fields at the bottom of the message, for easy parsing. This overrides the "from" field, and any information in the "from" field is lost.
• subject - This value gets put in the "Subject:" header of the message sent by htmail.
• apparently-subject - The same as the "subject" field, but it will also be included in the list of fields at the bottom of the message, for easy parsing. This overrides the "subject" field, and any information in the "subject" field is lost.
• successURL - The URL to which a successful htmail submission is directed. If this is left blank, then visitors to your page will be shown the default "success" message.
• to - The e-mail address enabled for htmail. The "to" field is set initially with the URL when you call htmail, but can be changed in the form to make it easy to have a drop-down list of people to deliver a message to, and for various other reasons.
• apparently-to - The same as the "to" field, but it will also be included in the list of fields at the bottom of the message, for easy parsing. This overrides the "to" field, and any information in the "to" field is lost.
• template - A hidden field with the name of the template file to be used when sending your message. No forward slashes are permitted in this field. For more information on templates, see the templates section of this document.
• template_source - Can be used to specify the location of your templates in IFS. This field is not normally used, but can contain the name of an IFS home directory. No forward slashes are permitted in this field. For more information on templates, see the templates section of this document.

Note: If you include a field named "to" in your htmail form, you need to have every email address you may be sending email to enabled for htmail, or the behavior of the form may be erratic.

You may use any other name for fields you create; these extra fields will be appended to the bottom of the e-mail message you receive.

Using templates with htmail

This section of the documentation is not necessary to make a working form. Templates are intended to make htmail more flexible, but are not necessary. Using these templates, it is possible to format the e-mail message sent by your form in virtually any way you like. This could be used to make the submitted form easier to add to a database program or simply to make the submitted form more attractive and readable.

HTMail uses template files based on the Server Side Include (SSI) Standard. More information on SSIs is available from: http://www.umich.edu/faq.html

To make the e-mail address of the user appear in your template, you would use the tag:

<!--#echo var="from" -->

Be very careful that the variable names in your template file exactly match the form field names in your htmail form. This will ensure that the completed form will be passed along and sent to you in e-mail.

Step One: Create Your Template Directory

The following command, when issued on one of the ITD login servers, will create the necessary directory structure:

% mkdir -p ~/Public/html/cgi-data/htmail

To create the template file for a group directory, use:

% mkdir -p ~groupname/Public/html/cgi-data/htmail

Where groupname is the name of your group. In either case, be sure to leave off the "%" when copying the command. It is only there to demonstrate that these are UNIX commands.

Step Two: Create A Template

A template is simply a text file with SSI tags added. HTML will not work unless you use an e-mail client that interprets html tags. You can create this file using any text editor and save it in your newly created template directory.

An example of a template file may be helpful as a starting point.

This template expects to be called from a form with fields called from, body, and name.

Step Three: Add the "template" Tag to Your Form

The next step is to add the "template" tag to your form. This tag allows you to specify the file name (with no forward slashes allowed) of your template file. In a simple web form this looks like:

A simple htmail form with the template tag.

Another tag, the "template_source" tag, allows you to specify an IFS home directory other than your own if needs be. In most cases, this will not be necessary and you will not need to use the template_source tag.

Step Four: Test

Fill in your form completely and make sure all of the information you submit comes to you in e-mail. A good way of testing web forms is to fill in all the fields with that field's name (this only works for text inputs and text areas). This method allows you to see quickly and easily which fields, if any, are having problems.

If you do find any problems, be sure to correct them and re-test.

NOTE: If htmail has difficulty finding your template file it will send the message in the default format and give you some messages (via e-mail) about the problem with your template. No template error messages are ever given to the user of your form so be sure to check the e-mail messages closely when you are testing.