eformmail documentation

Welcome to eformmail. This program is a secure and safe solution to emailing the contents of a form to an email address.

The latest version is always available at: http://www.pobox.com/~berend/eformmail/.

Table of Contents:

Why eformmail?

The task: you want the persons who visit your site be able to give comments or feedback.

The problem: but as soon as you put an email address on your web page, email address harvesters wil come and start spamming that email address. This turns away many volunteers, because if you put their email address on a web page, they will get inundated with spam.

non-solution: instead of just providing an email address, the web page has a nice HTML form. Visitors fill this in and press a submit button. No email address shown, right? Not necessarily true. Popular programs currently in use, such as formmail, still require the email address to be there. It might not be visible to visitors, but automated email harvesters can easily extract it. You still have to put the email address on the form as a hidden field. But hidden is hidden for visitors, not for programs.

solution: eformmail requires no email address whatsoever to be present on the form. eformmail is a program which can gather and send the contents of any HTML form to an email address. The email address is not buried in the form, but remains hidden on the hosting server. It will never be revealed in any form to the outside world whatsoever.

In a hurry? The quick guide

You're a seasoned web master? Here the quick guide.

  1. Copy eformmail.cgi to your cgi-bin directory and give it a name that does not include the words "mail" or "spam". Example: 
    cp eformmail.cgi /var/www/cgi-bin/do_not_use_this_name.cgi
    Note: certain installations require that your cgi program is owned by a certain user.
  2. Copy main.conf to /usr/local/etc/do_not_use_this_name/do_not_use_this_name.conf
  3. Edit this file, follow the comments as a guide.
  4. Determine what field in your form contains the key. Let's assume the name of this field is "name", and the contents is "feedback".
  5. Copy key.conf to /usr/local/etc/do_not_use_this_name/feedback.conf
  6. Edit this file, follow the comments as a guide.
  7. Make sure your HTML form contains a field with field name as specified in main.conf.
  8. Make sure the value of this field refers to an existing key configuration file.
  9. The action attribute of the <form> tag of your HTML form contains the filename you gave to eformail.cgi.
  10. The method should be "post".

That's it. eformmail.cgi is now fully set up. If there are error messages, look in the error log file of your web server. For Apache this is usually /var/log/httpd/errorlog.

How eformmail protects the email address behind your form

Spam is Internet's biggest problem. If you put an email address on a web page, email address harvesters will come and use that email address to send spam to. Even if you put that email address in a hidden form field. That's no protection at all.

So eformmail does not need an email address in the form. Instead you put a key in the form. That key is read and used to lookup the email address. The email address resides safe on your server and is not accessible to the world.

How eformmail protects against misuse of itself

Other programs that can mail the contents of a form call themselves universal form to email gateways. Spammers did like that. They used it as an open relay tool to send email to everyone in the universe

eformmail is secure and safe and cannot be used to mail just anyone. It can only be used to the email address that is specified for that form.

eformmail can still be misused. Spammers could fill in the form with spam information and press the "Submit" button. That is unavoidably if the form is open to everyone in the world. Everyone includes spammers.

However, eformmail has taken the following precautions that make it hard for spammers to detect sites that use eformmail:

  1. The program name must not contain the word "mail" or "form". This will make it hard for spammers to use Google for example to find sites that use this tool. Only accidentally will they discover those sites. It is just not worthwhile to go looking for them.
  2. eformmail requires the presence of a key in the form. What field in the form is the key, is unknown for the spammer. Just sending random form data to eformmail and hope it will be sent to the email address behind it, will therefore not work.
  3. When an error occurs, eformmail does not tell what is wrong. Only a general error message is displayed. Detailed information is in the log files on the server, but this is never revealed to the entire world. So spammers can not learn that a certain program is actually eformmail or learn what form field is the key field. This all makes it harder to misuse eformmail.
  4. eformmail is still open to Denial of Service attacks: someone sending a barrage of email through eformmail. Currently eformmail has no protection against this kind of attack. Note that webservers can usually block sites by ip address or name, so if you detect such an attack you can simply deny that site access.

Main configuration file

The main configuration file is equal to the name of the program plus the .conf extension. So if you have named the program save_it, the configuration file is save_it.conf. The program looks for this configuration file in the following directories, in this order:

  1. In the current directory.
  2. In /usr/local/etc/save_it/. The program name is appended to /usr/local/etc/. This subdirectory should exist and contain the file save_it.conf.
  3. In /etc/save_it/ and the file should also be called save_it.conf.

The configuration file contains the following pieces of information:

  1. the name of the field that is the key field in the form data that it receives. The program uses this key field to look for the key specific configuration file.
    The key field may be any field in your form, hidden or revealed. By having the key field in a configuration file is is harder for harvesters to find and misuse web pages that use this program.
    The key itself should conform to the rules for field names in a form. Usually the key is put as a hidden field in the form.
  2. The page to redirect browers to when the key field is not present.
    If the key field is not present, this indicates an error in creating the form or an attempt by spammers to misuse eformmail.
    The page to redirect to should be as general as possible and certainly not tell what field is the key field as spammers can use that information.
  3. Optionally you can specify the location of the sendmail binary. If you don't specify it, eformmail will look for it in certain well-known locations.

