Installing A Form to Email processor

Note from Russell (Author of FormMail)

Last updated: November 2008

Firstly, I'd like to thank Terry for creating this How-To guide for the manual setup of FormMail.

I've published this document with some additions to include my own strong recommendations when working with FormMail. The additions I've made are clearly identified.

I've also corrected a couple of typographical errors.

We hope you find this guide helpful, but I always recommend that you start by using our easy Configuration Wizard.

The Wizard is not free, but does come with a money back guarantee.

However, it's definitely the easiest way to get started. Once you've used the Wizard, you can come back to this document to understand what the Wizard has done for you. You'll then be in a better position to make further configurations manually including using advanced features.

Also, check out the How-To guides for more advanced features.

You can download Terry's original document.

Many years ago, among the numerous how-to guides, I wrote a guide for a form to email processor based around what was then the most popular script of it's type available, that from Matt's Script Archive - the venerable formmail.pl.

As is the saying, a year is an eternity in IT circles & over the past few years, I have migrated through the various security updates of the Matt's Script Archive version until it's final incarnation of 1.92. In the past year, a variety of problems have surfaced with the variety of versions, to the extent of a group of Perl coders have created more secure replacements for the Matt's Script Archive scripts such as Formmail.pl, WWWBoard & the like, entitled NMS & located at nms-cgi.sourceforge.net.

One thing with the current version of the NMS formmail.pl replacement is that it has no protection against automated spambots, which work by some spammer looking at your form, creating an automated submission tool & then trying it until it gets a successful submission. In the vast majority of cases, these automated submissions only ever end up in the inbox of the recipient of the form, but that seems to matter little to the idiots who perform this scourge of webmasters everywhere.

As one such victim, I decided to look for a secure form processor that was resistant to the various problems. The NMS project does have a tougher formmail.pl script but it's a bit of a pain, so I went looking for something a little better, such as adding an image verifier to the NMS script.

Tectite FormMail

During the course of this research, I came across a script simply titled formmail.php - from Root Software at www.tectite.com. This particular script had many of the features I was looking for & also had many options, including the latest incarnation of which has optional attack detection, an optional image verifier (also known as Captcha) & is under extremely active development.

Examples shown here have been tested on Mac OSX primarily, as well as a variety of other *nix based OS, plus a minor test for confirmation of Windows operation. You'll need to substitute the file paths & file names on your own installation, but you can follow the examples readily & be up & running in short order. This guide assumes that if you are reading this, you have a basic working knowledge of HTML, form creation & text editing.

To follow the guide properly, you'll need to download the latest versions of the following:

It's quite a large script, very well documented & requires PHP (obviously), plus you'll also need some PHP options enabled if you are going to use the image verifier.

First things first, you'll need to download the script from the Tectite site & open it up in a suitable text editor. On Mac OSX, you can open it in Text Edit, but Barebones software's TextWrangler is far superior for this purpose. On Windows, Notepad or Wordpad should suffice, or take your pick on other *nix installations. Alternatively, you can open up in Vi or Pico from a terminal on *nix based editors. Never use something like Dreamweaver - it will modify the script & cause it to be inoperable [Note from Russell: some customers have reported that recent versions of DreamWeaver no longer corrupt PHP scripts].

To enable the script to work, a simple one line change has to be made. With each version of the script (currently sitting at 7.14 as I write [Note from Russell: in recent versions of FormMail, these configurations are around line 240)]), the line number changes, but do a search for a line which looks like the following (outlined in blue in this example):

Note from Russell: above each setting is a URL to the documentation for that setting. The page at that URL contains lots of information and other examples. The documentation for TARGET_EMAIL is here: http://www.tectite.com/fmdoc/target_email.php

So, following the documentation and examples, we'll say that you only want to set this up for a single email address - let's use the example email address max@testing.com - for security purposes & because PHP doesn't like improperly used characters etc... in the wrong place, we need to specially format that address so it can be the only recipient - when properly modified, the line will now look like the following (substitute your own email address here):

