/ 
Net-OpenSRS-Email_APP-0.61
River stage zero No dependents
/ Net::OpenSRS::Email_APP

NAME

Net::OpenSRS::Email_APP -- Communicate using the OpenSRS Email Service Account Provisioning Protocol

VERSION

Version 0.61

SYNOPSIS

use strict;
use Net::OpenSRS::Email_APP;

my $app = new Net::OpenSRS::Email_APP(Environment=>'test',
                                      User=>'admin',
                                      Domain=>'example.com',
                                      Password=>'secret')
      || die "I encountered a problem: " . \ 
         Net::OpenSRS::Email_APP::errstr();

$app->login();

my $rows = $app->get_company_domains();
foreach my $r (@$rows) {
   print "$r->{DOMAIN}\n";
}

$app->quit();

DESCRIPTION

"Net::OpenSRS::Email_APP" provides an object interface for
communicating OpenSRS Email Service Account Provisioning Protocol
(APP).  For this module to be useful to you, you will need an
OpenSRS reseller account, and MAC credentials.  This module uses
IO::Socket::SSL, thus depends upon its presence to function.

CONSTRUCTOR

new ( [ARGS] )

Creates a "Net::OpenSRS::Email_APP" object.  "new"
requires the User, Domain and Password arguments in
key-value pairs.

The following key-value pairs are accepted:

  Environment   Either 'test' or 'production' - defaults to 'test'
  User          User for login() to use
  Domain        Domain for login() to use
  Password      Password for login() to use

GENERAL METHODS

login ()

Attempt to login to OpenSRS APP

quit ()

Close your APP connection

debug ( $level, $debug_cb )

Set the debug level, debug output will optionally be returned
using supplied callback

If $debug_cb is not supplied, output will be emitted via STDERR

last_status ( )

Returns an array containing the status code and status text from
the last OpenSRS call

Note: The status text may be undefined, you should test for this.

GET METHODS

get_admin ( [ARGS] )

The privilege level of this mailbox

  Required: Domain Mailbox

get_alternate_mailbox_names ( [ARGS] )

Given a comma-seperated list of email addresses, provide a
comma-seperated list of available alternatives

  Required: Mailbox_List

get_company_domains ()

A list of all domains

get_domain ( [ARGS] )

Information about this domain

  Required: Domain

get_domain_allow_list ( [ARGS] )

The allowed senders list for this domain

  Required: Domain

get_domain_block_list ( [ARGS] )

The blocked senders list for this domain

  Required: Domain

get_domain_brand ( [ARGS] )

The name of the brand associated to this domain

 Required: Domain

get_domain_mailboxes ( [ARGS] )

The list of mailboxes for this domain

  Required: Domain

get_domain_mailbox_limits ( [ARGS] )

Counts of each mailbox type permitted to be configured for
this domain

  Required: Domain

get_domain_workgroups ( [ARGS] )

The list of workgroups for this domain

  Required: Domain

get_group_alias_mailbox ( [ARGS] )

List the attributes and members of this mailing-list

  Required: Domain Group_Alias_Mailbox

get_mailbox ( [ARGS] )

Information about this mailbox (ONLY regular and filter-only
mailboxes)

  Required: Domain Mailbox

get_mailbox_allow_list ( [ARGS] )

The allowed senders list for this mailbox

  Required: Domain Mailbox

get_mailbox_any ( [ARGS] )

Information about this mailbox (INCLUDING forward-only and
mailing-lists)

  Required: Domain Mailbox

get_mailbox_autorespond ( [ARGS] )

The autoresponse state, text and attributes for this mailbox

  Required: Domain Mailbox

get_mailbox_availability ( [ARGS] )

Supplying a comma-seperated list of users, indicate whether
they already exist or not

  Required: Domain Mailbox_List

get_mailbox_block_list ( [ARGS] )

The blocked senders list for this mailbox

  Required: Domain Mailbox

get_mailbox_forward ( [ARGS] )

Configured forwarding details for this regular mailbox

  Required: Domain Mailbox

get_mailbox_forward_only ( [ARGS] )

Details for this forward-only mailbox

  Required: Domain Mailbox

