/ 
WWW-Mailman-1.061
River stage zero No dependents
/ WWW::Mailman

NAME

WWW::Mailman - Interact with Mailman's web interface from a Perl program

SYNOPSIS

use WWW::Mailman;

my $mm = WWW::Mailman->new(

    # the smallest bit of information we need
    uri      => 'http://lists.example.com/mailman/listinfo/example',

    # TIMTOWTDI
    server   => 'lists.example.com',
    list     => 'example',

    # user / authentication / authorization
    email    => 'user@example.com',
    password => 'roses',              # needed for user actions
    moderator_password => 'Fl0wers',  # needed for moderator actions
    admin_password     => 's3kr3t',   # needed for action actions

    # use cookies for quicker authentication
    cookie_file => "$ENV{HOME}/.mailmanrc",

);

# authentication is automated, no need to think about it

# user options: get / change / update
my $options = $mm->options();
$options->{nodupes} = 0;
$mm->options( $options );

# just change one item
$mm->options( { digest => 1 } );

DESCRIPTION

WWW::Mailman is a module to control Mailman (as a subscriber, moderator or administrator) without the need of a web browser.

The module handles authentication transparently and can take advantage of stored cookies to speed it up.

It is meant as a building block for your own Mailman-managing scripts, and will include more routines in the future.

METHODS

Constructor

new( %options )

The new() method returns a new WWW::Mailman object. It accepts all accessors (see below) as parameters.

Extra parameters:

If the robot paramater is not given, the constructor will automatically provide one (this is usually the best choice). If cookie_file is provided, the provided robot will read cookies from this file, and save them afterwards.

Using a cookie file will make your scripts faster, as the robot will not have to fill in and post the authentication form.

Accessors / Mutators

WWW::Mailman supports the following accessors to its attributes:

secure

Get or set the secure parameter which, if true, indicates the Mailman URL is accessible via the https scheme.

server

Get or set the server part of the web interface.

userinfo

Get or set the userinfo parameter for servers requesting authentication to access the Mailman interface.

This is a string made up of the login and password joined by a colon (:).

Note that the URI object returned by uri() will show this information.

prefix

Get or set the prefix part of the web interface. (For the rare case when Mailman is not run from the top-level /mailman/ URL.)

program

Get or set the program name. The default is mailman. Some servers define it to something else (e.g. SourceForge uses lists.

WWW::Mailman should usually be able to guess it. If not, you'll need to pass the program parameter to the constructor, as a hint.

list

Get or set the list name.

uri

When used as an accessor, get the default listinfo URI for the list, returned as a URI object.

When used as a mutator, set the secure, server, prefix and list attributes based on the given URI.

email

Get or set the user's email.

password

Get or set the user's password.

moderator_password

Get or set the moderator password.

admin_password

Get or set the administrator password.

robot

Get or set the WWW::Mechanize object used to access the Mailman web interface.

ACTION METHODS

WWW::Mailman is used to interact with Mailman through its web inteface. Most of the useful methods in this module are therefore related to the web interface itself.

Options

Note that since Mailman's options form has six submit buttons, each of them managing only a subset of this form's input fields, the handling of this form has been split in six different routines.

options( [ \%options ] )

Get the user options as a reference to a hash.

If an hash reference is passed as parameter, the given options will be updated.

address( [ \%options ] )

Change the user email address (when reading, the field is empty) and real name.

Parameters are: new-address, confirm-address, fullname and changeaddr-globally.

changepw( [ \%options ] )

Change the user password for the mailing list.

Parameters are: newpw, confpw and pw-globally.

unsub( [ \%options ] )

Unsubscribe the user from this mailing-list.

The parameter unsubconfirm must be set to 1 for the unsubscription to be acted upon.

othersubs( )

Returns a list of Mailman-managed mailing-lists, that this user is subscribed to on the same Mailman instance.

Note: if you're logged in as an admin (or have an admin cookie), this method may return an empty list (this is a bug in Mailman's interface).

