mailto - Web-based email Form Handler

Notice: This mailto application and the examples below will only work on www.washington.edu. It will not work on other hosts, including other centrally-managed UW servers such as depts.washington.edu.

If you wish to implement a form on another web site which will send email, you need to make sure you have a script on the web server which will send the email.

We are unable to redistribute the code.

The mailto script allows you to allow people to mail comments to a specified address. It requires that the user enter an email address with a valid hostname after the @, and the mail which is sent will appear to come from that email address. For example, username@u.washington.edu.

If you have any questions which are not covered with this document, please send a message to the www-mgmt group.

Warning: this script has no means of verifying that what the end user types in for the email address or personal name is actually correct, even though it does try to make sure the hostname is a valid one. It is possible for users to falsify information or complete the form multiple times. However, an extra mail header is added to show from what host the browser is running (and, in some cases, the proxy cache being used if any). See the example mail below for what this extra header looks like.

At the bottom of this document are some hints for configuring mailto for special needs.

Basic Example

mailto requires a form for the user to enter data, and a configuration file so mailto knows where to send the mail, etc.

You can try using the example form which will send mail to a dummy user. This form uses a simple configuration file and response skeleton files:

basic.html, the HTML form
basic.mailto, the config file
accept.html.skel, the valid response template, and
reject.html.skel, the error template

Note that you must fill in all three fields.

Sample mail sent by the basic form example.

Complex Example

This more complex example shows:

How to add other fields which should be added to the mail.
The comments section is implemented as a hidden field, because its use in this example is not mandatory.
If you try to prepend a field which is not part of the form, mailto assumes it is an environment variable and includes the value of the environment variable instead.
The config file specifies that the environment variable should have different output than the standard; the name of the field is changed and the separator between the field and the value is "=" instead of ": ".
A user-selected topic is appended to the subject
How to require a field, and how to set up a require group.

The files involved are:

complex.html, the HTML form
complex.mailto, the config file

The two template files, accept.html.skel and reject.html.skel are the same as in the basic example.

Sample mail sent by the complex form example.

Attachment Example

The attachment example shows:

How to attach a file.
How to require a field, and have a custom error message if that field is not included (in this case, an attached file).
Using <label></label> to associate form text with fields.

The files involved are:

attach.html, the HTML form
attach.mailto, the config file

The two template files, accept.html.skel and reject.html.skel are the same as in the previous examples.

Details About Using mailto

The mailto script requires four different files:

An HTML file with a form
A mailto config file
A confirmation skeleton file
An error skeleton file

HTML File with Form

If you haven't created HTML forms before, take a look at the documentation for Mosaic for X 2.0 Fill-Out Form Support.

Your form must supply at least three fields with the names:

sender for the email address of the person filling out the form. The mailto script will check that it looks like a reasonable email address, and that the hostname after the @ is a valid host.
sendername for the real name of the person filling out the form.
comments for the text of the mail message that gets sent. This field is normally set up as a <textarea> field.

If you wish any of these fields to not be required, you should make them hidden fields with valid text. For example, if you don't wish to require that the user enter their personal name, you can use something like:

<input type="hidden" name="sendername" value="name">
<input type="text" name="optsendername" size=35 value="">

The form's action should be the logical path to the configuration file. For example, in the basic example above, the form line is:

<form action="/webinfo/mailto/basic.mailto" method="post">

Note that the subject will always be either "Comments from the Web" or a subject which is configured in the config file. However, if your form contains a field named subjectadd, the contents of that field are appended to the subject.

Mailto Config File

The config file is rather free-form in structure. Even though it looks like HTML, it isn't really HTML. There are no nested tags, no error checking, and leading and trailing whitespace is trimmed.

Entries are surrounded by tags embedded with <> pairs. For example, to specify the destination for the message, you'd use:

<to>user@hostname</to>

The only field which is required is the <TO>user@host</TO> field. It can contain only one email address. All mail sent by the mailto form will go to this user. Optional fields are:

<bcc>user1@host1 user2@host2</bcc>

Blind carbon copy recipients of the message.

<accept_tmpl>filename</accept_tmpl>

An HTML template displayed after successful submission of a message. An error is generated if the specified file does not exist. If this option is omitted, the file accept.html.skel is used.

