WWW::Mailman - Interact with Mailman's web interface from a Perl program
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 } );
WWW::Mailman is a module to control Mailman (as a subscriber, moderator or administrator) without the need of a web browser.
WWW::Mailman
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.
The new() method returns a new WWW::Mailman object. It accepts all accessors (see below) as parameters.
new()
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.
WWW::Mailman supports the following accessors to its attributes:
Get or set the secure parameter which, if true, indicates the Mailman URL is accessible via the https scheme.
Get or set the server part of the web interface.
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.
uri()
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.)
/mailman/
Get or set the program name. The default is mailman. Some servers define it to something else (e.g. SourceForge uses lists.
mailman
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.
program
Get or set the list name.
When used as an accessor, get the default listinfo URI for the list, returned as a URI object.
URI
When used as a mutator, set the secure, server, prefix and list attributes based on the given URI.
Get or set the user's email.
Get or set the user's password.
Get or set the moderator password.
Get or set the administrator password.
Get or set the WWW::Mechanize object used to access the Mailman web interface.
WWW::Mechanize
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.
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
Get the user options as a reference to a hash.
If an hash reference is passed as parameter, the given options will be updated.
Change the user email address (when reading, the field is empty) and real name.
Parameters are: new-address, confirm-address, fullname and changeaddr-globally.
new-address
confirm-address
fullname
changeaddr-globally
Change the user password for the mailing list.
Parameters are: newpw, confpw and pw-globally.
newpw
confpw
pw-globally
Unsubscribe the user from this mailing-list.
The parameter unsubconfirm must be set to 1 for the unsubscription to be acted upon.
unsubconfirm
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).
Request the password to be emailed to the user.
This method doesn't require authentication.
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:
Fundamental list characteristics, including descriptive info and basic behaviors.
Change list ownership passwords.
Natural language (internationalization) options.
Policies concerning immediately delivered list traffic.
Batched-delivery digest characteristics.
The policies that control the automatic bounce processing system in Mailman.
List traffic archival policies.
Mail-to-News and News-to-Mail gateway services.
Auto-responder characteristics.
Policies concerning the content of list traffic.
List topic keywords.
The above methods are actually curryied from the generic admin() method and can be called directly like this:
admin()
# identical ways to set general options: $mm->admin_general($options); $mm->admin( general => $options );
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.
Returm 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.
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 } ); }
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.
options()
admin_general()
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)
Philippe Bruhat (BooK), <book at cpan.org>
<book at cpan.org>
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.
bug-www-mailman at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc WWW::Mailman
You can also look for information at:
One of the official repositories:
http://github.com/book/WWW-Mailman
http://git.bruhat.net/cgi-bin/gitweb.cgi/WWW-Mailman.git
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Mailman
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/WWW-Mailman
CPAN Ratings
http://cpanratings.perl.org/d/WWW-Mailman
Search CPAN
http://search.cpan.org/dist/WWW-Mailman
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 2010 Philippe Bruhat (BooK), all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install WWW::Mailman, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Mailman
CPAN shell
perl -MCPAN -e shell install WWW::Mailman
For more information on module installation, please visit the detailed CPAN module installation guide.