NAME

WWW::Postini - Interact with the Postini mail filtering service

SYNOPSIS

  use WWW::Postini;

  my $p = new WWW::Postini();
  $p->login($login, $password);

DESCRIPTION

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.

A NOTE ON EXCEPTIONS

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.

In order to properly handle such errors, it is important to enclose any calls to this module in an eval{} block.

  # 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.

CONSTRUCTOR

new()

new($host)

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.

  my $p = new WWW::Postini('login2.postini.com');

OBJECT METHODS

user_agent()

user_agent($ua)

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();

login_host()

login_host($host)

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.

admin_host()

admin_host($host)

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($email,$password)

Attempt to login to the Postini mail filtering service with the credentials $email and $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.

get_user_id($email)

Returns the user ID of the supplied $email argument.

On failure, this method will throw an instance of the class WWW::Postini::Exception::UnexpectedResponse.

list_messages($user_id)

list_messages(%args)

list_messages(\%args)

In its single-argument form, this method will retrieve a list of messages quarantined for the specified $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

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

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";
  
  }

get_message_info($user_id,$message_id)

Retrieve detailed information about the message $message_id belonging to $user_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.

On failure, this method will throw a WWW::Postini::Exception::UnexpectedResponse exception.

delete_messages($user_id,@messages)

delete_messages($user_id,\@messages)

The specified @messages for $user_id will be marked as deleted.

On success, returns the number of messages successfully deleted.

On failure, this method will throw a WWW::Postini::Exception::UnexpectedResponse exception.

process_messages(%args)

process_messages(\%args)

Process one or more messages. The following parameters are recognized:

user_id - $user_id

recipient - $recipient_value

Specifies where to deliver message. For appropriate values, please see the "Message recipient" section of WWW::Postini::Constants. Defaults to RECIPIENT_USER

mark - 0 or 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.

On failure, this method will throw a WWW::Postini::Exception::UnexpectedResponse exception.

SEE ALSO

WWW::Postini::Base, WWW::Postini::Constants

AUTHOR

Peter Guzis, <pguzis@cpan.org>

COPYRIGHT AND LICENSE

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.