Help for htmail v1.5
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.
How to use htmail at the University of Michigan
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.
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 send e-mail to firstname.lastname@example.org
and ask that your e-mail address be enabled for use with htmail. Note:
htmail service is available only to U-M facutly, staff, students, and affiliates.
Your e-mail address will be enabled for use with htmail within 2 days.
When your e-mail address is enabled, you will receive an e-mail message
which describes how to get started with htmail.
Use your favorite web browser (i.e. Netscape, Internet Explorer, Mosaic,
etc.) to open the URL: http://www.umich.edu/cgi-bin/htmail/e-mail@address
where e-mail@address is replaced with the e-mail address you have
just had enabled for use with htmail.
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.
How to customize htmail at the University of Michigan
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
The fields that you may use in your htmail forms include:
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.
body - Usually a TEXTAREA that is used as the main body of your
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.
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
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.
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.
How to get htmail to install at your own site
For help, contact email@example.com.
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 lake. 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. Mor 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 carefull that the variable names in your template file
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 By Step
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. The following template code, saved in the file "~websvcs/Public/html/cgi-data/htmail/example.tmpl",
demonstrates a simple template:
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:
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
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.
Copyright (C) 1996 by the Regents of the University of Michigan. User
agrees to reproduce said copyright notice on all copies of the software
made by the recipient.
All Rights Reserved. Permission is hereby granted for the recipient
to make copies and use this software for its own internal purposes only.
Recipient of this software may not re-distribute this software outside
of their own institution. Permission to market this software commercially,
to include this product as part of a commercial product, or to make a derivative
work for commercial purposes, is explicitly prohibited. All other uses
are also prohibited unless authorized in writing by the Regents of the
University of Michigan.
This software is offered without warranty. The Regents of the
University of Michigan disclaim all warranties, express or implied, including
but not limited to the implied warranties of merchantability and fitness
for any particular purpose. In no event shall the Regents of the University
of Michigan be liable for loss or damage of any kind, including but not
limited to incidental, indirect, consequential, or special damages.
w e b s e
r v i c e s @ u m i c h . e d u
Page Last Modified: Tuesday, 28-Mar-2000 16:14:36
U-M Gateway | ITWeb