get_mailbox_suspension ( [ARGS] )

List the suspension status of each service for this mailbox

  Required: Domain Mailbox

get_num_domain_mailboxes ( [ARGS] )

Counts of each mailbox type and whether a domain
catch-all is configured

  Required: Domain

CREATE METHODS

create_alias_mailbox ( [ARGS] )

Add an alias pointing to another mailbox on this domain

  Required: Domain Alias_Mailbox Mailbox

create_domain ( [ARGS] )

Add a new domain

  Required: Domain
  Optional: Timezone Language FilterMX Spam_Tag Spam_Folder Spam_Level

create_domain_alias ( [ARGS] )

Creates a domain aliased to this one

  Required: Domain Alias

create_domain_welcome_email ( [ARGS] )

The welcome message to send to each new user for this domain

  Required: Domain Welcome_Text Welcome_Subject From_Name From_Address Charset Mime_Type

create_group_alias_mailbox ( [ARGS] )

Creates a mailing-list to the specified list of addresses

  Required: Domain Group_Alias_Mailbox Workgroup Alias_To_Email_CDL
  Optional: Spam_Level

create_mailbox ( [ARGS] )

Create a regular or filter-only mailbox

  Required: Domain Mailbox Workgroup Password
  Optional: FilterOnly First_Name Last_Name Phone Fax Title Timezone Lang Spam_Tag Spam_Folder Spam_Level

create_mailbox_forward_only ( [ARGS] )

Creates an alias which forwards to any single address

  Required: Domain Mailbox Workgroup Forward_Email
  Optional: Spam_Level

create_workgroup ( [ARGS] )

Create a workgroup within this domain

  Required: Domain Workgroup

DELETE METHODS

delete_domain ( [ARGS] )

Delete this domain

  Required: Domain
  Optional: Cascade

delete_group_alias_mailbox ( [ARGS] )

Deletes this mailing-list

  Required: Domain Group_Alias_Mailbox

delete_domain_alias ( [ARGS] )

Delete this domain alias

  Required: Alias

delete_domain_welcome_email ( [ARGS] )

Delete the welcome email for this domain

  Required: Domain

delete_mailbox ( [ARGS] )

Deletes this regular or filter-only mailbox

  Required: Domain Mailbox

delete_mailbox_any ( $domain, $mailbox )

Deletes this mailbox (irrespective of type)

  Required: Domain Mailbox

delete_mailbox_forward_only ( [ARGS] )

Deletes this forward-only mailbox

  Required: Domain Mailbox

delete_workgroup ( [ARGS] )

Delete a workgroup within this domain

  Required: Domain Workgroup
  Optional: Cascade

CHANGE METHODS

change_domain ( [ARGS] )

Change this domain's details

  Required: Domain (and at least one of the optionals)
  Optional: Timezone Language FilterMX Spam_Tag Spam_Folder Spam_Level

change_group_alias_mailbox ( [ARGS] )

Alter this mailing-list

  Required: Domain Group_Alias_Mailbox (and one optional)
  Optional: Alias_To_Email_CDL Spam_Level

change_mailbox ( [ARGS] )

Alters this regular or filter-only mailbox

  Required: Domain Mailbox
  Optional: Workgroup Password FilterOnly First_Name Last_Name Phone Fax Title Timezone Language Spam_Tag Spam_Folder Spam_Level

Note: When specifying FilterOnly, it may only be 'F' - you may change a filter-only mailbox to regular, but not the reverse.

change_mailbox_forward_only ( [ARGS] )

Alters this forward-only mailbox

  Required: Domain Mailbox Forward_Email
  Optional: New_Mailbox_Name Spam_Level

SET METHODS

set_domain_admin ( [ARGS] )

Specify the domain administrator for this domain

  Required: Domain Mailbox
  Optional: State

set_domain_allow_list ( [ARGS] )

Set the permitted sender list for this domain

  Required: Domain List

set_domain_block_list ( [ARGS] )

Set the blocked sender list for this domain

  Required: Domain List

set_domain_brand ( [ARGS] )

Assign a brand for this domain

  Required: Domain Brand_Code

