readme

webmail java unix programming

README

System requirements
In order to run Webmail your server must be running Perl 4.036 or newer.

Installation of Webmail
Basically, to install Webmail all you have to do is ftp it to a cgi directory. There are, however, a couple things you will want to check, just to make sure Webmail can function properly on your system.

Unix users, make sure the file is executable itself, if it isn't already. To do this, telnet into your cgi directory and type the following command:

chmod 755 webmail.cgi

If you are using a Dos-based or Macintosh system, you will need to make sure that .cgi files are running the perl interpreter. If this is a problem, you can always rename the file to run the interpreter correctly.



User's Guide

Configuration Options

"Normal Mail" vs. "Sendmail"

Webmail has the option of using either "Normal Mail" or "Sendmail". "Normal Mail" automatically sets the "reply-to" email address of messages generated by Webmail to the default address for the server's mailing system. It's usually something like "[e-mail]". For most people's purposes this is fine, so this is the option that is used when you first install it.

"Sendmail" allows you to manually set the "from" email address and "reply to" email address. To switch Webmail to this mode, edit the file named webmail.cgi where it says this:

# Set MODE to '1' - normal mail '2' - sendmail
$MODE = '1';
Simply change the line that says "$MODE = '1';" to "$MODE = '2';".

Then modify the next few lines of that file to reflect the location of the "sendmail" program on your server, the from email address, and the reply to email address:

# If MODE set to '2' this SENDMAIL program is used
$SENDMAIL = "/usr/sbin/sendmail"; # Adjust as needed
# FROM_EMAIL is only used in mode '2' (sendmail mode)
$FROM_EMAIL = 'youremail\@yourdomain.com';
# REPLY_EMAIL is only used in mode '2' (sendmail mode)
$REPLY_EMAIL = 'replytoemail\@yourdomain.com';


Sorting Mode

When you install Webmail it is set to list the form fields in alphabetical order in the emails that it sends. You can change this so that it lists the form fields in the order that they were found on the web page, by editing the following option in the webmail.cgi file:

# Set SORT_MODE to '1' - alphabetic sorting or '2' for sorting as found
$SORT_MODE = '1';

Setting Up Your Form

The trick to effectively using Webmail is in the form. Once Webmail itself is installed, you can forget about it. We assume you know how to create and use forms already. The form you create can contain as many fields as you like. There are, however, a few things which must be present. These are:

* The location of your copy of Webmail.
* The address to send the email to.
* The subject line of the email.
*
An example (feel free to copy this if you like) of the code needed to implement Webmail is included below, with an explanation of each line. Note: this is just the code to implement Webmail -- no information is collected from the user. In fact this code alone will do nothing. You will need to include text entry boxes, pull down menus, or other types of form inputs for the information you want to collect and a submit button in order to have a functioning form.

<FORM ACTION="/cgi-bin/webmail.cgi" METHOD="post">
<INPUT TYPE=hidden NAME="send_to" VALUE="[e-mail]">
<INPUT TYPE=hidden NAME="subject" VALUE="Your Subject">
<INPUT TYPE=hidden NAME="response_url" VALUE="http://www.sitename.com/thanks.html">
</FORM>

Line 1. Gives the relative location of Webmail on your server. If you're using the example form, edit the details to correspond with your server.

Line 2. Gives the email address Webmail should send the email to. Again edit to your needs.

Line 3. Gives the subject line of the email. This should also be changed to reflect your purposes.

Line 4. Gives a response url. This is optional and will redirect users to the specified page once they submit the form. If you don't use this, then it will display a plain white page saying "WebMail Response - Thank you for your submission. The information you provided is being emailed to [email address]." (Where "[email address]" is the email address that you set up in Line 2.)

Once you have created the form you want to use, include it in the HTML for the page it is going on. Now FTP that page to your server. That's really all there is to do. Whatever email address you defined as the recipient of Webmail's outgoing email should begin receiving that email as soon as someone fills out the form.

Should you experience problems with the mail (i.e. it doesn't get sent), you will probably need to adjust the $MAIL setting in the script. Ask your system administrator the location to use for the system's mail program.