Mail::SimpleList README
-----------------------

Version 0.70, Sun Jun 15 19:11:31 GMT 2003, somewhere over Alabama (maybe)

Mail::SimpleList is a set of modules for creating and using small, simple
mailing lists.  They're intended to be temporary and very easy to use.  They're
not tremendously featureful, but they work pretty well.

The idea came about one afternoon when we were debating what to do after work
on Friday.  We'd sent several mails back and forth and the Cc line had grown
unwieldy.  One person said, "Take me off the list; I'll be out of town", but
not everyone had received that message yet and the replies were getting
unwieldy.

What we needed was a simple way to start a small mailing list that would only
be active for a few days, where everyone could subscribe or unsubscribe at
will.

That's what Mail::SimpleList does.

For more information, feel free to consult the talk I gave to the Portland Perl Mongers (http://pdx.pm.org/) on 11 June 2003.  The slides are available at:

	http://wgz.org/chromatic/talks/MailSimpleList/

INSTALLATION
------------

First, run the Build.PL file to create the Build program.  Then install as
normal:

	$ ./Build
	$ ./Build test
	$ sudo ./Build install

All of the tests should pass.  If not, please send the complete diagnostic
output to the author and we'll try to fix the bugs.  This should work on any
Unix system and probably elsewhere, but that'll depend on several other
components.

To use this program, you need to create a new account on your mail server.  I
use 'alias'.  This user also needs a writeable directory.  I use
/home/alias/aliases/.  Make sure this directory exists and is writeable by this
user.

This user must also be able to receive e-mail and execute a procmail-style
.forward or .qmail file.

This user must also receive mail with an optional delimiter.  For example, the
user 'alias' must be able to receive mail to 'alias+somelistsname'.  The
extended name must be passed through to the program for mail to reach any
lists.

See the examplefilter.pl file for the recommended way to execute the mailing
list manager.  The $alias_dir variable must contain the absolute path to the
aliases directory -- if this path is incomplete, the program will fail.  Put
this file in the alias user's path and make sure it is executable.  I like
/home/alias/bin/simplelist.pl.

Your .forward or .qmail file should contain something like the following:

	# .forward style
	| "/home/alias/bin/simplelist.pl 2>> simplelist.log"

or

	# .qmail style
	preline /home/alias/bin/simplelist.pl 2>> simplelist.log

Please consult the documentation for your mail delivery program if neither of
these work.  The log file can be handy for determining path and permissions
problems.

USAGE
-----

This information is also contained within the POD of Mail::SimpleList:

	$ perldoc Mail::SimpleList

Creating a list is simple.  Just send an e-mail to the alias user on your host.
To create a list, the mail subject must start with *new*.  The body of the list
should contain a list of e-mail addresses to subscribe to the list.  As the
sender, you will be marked as the list owner and you will be subscribed
automatically.

The list creator will receive an e-mail if the list is created successfully.
It will include the posting address of the list.  All other users will be
notified that they have been subscribed to the list.

Posting to the list is simple; just send a message to the list alias.  Anyone
included in the To: or Cc: lines of the e-mail will automatically be subscribed
to the list.

Unsubscribing from a list is also simple.  Send a message to the list alias
with a subject starting with *UNSUBSCRIBE*.  You should receive a success
message.


DIRECTIVES
----------

As of version 0.60, you can also specify additional directives in the body of
the creation message.  The useful directives right now are 'Expires',
'Auto_add', and 'Closed'.  Directives precede any subscribable addresses.  They
take the form:

	Directive: argument string

Aliases can be closed to non-members.  This directive:

	Closed: yes

will create a list that does not allow messages to be posted from
non-subscribers.  They can receive mail also sent to the alias, however.

You can create an alias that will accept messages for a limited period of time.
The Expires directive takes a time string when to expire the alias in the form
of Months, weeks, days, hours, and minutes.  Thus this directive:

	Expires: 1M2w3d4h

will make the alias expire in 1 Month, 2 weeks, 3 days, and 4 hours.  For the
purpose of simplicity, one Month is equal to thirty days.

Messages sent to the alias after the expiration period is over will not be
delivered.  The sender will receive a message to this effect.

Aliases automatically subscribe addresses found in the Cc header by default.
The Auto_add directive controls this.  Saying:

	Auto_add: no

will disable this feature.

Added addresses will receive the standard subscription notice and they will be
removed from the headers of the message, so as not to receive duplicate
messages.  For now, these addresses must appear in the Cc header, not the To
header.

ADVANCED USAGE
--------------

The auto-generated list aliases can be unwieldy.  Since everything is stored in
simple text files, one per list, you can create a symlink to an alias with a
nicer name and post to that list instead.  This is much nicer for
longer-lasting lists.

If subscribing and unsubscribing is too difficult, you can edit the files
manually, if you know YAML sufficiently well.  It's really easy, so it
shouldn't be much trouble.

ENHANCEMENTS
-------------

This is intended to be a simple program with a simple purpose.  It does just
about everything I could ever want right now, but there are a few improvements
up my sleeve.

Any address in the To header besides the alias address appears to wreak some
havoc with the program.  Try to avoid this for now.

This is all the documentation there is for now, except for the tests.  The
code's pretty simple, and I'm supposed to give a talk on this at the June 2003
Portland Perl Mongers tech meeting, so I'll have better docs soon.

There's no real help from within the program.  That should also be simple to
add, especially unsubscription options.

There's not much security on lists; address spoofing is possible.  I'd like to
add optional cryptographic signing.

There's no archiving yet, but it should be fairly easy to add.

There are a few hard-coded things, such as the alias delimiter.  That should be configurable.

There's always room for a few more tests, though I'm not sure what they might
be.

LICENSE, COPYRIGHT, and CREDITS
-------------------------------

Copyright 2003, chromatic <chromatic@wgz.org>

This software is made available under the same license as Perl.

This software would not have been possible without the inspiration of Simon
Cozen's Mail::Audit.
