NAME

WWW::Yandex::MailForDomain - Yandex Mail for Domain API

SYNOPSIS

    use WWW::Yandex::MailForDomain;

    my $pdd = WWW::Yandex::MailForDomain->new(
        token       => '2009....a0ab',
        on_error    => sub { die shift }
    );

    # Add new mailbox
    $pdd->add_user('john', 'pass123');
    $pdd->modify_user('john',
        first_name  => 'John',
        last_name   => 'Doe'
    );

    # List all mailboxes and display number of unread messages
    for my $user (sort(@{$pdd->get_users})) {
        my $unread = $pdd->get_unread_count($user);
        print "$user\t$unread\n";
    }

DESCRIPTION

The WWW::Yandex::MailForDomain module allows you to use Yandex Mail for Domain service (http://pdd.yandex.ru) via simple interface.

Authorization token

For using API, you need an authorization token. When you logged in into your Yandex account (used for domain activation), just get page at https://pddimp.yandex.ru/get_token.xml?domain_name=example.org, where example.org is the domain name for your mail. The token (some hexadecimal value) will be found in page's body in the XML attribute.

You need to get token only once for specific domain name.

USAGE

Interaction with Yandex Mail for Domain API executes by methods of the WWW::Yandex::MailForDomain object, which is needed only one to perform all actions with specific mail domain. This mail domain, as well as the authorization data, unambiguously identified by the authorization token.

The object provides methods for:

Retrieving information about the mail domain capabilities
Retrieving information about the user mailbox
Manipulating the users' mailboxes: creating, modifying etc.
Setting up, starting and stopping mail import by POP or IMAP protocol
Initiating mail forwarding

Constructor

WWW::Yandex::MailForDomain->new(%options)

This method constructs a new WWW::Yandex::MailForDomain object and returns it. Key/value pair arguments may be provided to set up the initial state.

    token             The authorization token (required)
    ua                Your own LWP::UserAgent object (optional)
    on_error          The callback to invoke error processing (optional)

If token absent, an object will not be created and undef returned. If ua is not defined, it will be created internally. Example:

    my $pdd = WWW::Yandex::MailForDomain->new(
        token => '2009....a0ab'
    );

Errors processing

All methods returns undef when an error is detected. Afterwards, method error returns a message describing last ocurred error.

error

Returns last error.

    my $uid = $pdd->add_user('alice', 'pass123');
    if (! defined($uid)) {
        warn($pdd->error);
    }

Callback function

Additionally, you can define a callback function in the constructor's option on_error. This function will be fired when an error will be occurred.

    my $pdd = WWW::Yandex::MailForDomain->new(
        token       => '2009....a0ab',
        on_error    => sub {
            my ($err) = @_;
            log(time, $err) and die $err;
        }
    );

User Registration Fields

Data, returned by get_user_info() method, consist of following fields:

    login                     Login name

    enabled                   Is the mailbox enabled or blocked
    eula_signed               Was EULA signed by user

    nickname                  User's nickname
    first_name        (*)     First name
    last_name         (*)     Last name
    date_of_birth             Date of Birth, in YYYY-MM-DD format
    sex               (*)     Gender: 1 - male, 2 - female, 0 - uncertain

    secret_question   (*)     Secret question for password recovering
    secret_answer     (*)     Answer to secret question

Fields, marked with asterisk (*), can be changed with modify_user() method.

All values are UTF-8 encoded scalars.

General information about mail domain

domain

Returns the domain name, associated with authorization token.

domain_status

Returns the domain activation state. Possible values are domain-activate, mx-activate and added.

users_total

Returns the number of currently existing mailboxes.

users_max_number

Returns the maximum number of mailboxes, allowed for your mail domain.

refresh_counters

Because both of users_total and users_max_number methods caching their values for performance reasons, and only several functions (such as add_user()) automatically updating the cache, use refresh_counters to force getting the actual numbers.

get_users_one_page($on_page, $page_n)

get_users_one_page

Returns an arrayref with usernames. This list is splitted by pages, contains not over than 100 items on page. You can specify the page number with $page_n, which starting from 1, and quantity of items on page with $on_page.

Also, you can use this methods without any arguments for default behaviour. See "known bugs".

get_users

Proceed page by page retrieving and returns the complete list of users in arrayref. See "known bugs".

Mailboxes management methods

In this section described methods for manipulating mailboxes and for getting information about them. The mailbox's name is the same thing as login name or user name.

Some of these methods returns a kind of UID value, that is useless in general.

check_user($login)

Returns 1 if mailbox with specified login exists, or 0 if not exists.

add_user($login, $password)

Creates a new mailbox, specified by username and password. Returns UID if mailbox was successfully created, or undef by various reasons (bad username, password is too short, mailbox already exists and so on).

add_user_encrypted($login, $password_digest)

Same as add_user(), but accepts a MD5-based encrypted password. You may use a unix_md5_crypt() function, see Crypt::PasswdMD5. Example:

    use Crypt::PasswdMD5;
    $r = $pdd->add_user_encrypted('alice', unix_md5_crypt('pass123'));

There is no analogous functionality for change_password() method.

delete_user($login)

Removes a mailbox.

ATTENTION: a mailbox with all messages in it will be dropped without any additional confirmation!

Returns 1 if mailbox was successfully removed.

modify_user($login, $field_name => $value, ...)

Modifies user data. Possible fields are:

    first_name
    last_name
    sex
    secret_question
    secret_answer

If a value is not defined, or is empty string, the correspondent field will not be modified. See ""User Registration Fields"".

Returns UID.

change_password($login, $new_password)

Changes password for the mailbox. Returns UID if password was successfully changed.

get_user_info($login)

Returns hashref with user data. See ""User Registration Fields"".

get_unread_count($login)

Returns total number of new (unread) messages in the mailbox.

Importing mail from other server

Naturally, Yandex Mail for Domain service is suitable not only for creating new mailbox sets. If you already have numerous mailboxes on your domain, you should be want to moving their content, when moving user accounts to Yandex Mail for Domain.

Yandex API provides special methods for simplifying this procedure.

register_source($param => $value, ...)

Registers a mail server that holds user mail at present. Key/value pair arguments must be specified to set up the connection parameters.

    host              The server's hostname (required)
    port              The server's port number, if it is not standard (optional)
    protocol          Name of protocol: 'POP3' (default) or 'IMAP'
    no_ssl            Server doesn't support SSL connection (optional)
    notify            URI for callback (optional)

The notify is an URI, which will be requested when the import session will be finished. URI will be amplified with query part login=imported_mailbox. It's supposed that request will receive XML document like this:

    <page><status>moved</status></page>

if import process finished correctly, or something else otherwise. Example:

    $r = $pdd->register_source(
        protocol    => 'pop3',
        host        => 'mail.example.org',
        notify      => 'http://example.org/transfer_finished.cgi',
    );

start_import($login, $param => $value, ...)

Begins importing process for user $login. The parameters are remote_login and remote_password, needed for authentication on the source server. Example:

    $pdd->start_import('alice', remote_login => 'Alice.Smith', remote_password => 'pass123');

The remote_login may be omitted, if it is equal to $login.

stop_import($login)

Terminates importing process for specified user.

check_import_status($login)

Returns a hashref with two elements: time - a timestamp when last event took place, and state - a text message describing current state of importing process.

Mail forwarding

set_forwarding($login, $to)

set_forwarding($login, $to, $dont_keep)

Starts mail forwarding from mailbox, specified by $login, to address $to. If $dont_keep is defined and is a true value, the messages will be erased after sending.

    # Setup forwarding, but keep original messages
    $r = $pdd->set_forwarding('alice', 'bob@example.org');

    # Setup forwarding and don't save original messages
    $r = $pdd->set_forwarding('carol', 'carol@home.example.org', 1);

Be careful:

a) $to address will not be checked for well-formedness.
b) You may set more than one address for forwarding. The order of executing forwarding rules is not determined, so if any of them doesn't keep messages in mailbox, proceeding the next rules will be uncertain.
c) There is no way to cancel forwarding via API.

Returns 1 on success.

KNOWN BUGS

When a number of existing mailboxes is a little, the request users list by get_users_one_page() with specific $page_n may cause a wrong number of items in the returned list. Compare number of items with users_total value, or try call get_users_one_page() without any parameters.

On the other hand, if a number of mailboxes is a large, get_users() method may return a wrong number of items too.

I hope, the paging of retrieving mailboxes process will be fixed. A bug report has been sended to Yandex.

COPYRIGHT

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Oleg Alistratov <zero@cpan.org>

To install WWW::Yandex::MailForDomain, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WWW::Yandex::MailForDomain

CPAN shell

perl -MCPAN -e shell
install WWW::Yandex::MailForDomain

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)