Make sure you use the backslash before the dot-com part or you'll have problems. For the moment, you could leave it at that, save & then upload the script to your server (make sure it's in ASCII text format), but we want to ensure that it's working properly.

A little further down the script, you'll find a section where you can have alerts on script errors emailed to you - this is extremely valuable for debugging purposes. What you're looking for is a line similar to this (again outlined in blue in this image):

So you can receive alerts on problems, change this line to the following, again using the max@testing.com address - just substitute your own address instead:

Notice this time you can use the regular format of your email address. A note on this is to remove your address from this field once you are 100% sure your script is working. Why? Well, spammers will begin 'trying the doors' on your script as soon as they find it, submitting faulty submissions in an attempt to bypass your script's security & when they fail, you'll get each & every attempt in your email inbox, so better safe than sorry.

I don't recommend you ever disable DEF_ALERT (remove your email address from it). Alerts are the only way FormMail can tell you about faults. We often get told by customers "my forms were working but now they are not". The cause of this is the hosting provider changing something on the server. But if FormMail cannot send you an alert, it can't tell you about the problem! FormMail has anti-spam features built in, so it's rare that you'll get spam sent to you via an alert message.

You also have control over what alerts you get with these settings: ALERT_ON_USER_ERROR, ATTACK_DETECTION_IGNORE_ERRORS, and ALERT_ON_ATTACK_DETECTION.

Once you've set DEF_ALERT, you should immediately test that your server can send you email. Replacing "testing.com" with your website domain name, open this URL in your browser:

http://testing.com/formmail.php?testalert=1

For more information, or if you're having problems sending/receiving email, check this document: http://www.tectite.com/fmdoc/emailproblems.php

By this time, you're ready to implement your script, point your forms at the script, using something like the following (again substituting your domain name here) & begin testing:

Assuming there are no oddities, it's time to look a little further at what security measures you can take by enabling some nice features - brief descriptions of what some of the many options mean are found in the following table:

AT_MANGLE	Allows you to modify an email address within a form to hide or mask the address from spammers & spambots
FORM_INI_FILE	Enables you to use a configuration file to store sensitive configuration information such as form recipients, required fields etc..., that cannot be bypassed by spammers trying to get around your form
CHECK_FOR_NEW_VERSION	Checks for & alerts you for updates to the Formmail.php script.
ENABLE_ATTACK_DETECTION	Enables detection of some of the vast array of attacks on your forms.
ATTACK_DETECTION_URL	Send attackers to a particular URL of your choice. Note from Russell: remember that sometimes real users accidentally trip the attack detection. So, the URL you send them to should be quite friendly and explain what happened, and how to try again. From version 7.14, the default page for attack detection has been updated to include a link to this explanatory page.
ATTACK_DETECTION_MIME	Detect specially crafted email address submissions designed to fool vulnerable formmail processors.
ATTACK_DETECTION_SPECIALS	Enables formmail.php to detect people trying to bypass your special fields. Note from Russell: Specifically, this tests for email addresses in special fields that shouldn't contain email addresses.
ATTACK_DETECTION_MANY_URLS	Some spambots submit multiple URLs to forms - you can set how many URLs to trigger this detection.

Take a good look at these options. They are there to assist you in preventing spammers & other attackers from bypassing or exploiting your security - the script has great documentation surrounding each of these options, as well as a good number more.

The .ini file

Enabling a .ini file is as simple as creating a simple text file called something like formmail.ini or whatever you like & placing it somewhere that is able to be accessed by the formmail script, but not by any casual web surfer or deviant looking to exploit your configurations. Many servers will just serve this as a blank page if called upon anyway, but it's best to keep anything security related out of harm's way.

To enable formmail to utilize a .ini file, it's as simple as firstly creating the .ini file. It's easily constructed, as mentioned using a text editor. The format of the file can be as simple or as complex as you like, but a good setup for starters would be something like that shown in the image:

