I have a simple, all-HTML website for my business as a performing magician, daveshepmagic.com. One of the most important features of that site is a simple email contact form. I recently moved that site to a new server and wanted to make sure the form mail worked okay. I had been using a version of Matt’s FormMail. It turns out that Matt’s FormMail is rather susceptible to spambots.

TFmail is a perl script for form mail, more secure than Matt’s FormMail, that is relatively simple to set up–if you know how. But there’s not very much online help to tell an average computer user how to do the setup.

I’ll try to do that here. I will assume you have FTP access to the server where your site is located. There are a lot of different FTP clients. I use Fetch on a Macintosh. If you want a free FTP client, the newest version of Firefox has an FTP plugin available.

The basic concept: Form email takes data that a user types into your website and converts it into an email that is sent to a specified recipient (usually you, the site owner). To give you an example, when people go to my magic site, I want them to be able to type some information into a form and then click a button, which will send me an email inquiry.

TFmail stands for “template form mail.” This software allows you to configure different templates for different kinds of email to be sent to you (or whomever). One big difference between TFmail and, say, Matt’s FormMail, is that with TF mail you put the definitions and configuration instructions into a separate configuration file (which is easy to create), instead of directly into the code for your web page.

Here are the steps I took to set up TFmail. (I will omit many, many false starts and do-overs.) My sites are all on BlueHost, and I was setting this up in an addon domain, but your mileage may vary. NOTE: most of these instructions come from a thread on the LunarPages forum, which was the most helpful resource I could find. However, my situation was not precisely what was described there, so I had to modify those LunarPages instructions a bit.

  1. Download the TFmail software. Once you get the zip file, unzip it. Read through the ReadMe file, but don’t get discouraged. It is written in geek-speak, and it assumes you know a lot already. I’ll try to help.
  2. Use a plain-text editor (Notepad, TextEdit, etc.; but not a word-processor) and edit TFmail.pl as follows:
    use constant DEBUGGING      => 0;
    use constant LIBDIR         => '/home/username/tfmail/lib';
    use constant MAILPROG       => '/usr/sbin/sendmail -oi -t';
    use constant POSTMASTER     => 'webmaster@yourdomain.com';
    use constant CONFIG_ROOT    => '/home/username/tfmail/cfg';
    use constant SESSION_DIR  =>  '.';
    use constant MAX_DEPTH      => 0;
    use constant CONFIG_EXT     => '.trc';
    use constant TEMPLATE_EXT   => '.trt';
    use constant ENABLE_UPLOADS => 0;
    use constant USE_MIME_LITE  => 1;
    use constant LOGFILE_ROOT   => '/home/username/tfmail/log';
    use constant LOGFILE_EXT    => '.log';
    use constant HTMLFILE_ROOT  => '/public_html';
    use constant HTMLFILE_EXT   => '.html';
    use constant CHARSET        => 'iso-8859-1';

    Now. In my opinion, the trickiest part of this whole process is to figure out exactly what to put for those directory paths specifying the location of LIBDIR, CONFIG_ROOT and LOGFILE_ROOT. The ReadMe document talks about putting files in secure directories on your server. I just wanted to get TFmail working. So later on, when I put files on my server, I just put everything into my cgi-bin folder and had TFmail refer to those paths from there.

    Where the above example (taken from the LunarPages thread) says, for example,


    I typed


    and it worked. (I figured this out after two calls to BlueHost support.) The dot (‘.’) means with reference to the current directory–wherever TFmail.pl resides. Since all my files and directories are installed within my cgi-bin directory, that’s how I refer to them. I didn’t have to type


    but you might have to do some version of this. You will have to ask a support person at your hosting service how to do this. Once you get this figured out, you should be golden. I’ll proceed to describe my own setup, and I hope it will be close enough to your own that you can figure it out.

  3. Using a text editor, modify TFmail_config.pl in a similar way:
    use constant DEBUGGING      => 0;
    use constant LIBDIR         => '/home/username/tfmail/lib';
    use constant CONFIG_ROOT    => '/home/username/tfmail/cfg';
    use constant CONFIG_EXT     => '.trc';
    use constant LOGFILE_ROOT   => '/home/username/tfmail/log';
    use constant LOGFILE_EXT    => '.log';
    use constant CHARSET        => 'iso-8859-1';

    At the bottom of the “user serviceable” section, you’ll see a place to enter a password. Choose a strong password (not easily decipherable, mix of alpha and numeric characters, some uppercase), enter it there, and remember it. This is is the password you’ll use to configure TFmail for the various form mail pages you set up on your site.

  4. Use your FTP client to set up some folders and install some files on your sever. Once again, I’m describing what I did, which works. It does not take advantage of the full security features of TFmail, but it works. (I may hack at it some more this week to strengthen the security.)
    • Within cgi-bin, create a folder called tfmail. Inside of that folder, create three more folders, called cfg, lib, and log.
    • Upload TFmail.pl and TFmail_config.pl to your cgi-bin folder.
    • Upload NMSTreq.pm, NMSCharset.pm, and MIME_Lite.pm (all parts of the complete TFmail set) to cgi-bin/tfmail/lib.
    • Using your FTP software, set file permissions for TFmail.pl and TFmail_config.pl to 755. (See your FTP client help for instructions on how to set permissions.)

    These are the only files you have to upload right now. You will now use the configuration interface of TFmail to create specific configuration files.

  5. In your browser, go to http://yourdomain.com/cgi-bin/TFmail_config.pl. This is an “acid test” moment. If you entered the path names correctly when configuring TFmail.pl and TFmail_config.pl, then you will see a window asking for your password. If you get a 500 error or some other error, something is wrong in the setup. Most likely you are referring to your files incorrectly, somehow. Alas, since there are so many different server setups in the world (I’ve used four different servers in the past three months!), you’ll have to call or write your tech support to ask about this. BUT–if you see the password window, you are now home free. Installation is basically done, and your task now is to configure settings for your own web-page form.
  6. Type your password into the box (that’s the password you entered into TFmail_config.pl before uploading that file). You’ll be taken to the configuration page. This is where all the important work happens with TFmail. What you will do in this page is state which fields are required in your form, state where the email is to be sent, state how you want the email to look, and even set up a web page that will show up for the user if the form is successfully submitted, and another page for a submission error.When you’ve sucessfully logged into the TF mail configuration page, you’ll see some start-off settings for a configuration file called “default.” You will modify those for your own use, and then at the bottom of the page, you’ll see a button and window saying “Save this configuration as”. You’ll want to give your new configuration a name that makes sense. Mine is called “online_inquiry,” for example. Once you save it, a button linking to it will appear at the top of the configuration page when you log in, so you can edit it later. (Incidentally, you’ll want to bookmark that URL to your TFmail_config page. You’ll go there in your browser any time you want to change something in the setup.)

    At this point, rather than just re-type stuff from the LunarPages forum thread, I’ll just refer you to that thread for how to set up your configuration. But let me say one very important thing that Priest, the support supervisor at Lunar Pages, left off his instructions: you must set up a log file in order for this thing to work, even if you don’t think you need a log of activity. If you don’t set up a log file, the thing will look broken in a strange and unpredictable way.

  7. Now you need to deal with the HTML code in your web page. When you saved your configuration settings with TFmail_config, the confirmation page included a line of code that you will need to include in your web page HTML, something like
    <input type="hidden" name="_config" value="online_inquiry" />

    Obviously, your line won’t necessarily have “online_inquiry” in it, but instead the name of the configuration file you just created in step 6. Now create a web page with some form tags in it. You’ll start the form section of your page with this line, or a line like it:

    <FORM METHOD="POST" ACTION="./cgi-bin/TFmail.pl">

    and you’ll close it off with


    In between those two container tags, you’ll need to put that line that TFmail_config generated, and then whatever form fields you want people to enter. You can put any fields you want here. Here are a few examples from my own site:

    <input name="realname" size="40" type="text" />
    <input name="eventtype" size="40" type="text" />
    <input name="telephone" size="13" type="text" />
    <input value="Submit" type="submit" />
    <input value="Clear form" type="reset" />

    Make sure you put those last two lines of code in at the end. Those create the buttons your user clicks to submit the information to TFmail.
    When you did the configuration and specified “required” fields, that only referred to fields that, when left blank, generate the error page for the user. Obviously you can use other fields, and in your configuration, you can also specify how any of these fields show up in the email you receive.

