Andrei Lukovenko
and 1 contributors

NAME

WWW::Yandex::PDD - Perl extension for Yandex mailhosting

SYNOPSIS

Obtain token at https://pddimp.yandex.ru/get_token.xml?domain_name=yourdomain.ru

        use WWW::Yandex::PDD;

        my $pdd = WWW::Yandex::PDD->new( token => 'abcdefghijklmnopqrstuvwxyz01234567890abcdefghijklmnopqrs' );
        $pdd->create_user( 'mynewuser', 'mysecretpassword' );

DESCRIPTION

WWW::Yandex::PDD allows to manage user mail accounts on Yandex mailhosting

METHODS

$pdd->new( token => $token );
$pdd->new( token => $token, cert_file => $cert_file );

Construct a new WWW::Yandex::PDD object

        $token A string obtained at L<http://api.yandex.ru/pdd/doc/api-pdd/reference/get-token.xml#get-token>

        $cert_file New $ENV{HTTPS_CA_FILE} value
$pdd->get_last_error()

Returns undef if there was no error; otherwise

                $return = {
                        code => $error -> {code},
                        info => $error -> {info},
                };

DOMAINS

$pdd->domain_reg( $domain )

Sign up $domain for Yandex Mail API

Returns undef if error, otherwise

        $return = {
                name                    => $domain_name,
                secret_name     => $secret_name,
                secret_value    => $secret_value,
        }
$pdd->domain_unreg( $domain )

Disconnect this $domain

Returns 1 if success, undef if error

$pdd->domain_add_logo( $domain, $file_name )

Adds logo from $file_name (jpg, gif, png; < 2 Mb) to $domain.

Returns undef if error, otherwise

        $return = {
                name                    => $domain_name,
                logo_url                => $logo_url,
        };
$pdd->domain_del_logo( $domain )

Removes logo from $domain

Returns undef if error, otherwise

        $return = {
                name                    => $domain_name,
        }
$pdd->domain_add_admin( $domain, $login )

Adds new administrator $login for domain $domain.

Note: $login should be a separate mail box hosted on yandex.ru outside of $domain. For example, if you are adding foobar@yandex.ru, $login is 'foobar'

Returns undef if error, otherwise

        $return = {
                        name                    => 'somedomain.org',
                        new_admin               => 'foobar',
                }
$pdd->domain_del_admin( $domain, $login )

Removes $login from domain $domain administrators.

Returns undef if error, otherwise

        $return = {
                        name                    => 'somedomain.org',
                        deleted                 => 'foobar',
                }
$pdd->domain_get_admins( $domain )

Returns a list of secondary $domain administrators.

Returns undef if error, otherwise

        $return = {
                        name                    => 'somedomain.org',
                        other_admins    => [ 'admin', 'anotheradmin' ],
                }
$pdd->domain_set_default_user( $domain, $login )

Sets address $login@$domain as a default address. All mail to non-existing addresses will route to this poor guy.

Returns undef if error, otherwise

        $return = {
                        name    => 'somedomain.org',
                        email   => 'johndoe',   
                }

USERS

$pdd->create_user( $login, $password );
$pdd->create_user( $login, $encrypted_password, 'encrypted' );
        $encrypted_password is MD5-CRYPT password hash: "$1$" + 8 character salt [a-zA-Z0-9./] + "$" + 22 character checksum [a-zA-Z0-9./]
$pdd->update_user( $login, password => $password, iname => $iname, fname => $fname, sex => $sex, hintq => $hintq, hinta => $hinta )

See $pdd-get_user> for parameters meaning

Returns UID if success, undef otherwise

$pdd->delete_user( $login )
$pdd->delete_user( $login, $domain )
        Optional $domain if $login is in another domain

Returns 1 if success

$pdd->get_unread_count($login)

Returns number of unread messages, undef if error

$pdd->get_user( $login )

Returns undef if fail, or the following structure if success:

        $result = {
                domain      => 'mydomain.org',
                login       => 'username',
                birth_date  => '1900-01-01',
                iname       => 'John',
                fname       => 'Doe',
                hintq       => 'Your mother\'s maiden name?', # utf-8
                hinta       => '*****',
                mail_format => '', # preferred mail format
                charset     => '', # preferred charset
                nickname    => 'johnny',
                sex         => 1, # 0 - N/A, 1 - male, 2 - female
                enabled     => 1, # 1 - normal, mail accepted; 0 - locked, mail rejected
                signed_eula => 1, # user accepted EULA: 1 - yes, 0 - no
        };
$pdd->get_user_list($page, $per_page)