<reject_tmpl>filename</reject_tmpl>

An HTML template displayed after the failed submission of a message. An error is generated if the specified file does not exist. If this option is omitted, the file reject.html.skel is used. Any line containing the string --error-- is removed and an appropriate error message is put in its place.

<msg_no_name>string</msg_no_name>

Message to use in <reject_tmpl> when the user enters nothing in the sendername field. The default string is You did not supply your name

<msg_no_text>string</msg_no_text>

Message to use in <reject_tmpl> when the user enters nothing in the comment field. The default is Please complete the form

<msg_bad_host>string</msg_bad_host>

Message to use in <reject_tmpl> when the user enters an email address in the sender field that has an invalid hostname. The default is Your mail address contains an invalid hostname

<msg_invalid>string</msg_invalid>

Message to use in <reject_tmpl> when a <validate> statement fails. The default is Not all fields had correct values.

<subject>string</subject>

The subject of each message sent. The default is Comments from the Web.

<cc_sender/>

Send a copy of the message to the person filling out the form. Warning: This option should be used with great caution, since the user can fill out any address (even not his or her own) as the sender.

<xtra_headers>headers</xtra_headers>

Headers to be added to the message sent. For example:

<xtra_headers>
Requesting-Form: basic.mailto
From-Host: www.washington.edu
</xtra_headers>

The headers must be valid RFC 822 headers, so you cannot use freeform text as extra headers.

<prepend_fields>fields</prepend_fields>

Prepend specified fields from the form to the beginning of the message text. This allows any additional information collected to be presented within the message. Field names are specified in two forms:

field
field:tag

The first form will include the contents of the named field in the mail message as:

field: Contents

and the second form will include the contents as:

tag: Contents

You can also specify the separator by including that separator between colons. For example:

field:=:tag

becomes

tag=Contents

If no tag is specified, the field name is used.

Requiring fields

If you wish to have some of these fields be required (as the comments, sender, and sendername field are) you need to prepend the field name with an asterisk (*). For example:

*phone

will make phone a required field. If the field is not present, the user will receive the same error message as if they didn't supply data for the comments field.

Requiring field groups

You may have an application where you need to require either one field or another, but not both. For example, you may wish to require either a phone number or an email address. To do this, you can define required groups by putting a group name before an asterisk. Only one field in the group is required, but an error will result if no fields in the group is provided. For example:

contact*phone contact*email

defines a required group named contact. This enforces that either phone or email (or both) is filled in. If both fields are left blank, then mailto will generate the same error as if the comments field were left blank.

Error Messages for required fields

If you wish to have an error message which is specific to a required field rather than the default Please complete the form you can specify one on the same line. For example:

*phone#You must enter a phone number

will display You must enter a phone number as the error message if the field is not filled.

You can also specify error messages for field groups. You only need to specify the message once; if you specify more than one message, the last one will be used.

<if conditional> if-code <elseif conditional> elseif-code <else> else-code </if>

Conditionals let you use one mailto config file to act in different ways depending on the contents of the form. The <elseif conditional> and <else> statements are optional.

The conditional consists of a form field name followed by a conditional test, followed by a string:

Test	Explanation
var `== "`str`"`	form field var is equal to str
var `!= "`str`"`	form field var is not equal to str
var `> "`str`"`	form field var is numerically greater than str
var `>= "`str`"`	form field var is numerically greater than or equal to str
var `< "`str`"`	form field var is numerically less than str
var `<= "`str`"`	form field var is numerically less than or equal to str
var `=~ "`str`"`	form field var matches the regular expression str
var `!~ "`str`"`	form field var does not match the regular expression str

As an example, if you have a menu of different items, you could require different fields depending on the value chosen by the user. Assuming that the contactoption field contains how the user wishes to be contacted:

<prepend_fields>
<if contactmethod == "Phone">
    *phone
    email
<elseif contactmethod == "Email">
    phone
    *email
<else>
    phone
    email
</if>
</prepend_fields>

This code will require the phone field be filled in if the user chose "Phone" as the contact method, will require the email field be filed in if the user chose "Email" as the contact method, and will require neither in all other cases.

<validate var>pattern</validate>

If you wish for mailto to make sure that form field values match certain regular expression patterns. For example, if your form has a field named "box" into which the user must type a valid UW box number, you can validate the field with:

