Tmail is a simple and powerful CGI tool used for sending form results to one or multiple email accounts. Tmail requires little additional knowledge besides that of basic HTML and HTML forms to implement.
Tmail does require a .tmail file located in any web accessible folder.
Note: Updates from version 2.0 to 2.1 are in bold.
The first step in implementing tmail is to prepare the HTML form so it may submit its information to the tmail script.
The form tag's action attribute should be set to the tmail script's URL address. UWP's tmail script is located at the following URL:
http://devcgi.uwplatt.edu/cgi-bin/tmail/index.pl
Example:
<form method="post" action="http://devcgi.uwplatt.edu/cgi-bin/tmail/index.pl">
To process the form data the tmail script requires a tmail file. The location of this file must be specified within the form as well. The tmail file location is included in a hidden form field with a name and id of tmail_file. The value must be the exact location of the tmail file. For example:
<input name="tmail_file" id="tmail_file" type="hidden" value="http://www.uwplatt.edu/test.tmail">
The tmail file contains all of the instructions the script needs to properly constuct an email and provide a response.
TopA tmail file is a plain text and should be properly titled with .tmail as the extension. The tmail file contains everything the script needs to construct an email based upon the HTML form. A tmail file contains at three sections, first, a header section containing the tmail file version number, runtime options, and email response directives. The second section is the email contents followed by the final section, a response to the client.
The first line of the tmail file contains a few pieces of important information. First, the tmail file version number and on that same line a list of the runtime options. The current version of tmail is 2.1. The following code is an example of the first line in a tmail file without any runtime options specified.
Tmail: 2.1
Runtime options allow a tmail file to modify tmail's behavior without affecting other tmail files that exist independently.
Tmail: 2.1 -d -ne
Options start with a - followed by the option name and another optional sting, if required. The available options in version 2.0 are as follows:
-d-neAfter the tmail's first file line the subsequent lines are email response directives. These lines give information regarding the tmail's email response, such as the email address to send the email, and the subject. There is no limit to the number of directives a tmail can have except subject which can only occur once. Directives are entered one per line. A directive should contain only one email address. Directives are in the following form:
Directive name: data
Tmail currently supports a number of directives including:
Subject: subjectTo: email@address.comCc: email@address.comBcc: email@address.comIn version 2.1 it is now possible to have a form field specify where the tmail program should send the email. This is done using the following syntax.
To: email@address.com[form_field_name:value_string]
If form_field_name exists and has a value equal to that of value_string then email@address.com will be included in the list of recipients.
:value_string is optional. If not included tmail will only check to see that form_field_name exists before including email@address.com in the list of recipients. Variable addressing will also function with CC and BCC directives.
Note: Tmail requires that a tmail file have at least one valid to address and an email subject to function properly.
TopThe remaining sections contain templates for the email as well as the response to the client. These two templates are separated by the command tag [%%end], this is explained below.
Tags are used to insert data into the email and the response templates. There are three types or tags as well as a number of tag expansions that allow the tmail script to produce a custom email and response for each tmail file.
All tags begin and end the same way, using the [ and the ] characters respectively. The text between the two characters determines the tag's function.
Note: Tags are valid in the email and response sections only. Additionally, tags cannot be nested.
[form_field_name]
This is the most basic tag type. A form field tag is replaced with the contents of the corresponding form field. For example, if the form contained a text input with a name and id of "email_address" the corresponding tag would that would insert that value would be [email_address].
Note: These tags are case sensitive.
Note: These tag names must be 3 characters or longer.
Top[%GGI_variable_name]
Tags that start with % are CGI variable tags. These tags are replaced with information provided by the tmail script. For example, if you wanted to include the client's browser information within the email the http user agent variable would be used. [%HTTP_USER_AGENT] The CGI variables available are as follows:
[%REMOTE_HOST][%REMOTE_ADDR][%REMOTE_USER][%HTTP_USER_AGENT]Note: These tags are not case sensitive.
TopTags beginning with %% are commands to the tmail program. Unlike the other tags, these don't insert information, instead they represent other options that affect how the tmail script functions.
[%%end]Content-Type: text/html, an empty line, and then the HTML response body.[%%entify]<, >, ", and & characters have special meanings and need to be escaped with < > " and & respectively. By default this conversion is disabled during mail message composition, before an [%%end] tag, and enabled during the response section, after an [%%end] tag.[%%noentify]Note: These tags are not case sensitive.
TopExtensions to the tag format allows information other than the exact contents of a tag field or CGI variable to be inserted based on the contents of that field or variable.
[form_field_name:string]
[%GGI_variable_name:string]
If the form field or CGI variable contains a non-empty string the specified string following the : is inserted into the text in place of the field name or CGI variable value. If the form field or CGI variable is empty or non-existent nothing is inserted.
[form_field_name:string1::string2]
[%GGI_variable_name:string1::string2]
This is similar to the expansion above, except if the form field or CGI variable is empty or non-existent the string after the :: is then inserted.
[form_field_name?string]
[%GGI_variable_name?string]
If the form field or CGI variable's value is equal to "on" (for evaluating checkboxes) then the string following the ? is inserted, otherwise nothing is inserted.
[form_field_name?string1??string2]
[%GGI_variable_name?string1??string2]
This is similar to the expansion above, except if the form field or CGI variable is not equal to "on" then the string after the ?? is then inserted.
In a tmail file a number of characters have special meanings. To use these characters normally they must be escaped. Escaping informs the tmail program that an individual character does not have a special meaning.
| Character | Escaped character |
Meaning |
|---|---|---|
[ |
[[ |
left square bracket |
] |
[] |
right square bracket |
? |
[? |
question mark |
: |
[: |
colon |
<h1>Send Web a Message<h1>
<form method="post" action="http://devcgi.uwplatt.edu/cgi-bin/tmail/index.pl">
<label for="name">Your Name:</label>
<input name="name" id="name" type="text" /><br />
<label for="email">E-mail Address:</label>
<input name="email" id="email" type="text" ><br />
<label for="phone">Phone Number:</label>
<input name="phone" id="phone" type="text" ><br />
<label for="descprob">Description of Problem:</label><br />
<textarea name="descprob" id="descprob" ></textarea><br />
<label for="comments">Comments:</label><br />
<textarea name="comments" id="comments" ></textarea><br />
<div style="text-align:center;">
<input name="tmail_file" id="tmail_file" type="hidden" value="http://www.uwplatt.edu/test.tmail">
<input type="submit" value="send">
<input type="reset" value="clear">
</div>
</form>
tmail: 2.1 -ne
To: web@uwplatt.edu
Subject: Message to Web Development
Sending client address: [%REMOTE_ADDR]
Your Name: [name]
E-mail Address: [email]
Phone Number: [phone]
Description of Problem:
[descprob]
Comments:
[comments]
[%%end]
content-type: text/html
<html>
<head>
<title>
Message To Web Sent
</title>
</head>
<body>
<p>Your message was successfully sent. Thank you [name] for your feedback.</p>
<p><a href="http://www.uwplatt.edu/web">Return to WEB</a></p>
</body>
</html>
This is a list of errors generated by the tmail script along with a more detailed explanation of each individual error. If this does not help you please contact web development.
Level 100 errors deal with the tmail file its version, location and format.
Error 100: Tmail does not support this tmail file becuase it's version is too new. This version supports tmail files version (current tmail version number) and lower.
The tmail file version is too new. There may be features that are not supported in the current version. Check the first line of the tmail against the current version of tmail.
Error 105: The provided file is not a valid tmail file.
Tmail was unable to parse the included tmail file. The file could either be of the wrong extension or have an invalid format. Please see the documentation above for the correct format.
Error 110: (various error messages)
There has been an error when tmail has tried to fetch the tmail file specified. These errors are not generated by the tmail script but another resource that tmail uses. If you have are having problems please contact web development.
Error 115: No tmail file url provided. This is required.
No tmail file was provided. Tmail requires a tmail file to work correctly. This must be included in the form data submitted. See the example above.
Error 120: '(tmail file url)' The tmail file url is not valid.
The listed tmail file url is not located within the uwplatt.edu domain. Tmail will only work with files hosted under the uwplatt.edu domain.
Level 200 errors deal with the generation of the email within tmail.
Error 200: No 'to:' email directive provided. This is required.
No address was provided to receive the resulting email. This is required for tmail to work properly.
Error 205: No 'subject:' email directive provided. This is required.
No subject was provided for the resulting email. This is required for tmail to work properly.
Error 210: Based upon user data there is no valid 'to:' email directive
This error was introduced in version 2.1 with the addition of variable addresses. Because it’s possible for the user to submit data that would result in an email with no destination address an error must be generated if there is no valid destination address after parsing the tmail file. Check to make sure there will always be at least one valid destination address.
Error 215: Max email recipients exceeded.
Because of SPAM concerns tmail is limited to sending a max of 5 emails per submission.
Error 220: '(email address)' This email not allowed.
Because of SPAM concerns all email address must be from the uwplatt.edu domain.
Level 300 errors deal with the html referrer URL.
Error 300: Empty referrer not allowed.
The referrer is a string the contains the URL of the document that contained a form. Because of SPAM and other concerns the referring document’s domain must contain uwplatt.edu. An empty referrer may also occur if the file is run locally and not accessed using it’s URL.
Error 305: '(html document url)' This referrer is not allowed.
The referrer is a string the contains the URL of the document that contained a form. Because of SPAM and other concerns the referring document’s domain must contain uwplatt.edu
Level 400 errors deal with the actual sending of emails.
Error 400: (various error messages)
There has been an error when tmail has tried to send an email. These errors are not generated by the tmail script but another resource that tmail uses. If you have are having problems please contact web development.
Top