Returns domain information and user list, undef if error

        $page Page number.

        $per_page Number of mailbox records on a single page; cannot be more than 100; 100 records by default.

        $result = {
                'action-status'    =>  '',                              # error message
                'found'            =>  18,                              # number of users returned
                'total'            =>  18,                              # total number of users in this domain
                'domain'           =>  'mydomain.org',
                'status'           =>  'added',                 # added, mx-activate, domain-activate
                'emails-max-count' =>  1000,                    # maximum users for this domain
                'emails'           =>  [ 'jdoe', 'mkay' ], # user list
        }
$pdd->is_user_exists( $login )

Returns 1 if exists, 0 if doesn't exist, undef if error

$pdd->set_forward( $login, $forward_to, $save_copy )

Sets forwarding to $forward_to

$save_copy: "yes", "no"

Returns 1 if OK, undef if error

$pdd->get_forward_list($login)

Returns undef if error

Returns full description of forward rules for $login:

        $result = {
                filter_id                       => 12342343,
                enabled                         => 'yes', # 'yes' / 'no'
                forward                         => 'yes', # 'yes' / 'no'
                copy                            => 'no', # 'yes' / 'no'
                to_address                      => 'sameuser@otherdomain.org',
        }
$pdd->delete_forward( $login, $filter_id )

Removes forward for user $login, forward rule $filter_id. Returns undef if error.

IMPORT

$pdd->prepare_import( $server, method => $method, port => $port, callback = $callback, use_ssl => $use_ssl )

Set import options for the domain

        $method: 'pop3', 'imap', default 'pop3'

        $port: 100 POP3 w/o SSL, 995 POP3 with SSL; optional

        $use_ssl: 'yes'/'no'; default 'no'

        $callback: URL. If not empty, an HTTP request will be made to this address 
        with login="imported user's login" parameter after finishing import

Returns 1 if OK, undef if error

$pdd->import_user( $login, $password, ext_login => $ext_login, ext_password => $ext_password, forward_to => $forward, save_copy => $save_copy )

Register a new user and import all the mail from another server

$ext_login login on the source server, defaults to $login $ext_password user's password on the source server, defaults to $password $forward_to optional, set forwarding for this new mailbox $save_copy works only if forwarding is on; 0 - do not save copies in the local mailbox, 1 - save copies and forward

$pdd->get_import_status( $login )
        Returns: {
                last_check => $last_check,
                imported   => $imported,
                state      => $state
        };
$pdd->start_import( $login, ext_login => $ext_login, password => $password )
        $ext_login login on the source, defaults to $login
        $password on the source

Returns 1 if OK, undef if error

$pdd->stop_import($login)

Returns 1 if OK, undef if error

$pdd->import_imap_folder($login, password => $password, ext_login => $ext_login, ext_password => $ext_password, copy_one_folder = $copy_one_folder)
        $ext_login login on the source, defaults to $login
        $ext_password password on the source
        $password in the domain, mandatory if $login is a new user
        $copy_one_folder folder on the source; UTF-8, optional

Returns 1 if OK, undef if error

MAILLISTS

$pdd->maillist_create( $domain, $login, $listname )

Creates a new mailbox $login. Messages to this mailbox will be sent to all $domain users

Returns undef if error, otherwise

        $return = {
                        name    => 'somedomain.org',
                }
$pdd->maillist_destroy( $domain, $login, $listname )

Deletes previously created list and mailbox $login

Returns undef if error, otherwise

        $return = {
                        name    => 'somedomain.org',
                }

SEE ALSO

http://pdd.yandex.ru/ http://api.yandex.ru/pdd/doc/api-pdd/api-pdd.pdf http://api.yandex.ru/pdd/doc/api-pdd/concepts/general.xml

ENVIRONMENT

Setting ALUCK_TRACE environment variable to some debug file name causes WWW::Yandex:PDD to turn on internal debugging, and put in this file server XML responses.

AUTHORS

dctabuyz, <dctabuyz at ya.ru> Andrei Lukovenko, <aluck at cpan.org>

BUGS

Please report any bugs or feature requests to bug-www-yandex-pdd at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Yandex-PDD. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

HISTORY

Original version by dctabuyz: https://github.com/dctabuyz/Yandex-API-PDD.perl

SUPPORT

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

    perldoc WWW::Yandex::PDD

You can also look for information at:

COPYRIGHT AND LICENSE

    Copyright (c) 2010 <dctabuyz at ya.ru>
    Copyright (c) 2013 <aluck at cpan.org>

    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.7 or,
    at your option, any later version of Perl 5 you may have available.