So now, having set up your TFmail configuration and written a web page with form mail code that points to it, see whether it works. Upload your HTML file to your server and open it in a browser. Fill in the form fields and see if it sends you an email. If it works, you’ll see a success page. You should also try submitting without including one of your required fields, to see whether the error page works. If all is well, you will get an email submitted automatically by TFmail.

I mentioned the LunarPages forum as a good resource for TFmail. Just remember that your pathnames will differ, and that you must create a log file in your configuration. If you need help with understanding HTML form tags, take a look at this overview of form tags.

Please feel free to email me if you have any questions about this. I’m no expert, but I might be able to give you some insight into your situation. No guarantees! Feel free also to grab the code from my site, daveshepmagic.com/contact.html. I put my form into a table, which was tedious to hand-code, but looks pretty decent.

4 Responses to “How to set up TFmail”

  • Thanks for this, made my afternoon a lil easier!!


  • Hi Dave – I have started using TFmail today as an alternative to formmail which is falling over badly on my web host. Thanks for this useful breakdown of the main points to consider – very useful.

    You may not be able to assist with my remaining query but here goes: I already have a confirmation page that I would prefer to use instead of the one that the configuration file provides. Is it possible to tailor the code to run my own ‘success’ page?

    Grateful for any advice you can provide.


    John Brindle

  • Yep, thanks. Helped a ton!

  • Thank you for this blog. Matts Form is making me nuts.

    When I submit I get this message “Application Error An error has occurred in the program ”

    I’m thinking this is because I have not made a log file.
    I have the ‘log’ folder on the server like you said but what is the ‘log’ files name and what is in it. Is it simply ‘.log’ with no information in it?

Leave a Reply