MAILTO CGI Program

MAILTO.EXE will allow you to create your own form and have the results formatted and sent to one (or more) mail addresses. You can specify the name of the mail server, subject of the mail and (if you use the right fields), the mail will appear at your chosen account with the correct user name and email address (so that you can reply to it).

The only required hidden fields are sendto and server. The sendto field is the e-mail address that the form results will be mailed to. Our mail server will not normally accept an address outside of our domain or our hosted domains. If you want to set up a form to mail to an address outside our network, leave a message for don@midtown.net for special arrangements. The server field should be mail.midtown.net.

To call the mailto.exe program, your FORM ACTION line should be:

<FORM ACTION="/scripts/mailto.exe" METHOD="post">

The /scripts directory is an alias to the actual directory where mailto.exe program is stored. It is available from any directory you have created. Because /scripts is a common, aliased directory, be sure you don't create a directory by the same name within your web site area!

 

Fields & checking

There are two different types of fields for the MAILTO program. The first set specify what to do with the email message and the second specify what information to put into the message. All these details are written into "hidden" fields in the HTML Form - this allows the configuration to be in one place and means that the form user presented with a simple interface. Unless otherwise stated, all fields are optional.

Email Fields

The following fields specify what is done with the email message.

sendto

The address of the recipient of the email message. If this field is not present, no email message will be sent. This field is the one that is checked by the security checking discussed elsewhere. For example:

<INPUT TYPE="hidden" NAME="sendto"

VALUE="DanceMaster@net-shopper.co.uk">

cc

A comma separated list of other recipients of the form contents. For example:

<INPUT TYPE="hidden" NAME="cc"

VALUE="abc@company.com,efg@company.com">

server

Name of one or more mail servers to send the mail to. If more than one mail server is specified (as a comma separated list) then MAILTO will work though the list giving each mail server five seconds before moving on to the next. This must be a ANAME or CNAME of the server (that is, one you can ping) and if omitted the localhost will be used. For example the following definition will cause MAILTO to send all mail to the mail server called mail.company.com and then mail.another.com if the first is not available:

<INPUT TYPE="hidden" NAME="server"

VALUE="mail.company.com,mail.another.com">

subject

The subject of the mail message. If not specified, the value variable "HTTP_REFERER" will be used and if that is not provided by the WWW server, the default string "Completed WWW Form" will be used.

resulturl

The full URL for the next page to display if the mail operation was successful. If neither this nor resulttxt is defined, a default "thankyou" message will be displayed.

resulttxt

Some text that is displayed in the Thankyou message after the mail message has been sent. This allows a form to be created quickly. If neither this nor resulturl is defined, a default "thankyou" message will be displayed.

uname

Name of the user who has completed the form. This field will be placed in the "From:" clause of the email message to aid filing.

email

The email address of the person filling the form. The contents of this field will also be placed into the From: clause of the mail message. When you receive this message, you will be able to type "Reply" and reply to the person who filled the form.

webmaster

This field contains the email address of the World Wide Web Server Administrator. Whenever an error message is displayed and this value is defined, a "selectable" email address will be appended to the end of the message.

Message contents fields

These hidden fields have the same name as the field they control except that they have a "_command" afterwards and the value may be text message to display to the user if the test fails. More than one command may be used for each field. The MAILTO program will search for any conditions that fail and display all the error messages at the same time. This means that the user may be presented with a list of things to correct rather than one item at a time.

_required

This command indicates that the specified field must be completed by the user before the email message is sent. As long as the user enters something, the test is satisfied. If nothing is entered, the text in the "value" clause is displayed. For example:

<input type="hidden" name="uname_required"

value="Please enter your name">

will force the user to enter something in the field called "uname". If they do not enter anything, they will be told:

Please enter your name

_counter

The MAILTO program will maintain a set of counters so that you can uniquely identify every message that has been processed. The _counter command will access the specified counter, increment it and place the result in the email message. If any of the conditions fail, the counter will not be incremented. For example:

<input type="hidden" name="applications_counter">

will add the following line to the resulting email message:

applications = 3

If the counter does not exist, it will automatically be created and given the value 1.

Important! If you use the _counter field, please identify your site in the name field. The counters are kept in a common registry area, so if you use name="homepage_counter" and someone else on our system has used "homepage" before you, your counter name won't be unique. Please preface the name of the counter with your domain name, as: name="mydomain.homepage_counter".

_email

Check that the specified field could be a valid email address. The check that MAILTO carries out is to make sure the text entered has a "@" sign in it. Thus "mark" would fail and "mark@company.com" would succeed. Note that "mark@" would also succeed and that the domain name is not verified. If the check fails, the message in the "VALUE" part is displayed. For example:

<input type="hidden" name="email_email"

value="Please enter your email address">

will force the user to enter an email address in the field called "email". If they do not enter anything they will be told:

Please enter your email address

_num

Check that the specified field contains a valid number. The following characters are allowed in a number:

0 1 2 3 4 5 6 7 8 9 0 + - . , E e

If anything else is entered the user will be presented with the text in the "value" field. For example:

<input type="hidden" name="age_num"

value="Please enter your age in years">

will force the user to enter an number in the field called "age". If they do not enter anything they will be told:

Please enter your age in years

_display

This command can be used to place the values of variables supplied by the WWW server into the email message. The special field "*_display" will cause all variables from the WWW server to be displayed - this can be used to select those that may be of interest. The following values may be of interest:

SERVER_SOFTWARE Name of the server software.
SERVER_NAME Name of the WWW server.
SERVER_PROTOCOL HTML protocol supported by the server.
SERVER_PORT Port number of connection from remote client.
REMOTE_HOST IP address of the remote client.
REMOTE_ADDR IP Address of the remote client.
HTTP_USER_AGENT The remote client software.
HTTP_REFERER URL of the page where the form was entered.

Thus the command:

<input type="hidden" name="REMOTE_ADDR_display">

will add the field:

REMOTE_ADDR = 123.123.123.123

to the resulting email message. You can obtain a list of variables that are available from the WWW server by switching he debug option on (see below).

_hidden

This command forces the variable to be excluded from the email message or file.

 

Example

<FORM ACTION="/scripts/mailto.exe" METHOD="post">
<INPUT TYPE="hidden" NAME="sendto" VALUE="name@yourcompany.com">
<INPUT TYPE="hidden" Name="server" value="mail.midtown.net">
<INPUT TYPE="hidden" NAME="subject" value="Subject of form">
<INPUT TYPE="hidden" NAME="resulturl" value="http://yourcompany.com/done.htm">
<P>
Your details:<p>
Name:            <INPUT NAME="uname" SIZE=30><br>
Position:        <INPUT NAME="title" SIZE=30><br>
Company Name:    <INPUT NAME="company" SIZE=40><br>
E-Mail:          <INPUT NAME="email" SIZE=30><p>

Press <INPUT TYPE="submit" VALUE="Submit"> and your request will be processed
or <INPUT TYPE="reset" VALUE="Clear"> to start again.<p>
</FORM>

When the user presses the SUBMIT button, the user will see the page refered to by the optional resulturl field. Then, the information is sent to the WWW server which calls /scripts/mailto.exe. MAILTO.EXE will read the details sent and format a message which looks something like:


From: A N Other <other@company.com>
To: <name@yourcompany.com>
Subject: Subject of form
Date: Thu, 22 Jun 95 13:22:28 GMT+0000

The following form contents were entered on 22nd Jun 95
Date = 22 Jun 95 13:22:26
subject = Subject of form
uname = A N Other
title = Network Administrator
company = Elephants Inc
email = other@company.com