cgi-mailer: an easy to use form-to-email gateway

Requirements

All you need is your html form, a format file and (optionally) a response file.

Instructions

1. Your html form must have two hidden input fields, named 'destination' and 'subject'. The 'destination' field will have the email address where the email is to be sent, and the 'subject' field will contain the subject for the email message.

2. Other message headers can be set using inputs of the form

   header:<header-name>

   For example, to set the Reply-To: header, use the html

   <input name="header:Reply-To" value="j.smith@domain.com" type="hidden" />

3. The format file is essentially the body of the email message to be sent. Form fields that you want in the email message just need to have a '$' pre-pended to them. i.e. a form field of 'name' will become '$name' in the format file.

4. The FORM tag should be set to:

   <form action="http://www.monash.edu.au/cgi-bin/cgi-mailer.pl" method="post">

5. The format file must be in the same directory as the HTML form, and with the same name as the form, but with an extension of '.data' instead of '.html'. e.g. If your form is 'myform.html', then your format file must be called 'myform.data'.

6. The response file must be in the same directory as the HTML form, and with the same name as the form, but with an extension of '.response' instead of '.html' (as with '.data' above (eg myform.html becomes myform.response). The response file will contain the html page you be returned to the user upon successful completion of the form. It can also contain the same fields as the format file (i.e. use $name to display fields that the user filled out).

7. If you wish to make the filling out of some fields in your form mandatory, you can add a "required" file. Create a file called 'myform.required', containing one or more lines of

   field-name<tab>Description

   Each field name will be checked against the input to see if it isn't empty. If it is, an error will be shown using the Description to instruct the user to fill in that particular field.

8. If you don't wish to send an email message, and only want to format and show the response file, include an input field of the name nodata set to the value true.

   <input name="nodata" value="true" type="hidden" />

   In this situation, you don't need a format (.data) file, just a response file.

9. If you want to use an index file for your form (i.e. where the URL of the page ends in '/'), you will need to include a hidden field which specifies the name of the index file:

   <input name="index-file" value="index.html" type="hidden" />

   You can replace "index.html" with the appropriate filename.

10. You might also like to add a hidden field that contains the absolute URL of the form. This will assist users whose browsers or proxy servers don't send or remove the Referer header (which CGI-Mailer relies upon). This field must be called CgiMailerReferer.

    <input name="CgiMailerReferer" value="http://www.foo.com/forms/feedback.html" type="hidden" />

    You can replace "http://www.foo.com/forms/feedback.html" with the appropriate URL.

11. You can reproduce CGI environment variables in the email message and response page by simply referring to them directly. e.g. $ENV{'REMOTE_HOST'}

12. .htm, .dat, .res and .req can be used as the extensions on the above files, but the use of the shorter forms is discouraged.

Anti-Spam measures

Spambots are constantly crawling public websites looking for opportunities to submit advertising material via webforms, and forms created that use cgi-mailer are no exception. In an effort to stop staff members from receiving annoying spam, and to try and prevent legitimate incoming submissions, the following measures have been added to CGI-Mailer.

Confirmation Challenge

By default, any form that uses cgi-mailer will now have a confirmation page. Users that submit data will be asked to answer a simple question in order to confirm that they are a robot. In order to make this question as open to as many potential website users as possible, we have initially implemented a simple "what is x + x?" question, where x is a random integer number under 5.

If the answer is incorrect, the confirmation page will be presented again, and so on, until a correct answer is submitted. At that point the process continues and sends the email to the recipient.

This is now the default behaviour of CGI-Mailer.

Unrequired fields

Similarly to creating a required field (see 7. above), authors can create a form that includes a field that is hidden to normal users, but is visible to bots, and then designate this field as an unrequired field - ie: if it has a value, then the form will be rejected.

A hidden field can be created by either:
<input type="hidden" name="unrequired" />
or
<type="text" style="display:none;" name="unrequired" />

To set this field as unrequired, create (or use an existing) file called 'myform.required', and place a line in it:
!unrequired<tab>Description
Note the exclamation mark (!) at the start of the line - without that mark, the field will be required rather than unrequired, and this will probably cause some user confusion.

Submissions that put data in that field will now be rejected.

Suggested Methods of Use

Currently the cgi-mailer uses spamassasin to try and mark any incoming queries as spam or not spam. However, this is proving not terribly accurate as the software is marking many legitimate queries as spam.

If either a _no_confirm field is set, or the user has passed the confirmation challenge above, then the query is no longer passed through spam assassin. Instead any determination will be left to the spam filtering provided by the IMS team at the server level.

To set a _no_confirm field, include this within your form:
<input type="hidden" name="_no_confirm" value="1" />

We would recommend that the _no_confirm field is only used on forms for which the user has already logged in. Thus students or staff that have already confirmed their identity by logging in via their authcate passwords will not have to deal with the confirmation screen nor will their query/email be screened by spam assassin (nor will the recipient get bombed with automated spam).

For webpages that wish to provide a slightly smoother process to users than the confirmation-challenge pathway, we would recommend adding in the unrequired field option. This will help reduce the number of robots that abuse the form without adding extra load to the site users.

Example form

HTML (formname.html)

See the Monash Web Style for more information on designing forms.

Visual format of example form

Form required & unrequired field file (formname.required)

Email format file (formname.data)

First Value: $one
Third Value: $three
--------------------------------
Fourth: $four; Second: $two
--------------------------------
Fifth: $five; Sixth: $six
--------------------------------
List option: $list

Email received

Credits and license terms

• cgi-mailer is copyright 1996-2000, Martin Gleeson.
• Permission is granted to copy and distribute this work provided that this notice remains intact.
• Credit for using this program must be given to Martin Gleeson in all derived works.
• Including the following HTML at the end of your form or response page is enough to satisfy this requirement:
  <p>Produced by <a href="http://martin.gleeson.com/cgi-mailer/">cgi-mailer.</a></p>

Based on the cgi-mailer user documentation.
Copyright © 1996-1999 Martin Gleeson.