set_domain_catch_all_mailbox ( [ARGS] )

Set the mailbox to receive mail for any non-existent recipients

  Required: Domain (and one of the optionals)
  Optional: Mailbox State

Note: OpenSRS will return Internal system error if you attempt to
set State='T' on a domain which currently does not have a
catch-all mailbox.  OpenSRS have deprecated catch-all addresses.

set_domain_disabled_status ( [ARGS] )

Enable or disable this domain

  Required: Domain Disabled

set_domain_mailbox_limits ( [ARGS] )

Set the limit of each mailbox type which may be created on this domain

  Required: Domain
  Optional: Mailbox Filter_Only Alias Forward_Only Mailing_List

set_mail_admin ( [ARGS] )

Grant or revoke administrative privileges for this mailbox

  Required: Domain Mailbox
  Optional: State

set_mailbox_allow_list ( [ARGS] )

Set the permitted sender list for this mailbox

  Required: Domain Mailbox List

set_mailbox_block_list ( [ARGS] )

Set the blocked sender list for this mailbox

  Required: Domain Mailbox List

set_mailbox_autorespond ( [ARGS] )

Configure autoresponse for this mailbox

  Required: Domain Mailbox (and at least one optional)
  Optional: State Text

set_mailbox_forward ( [ARGS] )

Configure forwarding for this mailbox

  Required: Domain Mailbox (and at least one optional)
  Optional: Forward Keep_Copy State

set_mailbox_suspension ( [ARGS] )

Enable or disable services for this mailbox

  Required: Domain Mailbox
  Optional: SMTPIn SMTPRelay IMAP POP Webmail

set_workgroup_admin ( [ARGS] )

Add or remove a workgroup administrator

  Required: Domain Mailbox
  Optional: State

RENAME METHODS

rename_mailbox ( [ARGS] )

Rename this regular mailbox and update all references to it

  Required: Domain Old_Mailbox New_Mailbox

VERIFY METHODS

verify_password ( [ARGS] )

Verify this mailbox's password

  Required: Domain Mailbox Password

SHOW METHODS

show_available_offerings ( [ARGS] )

Available offers for this mailbox

  Required: Domain Mailbox

show_enabled_offerings ( [ARGS] )

The active offers for this mailbox

  Required: Domain Mailbox

DISABLE METHODS

disable_offering ( [ARGS] )

Disables an active mailbox offer

  Required: Mailbox_Offering_ID

ENABLE METHODS

enable_offering ( [ARGS] )

Activate the specified offer for this mailbox

  Required: Domain Mailbox Offering_ID
  Optional: Auto_Renew

NOTES

The functions get_mailbox_status and set_mailbox_status are not implemented, OpenSRS have tagged these functions as being deprecated. Use get_mailbox_suspension and set_mailbox_suspension functions instead.

AUTHOR

Mark Goldfinch, mark.goldfinch at modicagroup.com

BUGS

The internal functions _parse_single_row and _parse_multiple_rows currently make use some handwritten logic to correctly parse the rows as returned by APP. The OpenSRS supplied documentation includes an ABNF definition for the entire protocol. The handwritten logic could likely be replaced by Parser::RecDescent (or similar) logic. A hurdle to this is the left-resolving the supplied ABNF uses, Parser::RecDescent's design inhibits the use of left-resolving parsing. Patches are welcome to address this. My testing suggests the current handwritten logic is robust and functional however.

Other than presence of required arguments, no validation of supplied arguments is currently performed.

Otherwise please report any bugs or feature requests to bug-net-opensrs-email_app at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-OpenSRS-Email_APP.

SEE ALSO

This implementation is based upon documentation from http://opensrs.com/docs/OpenSRS_APP_Dev_Guide.pdf dated December 14, 2010. Please read the pdf for greater detail about the protocol, required and returned values of each function.

SUPPORT

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

perldoc Net::OpenSRS::Email_APP

You can also look for information at:

ACKNOWLEDGEMENTS

Thank you to Modica Group http://www.modicagroup.com/ for funding the development of this module.

LICENSE AND COPYRIGHT

Copyright 2011 Mark Goldfinch.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.