Integrate Soupermail

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

Soupermail is 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 separate 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 dependency 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 executable. Following are the variables that you will probably need to change:

$soupermailAdmin = '[email protected]';
$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: [email protected] 
# 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 using a MKDoc HTML component and set the action to point to the ScriptAlias, and you need a hidden field for the configuration file, 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>

Further customisation

Soupermail is very flexible. If needs be, both the error page and the page you get on success can be customised to make them look like the rest of your site, in addition a template can be created for the email message that is sent out.

Success template

To create a template for people to get when they successfully submit a form you need to add this to the soupermail.con configuration file:

# Template to use upon success
success: success.html
successmime : text/html; charset=utf-8

Then you need to create this template, the easiest thing is to probably copy an existing page generated by MKDoc, for example the sitemap or search results page and then add something like this to the main body of the page:

<p>
  Thank you for your feedback, following is 
  the information you have submitted:
</p>
<pre>
<output name="Subject" type="html" pre="Subject: "> 
<output name="Name" type="html" pre="Name: ">
<output name="Email" type="html" pre="Email: "> 
<output name="Message" type="html" pre="Message: "> 
</pre>

Failure template

Set up the failure template the same as the success one, with this in the soupermail.con file:

# Template to use on failure
failure: sorry.html

And use this in the template:

<p>
  Sorry the following fields are compulsory, 
  please use the <strong>back</strong>
  button in your web browser to return to the form 
  and complete the missing fields.
</p>
<ul>
  <li>
    <output name="Email" 
      alt="<li>You need to provide a <strong>Email address</strong></li>" 
      sub="">
  </li>
  <li>
    <output name="Subject" 
      alt="<li>You need to provide a <strong>Subject</strong></li>" 
      sub="">
  </li>
</ul>

Email template

Add this to the soupermail.con configuration file:

mailtemplate: mail.txt 

Then create the mail.txt template:

From:  <output name="Name">
Email: <output name="Email">
<output name="Message">
--
<output name="http_remote_addr">
<output name="http_remote_host">
<output name="http_user_agent">