NAME

XMail::Ctrl - Crtl access to XMail server

VERISON

version 2.3 of XMail::Ctrl

released 07/10/2004

SYNOPSIS

use XMail::Ctrl;
my $XMail_admin      = "aaron.johnson";
my $XMail_pass       = "mypass";
my $XMail_port       = "6017";
my $XMail_host       = "aopen.hank.net";
my $test_domain      = "aopen.hank.net";
my $test_user        = "rick";

my $xmail = XMail::Ctrl->new(
            ctrlid   => "$XMail_admin",
            ctrlpass => "$XMail_pass",
            port     => "$XMail_port",
            host     => "$XMail_host"
        ) or die $!;

my $command_ok = $xmail->useradd(
        {
            username => "$test_user",
            password => 'test',
            domain   => "$test_domain",
            usertype => 'U'
        }
        );

printf("Failed to add user <%s@%s>\n", $test_user, $test_domain)
   unless $cmd_ok;

# setting the mailproc.tab

my $proc = $xmail->usersetmproc(
        {
            username       => "$test_user",
            domain         => "$test_domain",
            output_to_file => "command for mailproc.tab",

        }
         );

$xmail->quit;

DESCRIPTION

This module allows for access to the Crtl functions for XMail. It operates over TCP/IP. It can be used to communicate with either Windows or Linux based XMail based servers.

The code was written on a Win32 machine and has been tested on Mandrake and Red Hat Linux as well with Perl version 5.6 and 5.8

As of version 2.0 all code is written on under a Linux platform using Perl 5.8. It has been tested on: - Mandrake 9.0 with Perl 5.8 by Aaron Johnson - Mandrake 8.2 with Perl 5.6.1 by Aaron Johnson - ActiveState Perl (5.8) on Windows by Thomas Loo

Version 2.0 and higher require Digest::MD5, all passwords are now sent as an MD5 value.

Overview

All commands take the same arguments as outlined in the XMail (http://www.xmailserver.com) documentation. All commands are processed by name and arguments can be sent in the any order.

Example command from manual (is one line): "useradd"[TAB]"domain"[TAB]"username"[TAB]"password"[TAB]"usertype"<CR><LF>

This turns into:

$xmail->useradd( {
    domain => "domain.com",
    username => "username",
    password => "password",
    usertype => "U"
    }
    );

You can put the four parts in any order, they are put in the correct order by the modules internals.

The command structure for XMail allows a fairly easy interface to the command set. This module has NO hardcoded xmail methods. As long as the current ordering of commands is followed in the XMail core the module should work to any new commands unchanged.

Any command that accepts vars can be used by doing the following:

To send uservarsset (user.tab) add a vars anonymous hash, such as:

$xmail->uservarsset( {
domain   => 'aopen.hank.net',
username => 'rick',
vars     => {
    RealName      => 'Willey FooFoo',
    RemoteAddress => '300.000.000.3',
    VillageGrid   => '45678934'
    }
} );

The ".|rm" command can used as described in the XMail docs.

If you are having problems you might want to turn on debugging (new in 1.5)

$xmail->debug(1);

to help you track down the cause.

Setting the debug level to 4 will provide a very complete output of the communication between the server and your program. A line starting with >> (incoming) indicates what the Ctrl service sent back and << (outgoing) indicates what the XMail::Ctrl sent to the server.

All commands return a 1 if successful and undef on failure.

Lists

Lists are now (as of 1.3) returned as an array reference unless you set the raw_list method to true.

$xmail->raw_list(1);

To print the lists you can use a loop like this:

my $list = $xmail->userlist( { domain => 'yourdomin.net' } );
foreach my $row (@{$list}) {
print join("\t",@{$row}) . "\n";
}

Refer to the XMail documentation for each command for information on which columns will be returned for a particular command.

You can send a noop (keeps the connection alive) with:

$xmail->noop();

As of version 1.5 you can perform any froz command:

$froz = $xmail->frozlist();

foreach my $frozinfo (@{$froz}) {
    s/\"//g foreach @{$frozinfo};
    $res = $xmail->frozdel( {
                    lev0 => "$frozinfo->[1]",
                    lev1 => "$frozinfo->[2]" || '0',
                    msgfile => "$frozinfo->[0]",
                    });
    print $res , "\n";
}

BUGS

Possible problems dealing with wild card requests. I have not tested this fully. Please send information on what you are attempting if you feel the module is not providing the correct function.

AUTHOR

Aaron Johnson solution@gina.net

THANKS

Thanks to Davide Libenzi for a sane mail server with an incredibly consistent interface for external control.

Thanks to Mark-Jason Dominus for his wonderful classes at the 2000 Perl University in Atlanta, GA where the power of AUTOLOAD was revealed to me.

Thanks to my Dad for buying that TRS-80 in 1981 and getting me addicted to computers.

Thanks to my wife for leaving me alone while I write my code :^)

Thanks to Oscar Sosa for spotting the lack of support for editing the 'tab' files

Thanks to Thomas Loo for making many major refactoring contributions for version 2.0 as well as providing better debugging output.

CHANGES

Changes file included in distro

COPYRIGHT

Copyright (c) 2000,2001,2002,2003 Aaron Johnson. All rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

cpanm XMail::Ctrl

perl -MCPAN -e shell
install XMail::Ctrl