A PLAIN TEXT VERSION OF THIS DOCUMENT IS INCLUDED IN THE .ZIP ARCHIVE.

Installation and Usage
for MAILMATIC Survey and Mailing List Manager

This copy of MAILMAT.ZIP contains the latest revised
edition with all required files for a complete installation.

Revision Date: mailmat.zip - April 7, 1998
Copyright: 1996,1997,1998 by Joe DePasquale
E-Mail: crypt@getcruising.com
Website: http://www.GetCruising.com

========================================================================
This application is for Unix web servers running Perl 5.0 or higher.

Additional documentation is available at http://www.GetCruising/crypt
helpme.txt - How to install Perl scripts on a Unix server.
whatsnew.txt - Revision history for all 'CGI Scripts from the Crypt'.

Also visit the "Users' Self-Support Forum" to post questions and
answers, especially if you have some extra time, knowledge and
a desire to help some other poor lost souls!

THERE IS *NO* FREE *NOR* FEE-BASED TECHNICAL SUPPORT FOR THESE SCRIPTS!
Due to extremely limited time, E-Mail with technical support
questions WILL NOT BE ANSWERED! Please use the available resources
here and elsewhere on the WWW to solve problems.
E-Mail genuine bug reports to: crypt@getcruising.com

========================================================================

WHAT IT DOES:

MAILMATIC asks your visitors a few multiple-choice questions about your
website. Scores are accummulated in 'mail.ttl' and the user can view
the instantly-updated total survey results. If the visitor completes
the survey, results are also E-Mailed to manager.

If you also use HITMATIC, you can have the hit log lines for the
respondent included, so you can see where they been before they
answered the survey.

If user chooses to join one or more of your subject mailing lists,
a record is added to 'mail.dat' containing user's E-Mail address,
Name, Company, SubjectKeys and DateStamp.

When you place links to the script on your HTML pages, you can include
the SubjectKey for that page in the URL. This will cause the
survey to open with a subject checked [X] in the mailing list options.
The basic template for the survey page is 'mailtemp.html'.

The manager module (mailman.pl) allows the manager to send bulk
E-Mail to recipients on the mailing list using the BCC (blind-carbon-copy)
function of 'sendmail'. Everyone will receive a 'copy' of the message
which you are sending to '$toMail' as you will define in the script.
You can use any existing E-Mail address, usually one of your own.
Recipients will not see their own address nor any of the other
addresses on the mailing list. Recipients can be selected by subject
key(s) or by range of last-mailed dates.

During mail processing, a temporary log is made of the recipients in
'mail.log' and if users answer the survey while manager is editing or
sending, their responses are added to a holding file 'mail.tmp' and
are added to the regular 'mail.dat' file the next time the script is
run (if manager is not still using files).

There is a simple built-in text editor for composing the message and
there is an option to attach a signature file. Text is saved in
'mail.txt'.

MAILMATIC uses the Perl 'flock' function to prevent simultaneous
changes (corruption) of data files. A double-lock (using 'mail.flk')
wraps processes when 2 or more files must be open simultaneously.

========================================================================

INSTALLATION:

1. SETUP YOUR FILES -

Edit the survey template 'mailtemp.html'. Find this line and change
the path to your script's URL:

<form action="http://your-server.com/cgi-bin/mailmat.cgi" method="POST">

The script needs to find the special comment lines that look something
like <!-- MAILMATIC BLAH BLAH BLAH --> so be sure not to change or
delete them. Otherwise you can add any HTML text or graphics to the
page. You can even leave it just like it is!

The 'mail.ttl' file has a line for each question in a 5-question survey.
Add or delete lines so that the number of lines EXACTLY matches the
number of questions in your survey. Follow the format in the file.

2. CONFIGURE THE SCRIPT -

After you have the script running with the sample questions, you
can devise your own survey questions by altering the 'keys' and
'values' in the configuration section below.

Open the main script file 'mailmat.cgi' in a text editor and change
the sample paths in the "CONFIGURE THE SCRIPT" section,
following the instructions found there.

3. UPLOAD FILES AND SET (CHMOD) PERMISSIONS -

All files should be uploaded in ASCII mode.

Place 'mailmat.cgi' (755) and 'mailman.pl' (644) into your cgi-bin
directory.

Create a directory named 'mailmat' (755). Place 'mailtemp.html' (644),
'mail.dat' (666), 'mail.ttl' (666), 'mail.txt' (666), 'mail.flk' (666)
'mail.log' (622), 'mail.tmp' (666) and 'mailmat.pwd' (666) into the
'mailmat' directory. Change the '.htm' extension to 'html'.

If you enable the back-up option, create an empty directory named
'bak' (777) which can be shared with other 'CGI Scripts from the Crypt'
that make back-up files. This directory MUST be world-writeable!

========================================================================

HOW TO USE IT:

To run the main script from the web, enter the URL of the script
itself. This will cause the survey page to load in the browser,
using the questions you added in 'CONFIGURE THE SCRIPT' ..

Example -
http://www.GetCruising.com/cgibin/mailmat.cgi

To load the survey page with SubjectKey 'G' checked ..

Example -
http://www.GetCruising.com/cgibin/mailmat.cgi?checked=G

To RUN MAILMATIC MANAGER, use 'manager' as a query-string.

Example -
http://www.GetCruising.com/cgibin/mailmat.cgi?manager

The response should be the password authorization form. The
initial password is 'password'. Of course you should change it soon
to something unique by entering a new password in the
'Change Password' box.

Next, you will see the EDITOR screen. The simple built-in editor allows
composition and editing of the E-Mail message. When you SAVE or SEND
your first message, 'mail.txt' will contain the Subject/Message.
Thereafter, everytime EDITOR is started, the contents of 'mail.txt'
will be loaded for editing. After making desired changes to message,
press SEND MAIL to begin processing or SAVE MESSAGE if you do not
want to send mail at this time.

Each recipient's record contains the date they were last E-Mailed
and the Subject Key(s) they selected in MAILMATIC. You can fill-in
a DATE RANGE and/or SUBJECT KEY(S) to restrict the recipients to
matching records only. Leaving these boxes at their defaults will
send the mailing to everyone on the list.

========================================================================

AND REMEMBER, SPAM IS NOT JUST PORK ENTRAILS!

HOME|PLEASE VISIT GETCRUISING'S SPONSOR: