Introduction to Form Mail
Feedback from users is important to most commercial websites (and some hobby/information sites). The simplest way to allow feedback is to publish an email address and, possibly create a link with an url that reads something like mailto:wilma. firstname.lastname@example.org. When a user clicks the link, their default email client (e.g. Outlook Express) will open.
The next method of providing feedback is to create a form that the user fills in and sends to you. This has the advantage that you can request specific data. You create the form with the following HTML code
<form action="mailto:email@example.com?subject=Dino" enctype="text/plain" method="post"> ...... form contents </form>
However, this still needs the user's email client to send the data (a bit clunky) and you may not wish users to know the address to which that data is sent. In addition, you might want the data to be sent to several departments and this would require automated forwarding at your end.
Form Mail Programs
The solution to the problems outlined above is to use a form-mail program. Such programs run on the server (not on the user's computer). The form data is sent to this program and the server then sends it to the required address(es).
There are several tasks in creating a form mail system.
- Create the HTML page (including the form) in which the user enters required data.
- Validate the data and return the user back to the page highlighting errors (if any).
- Send the form data.
- Issue a confirmation so that the user knows the mail was sent correctly.
Uniform Mail : Main Features
- It is platform independent. The unix sendmail program
is not required. Instead, it uses the smtp module that
is standard to modern distributions of Perl.
It has been tested on Windows 2000 and XP systems as well as Unix servers.
- It is secure. One potential problem of form-mailers is that they can be hijacked by spammers to send unsolicited mail. When configured correctly, Uniform Mail cannot be usefully hijacked.
- It is powerful and flexible.
Many configuration parameters can be specified by url as well as by file.
- A comprehensive diagnostic mode should enable you to quickly discover the cause of any problems during testing/configuration.
- The format of the result page can be adjusted using the file uniformmail.css.
- Copies can be sent to any number of additional recipients. No additional email forwarding is required.
- Ticket numbers can be generated automatically and placed in the subject line.
uniformmail.js can be used to validate several types of
New (V 2.0)
- Most configuration parameters can be specified indirectly using (hidden) data fields in the form.
- The result page can be injected into another static html page.
- The perl script can validate data using regular expressions.
- A receipt can be sent.
What Uniform Mail cannot do
- It is not a webmail program. It cannot be used to read emails.
- It is not a bulk emailer. It does not support contact or mailing lists.
- It cannot generate html forms. These must be created as common html pages.
- It cannot be used to send HTML data or attachments. Only plain text is allowed.
- Also see authentication.
Having downloaded the Uniform Mail package, the first task is to install the main program, uniformmail.pl on your server.
- The Uniform Mail package contains relevant parts of this website.
- All files required for installation and testing are located in the script directory.
- Versioned file names such as uniformmail_1x.pl may be used in the package, however, when installed on your server, you should use the generic name uniformmail.pl or uniformmail.cgi - this will allow you to upgrade to newer versions without editing html pages.
uniformmail.pl is a perl script. Normally you should place it in a subdirectory of /cgi-bin. e.g. create a directory called formmail in the /cgi-bin directory and upload uniformmail.pl into this directory. When uploading, you must use ASCII mode otherwise the end-of-line markers may be invalid and the script will fail.
- The cgi-bin is a special directory, it can only be created by an administrator.
- If the cgi-bin does not exist, your hosting package may not include cgi support.
Internet Explorer and FTP
If you use the built-in FTP capabilities of Internet Explorer to upload your files, you've got a problem - it does not seem to support ASCII mode so you will have to use the command-line program ftp.exe. You will need to use the commands open (to connect), ascii (enter ascii mode), cd (change directory), dir (get directory list) send (upload the program) and quit.
You must set the access rights of the script file and the directory to 755. If you have command-line access to the server, this is typically done using the chmod command. If you are using Internet Explorer, right click the directory and choose properties from its popup menu. An array of boxes will be displayed representing 9 attributes. The Owner must have complete access (all three boxes ticked). Other groups should be given execute and read access. Repeat this process for the script file uniformmail.pl
Testing the installation
To verify that it has been installed correctly, open a browser
window and type in an url of the form :-
If it is working correctly, an error page should be displayed that reads something like MAIL ERROR: File not found - uniformmail.params. (Don't worry if a slightly different error message is displayed, it just means the script has been modified slightly since this was written.)
If it fails, do the following.
- Check that the case of each url character is correct. URLS ARE CASE SeNSItive !!!!
- Check that you have set the access rights correctly for both the script file and the directory.
- Check that you uploaded the script file in ASCII mode. This ensures end-of-line markers are translated correctly.
- Check that uniformmail.pl is located in the /cgi-bin directory (or a subdirectory thereof).
- Check your webserver tech support pages and ensure that the path to perl directory corresponds exactly with the value on the first line of the script file. (Open the script file with a plain text editor such as Windows Notepad and if necessary, adjust and upload the new version. NB The first two characters of the line must be #! Also check that the file is not obviously corrupted - there should be no strange characters. If there is a strange character at the end or beginning of each line, it is because the end-of-line markers have not been translated correctly. Try using a different editor such as Windows Wordpad but be sure to save any changes in plain text mode.)
- Try renaming the script file uniformmail.cgi.
- Finally, try uploading in BINARY mode. This may work if your server is running Windows rather than Unix/Linux.
- If none of these helps, you will need the help of a webmaster or some other tech support. Unfortunately, Cathonian Software cannot offer such support.
- Assuming it is working, you will need to upload the files
uniformmail.params and uniformmail.css
These files must be placed in the same directory as uniformmail.pl. The first file is essentially a security file. General purpose form-mail scripts can, in theory, be abused by people sending unwanted emails - this must be prevented. The second file is a style sheet used to display success or error messages. This is not essential and you may safely modify this file to suit the style of your website. Both files must be uploaded in ASCII mode.
- Re-enter the url again (or press F5).
Again, an error message should be displayed. It should be one of the following :-
1) MAIL ERROR: server must be specified in .params file.
2) MAIL ERROR: CREATE
3) MAIL ERROR: To: address missing.
You must edit the file uniformmail.params (but keep a copy of the original file for reference purposes).
If 1) or 2) is displayed, you must edit the mailserver value. Use the name of your smtp server - this will be the value set in your email client (e.g. Outlook Express) and is typically smtp.yourdomain.com or mail.yourdomain.com or simply yourdomain.com. The value localhost (or possibly mailhost) may be preferred on some systems.
You must also edit the to value. Use something like "FORM MAIL"<firstname.lastname@example.org>.
The "quoted" part is the display name. The part in <angle brackets> is the email address.
- Having edited and uploaded this file, re-enter the url again
(or press F5).
This time the mail should be sent successfully to email@example.com, HOWEVER, if this mailbox has not been created, the mail will never arrive!!
Of course, you haven't sent anything useful. The actual body of the email can be specified in the url, but this is disabled by default. Normally, you would call uniformmail.pl using the form submit method or a form submit button. In this case, all the data from the form elements is collected automatically and posted to uniformmail.pl which reads the data and sends it to the required address(es).
- Now study the examples. Don't try to absorb every detail, just get an idea of how it works.
Smtp servers may require authentication, unfortunately, this is not supported by Uniform Mail. However, authentication is not normally required if :-
- The connection to the mail server is local.
i.e. you are using an smtp server on the same domain as the mail program.
- Mail is sent only to local mailboxes e.g. firstname.lastname@example.org
Since both these criteria will be met normally, you should not experience problems. If both these criteria are met (or you cannot meet one of them) and you are experiencing problems :-
- Contact your network administrator, explain the problem clearly and concisely - they may be
prepared to change the server configuration.
- Using a text editor such as notepad open uniformmail.pl and search for authentication.
You may embed a username and password in the program code. HOWEVER, whether this works is dependent on what authentication protocols are supported by the mail server and by your distribution of perl. THIS CODE IS UNTESTED.
Also, placing a username and password in a text file, even one that cannot be read by the public, should not be done without due consideration of the security implications.