CGI Mailer

How to use CgiMailer

This is a simple tutorial for setting up CgiMailer.

You can download the example files to get started.

1. Creating the HTML form

The form itself should POST to the CgiMailer URL:

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

To send an email, the form needs two hidden input fields like the following:

<input type="hidden" name="destination" value="johnsmith@example.com">
<input type="hidden" name="subject" value="Online feedback form">

CgiMailer will send an email to the email address in the destination field. You can put in more addresses, separated by commas.

Here is an example of a working form:

<form method="post" action="https://www.unimelb.edu.au/cgi-bin/cgi-mailer.pl">
  <input type="hidden" name="destination" value="destination@example.com">
  <input type="hidden" name="subject" value="testing cgi-mailer">
  
  <div class="q">
    <div class="question">
      <label for="q1">Name:</label>
    </div>
    <div class="answer">
      <input type="text" name="name" id="q1" size="30" />
    </div>
  </div>

  <div class="q">
    <div class="question">
      <label for="q2">Email address:</label>
    </div>
    <div class="answer">
      <input type="text" name="email_address" id="q2" size="30" />
    </div>
  </div>

  <div class="q">
    <div class="question">
      <label for="q3">Favourite colour:</label>
    </div>
    <div class="answer">
      <select name="question" id="q3">
        <option value="red">Red</option>
        <option value="green">Green</option>
        <option value="blue">Blue</option>
      </select>
    </div>
  </div>

  <div class="q">
    <div class="question">
      <label for="q4">Comments:</label>
    </div>
    <div class="answer">
      <textarea name="message" rows="3" cols="40" id="q4"></textarea>
    </div>
  </div>
  
  <input type="submit" value="Send message" />
</form>

2. Creating the format file

After creating your web form, you also need to create a format file. This format file is used by CgiMailer to compose the email message it will send.

A format file is simply a text file with the contents of the email you want to be sent. Keywords using the names of fields in your form will be replaced with the submitted values. Keywords are prefaced with the $ dollar sign to indicate that they are values..

This example is based upon the example html form above:

You have a new message from $name with email address $email_address
-------------------------------
$question
--------------------------------
$message

The format file must be uploaded to the same directory as the HTML form, and with the same name as the form, but with an extension of .data. i.e. If your form is myform.html, then your format file must be called myform.data.

3. Creating a response file

You may optionally create a response file which contains a web page that should be displayed to a user who uses your web form.

The response file must be in the same folder on your website as the HTML form, it must have the same filename as the form, but with an extension of .response.

4. Required fields

If you wish to make the filling out of some of fields in your form mandatory, you can add a .required file.

Create a file with the extension .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.

name    Name
email_address   Email address

Further information

Handling web pages that don't end in .html

In some cases the URL of your form will not end in .html (i.e. where the URL of the page ends in '/'), in this case 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">

Where index.html is the name of the html file containing the form.

Specifying a From email address

By defult, emails will appear to be from a default email address as configured by the person who installed CgiMailer. If you wish to use a From address other than the default, you can add the following to your form:

<input type="hidden" name="From" value="bob@example.com" />

Default required, data and response files

For cases in which you have multiple forms with the same input fields (eg. two pages asking for the name and email address of interested parties) it is possible to set up default files which will be used by all forms.

The default files and html pages with similar forms should all be in the same directory on the web server, the default file names are as follows:

If you are using long filenames (with the full .html extension) CgiMailer will look for:

Sending an email response to the form user

If you want the user of a form to receive the email response as well as the 'destination' recipients a 'mailtouser' field can be used, ie:

<input type="hidden" name="mailtouser" value="UserEmail"/>
<input type="text" name="UserEmail">

The value of the "mailtouser" field specifies the name of the field that will receive the user's email address.

Email addresses with special characters

If there are any non-standard characters in the email address it will be discarded for security reasons. If the user enters a typo in their email they will not receive the email response.

Special headers

You can specify that other email headers be included in the email, for example:

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

Referring URL

CgiMailer depends upon the users web browser sending the Referring URL which indicated which web page the user just visited.

Some older web browsers, proxy servers don't send referring information. You can add support for these browsers by adding a field called CgiMailerReferer. Don't forget to make sure you are using the url to your own form.

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

CgiMailer is configured to work only for forms hosted within the University network.

Password or IP restricted forms

If your HTML form and the format file are both in either an IP restricted or password protected folder on your website, you will need the following setup:

Change the action target of the form:

<form method="post" action="http://cgimailer.unimelb.edu.au/cgi-mailer.pl">

and specifically allow from the IP address 128.250.158.152

If you were using .htaccess to protect the folder, the file might look like this:

AuthName "Protected"
AuthType Basic
AuthUserFile /servers/http/www.yoursite.unimelb.edu.au/your_directory/.htpasswd
AuthGroupFile /dev/null
require valid-user
order deny,allow
deny from all
allow from 128.250.158.152
Satisfy Any