CGI Mailer

How to use CgiMailer

Below is a tutorial on how to use CgiMailer. For those in a hurry, you could download the example files at http://github.com/dongyage/CgiMailer/tree/master/example/

1. Creating the HTML form

The form itself should POST to the URL that CgiMailer has been installed:

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

Add a html form to your website with 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">

Here is an example of a working form:

    <form method="post" action="http://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">
    <b>Name:</b> <input type="text" name="name" size="30"><br/>
    <b>Email address:</b> <input type="text" name="email_address" size="30"><br/>

    <select name="question">
        <option value="feedback">Feedback</option>
        <option value="question" selected="selected">Question</option>
        <option value="other">Other</option>
    </select><br/>
    <textarea name="message" rows="3" cols="40">
    </textarea><br/>
    <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 work out how to format the email message it will send to you.

A format file is simply a text file with the contents of the email you want to be sent. Every time a word starts with $ it will be replaced with the user submitted data.

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.

Troubleshooting

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' 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" />

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: 

<form method="post" action=">http://cgimailer.unimelb.edu.au/cgi-mailer.pl">
and an allow from 128.250.158.152 in the .htaccess of the folder An example .htaccess file would take the form of: 
<
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

>