The file shown above is easily understood, provided you know what you're looking at. the part listing special_fields, tells formmail what it should do if a form comes in & if the form submission is missing the fields shown in the required line above, then formmail will reject the submission with an error.

The second section, headed email_addresses, allows you to include a single, or many addresses, without the need to include the actual address of the form's recipient within the HTML of your form. You can simply set your form to refer to recipients in the above example as:

This is of course much better than having an email address exposed in a form. You can also include more than one address in the .ini file within the [email_addresses] section, by simply adding each additional address in, separated by a comma in the following format:

Secondly, you will need to tell your formmail.php script to utilize the .ini file & you need to tell it where to find the file. Note carefully that the location you choose should be - a: accessible by your web server & - b: inaccessible to web surfers. going back to your formmail script, look for a line similar to the following example:

In between the inverted commas, you will need to specify the location of the .ini file you created in the last step, so enter the full path to your file as it sits on your server:

Now, save your formmail script & you're ready to roll with the .ini file being called whenever someone submits a form on your pages.

Image Verification (or Captcha)

If you see an image, it works, if not, then you need to look at your PHP installation & see what's missing or what permissions might be wrong. Click the reload button on your browser - the image should change. If so, job done & we can move onto the second part of image verification.

Before we do however, some people have difficulty reading the images with the background patterning, so if you're not happy with the amount of 'noise' around the image, you can clean the generated images up somewhat by changing a field in the verifyimg.php script. As with formmail.php, it's documented & you're looking for the following line:

Changing that line to replace FALSE with TRUE, once saved, calling up verifyimg.php will generate a cleaner image like so:

Bear in mind that this is less secure & spammers 'may' be able to read your images using OCR to gain a correct form entry. If your users are really pedantic, you can also change the field $bWobbleChar to FALSE to stop individual characters from moving about in the generated image. Changing either of these fields is lessening the security of your formmail, so the choice is yours.

The second part of image verification is another PHP script, this one called verifytest.php - This script basically does a call to the first script to pull out the image as shown above & 'reads' the image to grab the characters & numbers. Your form will input will go to this script & it will come back with a positive or negative result based on the form input & either accept the correct response or respond with an incorrect input notice that formmail.php hooks into.

Installation of this script once again is very easy - upload the verifytest.php script to the server, into the same directory as verifyimg.php - you can easily test if the script is working, just call it up in web browser & you should see a screen like this:

If you enter the correct letters, the script will respond with the appropriate 'correct response', or enter the incorrect letters & it'll let you know you were wrong. This is pretty much all the testing you need to do with image verification, so it's time to tie it all together & set up the form.

The Form

The sample form is normal HTML, pulling together all of the elements of a successful submission form that you can modify to suit your own setup. It's important to utilize parts of the form. The basic steps to getting this working properly are documented in the sample form, but essentially you need to modify the lines in the form to point at your server's formmail.php script as well as specify your address as the recipient.

Note that you need to ensure the above lines represent your own setup - the examples shown will not work on your server. To test out the operation of your form, it's as simple as making a successful submission using the form fields. If you submit the form & get an email with the submitted data, you're ready to roll.

Finishing Up

Neither of these are required inclusions, but if you include something along the lines of:

form submissions will be redirected according to a good or bad submission. If you do exclude either of these from your forms, formmail.php will provide a preformatted output for the user - excluding the bad_url directive will generate a page with the exact errors from the form submission to the user (such as missing fields etc...).

So that's it for the basics. You should now have a grasp of how formmail.php works & how to implement both .ini files & image verification, good luck with your formmail script. If you need help, do some research on the Tectite website, particularly the forums - if you can't find the answer there, ask!

-------------------------------------------------------------------------------------

Terry Allen does IT support, web design, server maintenance & setup plus a billion other things - you can reach him at hmag@ozemail.com.au