WWW::Postini - Interact with the Postini mail filtering service
use WWW::Postini; my $p = new WWW::Postini(); $p->login($login, $password);
This module is an attempt to provide a simple interface to the email quarantine functionality offered by the Postini (http://www.postini.com/) mail filtering service. Behind the scenes, this is achieved by screen-scraping the Postini administration web site.
Please note WWW::Postini makes extensive use of Exception::Class objects for improved error handling. Many object methods will throw (read: die()) upon error with a subclass of Exception::Class.
die()
In order to properly handle such errors, it is important to enclose any calls to this module in an eval{} block.
eval{}
# try eval { my $p = new WWW::Postini(); $p->login($email, $password); }; # catch if ($@) { if (UNIVERSAL::isa($@, 'Exception::Class')) { printf "Caught an exception: %s\n", $@->as_string; } else { printf "Caught a native error: %s\n", $@; } exit; }
For more information, please see Exception::Class. Wherever appropriate, this document will detail which subclasses of Exception::Class may be thrown from each method.
Creates a new instance of WWW::Postini. If $host is specified, it is used as the object's login host, otherwise the default of login.postini.com is used.
$host
login.postini.com
my $p = new WWW::Postini('login2.postini.com');
Get or set the underlying WWW::Postini::UserAgent object
This method is present in case WWW::Postini needs to be subclassed or the programmer needs access to the user agent itself for other reasons.
my $user_agent = $p->user_agent();
Get or set login host.
The login host defaults to login.postini.com, unless a host is specified in the constructor. Changing the login host is not necessary at this point, as there is currently only one Postini login server.
Get or set administration host.
The administration host is determined automatically during the login() procedure. Until a successful login has taken place, the value of admin_host() will be undefined. It is not necessary to manually set the administration host, but you may if desired. In this case, be sure to set admin_host() after login, but before any other other methods are called.
login()
admin_host()
Attempt to login to the Postini mail filtering service with the credentials $email and $password
$email
$password
On failure, this method will throw an instance of the class WWW::Postini::Exception::LoginFailure and it is up to the programmer to catch this exception.
Returns the user ID of the supplied $email argument.
On failure, this method will throw an instance of the class WWW::Postini::Exception::UnexpectedResponse.
In its single-argument form, this method will retrieve a list of messages quarantined for the specified $user_id.
$user_id
If this method is passed a list of key/value pairs or a hash reference, the following keys may be used:
user_id - Target user ID
show - Scope of quarantine listing.
For a listing of values this parameter accepts, please see the "Message searching" section of WWW::Postini::Constants. Defaults to SHOW_ALL
SHOW_ALL
sort - Message sort method
For a listing of values this parameter accepts, please see the "Message sorting" section of WWW::Postini::Constants. Defaults to SORT_NONE
SORT_NONE
recipient - Narrow searcg by recipient address
Only messages containing this text in the recipient field will be included in the resulting message list. Note: this is a partial text match.
sender - Narrow search by sender address
subject - Narrow search by subject
filter - Narrow search by filter description
On success, this method returns an array reference populated with messages. Each message is a hash reference formatted similar to the following:
{ sender => $sender_address, recipient => $recipient_address, subject => $subject, date => $date, filter => $filter_description, id => $message_id, uid => $user_id }
On failure, this method will throw a WWW::Postini::Exception::UnexpectedResponse exception.
use WWW::Postini::Constants ':show'; # show only quarantined messages my $messages = $p->list_messages( user_id => $user_id, show => SHOW_QUARANTINED ); print "Received the following messages\n\n"; foreach my $msg (@$messages) { print "Message ID: $msg->{'id'}\n"; }
Retrieve detailed information about the message $message_id belonging to $user_id.
$message_id
On sucess, a hash reference of the following format will be returned:
{ headers => $header_text, body => $body_text, attachments => [ $file1_name, $file2_name, ... ] }
Note: the text returned may be truncated by Postini itself. In addition, attachments will only contain filenames when the current message was blocked due to a disallowed file attachment type.
attachments
The specified @messages for $user_id will be marked as deleted.
@messages
On success, returns the number of messages successfully deleted.
Process one or more messages. The following parameters are recognized:
user_id - $user_id
recipient - $recipient_value
$recipient_value
Specifies where to deliver message. For appropriate values, please see the "Message recipient" section of WWW::Postini::Constants. Defaults to RECIPIENT_USER
RECIPIENT_USER
mark - 0 or 1
0
1
Mark message as delivered. Defaults to 1
clean - 0 or 1
Virus clean before delivering message. Defaults to 1
On success, this method returns the number of messages processed.
WWW::Postini::Base, WWW::Postini::Constants
Peter Guzis, <pguzis@cpan.org>
Copyright (C) 2005 by Peter Guzis
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.
Postini, the Postini logo, Postini Perimeter Manager and preEMPT are trademarks, registered trademarks or service marks of Postini, Inc. All other trademarks are the property of their respective owners.
To install WWW::Postini, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Postini
CPAN shell
perl -MCPAN -e shell install WWW::Postini
For more information on module installation, please visit the detailed CPAN module installation guide.