/////////////////////////////////////////////////////
//                                                 //
//             P H P M a i l L i s t               //
//                 Version 1.8.0                   //
//                                                 //
//                 Copyright 2002                  //
//                  David Broker                   //
//          http://php.warpedweb.net/              //
//              All Rights Reserved                //
//                                                 //
//          In using this script you               //
//           agree to the following:               //
//                                                 //
//      This script may be used and modified       //
//              freely as long as this             //
//             copyright remains intact.           //
//                                                 //
//     You may not distibute this script, or       //
//           any modifications of it.              //
//                                                 //
//   A link must be provided on the website that   //
//             uses the script to:                 //
//          http://php.warpedweb.net/              //
//                                                 //
//      Any breaches of these conditions           //
//        will result in legal action.             //
//                                                 //
//      This script is distributed with            //
//        no warranty, free of charge.             //
//                                                 //
/////////////////////////////////////////////////////

Contents:

• About
• Included Files
• Installation/Usage
• Change log
• To do

About

PHPMailList is a powerful, yet simple to use, email announcement script.
It allows people to subscribe/unsubscribe through a web-based form, checking for valid addresses,
The web-based administration module allows the owner to send messages to the list, subscribe/unsubscribe people, view the list of subscriber, and configure the script.
Installation is simple, and configuration of confirmation messages, welcome messages and goodbye messages, as well as signatures are all maintained through the password protected administration.

Included Files

1. readme.html
   This file.
2. maillist.php
   The php script which controls the mailing and subscriptions.
3. list.dat
   The file where the email addresses are stored.
4. ml_config.dat
   The file where configuration details are stored.

Installation/Usage

1. Requirements:
   • PHP Version 4.0.2 or greater.
     It is best to make sure you have the latest version installed to ensure the script works as intended.
   • MAIL Options must be configured correctly on your server.
     Try this address http://www.php.net/manual/en/function.mail.php if you need more information or contact your system's administrator for more info.
   • VERY basic knowledge of PHP.
     This is required to install the script. You need to edit a few lines of the script, all of which is described in detail.
   • The browser you use for administration of the script must have Javascript enabled, preferable a version 5+ browser.
2. Edit the scripts: In maillist.php there is one line of code to edit.
   This should be set to the full server path to the configuration file (ml_config.dat). If using Windows you must use double backslashs (\\).

   EG: $config_file = "c:\\www\\config.dat";
       $config_file = "/home/user/maillist/config.dat";

3. Upload the files and set the permissions.
   * Note that it is preferable to keep the ml_config.dat and list.dat files in a seperate directory to the script, where they cannot be accessed by the public. *
   1. Upload the files to the server.
   2. If using Unix set the permissions as follows:
      list.dat: CHMOD 666 (or 777 if that fails)
      ml_config.dat: CHMOD 666 (or 777 if that fails)
4. Configure the Script:
   First access the administration module like so:

   http://www.path.to/script/maillist.php?action=admin

   This will bring up a Logon screen.
   Log on using:

   Username: user
   Password: pass

   You will see 4 options.
   Select "Administration" and click "Submit".
   From this page you can change the settings of the entire script.
   
   The only lines you really HAVE to edit are the first 5, there are:
   • Username
     Set it to something memorable. Note that it is case sensitive,
   • Password
     Also set it to something memorable, it is also case sensitive,
   • List Name
     The title of your mailing list.
   • List File
     The FULL SERVER PATH to the list.dat file.

     IE: c:\www\list.dat
        /home/username/list.dat

   • Owner's Email
     The email address all messages will be sent from. Must be valid.
   The rest are entirly optional, the script will function fine if you leave them as their default:
   • Default # Subscribers/page:
     The default number of email addresses shown per page when you "View Subscribers".
   • Banned Addresses
     Email addresses that are not allowed to subscribe.
     One email address to each line only.
   • Signature
     What you type in here will be included on the bottom of all welcome messages and messages you send to the subscribers.
   • Send Email Asking for confirmation?
     If this is ticked a subscriber will recieve an email asking them to confirm the subscription of their email address.
   • Confirmation Subject.
     The subject of the above mentioned letter.
   • Confirmation Message
     The body of the above mentioned letter.
   • Send Welcome Message?
     Will send a welcome message on sucessful subscription if ticked,
   • Welcome Message Subject
     The subject of that message.
   • Welcome Message
     The body of that message.
   • Send Goodbye Message?
     Will send a message on unsubscription if ticked.
   • Goodbye Message Subject
     The subject of that message.
   • Goodbye Message
     The body of that message.
   
   Note On Shortcuts:

   There are a number of "shortcuts", as I call them, built into the script.
   These allow for the proper working of the confirmation function as well as other messages.

   You just need to include these in the messages.
   Here is an example:

   "To confirm your subscription to %list_name% please visit this address: %confirm_url%."

   The script will automatically replace %list_name% with the name of the list and %confirm_url% with the URL the subscriber needs to go to to confirm their subscription.

   Here is a list of the shortcuts:

   %list_name%        =  The name of the list.
   %email%            =  The email address the email is being sent it.
   %confirm_url%      =  URL user must go to to confirm subscription.
   %subscribe_url%    =  URL users go to to resubscribe.
   %unsubscribe_url%  =  URL where user can unsubscribe.

   These shortcuts do not work when sending messages to the list, only in confirmation, welcome and goodbye messages.
5. Using the Script
   1. Subscribing/Unsubscribing
      There are 2 ways to subscribe/unsubscribe to the list.
      1. Just point your web browser to the script:

         EG: http://www.mysite.com/maillist.php.

         And you will see a subscription form. Just enter your email address to add/remove yourself from the list.
      2. You can use a form on another page to send the subscription request. It would look like this:

         Subscribe:
         <form method="post" action="http://www.path.to/script/maillist.php">
         <br><input type="text" name="email" value="Your Email Address" size="20">
         <br><input type="radio" name="action" value="sub" checked>Subscribe
         <br><input type="radio" name="action" value="unsub">Unsubscribe
         <br><input type="submit" value="Submit"></form>

   2. Administration
      To access it just go to the URL of the script like so:

      http://path.to/script/maillist.php?action=admin

      Note the "action=admin" this gives you access the the logon screen.
      There are 3 other options in the administration module than what was described above:
      1. Send a message. Pretty simple just type your subject/message in the text boxes and press send. Your will be asked to confirm the message before really sending it. A copy will be sent to the owner's email address.
      2. View Subscribers. Shows a count and list of subscribed email addresses.
      3. Add/Remove Subscribers. Allows you to clear all subscribers, add single subscribers or many at once, and remove some subscribers.
      That's all there is to it!

ChangeLog