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