ListMail Documentation
A powerful, hands-free mailing list manager that allows you
to create multiple mailing lists. ListMail allows you to easily maintain your
mailing list via the web and comes with a plug-in for Matt's WWWBoard. Your
subscribers can create and send mail to all members of the list directly from
their browser. ListMail is capable of providing for uploaded attachments to be send
with messages. Users can add themselves quickly and easily. The webmasters page is
password protected and contains tools for administration and configuration of lists.
The admin area shows the list of all members, allows subscribing of non-members,
removal of users, and provides the security option to filter out unwanted IP Addresses,
URLs and Email Addresses. Includes Password encryption for user access and database
tracking of subs/unsubs and messages sent. Does not archive messages. Also contains
a simple plugin script for Matt's WWWBoard which allows all postings to be mailed
to list member.
Table Of Contents
COPYRIGHT NOTICE
Modules supplied with ListMail:
lmcfg.pl - CONFIGURATION MODULE
lmadm.pl - ADMINISTRATION MODULE
lmail.pl - MAIN MODULE
lmlib.pl - LIBRARY MODULE
wwwmail.pl - Matt's WWWBOARD PLUGIN MODULE
index.htm - sample index form.
multilst.htm - sample index form for managing multiple lists
INSTALLATION
ACCESSING LISTMAIL FOR THE FIRST TIME
ACCESSING ADMINISTRATION
Change Admin Password:
Exclusions:
User Maintainance:
USER ACCESS
WWWBOARD PLUGIN SETUP
Copyright 1998 P.M.Systems All Rights Reserved.
ListMail may be used and modified free of charge by anyone so long as this copyright
notice and the comments above remain intact. By using this code you agree to indemnify
Paul Mele and P.M.Systems from any liability that might arise from its use.
Selling the code for this program without prior written consent is expressly
forbidden. In other words, please ask first before you try and make money off of
my program.
Obtain permission before redistributing this software over the Internet or in
any other medium. In all cases copyright and header must remain intact.
Archived at:
http://www.pmsys.com/software/
Contact:
webmaster@pmsys.com
Handles the creation and maintainance of the ListMail configuration files.
This script must be run first in order to initially create the configuration
file for each list. ListMail allows for multiple lists, each with its
own configuration file. Administrators only need to point to the
directory and name of the file to be created, everything else is
handled through menus and input forms.
Handles user and security maintainance of the ListMail system.
Maintainance of these settings include:
- Maintenance of the admin password
- Removal of subscribed users
- Adding of unsubscribed non-member users
- Exclusion of
- IP Addresses
- URL Addresses
- Email Addresses
- Links to Configuration and ListMail scripts
This is the script users of the ListMail system use to access the system.
From this, users can subscribe, unsubscribe, send mail and list all members
of the list. When the administrator of the list logs on, additional links
to configuration and ListMail scripts will be accessable.
This file contains routines common to all scripts. Refer to other
scripts for details on setup and usage.
This script is designed to plug into Matt's WWWBoard. This can be found at
Copyright 1996 Matt Wright (mattw@worldwidemart.com)
Scripts Archive at: http://www.worldwidemart.com/scripts/
Using this plugin, all posts to the WWWBoard will also be mailed to all members of
the list. This allows members to stay in touch with postings without having to visit
the board. An added advantage is all members can contact all other members through
ListMail without maintaining individual address lists.
Use this in order to access the system. All scripts require parameters to be
passed to them in order to properly operate. This sample page uses form tags to
send the correct parameters to each script.
Installing ListMail is simple and requires a few steps to begin configuring
your own ListMail system
- Extract the archives using WinZip, PKZip, or a similar program into any folder on your system. This step must already have been completed if you are reading this file.
- Open each script file and modify the following information at the top:
- Change the location of perl on your server on the first line.
#!/usr/local/bin/perl
- $cgi_dir - url path to your cgi directory
$cgi_dir="http://www.yourserver.com/cgi-bin";
- $my_url - url path to this module
$my_url="http://www.yourserver.com/cgi-bin/lmadm.pl";
- $my_root - path to the root web directory relative to the server root
$my_root="/home/myname/public_html";
- require - path to the library file relative to the server root
require "/home/myname/cgi-bin/lmlib.pl";
No other settings need to be changed in these files.
- Log into your FTP server using your FTP client using your username and password.
- Place all script files, files ending in .pl, into your cgi-bin directory. Be sure
these files have read and execute permission (chmod 755)
Set permissions: 0755 (rwxr-xr-x)
- Create the following directories and set permissions using your FTP program. Then,
after you have created each directory, change permissions on the directories themselves
as instructed. Directory names are case sensitive, so be sure you watch your capitalization.
/home/myname/public_html/ListMail
Set permissions: 0755 (rwxr-xr-x)
Purpose: Main directory for html files.
/home/myname/public_html/ListMail/Files
Set permissions: 0777 (rwxrwxrwx)
Purpose: Storage of data files used by the system.
/home/myname/public_html/ListMail/Upload
Set permissions: 0777 (rwxrwxrwx)
Purpose: Temporary storage for uploaded files.
NOTE: All files for data and upload may be stored within
the same subdirectory. Keep in mind that all files within the directory
can be accessed by users. You may want to add a file named 'index.htm'
to prevent users the ability to browse the contents of the directory.
- Place the two html files into the ListMail directory.
Set permissions: 0755 (rwxr-xr-x)
Congratulations, you have now set up ListMail on your site! You now need to access
the configuration script to begin customizing your system.
URL: http://www.yourserver.com/ListMail/index.htm
You should see the display named 'Some List Configuration Settings'. From this
page you will be able to setup ListMail as you see fit. You can also access other
configuration files if you have multiple ListMail systems configured.
- General Information: General system settings such as sendmail location, data file location and return URL
- Name of mail list. This name will be used on headings and mailings
- Location of system mail program relative to server root directory.
- Directory where system data files will be stored relative to root of web directory.
- List Administrator's email address for all list members questions and comments
- Name of lock file. This file is used to lock user access while system files are being updated. Files will be created and maintained by the system in the specified data directory.
- Custom Message: Customized message files for mailed messages, HTML welcome and subscription verification. All settings in this category are optional, default messages will be used if left blank. Messages may be written offline and uploaded to the server or may be edited online.
- Complimentary subscription notification message to be mailed to the user after the administrator adds a Non-Member address. ListMail will automatically append an unsubscribe notice to the end of the message.
- Customized confirmation message to be mailed to the user after a successful subscription. ListMail will automatically append the email address and password entered in the subscription form to the end of the message.
- Customized message to be appended to the end of all mailed messages from list members. Usually contains information on how to unsubscribe from the list.
- Customized welcome message to be used after successful login to the list. Used on the page containing the main menu and displayed at the top of the page. Message can contain standard HTML tags where desired.
- Secondary verification page displayed prior to successful subscription. If defined, this is a customized html page, body only without tags, to be used to for the user to verify he wants to be subscribed to the list. Can be used for additional warnings due to certain content.
- Message upload area notes. Displayed in the message upload form for additional warnings prior to sending messages to list members.
- File Names: Names assigned to data file for users, admin, and email addresses. In most, if not all cases, the default names should be used. Files will be located in the data directory specified in 1c.
- File used to hold all subscribed members passwords and email addresses
- File used to maintain additional unsubscribed email addresses which the List Administrator wants mail sent to. Use when first setting up a list from another package or when there are already a number of email addresses aquired for a list. As each member subscribes themself, their address will be removed from this list and placed into the user file along with their password. Maintain through the LMADM script.
- HTML Tags: Specific settings for background images and color, text and link colors located in the body element of HTML pages generated by ListMail.
- Background color
- Text color
- Link color
- Active link color
- Visited link color
- Background Image
- URL to return user after using the system.
- URL for entry into the system. Used for mail messages and unsubscribe notices to inform the user where to go to gain access to the list.
- Log Files: Names of log files used to track Some List usage along with list subscriptions and removals. Log files are used to track system usage, subscriptions and removals.These files are not automatically purged and will grow in size as time goes on. Blank entries indicate no logs will be kept. Files will be located in the data directory specified in 1c.
- File used to track all mailings from list members. Items tracked are: date, user, subject, recipients and attached file name if binaries files are allowed
- File used to log all users subscribing and unsubscribing from the list. Items tracked are email address and passwords.
- Mail Preferences: General mail preferences to allow binary uploading, Subject prefix, Confirmation message and subject heading.
- Send copies of all subscription and unsubscribe notices to list administrator
- Allow binary uploads. If checked, please specify a world-writeable directory within your website to be used for temporary storage of uploaded files. Note, bandwidth will increase based on binary file sizes and number of list members.
- Subject prefix to be used on all mailings from the list.
- Confirmation subject to be used on all mailings for successful subcriptions to the list.
- Complimentary subscription Notification subject to be used on all mailings for successful subcriptions made for non-members by the list Administrator.
- Security: List security file names used to lock out specified URLs, email addresses, IP addresses and to specify authorized URLs for access to script. Files will be located in the data directory specified in 1c.
- Name of List Administrator's name and password file. If name is set the same as email address, the administrator will be presented with an additional button for accessing the functions in LMADM script when accessing Some List user area.
- Name of file used to hold unauthorized URLs.
- Name of file used to hold unauthorized IP Addresses.
- Name of file used to hold unauthorized email addresses.
- List of authorized URLs allowed to use the scripts. At the very least your domain and url in http format should be used. Separate all entries using commas.
Congratulations, you have now completed setting up ListMail on your site! The last
thing you need to do is to setup get yourself setup as the administrator. This module
allows you to handles user and security maintainance of the ListMail system.
When you first access the ListMail Administration module, you must setup an admin
name and password. Complete this form as required to initialize your name and
password as the administrator.
HINT: Each person subscribing to your system must provide an email address which
will be verified for correctness in syntax. To allow yourself as administrator to have
access to both Admin and ListMail User functions you should use a valid email address
as your Admin Name. Doing so will you to have direct access to both areas using a
single logon.
Selecting Change Admin Password will prompt you for the same information you provided
upon initial startup. Complete the form by entering your current password followed by
your new password.
There are three methods of excluding users from your ListMail system. Each has it own
benefit depending on the reason for not allowing the users or group of users from
your system
- IP Addresses
- URL Addresses
- Email Addresses
Enter the appropriate information for the option selected then click Add New. Once
a user or group of users have been entered, an additional option will be provided to
remove a banned addresses from being excluded.
Allows unsubscribed users to be granted access to the list by the Administrator.
Useful for adding new members from an existing list. Users entered by the method
are sent mailing, but will require an actual subscription to the system before they
can send messages to others. The following message is displayed at the logon screen
'NOTE: If you are receiving mailings from this list, but have never subscribed or been assigned a password then enter your email address leaving the password field blank to unsubscribe from the list.'
Subscribed members can viewed in a drop-down list format. Selecting a user and
clicking on the Remove button will remove the user from the list. This function
is useful for those users wanting off the list, but forgot their password.
Three options are provided at the initial logon screen. The user enters his/her
email address along with a password and selects one of the following options:
- Enter
- Subscribe
- Unsubscribe
Once into the system users can:
- Send to the List
- View List Members (Only the first part of an email addresses are shown)
- Unsubscribe
Message Send
- Enter the subject of the message
- Select whether or not you wish to have a copy mailed to yourself
- Enter the contents of the message
- If uploading is enabled, browse and upload the file to be attached
- Setup ListMail and configure as required. Be sure it is working properly before
attempting to plugin this module.
- Make the appropraite changes in the script according to the installation section.
- Open the WWWBoard module 'wwwboard.pl'.
- Locate the line '&new_file;'. This should be about 60 lines into the
module (using Version 2.0 ALPHA 2). This should be just before adding the new
link to the wwwboard page and just after parsing incoming variables.
- Add the following lines just after the line found in the previous step:
# Added for ListMail
require "$ENV{DOCUMENT_ROOT}/your-cgi/lmlib.pl";
require "$ENV{DOCUMENT_ROOT}/your-cgi/wwwmail.pl";
&WWWMail("cfg_file","user\@domain","user_pass","on");
NOTES:
- Replace 'your-cgi' with the name of your cgi-bin directory.
- Replace 'cfg_file' with the path and name of your configuration file for the list. This is relative to the root of your web directory.
- Replace 'user\@domain' with a valid email address belonging to the list. Be sure to precede the @ symbol with a backslash.
- Replace 'user_pass' with the appropriate password for the user_name provided. This password is not encrypted.
- The "on" argument allows a copy of the posting to be sent to the user defined. Without this, the user defined in the subroutine arguments would not receive a copy of the post.
- Save and re-upload the file to your server.