NAME
Mail::Postini - Perl extension for talking to Postini
SYNOPSIS
use Mail::Postini;
my $mp = new Mail::Postini ( postini => 'https://login.postini.com/exec/login',
username => 'some@one.tld',
password => '3dk2j3jd8fk3kfuasdf',
secret => 'this is our secret postini key',
orgname => 'Our Customers' );
$mp->connect()
or die "Errors: " . join(' ', $mp->errors) . "\n";DESCRIPTION
Mail::Postini performs some web requests and some EZConnect API calls to a Postini mail server. It is meant to give a programmatic interface to many of the common tasks associated with adding, maintaining, and removing mail users from a Postini organization.
Nota bene: the web interface for Postini can change at any time, thereby breaking this module. We take some precautions against this, but can only do so much with web interfaces that aren't guaranteed like an API. Proceed with caution.
new ( %args )
Constructor.
Example:
my $mp = new Mail::Postini ( postini => 'https://login.postini.com/exec/login',
username => 'some@one.tld',
password => '3dk2j3jd8fk3kfuasdf',
secret => 'this is our secret postini key',
orgname => 'Our Customers' );connect ()
Makes a connection to the Postini mail server and initializes the object. If you're only using the EZCommands, you don't need to do this method (which can be slow).
Example:
$mp->connect() or die join(' ', $mp->errors);create_organization ( $organization_name )
Creates a new organization as a sub-org of the organization specified in the constructor by orgname.
Example:
$mp->create_organization( org => 'New Sub-Org' );list_organizations
Returns a hashref of organizations in this form:
{ orgid => <orgdata> }where orgdata is a hashref in this form:
{ key => value }This structure may vary from time to time, based on what is returned from Postini's "Download Orgs/Settings" link. You may use something like Data::Dumper to discover the keys and values returned in this method.
set_org_data( %parms )
Sets organization data. Currently, only the General Settings are supported.
GeneralSettings options:
Arguments (and values, if applicable):
- section
-
GeneralSettings
- name
- orgtag
- parent
- support_contact
- api_secret
- tight_postini
- default_user
- smartcreate
- quar_links
- timezone
- lang
- encoding
- cascade
set_org_mail_server( %parms )
Sets the mail server for an organization, as well as load-balancing and connection limit settings
$mp->set_org_mail_server( server1 => 'box.hosting.tld',
weight1 => 100,
maxcon1 => 500,
failover1 => 'backup.hosting.tld',
fo_weight1 => 100,
fo_maxcon1 => 300,
);You may specify as many serverN, pconnN and limitN as you wish (but Postini may have internal limits).
delete_organization ( $organization_name )
Deletes an organization. All domains must be deleted from the organization first.
Example:
$mp->delete_organization( org => 'Old Sub-Org' );org_from_domain ( $domain )
Returns the organization id that is the immediate parent of the given domain.
list_users ( %criteria )
Returns a hashref in the form of 'username => user data' for all users that match the given criteria. Currently 'user', 'domain', 'org', and 'orgid' criteria are supported.
Example:
## retrieve all users for this domain
my $users = $mp->list_users( domain => 'saltpatio.com' );list_aliases ( %criteria )
Returns a hashref of users and aliases in the form:
{ user1 => [ alias1, alias2 ],
user2 => [ alias1, ... ],
... }This method takes the same criteria as list_users().
Example:
my $aliases = $mp->list_aliases( domain => 'saltpatio.com' );
print "Aliases for joe: " . join("\n", @{$aliases->{'joe@saltpatio.com'}}) . "\n";get_user_data ( $username )
Retrieves the current settings for a user in the form of a hash.
Example:
my %data = $mp->get_user_data('joe@domain.tld');get_user_data is a shortcut for:
my %data = %{ $mp->list_users( user => 'joe@domain.tld' ) };get_orgid ( name => $organization_name )
Returns the numerical Postini organization id (used internally to identify a Postini organization or sub-organization).
Example:
my $orgid = $mp->get_orgid( name => 'My Org' );add_domain ( org => $org, domain => $domain )
Adds a domain to an organization.
Example:
$mp->add_domain( org => 'My Org', domain => 'somedomain.tld' );delete_domain ( domain => $domain )
Deletes a domain from a Postini configuration. All users must be deleted from the domain first.
$mp->delete_domain( domain => 'somedomain.tld' );add_user ( $username, [ field => value, ... ] )
Adds an email address to a Postini domain. When the user is added, Postini will filter mail for it. The domain must be added to an organization prior to you adding the user.
Example:
$mp->add_user( 'joe@somedomain.tld' );delete_user ( $username )
Deletes an email address from a Postini configuration.
Example:
$mp->delete_user( 'joe@somedomain.tld' );reset_user_password ( %args )
Resets a user's password. Arguments:
- user
-
The email address to change passwords for
- password
-
If specified, we'll use this password for the new password. Otherwise a new password will be generated and sent to the user.
- notify
-
If specified, email the user their new password (this only applies if a password is supplied).
errors ()
Returns a list of any errors accumulated since the last time errors were cleared.
Example:
print "Errors: " . join(' ', $mp->errors) . "\n";clear_errors ()
Clears the object's internal error list.
err_pages ()
Returns a list of HTTP::Response objects which you can use to troubleshoot connection or parsing problems.
my $res = ($mp->err_pages)[0];
print $res->content;clear_err_pages ()
Clears the object's internal error page list.
EXAMPLE
my $mp = new Mail::Postini ( postini => 'https://login.postini.com/exec/login',
username => 'joe@domain.tld',
password => 'mypasswordrocks!',
secret => 'My EZCommand Password',
orgname => 'My Customers' );
$mp->connect()
or die "Couldn't connect to server: " . join(' ', $mp->errors);
## 'Customer Accounts' is a sub-org of 'My Customers' (which is a
## template organization)
my $organization = 'Customer Accounts';
## add the domain to 'Customer Accounts' organization
$mp->add_domain( org => $organization,
domain => 'newdomain.tld' );
## add a new user to this domain
$mp->add_user( 'gordon@newdomain.tld' );
## get settings for this user
my %settings = $mp->get_user_data( 'gordon@newdomain.tld' );
print Data::Dumper::Dumper(\%settings);SEE ALSO
Mail::Foundry (some page parsing routines were done here first). HTTP::Response
AUTHOR
Scott Wiersdorf, <scott@perlcode.org>
COPYRIGHT AND LICENSE
Copyright (C) 2007 by Scott Wiersdorf
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.6 or, at your option, any later version of Perl 5 you may have available.