<validate box>^35\d\d\d\d$</validate>

You may also specify an error message if the pattern does not match by putting it in quotes after the field name. For the box number example:

<validate box "Box numbers must be 35<i>dddd</i> where <i>d</i> is a digit">^35\d\d\d\d$</validate>

Which will display the error message:

Box numbers must be 35dddd where d is a digit

<attachments>fields</attachments>

Users can send files to you as attachments with mailto. For each field which appears in the attachments section, mailto will see if that file was sent in the form and attach it to the mail if it exists. To enable attachments, you must make sure that your form can send attachments:

<form action="form.mailto" method="post" enctype="multipart/form-data">
form text here </form>

Within your form, you need to have at least one field which is of type file:

<input type="file" name="attachment">

where the name matches what you put in the attachments section of your mailto config file.

You can specify multiple attachments in your form and mailto config file. If you do so, you may want to also put the fields in the prepend_fields section of the mailto config file, since that will show you which files were used for which fields of your form. By doing this, you can also require that the fields be filled (meaning that files were attached.)

Warning: mailto cannot check whether attached files have viruses in them, so you should be very careful when you decide to allow users to attach files to your forms, as well as when opening attachments with your mail reader.

Confirmation Skeleton File

This file is actually straight HTML with no processing done by the mailto script. However, you may use chtml markup. For example:

<html>
<head>
<title>Mail Acknowledgement</title>
</head>

<body>
<h1>Mail Acknowledgement</h1>
Thanks for trying out mailto!
<p>
Return to <a href="/webinfo/mailto/">mailto documentation</a>
</body>
</html>

If you wish to use data from the form in your confirmation file, you can do so by putting the field name between dashes. For example, the snippet of code:

Thank you, --sendername--, for trying out mailto!

would insert the sender's personal name into the confirmation page.

Error Skeleton File

This file is also straight HTML, except when the mailto script runs across a line containing --error-- it will remove that line and replace it with the appropriate error message. As with the confirmation skel, chtml markup may be used. An example file:

<html>
<head>
<title>Mailto Error</title>
</head>

<body>
<h1>Mailto Error</h1>
--error--
<p>
Return to <a href="/webinfo/mailto/">mailto documentation</a>
</body>
</html>

Mailto Hints

Mailto was designed to work for most cases, but it can be configured to work in other applications.

Not requiring comments

If you don't wish to force the user to fill out a comment field, you can create a hidden comments field with a dummy value by including the following in your form:

<input type="hidden" name="comments" value="none">

The mail you receive will have a line which shows that the comment field is a value of none.

Requiring a selection in a pop-up list

If you wish to require that the user select from a pop-up list, you can take advantage of the fact that the comments field is required, and make a list which looks like:

<select name="comments">
    <option value="" selected>Select an option</option>
    <option value="first">First option</option>
    <option value="second">Second option</option>
    <option value="third">Third option</option>
</select>

If the user does not make a selection, then mailto will return an error. You should also set the MSG_NO_TEXT value in the config file to explain to the user that one of the options must be selected.

Require a validating checkbox

Some sites require that the user read an agreement statement and check a box verifying that it has been read. Again, the fact that the comments field is required can force the user to mark a checbox:

I agree with these terms. <input type="checkbox" name="comments" value="ok">

Because there is only one comments field, you cannot require both a checkbox and a selected pop-up value. Also, it is suggested that you change the MSG_NO_TEXT field of the config file.

Not requiring an email address

If your application does not require an email address, you can use a technique similar to making the comment field optional. Be sure that the dummy value is a valid email address, otherwise mailto will complain about it. For example, you could use:

<input type="hidden" name="sender" value="sender@u.washington.edu">

Note that all mail will appear to be from the user sender@u.washington.edu (or whatever value you happen to use.)

Formatting mail for automatic processing

If the mail generated by mailto will be fed into a script which automatically processes each message, you can use the various configuration options to format the mail. For example, if the mail will be sent to an address which adds users to a mail list and requires the body to contain:

subscribe user@address

then you can add the following to your config file:

sender: :subscribe

making sure there is a space between the colons. This will make the sender field to be written with subscribe instead of sender, and the text before the email address will be just a space.