The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mail-SimpleList-0.94
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ Mail::SimpleList

NAME

Mail::SimpleList - module for managing simple, temporary, easy mailing lists

SYNOPSIS

    use Mail::SimpleList;
    my $list = Mail::SimpleList->new( 'alias' );
    $list->process();

DESCRIPTION

Sometimes, you just need a really simple mailing list to last for a few days. You want it to be easy to create and easy to use, and you want it to be easy to unsubscribe. It's not worth setting up a complex system with one of the existing mailing list managers, but it's nice not to worry about who does and doesn't want to participate.

Mail::SimpleList, Mail::SimpleList::Aliases, and Mail::SimpleList::Alias make it easy to create a temporary mailing list system.

USING LISTS

INSTALLING

Please see the README file in this distribution for installation and configuration instructions. You'll need to configure your mail server just a little bit, but you only need to do it once. The rest of these instructions assume you've installed Mail::SimpleList to use the address alias@example.com.

CREATING A LIST

To create a list, send an e-mail to the address alias@example.com. In the subject of the message, include the phrase *new*. In the body of the message, include a list of e-mail addresses to be subscribed to the list. For example, you may create a list including Alice, Bob, and Charlie with an e-mail resembling:

    From:    you@example.com
    To:      alias@example.com
    Subject: *new*

    alice@example.com
    bob@example.com
    charlie@example.com

You will receive a response informing you that the list has been created. Alice, Bob, and Charlie will each receive a response indicating that you have subscribed them to the alias. Each message will include the alias-specific posting address. In this case, it might be alias+3abfeec@example.com.

You can specify additional directives when creating a list. Please see Directives for more information.

POSTING TO A LIST

To post to a list, simply send an e-mail to the address provided in the subscription or creation message. It will be sent to everyone currently subscribed to the list. You do not need to use the Reply-All feature on your mailer; Mail::SimpleList sets the Reply-To header automatically.

If you do include other e-mail addresses in the CC header, Mail::SimpleList will, by default, automatically subscribe them to the list, informing them of this action and sending them the current message. No one should receive duplicate messages, even if he is already subscribed.

UNSUBSCRIBING FROM A LIST

To unsubscribe from a list, send an e-mail to the address provided with a subject line of *unsubscribe*. In Bob's case, this message might be:

    From:    bob@example.com
    To:      alias+3abfeec@example.com
    Subject: *unsubscribe*

    no body here; it doesn't matter

Bob will receive an e-mail confirming that he has been unsubscribed. He will not receive any more messages directed to this list unless he resubscribes.

CLONING A LIST

To clone a list, duplicating its subscribers but setting yourself as the owner and changing other attributes, send a message to the main address (in this case, alias@example.com) with a subject containing the command *clone* and the address of the list to clone. Alice could clone the list above by sending the message:

    From:    alice@example.com
    To:      alias@example.com
    Subject: *clone* alias+3abfeec@example.com

    doug@example.com

Alice will receive a list creation message and the members of the cloned list will each receive a message informing them that they have been added to the clone. Doug will also be added to this new list.

DIRECTIVES

Lists have seven attributes. Creating a list will set two attributes, the list owner and the list members. You can specify the other attributes by including directives when you create or clone a list.

Directives go in the body of the creation or clone message, before the list of e-mail addresses to add. They take the form:

    Directive: option

Closed

This directive governs whether or not the list is closed to non-subscribers. If so, only members of the list may send a message to the list. Everyone else will receive an error message indicating that the list is closed.

This attribute is false by default; anyone can post to a list. To enable it, use either directive form:

    Closed: yes
    Closed: 1

Expires

This directive governs how long the list will be available. After its expiration date has passed, no one may send a message to the list. Everyone will then receive an error message indicating that the list has expired.

This attribute is not set by default; lists do not expire. To enable it, use the directive form:

    Expires: 7d2h

