Intergrate Soupermail

MKDoc does not have a form to email handler built in but often web sites need forms that send email, this how to explains how to intergrate soupermail, the same method can be used for any other web application.

Soupermail is a a very flexible form handler written in Perl and it is available from the Soupermail Sourceforge site.

Create new directories

You will need to set up a cgi-bin directory where the script can be run, for example, /var/www/your-mkdoc/site/cgi-bin/ and a seperate directory for the soupermail configuration files, eg /var/www/your-mkdoc/site/soupermail/, the second directory does not need to be served by Apache, it is the Soupermail $privateRoot.

Apache config

The key with the apache configuration is to have a ScriptAlias for soupermail before the MKDoc aliases, for example:

 ScripAlias /.soupermail   /var/www/your-mkdoc/site/cgi-bin/soupermail.pl
 Alias      /              /var/www/mkdoc-1-6/cgi/mkdoc.cgi/

The directory where soupermail is installed needs to be able to run CGI applications:

<Directory "/var/www/your-mkdoc/site/cgi-bin/">
    Options ExecCGI    
    AddHandler cgi-script .pl
    order allow,deny
    allow from all
    AllowOverride none
</Directory>

Install Soupermail

Soupermail does have one depandancy that is generally not installed on most distributions, MIME:Lite, this can be installed from CPAN.

Put the script in the new cgi-bin directory, check the path to perl and the other variables and make it execuatable, following are the variables that you will probably need to change:

$soupermailAdmin = 'vittal.aithal@bigfoot.com';
$privateRoot = "/home/httpd/soupermail.sourceforge.net/private";
$mailhost = 'localhost';
$mailprog = '/usr/lib/sendmail';

The mail settings will be different for different systems, if you are running Fedora Core / Red Hat then the mails settings should be changed to:

$mailhost = '';
$mailprog = '/usr/sbin/sendmail';

You will need to create a private root directory, say, /var/www/your-mkdoc/site/soupermail/ - this is where all the config files will go.

Configure Soupermail

Files that will need to be set up in the Soupermail configuration directory.

For a minimal install you will just need a soupermail.allow file, this can be an empty file, it just needs to exist, and a soupermail.conf configuration file:

# Specify some required fields (these are case sensitive): 
required: Email
required: Subject

# The line below lets Soupermail know who to send 
# the message to.
mailto: youraddress@example.org 

# Subject of the email can be set to the value of 
# the Subject form field, alternatively you can 
# hard code it here
subject: "$form_Subject"
subject: "Web Site Feedback"

# Email mime-type 
mailcharset : utf-8

Set up a form

Once Soupermail has been installed you can create a form and set the action to point to the Script alias, for example:

<form accept-charset="utf-8" action="/.soupermail" 
  method="post">
  <input value="~/soupermail.con" name="SoupermailConf" 
    type="hidden" />
  <fieldset>
    <legend>Your Details</legend>
    <p>
      <label for="Name">Name:</label><br />
      <input name="Name" title="Enter you name here." 
        id="Name" type="text" />
    </p>
    <p>
      <label for="Email">* Email:</label><br />
      <input name="Email" id="Email" 
        title="Enter your email address here." 
        type="text" />
    </p>
  </fieldset>
  <fieldset>
    <p>
      <legend>Your Message</legend>
    </p>
    <p>
      <label for="Subject">* Subject:</label><br />
      <input name="Subject" id="Subject" type="text" 
        title="Enter the subject of your message here." />
    </p>
    <p>
      <label for="Comments">Your Comments</label><br />
      <textarea name="Comments" id="Comments" 
        title="Enter the text of your message here" 
        rows="8" cols="50"></textarea>
    </p>
    <p>
      <input value="Submit" name="Submit" 
        type="submit" title="Submit your message." />
    </p>
  </fieldset>
</form>