Template-driven Mail Script

The template-driven mail script is a simple yet flexible way to deliver form data from an HTML form to a user via VMS callable mail. The script scans a template file to obtain the addressee, subject, and body of the message to be sent. The template may include named tags that get replaced during the scan by the corresponding fields of the form data included with the request.

Generating a form to use tmail

To use tmail you must create a form that specifies an action of POST and the tmail script as the action URL with the virtual path of the template file as the URL's path info (See sample form's HTML).

The sample form below specifies /wasd_root/src/osu/tmail.tmail as it's template file. The template file's to: field must be changed to specify the actual user you want the mail to go to.

Subject:
Title:
Body:

urgent

Sample form's HTML

<FORM method="POST" action="/htbin/tmail/wasd_root/src/osu/tmail.tmail">
Subject: <input type="text" name="subject" size=40 maxlength=100><BR>
Title: <input type="text" name="title" size=40 maxlength=100><BR>
<DL><DT>Body:</DT>
<DD><textarea a name="msg" size=80 rows=10 cols=60></textarea></DD>
</DL><P>
<input type="checkbox" name="urgent"> urgent<BR>
<input type="submit" value=" send "> <input type="reset" value=" clear ">
</FORM>

Template File Format

The template file consists of 1 or more header lines, a blank line (zero length), and zero or more body lines. A header line has a label terminated by a colon and an argument starting at the first non-space charater after the label and continuing to the end-of line. The body lines become the body of the sent mail message.

The very first line of a template file must contain "tmail: xxx" where xxx is a version number. This requirement is so the tmail script doesn't waste time trying to interpret a file that wasn't explicitly written as a tmail template.

Labels

To:
Specifies the email address of the person to receive the mail. This label is required
Subject:
Specifies an optional subject line to use for the message.
Success:
Specifies an alternate URL to return to indicate a successful send, may be either a local or remote redirect.
Success-sts:
Specifies a alternate HTTP return code to use rather than the standard 200 code. Specify a code of 204 to get a 'slient' repsonse to the post.
Tmail:
Signature used to indicate that this is a tmail template. The tmail: header line must be the first line of the template file.

Tags

A tag marks a point in template file where form data or CGI environment data is to be inserted. The format of a tag is [field-name], [%cgi-var], or [%%cmd], where field-name is an input field in the form, cgi-var is a CGI variable name and cmd is one of the special command keywords described below. Note that names inside tags are case sensitive. Tags may be placed in both body lines and header lines;

To place a literal "[" or "]" in the template file, specify "[[" and "[]" respectively.

Command (%%) tags

Tags prefixed with 2 percent signs (e.g. [%%end]) indicate special actions that tmail is to take during template processing.

%%end
Marks logical end of template, lines following this tag will are assumed to be a CGI response to send instead of the normal confirmation message. The first line following this tag must be a content-type header lines (e.g. "content-type text/html") followed by a blank line.

%%entify
Causes the script to convert any <, >, or & characters present in any succeeding tag expansions to their HTML 'entity' forms (e.g. '<' ==> '&lt;'). Entification is off by default for the portion of the template prior to [%%end] and on for the portion after the [%%end]

%%noentify
Turns off entification (see entify above).

Conditional expansion

You may optionally create tags with one of the extended formats [field-name:text] or [field-name?text]. Tags with the [field-name:text] format will substitute 'text' for a non-null field value and a null string if the field value is null. Tags with the [field-name?text] format will substitute 'text' for "on" and a null string otherwise (i.e. tests setting for checkbox input items).

Acknowledgements

The inspiration for tmail is the MIT cgiemail script, which uses unix sendmail as the mail transport. The code for tmail started life as Dick Munroe's cgi-mailto script.