This directive will cause the list to expire in seven days and two hours. Valid time units are:

  • m, for minute. This is sixty (60) seconds.

  • h, for hour. This is sixty (60) minutes.

  • d, for day. This is twenty-four (24) hours.

  • w, for week. This is seven (7) days.

  • M, for month. This is thirty (30) days.

This should suffice for most purposes.

Auto_add

This directive governs whether addresses found in the CC header will be added automatically to the list. By default, it is enabled. To disable it, use either directive form:

    Auto_add: no
    Auto_add: 0

Description

This is a single line that describes the purpose of the list. It is sent to everyone when they are added to the list. By default, it is blank. To set a description, use the form:

    Description: A list for discussing fluoridation.

Name

This isn't a directive in the sense that it's an intrinsic part of a list. It's just a way to give a list a nicer name when it's being created. Instead of having to rename a list to a nicer name, you can specify it with:

    Name: meat-eaters

Only letters, numbers, dashes, and the underscore characters are allowed in names.

METHODS

  • new( $alias_directory, [ $filehandle ] )

    new() takes one mandatory argument and one optional argument. $alias_directory is the path to the directory where alias data is stored. $filehandle is a filehandle (or a reference to a glob) from which to read an incoming message. By default, it will read from STDIN, as that is how mail filters work.

  • process()

    Processes one incoming message.

  • expansion_pattern()

    Returns a compiled regex to find expanded e-mail addresses (of the form you+expansion@example.com). If you've set your mail server to use a delimiter other than +, override this method. For example, Andy Lester uses addresses of the form you-expansion@example.com. What a nut.

  • add_signature( $signature )

    Adds the given string signature to the message, using the standard marker for signatures. If this message is a multi-part message, creates a new plain text attachment. Right now it only respects ASCII signatures.

  • add_to_alias( $alias, $post_address, @addresses )

    Adds each of the given @addresses to the $alias, notifying them of the addition and giving them the $post_address of the list (so they can post to it). This will only notify those addresses actually added to the list.

  • can_deliver( $alias, $message_headers )

    Given an Alias object for the list and the $message_headers, returns true if the sender can actually send a message to the list. Currently, all users can post to any list unless the list is closed to non-member postings or has expired.

  • deliver( $alias)

    Delivers the message, first checking can_deliver(), then adding all new addresses if auto-add is in effect, then setting the appropriate headers (such as list headers and the list description), and finally adding a signature and delivering the message.

    This is currently a lot of responsibility. Don't rely on everything all happening in this magic method.

  • generate_alias( [ $suggested_list_id ] )

    Generates a new alias for a list, given an optional list id. The current algorithm uses the current time plus a random number to avoid collisions with another list alias. It's mostly race-condition free.

  • notify( $alias, $list_address, @addresses )

    Sends a message from the list owner to each address in @addresses, notifying them that the system has added them to the $alias with the posting address of $list_address.

  • parse_alias( $address )

    Tries to discern the id of the alias from the given string containing an e-mail address. This will return the empty string if it could not find one.

  • post_address( $list_id )

    Given the id of the list, returns the e-mail address to use to post to the list in string form. This depends on your MTA setting the proper delivery headers.

  • reject( [ $reason ] )

    Rejects processing this message by dying with the error code 100. If there is no $reason, this reports an invalid alias.

    This method tends to end procmail processing, making the MDA report back to the sender, if so configured.

AUTHOR

chromatic, chromatic at wgz dot org, with suggestions from various friends and family as well as the subset of the Portland Perl Mongers who do not appear in a previous category.

BUGS

No known bugs, though something odd happens when you send a message with an invalid command to the base address (in our example, alias@example.com).

TODO

  • look for addable addresses in To header as well

  • allow the list owner to add people even if Auto_add is off

  • explore appropriate mailing-list and references headers

  • explicitly forbid loops (strip out all other alias addresses when sending)

  • allow list creation to be restricted to a set of users

  • show lists of which I am a member

COPYRIGHT

Copyright (c) 2016 chromatic. All rights reserved. This module is distributed under the same terms as Perl 5.24, in the hope that it is useful but under no warranty.