
#
# Group Mailer Readme.txt
# Version 1.2
#
# Files Included:
# manager.cgi - Add/Delete Users script
# mail.cgi    - Mailing Script
# readme.txt  - This file
#

******************************** NOTE **************************************
* If you wish to use the web interface version of this script point your   *
* browser to the mail.html to mass mail your users instead of following    *
* the mass mailing instructions in this file.                              *
******************************** NOTE **************************************

*===============================*
*       Steps to Install        *
*===============================*

1. Unzip the archive

2. Edit the variables inside each script according to the directions in the
   script.  Also edit the first line of each script to point at your perl
   interpreter.

3. If the directory you set as your $base_dir does not exist create it. Then
   chmod it to 777 by typing "chmod /path/to/directory 644" at the
   command prompt.  If the directory already exists just chmod it.

4. Now, setup a form where ever you want and let users register!  You can
   use the sample form that came with this archive if you do not know how
   to make forms.  More information on how to setup forms for Group Mailer
   is below.

*===============================*
*        Add User Form          *
*===============================*

All Group Mailer forms should be pointed at the manager.cgi with POST as
the request method.  Please use all capital letters for POST.

Sample:
<FORM ACTION="http://www.yourhost.xxx/cgi-bin/manager.cgi" METHOD="POST">

For the Group Mailer manager.cgi to work you must have some required fields
included in the form. You must have to have the following fields..

email
key

* email *

This field would be the place the user can input their email address.  This
is a required field.  The script will give an error if it is left blank.
Sample Code:
<INPUT TYPE="text" NAME="email" SIZE=20>

That line of code will create an input box for the user to enter their email
address.


* key *

This field is to specify which mailing list it is going to add to.  This field
usually should be hidden.  You should set this field to the name of your
mailing group.  If the group does not exist the script will automatically
create one inside the $base_dir.

Sample Code:
<INPUT TYPE="HIDDEN" NAME="key" VALUE="mygroup">

You can also make this a selection box and let users choose which group they
wish to be added to.

Sample Code:
<SELECT NAME="key">
<OPTION VALUE="mygroup"> My Group </OPTION>
<OPTION VALUE="hisgroup"> His Group </OPTION>

WARNING - Do not put any spaces for the group name! Also Please remember
that this is case sensative!


* Other Fields *

You can also make other input boxes for additional information and it will
automatically be entered into the database.  This is usefull for
personalizing each email.  These fields are not required and you can do
whatever you want.


*===============================*
*      Deleting Users Form      *
*===============================*

To create a form to allow you or your users to remove their email address
from the database there are 3 required fields that must be in the form.  No
other fields are neccesarry.  These forms should be very similar to the
adding form.

* email *

There must be an input box for them to enter their email; so the script can
search for their email address and remove it.

* key *

This should be a hidden field to specify which group he is going to be
removed from.  You can also make this a selection box.

* action *

There most be a hidden field called action to tell the script that it wants
to delete not add.

Sample Code:
<INPUT TYPE="HIDDEN" NAME="action" VALUE="delete">

Please remember that this is case sensative!


*===============================*
*        Mass mailing           *
*===============================*

To mass mail a group first create a txt file.  In that txt file write your
letter that you wish to email the group.  Then upload it to your $base_dir.

Now go into your cgi-bin directory or where ever your mail.cgi is.  And run
it with the following commands..

./mail.cgi <groupname> [message file] "[From]" [Reply-to] "[Subject]"

After you run the program it will ask you a few questions.  It will ask
who it is from, the subject, and the reply to email.  You can leave those
blank if you want and just press enter.

Example:

./mail.cgi mygroup news.txt "Web-Consult" web@web-consult.com "News Update"

That will get the group "mygroup" and mass mail them the letter inside
news.txt.  All the files must be placed in your base_dir for this to work.
If the file is not placed in your base_dir you can run it by pointing the
script to the full paths to the files.

To run the mail program in the background without having to remain logged
on to telnet type a '&' at the end.  Example:

./mail.cgi mygroup news.txt "Web-Consult" web@web-consult.com "News Update" &

*===============================*
*    Personalizing the mail     *
*===============================*

To personalize each mail you can enter tags inside your letter to be replaced
with their info.  For example: If the form you made, made them enter their
name into the database then you could write in the letter..

"Hello, <&name;> welcome to my web site."

<&name;> would be replaced with the field name "name".  So if in the field
"name" the value was their name then it would replace that with the persons
name.

The field names here are the same as what you set in the adding form.


*===============================*
*   Complete Sample Forms       *
*===============================*


* Add Form *

<FORM ACTION="http://www.web-consult.com/cgi-bin/manager.cgi" METHOD="POST">
<INPUT TYPE="HIDDEN" NAME="key" VALUE="mygroup">
<INPUT TYPE="TEXT" NAME="name" SIZE=20> Please Enter your name<BR>
<INPUT TYPE="TEXT" NAME="email" SIZE=20> Please Enter your email<BR>
<INPUT TYPE="SUBMIT" VALUE="Submit"><BR>
</FORM>

* Deleting Form *

<FORM ACTION="http://www.web-consult.com/cgi-bin/manager.cgi" METHOD="POST">
<INPUT TYPE="HIDDEN" NAME="key" VALUE="mygroup">
<INPUT TYPE="HIDDEN" NAME="action" VALUE="delete">
<INPUT TYPE="TEXT" NAME="email" SIZE=20> Please Enter your email<BR>
<INPUT TYPE="SUBMIT" VALUE="Submit"><BR>
</FORM>