An example configuration file is:

# Main configuration file for eformmail.

# The "key field name" should list the field name in the form that
# contains the key. The value of this field is used to lookup another
# configuration file which contains the email address.
# eformmail will redirect the user to the "error redirect" page if this
# key does not exist in the passed form data.

key field name = key


# The page to redirect browsers to when the key field was not present.
# If the key field is not present, this indicates an error in creating
# the form or an attempt by spammers to misuse eformmail.
# The page to redirect to should be as general as possible and
# certainly not tell what field is the key field as spammers can use
# that information.
# The contents of this field must be a full URL, a partial reference
# will not work.

error redirect = http://localhost/main_error.html


# Optionally can specify the location of sendmail (or a clone like
# postfix).
# If no location is specified, eformmail will try to find sendmail in
# certain well-known paths.
#
# The -i and -t parameters are required for sendmail!

#sendmail = /usr/sbin/sendmail -i -t

Key configuration file

Every form must contain a key. What field constitues the key field is in the main configuration file. When the key is found in the form, eformmail looks for another configuration file. The name of that file is the value of the key field plus the extension .conf. eformmail looks for that file in the same directory where the main configuration file is found.

Assume that the key is name and assume that the contents of this form field is "info". eformmail will look for a configuration file of the name info.conf.

Because eformmail uses the content of the key field to create a file name, the contents of the key field should consist of characters that make a valid file name. Else you won't be able to create that configuration file. Spaces and such are fine, but if the contents of the key field could be something like "this | is > not < a good filename", choose another key.

The key configuration file contains the following items:

  1. Where to get the values for the required email header fields:
  2. Where to redirect upon successful send.
  3. Where to redirect upon unsuccessful send.
  4. If and how the message must be formatted. The message is marked up as XML, so the usual candidate to process this would be an XSLT processor.
  5. A list of zero or more fields with should be validated. The contents of the fields in the form must conform to the regular expression that is specified.
    Any regular expression can be specified between the '/' characters. Precoded regular expressions can be specified by a name like 'email' which will validate the contents of the field against an email address.
# Key configuration file for eformmail.

# Where must contents of form be sent to?
# Contents of this field is copied straight to the To field of the email.
# This is a required field.

to = email@somehost.net


# In case the form contains a field where users can supply an email
# address, list that field here.
# The contents of that field will be used in the From field of the email.

from field name = from


# In case users don't have to supply an email address or when the
# email address is empty, use the contents of this field for the From
# header field of the email.
# This is a required field.

from = feedback@localhost


# In case the form contains a field which can be used as the subject
# of the email message, list that field here.
# The contents of that field will be used in the Subject field of the email.

subject field name = subject


# If subject prefix is set, it is prepended to the subject.
# This helps to identify messages send by eformmail.

subject prefix = [feedback]


# In case the form does not contain a subject, or if the subject is
# left empty, the contents of the following field is used in the
# Subject field of the email.
# This is a required field.

subject = (No Subject)


# Transformation of the body. Input is XML, so the transformation is
# probably an XSLT processor. The current directory is the eformmail
# directory, so style sheets do not have to be prefixed with the full
# path.
# It is considered an error if the program exits with any error code
# then 0.

#transform = /usr/local/bin/Xalan - test.xsl


# Form fields can be validated as well.
# A validation line is of the form:
# validate [field name] = type | /regular-expression/
#
# Recognized types are: double, email, integer, nonNegativeInteger, url
#
# Examples:
#   validate from = email
#
# Or
#
#   validate number = /[0-9]+/
#

validate from = email

#validate subject = /.+/


# If sending the email was successful, the user is redirect to this page.
# The contents of this field must be a full URL, a partial reference
# will not work.

success redirect = http://localhost/success.html


# If any other error occurs (for example the email could not be sent)
# the user is redirect to this page.
# The contents of this field must be a full URL, a partial reference
# will not work.

error redirect = http://localhost/key_error.html

The HTML form

If all has been setup, you can adapt or create an HTML form. The action of the form should refer to the location of your eformmail.cgi program. The method should be "post". Both the application/x-www-form-urlencoded and multipart/form-data encodings are supported. eformmail.cgi shouldn't be used yet to email binary files. They probably have to be sent as attachments to the email. This is scheduled for a future release.

<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">

<head>
<title>Test form</title>
</head>

<body>
<h1>Example form</h1>
<form method="post" action="/cgi-bin/do_not_use_this_name.cgi">
<p><input type="hidden" name="key" value="berend"/>
<label for="from">From: </label><input name="from"/></p>
<p><label for="subject">Subject: </label><input name="subject"/></p>
<p><label for="subject">Message: </label><textarea name="body" rows="10" cols="60"/></p>
<p><button name="Submit">Submit</button></p>
</form>
</body>
</html>

It will look like this:

Example form