emailpw( )

Request the password to be emailed to the user.

This method doesn't require authentication.

Admin methods

The following admin methods all have the same interface.

Without parameter, they return the requested options as a reference to a hash. If an hash reference is passed as parameter, the given options will be updated.

The admin methods are:

admin_general( [ \%options ] )

Fundamental list characteristics, including descriptive info and basic behaviors.

admin_passwords( [ \%options ] )

Change list ownership passwords.

admin_language( [ \%options ] )

Natural language (internationalization) options.

admin_nondigest( [ \%options ] )

Policies concerning immediately delivered list traffic.

admin_digest( [ \%options ] )

Batched-delivery digest characteristics.

admin_bounce( [ \%options ] )

The policies that control the automatic bounce processing system in Mailman.

admin_archive( [ \%options ] )

List traffic archival policies.

admin_gateway( [ \%options ] )

Mail-to-News and News-to-Mail gateway services.

admin_autoreply( [ \%options ] )

Auto-responder characteristics.

admin_contentfilter( [ \%options ] )

Policies concerning the content of list traffic.

admin_topics( [ \%options ] )

List topic keywords.

admin( $section [, \%options ] )

The above methods are actually curryied from the generic admin() method and can be called directly like this:

# identical ways to set general options:
$mm->admin_general($options);
$mm->admin( general => $options );

Other methods

roster( )

Request the list of subscribers to the mailing-list. Authentication is not required, but maybe be used.

Note that the list may be empty, depending on the level of authentication available and the privacy settings of the list.

version( )

Return the Mailman version as printed at the bottom of all pages.

Whenever WWW::Mailman downloads a Mailman web page, it tries to obtain this version information.

archive_mbox_uri( )

Return the URI of the mbox containing the whole mailing-list archive.

If archival is not configured for that mailing-list, querying this URI will return a 404.

EXAMPLES

See the distribution's eg/ directory for more examples.

Here's a script to update one's options across a number of mailing-lists:

#!/usr/bin/perl
use strict;
use warnings;
use WWW::Mailman;
use YAML::Tiny qw( LoadFile );

# some useful files
my %opts  = ( cookie_file => 'mailman.cookie' );
my $lists = LoadFile('mailman.yml');

# mailman.yml looks like this:
# ---
# - uri: http://lists.example.com/mailman/listinfo/example
#   email: user@example.com
#   password: s3kr3t

# I want to receive duplicates!
for my $list (@$lists) {
    my $mm = WWW::Mailman->new( %opts, %$list );
    $mm->options( { nodupes => 0 } );
}

Useful trick

All the methods that return a hashref with a set of form fields values (options(), admin_general(), etc.) also set the current form of the WWW::Mailman's robot to that form.

This allows you to dump the form, for example if you want to see what the possible values are for a given form:

my $mm = WWW::Mailman->new( %args );
$mm->admin_archive();
print $mm->robot->current_form->dump;

Which will output:

POST http://lists.example.com/mailman/admin/example/archive
  archive=1                      (radio)    [0/No|*1/Yes]
  archive_private=1              (radio)    [0/public|*1/private]
  archive_volume_frequency=1     (radio)    [0/Yearly|*1/Monthly|2/Quarterly|3/Weekly|4/Daily]
  submit=Submit Your Changes     (submit)

AUTHOR

Philippe Bruhat (BooK), <book at cpan.org>

BUGS

Please report any bugs or feature requests to bug-www-mailman at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Mailman. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc WWW::Mailman

You can also look for information at:

ACKNOWLEDGEMENTS

My first attempt to control Mailman with WWW::Mechanize is described in French at http://articles.mongueurs.net/magazines/linuxmag58.html#h3.

I'm not the only that would like to avoid using a web interface to interact with mailing-list software: http://www.jwz.org/doc/mailman.html

COPYRIGHT

Copyright 2010 Philippe Bruhat (BooK), all rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.