XMAIL ADMIN PROTOCOL

It's possible to remote admin AfterLogic XMail Server due to the existence of a 'controller server' that runs with AfterLogic XMail Server and waits for TCP/IP connections on a port (6017 or tunable via a '-Cp nport') command line option.

Admin protocol details:

Description
Adding a user
Deleting a user
Changing a user's password
Authenticate user
Retrieve user statistics
Adding an alias
Deleting an alias
Listing aliases
Listing user vars
Setting user vars
Listing users
Counting users
Getting mailproc.tab file
Setting mailproc.tab file
Adding a mailing list user
Deleting a mailing list user
Listing mailing list users
Adding a domain
Deleting a domain
Listing handled domains
Adding a domain alias
Deleting a domain alias
Listing alias domains
Getting custom domain file
Setting custom domain file
Listing custom domains
Adding a POP3 external link
Deleting a POP3 external link
Listing POP3 external links
Enabling a POP3 external link
Listing files
Getting configuration file
Setting configuration file
Listing frozen messages
Rescheduling frozen message
Deleting frozen message
Getting frozen message log file
Getting frozen message
Starting a queue flush
Do nothing command
Quit the connection
Do you want...?

Description

The AfterLogic XMail Server admin server 'speaks' a given protocol that can be used by external GUI utilities written with the more disparate scripting languages, to remote administer the mail server. The protocol is based on sending formatted command and waiting for formatted server responses and error codes. All the lines, commands, and responses are delimited by a <CR><LF> pair. The error code string (RESSTRING) has the given format:

 "+DDDDD OK"<CR><LF>

if the command execution is successful while:

 "-DDDDD ErrorString"<CR><LF>

if the command failed.

The '' character is not included in responses. DDDDD is a numeric error code while ErrorString is a description of the error. If DDDDD equals 00100, a lines list, terminated by a line with a single point (<CR><LF>.<CR><LF>), follows the response.

The input format for commands is similar to the one used in TAB files:

 "cmdstring"[TAB]"param1"[TAB]..."paramN"<CR><LF>

where 'cmdstring' is the command string identifying the action to be performed, and param1,... are the parameters of the command.

Immediately after the connection with AfterLogic XMail Server controller server is established the client receives a RESSTRING that is:

 +00000 <TimeStamp> AfterLogic XMail Server ...

if the server is ready, while:

 -DDDDD ...

(where DDDDDD is an error code) if not.

The TimeStamp string has the format:

 currtime.pid@ipaddress

and is used in MD5 authentication procedure.

As the first action immediately after the connection the client must send an authentication string with this format:

 "user"[TAB]"password"<CR><LF>

where user must be enabled to remote admin AfterLogic XMail Server. Clear text authentication should not be used due server security. Using MD5 authentication instead, the client must perform an MD5 checksum on the string composed by (<> included):

 <TimeStamp>password

and then send to the server:

 "user"[TAB]"#md5chksum"<CR><LF>

where md5chksum is the MD5 checksum (note '#' as first char of sent digest). The result of the authentication send is a RESSTRING. If the user does not receive a positive authentication response, the connection is closed by the server. It is possible to establish an SSL session with the server by issuing the ''#!TLS'' string as login string. In response to that, the server will send back a RESSTRING. In case of success RESSTRING, the client can proceed with the SSL link negotiation with the server.

[top]


Adding a user

 "useradd"[TAB]"domain"[TAB]"username"[TAB]"password"[TAB]"usertype"<CR><LF>

where:

domain

domain name (must be handled by the server).

username

username to add.

password

user password.

usertype

'U' for normal user and 'M' for mailing list.

The result is a RESSTRING.

[top]


Deleting a user

 "userdel"[TAB]"domain"[TAB]"username"<CR><LF>

where:

domain

domain name (must be handled by the server).

username

username to delete.

The result is a RESSTRING.

[top]


Changing a user's password

 "userpasswd"[TAB]"domain"[TAB]"username"[TAB]"password"<CR><LF>

where:

domain

domain name (must be handled by the server).

username

username (must exist).

password

new password.

The result is a RESSTRING.

[top]


Authenticate user

 "userauth"[TAB]"domain"[TAB]"username"[TAB]"password"<CR><LF>

where:

domain

domain name.

username

username.

password

password.

The result is a RESSTRING.

[top]

Retrieve user statistics

 "userstat"[TAB]"domain"[TAB]"username"<CR><LF>

where:

domain

domain name.

username

username/alias.

The result is a RESSTRING. If successful (00100), a formatted matching users list follows terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:

 "variable"[TAB]"value"<CR><LF>

Where valid variables are:

RealAddress

real address (maybe different is the supplied username is an alias).

MailboxSize

total size of the mailbox in bytes.

MailboxMessages

total number of messages.

LastLoginIP

last user login IP address.

LastLoginTimeDate

time of the last login.

[top]


Adding an alias

 "aliasadd"[TAB]"domain"[TAB]"alias"[TAB]"account"<CR><LF>

where:

domain

domain name (must be handled by the server).

alias

alias to add.

account

real email account (locally handled). This can be a fully qualified email address or a username inside the same domain.

The result is a RESSTRING.

[top]


Deleting an alias

 "aliasdel"[TAB]"domain"[TAB]"alias"<CR><LF>

where:

domain

domain name (must be handled by the server).

alias

alias to delete.

The result is a RESSTRING.

[top]


Listing aliases

 "aliaslist"[TAB]"domain"[TAB]"alias"[TAB]"account"<CR><LF>

or

 "aliaslist"[TAB]"domain"[TAB]"alias"<CR><LF>

or

 "aliaslist"[TAB]"domain"<CR><LF>

or

 "aliaslist"<CR><LF>

where:

domain

domain name, optional (can contain wild cards).

alias

alias name, optional (can contain wildcards).

account

account, optional (can contain wildcards).

Example:

 "aliaslist"[TAB]"foo.bar"[TAB]"*"[TAB]"mickey"<CR><LF>

lists all aliases of user 'mickey' in domain 'foo.bar'.

The result is a RESSTRING. In successful cases (00100) a formatted matching users list follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:

 "domain"[TAB]"alias"[TAB]"username"<CR><LF>

[top]


Adding an external alias

 "exaliasadd"[TAB]"local-address"[TAB]"remote-address"<CR><LF>

where:

local-address

local email address.

remote-address

remote email address.

For example, the following command string:

 "exaliasadd"[TAB]"axmsuser@home.bogus"[TAB]"axmsuser@axmsserver.org"<CR><LF>

will link the external email address 'axmsuser@axmsserver.org' with the local email address 'axmsuser@home.bogus'. The result is a RESSTRING.

[top]


Deleting an external alias

 "exaliasdel"[TAB]"remote-address"<CR><LF>

where:

remote-address

remote email address.

The result is a RESSTRING.

[top]


Listing external aliases

 "exaliaslist"[TAB]"local-address"[TAB]"remote-address"<CR><LF>

or

 "exaliaslist"[TAB]"local-address"<CR><LF>

or

 "exaliaslist"<CR><LF>

where:

local-address

local email address. This can contain wildcard characters.

remote-address

remote email address. This can contain wildcard characters.

Example:

 "exaliaslist"[TAB]"*@home.bogus"<CR><LF>

lists all the external aliases linked to local accounts in domain 'home.bogus'.

The result is a RESSTRING. In successful cases (00100) a formatted matching users list follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:

 "rmt-domain"[TAB]"rmt-name"[TAB]"loc-domain"[TAB]"loc-name"<CR><LF>

[top]


Listing user vars

 "uservars"[TAB]"domain"[TAB]"username"<CR><LF>

where:

domain

domain name.

username

username.

The result is a RESSTRING. In successfully cases (00100) a formatted list of user vars follow, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:

 "varname"[TAB]"varvalue"<CR><LF>

[top]


Setting user vars

 "uservarsset"[TAB]"domain"[TAB]"username"[TAB]"varname"[TAB]"varvalue" ... <CR><LF>

where:

domain

domain name.

username

username.

varname

variable name.

varvalue

variable value.

There can be multiple variable assignments with a single call. If 'varvalue' is the string '.|rm' the variable 'varname' is deleted. The result is a RESSTRING.

[top]


Listing users

 "userlist"[TAB]"domain"[TAB]"username"[TAB]"start_number"[TAB]"request_amount"<CR><LF>

or

 "userlist"[TAB]"domain"[TAB]"username"<CR><LF>

or

 "userlist"[TAB]"domain"<CR><LF>

or

 "userlist"<CR><LF>

where:

domain

domain name, optional (can contain wild cards).

username

username, optional (can contain wild cards).

start_number

start number of user in the list, optional (can contain integer numbers only).

request_amount

request amount - size of the batch of listed users, optional (can contain integer numbers only).

Example:

 "userlist"[TAB]"spacejam.foo"[TAB]"*admin"<CR><LF>

lists all users of domain 'spacejam.foo' that end with the word 'admin'.

The result are a RESSTRING. If successful (00100), a formatted matching users list follows terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:

 "domain"[TAB]"username"[TAB]"password"[TAB]"usertype"<CR><LF>

[top]


Counting users

 "usercount"[TAB]"domain"<CR><LF>

or

 "usercount"<CR><LF>

where:

domain

domain name, optional (can contain wild cards).

Example:

 "usercount"[TAB]"spacejam.foo"[TAB]"<CR><LF>

count all users from the domain 'spacejam.foo'.

The result are a RESSTRING. If successful (00100), a formatted usercount list follows terminated by a line containing a single dot (<CR><LF>.<CR><LF>). This is the format of the listing:

 "domain"[TAB]"usercount"<CR><LF>

[top]


Getting mailproc.tab file

 "usergetmproc"[TAB]"domain"[TAB]"username"<CR><LF>
 
or
 "usergetmproc"[TAB]"domain"[TAB]"username"[TAB]"flags"<CR><LF>

where:

domain

domain name.

username

username.

flags

flags specifying which mailproc to retrieve. Use 'U' for user mailproc, or 'D' for domain mailproc (or 'DU' for a merge of both). If not specified, 'DU' is assumed.

Example:

 "usergetmproc"[TAB]"spacejam.foo"[TAB]"admin"<CR><LF>

gets mailproc.tab file for user 'admin' in domain 'spacejam.foo'.

The result is a RESSTRING. In successful cases (00100) the mailproc.tab file is listed line by line, terminated by a line containing a single dot (<CR><LF>.<CR><LF>).

[top]


Setting mailproc.tab file

 "usersetmproc"[TAB]"domain"[TAB]"username"<CR><LF>
 
or
 "usersetmproc"[TAB]"domain"[TAB]"username"[TAB]"which"<CR><LF>

where:

domain

domain name.

username

username.

which

which mailproc.tab should be set. Use 'U' for the user one, and 'D' for the domain one. If not specified, 'U' is assumed.

Example:

 "usersetmproc"[TAB]"spacejam.foo"[TAB]"admin"<CR><LF>

sets mailproc.tab file for user 'admin' in domain 'spacejam.foo'.

The result is a RESSTRING. If successful (00101), the client must list the mailproc.tab file line by line, ending with a line containing a single dot (<CR><LF>.<CR><LF>). If a line of the file begins with a dot, another dot must be added at the beginning of the line. If the file has zero length the mailproc.tab is deleted. The client then gets another RESSTRING indicating the final command result.

[top]


Adding a mailing list user

 "mluseradd"[TAB]"domain"[TAB]"mlusername"[TAB]"mailaddress"[TAB]"perms"<CR><LF>

or

 "mluseradd"[TAB]"domain"[TAB]"mlusername"[TAB]"mailaddress"<CR><LF>

where:

domain

domain name (must be handled by the server).

mlusername

mailing list username.

mailaddress

mail address to add to the mailing list 'mlusername@domain'.

perms

user permissions (R or RW or RA). When 'perms' is not specified the default is RW.

The result is a RESSTRING.

[top]


Deleting a mailing list user

 "mluserdel"[TAB]"domain"[TAB]"mlusername"[TAB]"mailaddress"<CR><LF>

where:

domain

domain name (must be handled by the server).

mlusername

mailing list username.

mailaddress

mail address to delete from the mailing list 'mlusername@domain'.

The result is a RESSTRING.

[top]


Listing mailing list users

 "mluserlist"[TAB]"domain"[TAB]"mlusername"<CR><LF>

where:

domain

domain name (must be handled by the server).

mlusername

mailing list username.

The result is a RESSTRING. If successful (00100), a formatted list of mailing list users follows terminated by a line containing a single dot (<CR><LF>.<CR><LF>).

[top]


Adding a domain

 "domainadd"[TAB]"domain"<CR><LF>

where:

domain

domain name to add.

The result is a RESSTRING.

[top]


Deleting a domain

 "domaindel"[TAB]"domain"<CR><LF>

where:

domain

domain name to delete.

The result is a RESSTRING. This is not always a safe operation.

[top]


Listing handled domains

 "domainlist"<CR><LF>

or:

 "domainlist"[TAB]"wildmatch0"[TAB]...[TAB]"wildmatchN"<CR><LF>

The result is a RESSTRING. The wild match versions simply returns a filtered list of domains. If successful (00100), a formatted list of handled domains follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>).

[top]


Adding a domain alias

 "aliasdomainadd"[TAB]"realdomain"[TAB]"aliasdomain"<CR><LF>

Example:

 "aliasdomainadd"[TAB]"axmsserver.org"[TAB]"axmsserver.com"<CR><LF>

defines 'axmsserver.com' as an alias of 'axmsserver.org', or:

 "aliasdomainadd"[TAB]"axmsserver.org"[TAB]"*.axmsserver.org"<CR><LF>

defines all subdomains of 'axmsserver.org' as alises of 'axmsserver.org'.

[top]


Deleting a domain alias

 "aliasdomaindel"[TAB]"aliasdomain"<CR><LF>

Example:

 "aliasdomaindel"[TAB]"*.axmsserver.org"<CR><LF>

removes the '*.axmsserver.org' domain alias.

[top]


Listing alias domains

 "aliasdomainlist"<CR><LF>

or:

 "aliasdomainlist"[TAB]"wild-dom-match"<CR><LF>

or:

 "aliasdomainlist"[TAB]"wild-dom-match"[TAB]"wild-adom-match"<CR><LF>

The result is a RESSTRING. The wild match version simply returns a filtered list of alias domains. If successful (00100), a formatted list of alias domains follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). The output format is:

 "real-domain"[TAB]"alias-domain"<CR><LF>

[top]


Getting custom domain file

 "custdomget"[TAB]"domain"<CR><LF>

where:

domain

domain name.

Example:

 "custdomget"[TAB]"spacejam.foo"<CR><LF>

gets the custom domain file for domain 'spacejam.foo'.

The result is a RESSTRING. If successful (00100), the custom domain file is listed line by line terminated by a line containing a single dot (<CR><LF>.<CR><LF>).

[top]


Setting custom domain file

 "custdomset"[TAB]"domain"<CR><LF>

where:

domain

domain name.

Example:

 "custdomset"[TAB]"spacejam.foo"<CR><LF>

sets custom domain file for domain 'spacejam.foo'.

The result is a RESSTRING. If successful (00101), the client must list the custom domain file line by line, ending with a line containing a single dot (<CR><LF>.<CR><LF>). If a line of the file begins with a dot, another dot must be added at the begin of the line. If the file has zero length the custom domain file is deleted. The client then gets another RESSTRING indicating the final command result.

[top]


Listing custom domains

 "custdomlist"<CR><LF>

The result is a RESSTRING. If successful (00100), a formatted list of custom domains follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>).

[top]


Adding a POP3 external link

 "poplnkadd"[TAB]"loc-domain"[TAB]"loc-username"[TAB]"extrn-domain"=>
   [TAB]"extrn-username"[TAB]"extrn-password"[TAB]"authtype"<CR><LF>

where:

loc-domain

local domain name (must be handled by the server).

loc-username

local username which receives mails.

extrn-domain

external domain.

extrn-username

external username.

extrn-password

external user password.

authtype

authentication method (see [POP3LINKS.TAB]).

The remote server must support 'APOP' authentication to specify APOP as authtype. Using APOP authentication is more secure because clear usernames and passwords do not travel on the network; if you're not sure about it, specify 'CLR' as authtype.

The result is a RESSTRING.

[top]


Deleting a POP3 external link

 "poplnkdel"[TAB]"loc-domain"[TAB]"loc-username"[TAB]"extrn-domain"=>
   [TAB]"extrn-username"<CR><LF>

where:

loc-domain

local domain name (must be handled by the server).

loc-username

local username which receives mails.

extrn-domain

external domain.

extrn-username

external username.

The result is a RESSTRING.

[top]


Listing POP3 external links

 "poplnklist"[TAB]"loc-domain"[TAB]"loc-username"<CR><LF>

or

 "poplnklist"[TAB]"loc-domain"<CR><LF>

or

 "poplnklist"<CR><LF>

The result is a RESSTRING. If successful (00100), a formatted list of handled domains follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). The format of the listing is:

 "loc-domain"[TAB]"loc-username"[TAB]"extrn-domain"[TAB]"extrn-username"=>
   [TAB]"extrn-password"[TAB]"authtype"[TAB]"on-off"<CR><LF>

[top]


Enabling a POP3 external link

 "poplnkenable"[TAB]"enable"[TAB]"loc-domain"[TAB]"loc-username"=>
   [TAB]"extrn-domain"[TAB]"extrn-username"<CR><LF>

or

 "poplnkenable"[TAB]"enable"[TAB]"loc-domain"[TAB]"loc-username"<CR><LF>

where:

enable

1 for enabling - 0 for disabling.

loc-domain

local domain name.

loc-username

local username which receives mails.

extrn-domain

external domain.

extrn-username

external username.

In the second format all users, links are affected by the enable operation.

The result is a RESSTRING.

[top]


Listing files

 "filelist"[TAB]"relative-dir-path"[TAB]"match-string"<CR><LF>

where:

relative-dir-path

path relative to MAIL_ROOT path.

match-string

wild card match string for file list selection.

The result is a RESSTRING. If successful (00100), the directory is listed line by line, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). The listing format is:

''filename''[TAB]''filesize''<CR><LF>

[top]


Getting configuration file

 "cfgfileget"[TAB]"relative-file-path"<CR><LF>

where:

relative-file-path

path relative to MAIL_ROOT path.

Example:

 "cfgfileget"[TAB]"ctrlaccounts.tab"<CR><LF>

The result is a RESSTRING. If successful (00100), the file is listed line by line, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). You CANNOT use this command with indexed files !

[top]


Setting configuration file

 "cfgfileset"[TAB]"relative-file-path"<CR><LF>

where:

relative-file-path

path relative to MAIL_ROOT path.

Example:

 "cfgfileset"[TAB]"ctrlaccounts.tab"<CR><LF>

The result is a RESSTRING. IF successful (00101), the client must list the configuration file line by line, ending with a line containing a single dot (<CR><LF>.<CR><LF>). If a line of the file begins with a dot, another dot must be added at the beginning of the line. If the file has zero length the configuration file is deleted. The client then gets another RESSTRING indicating the final command result. Remember that configuration files have a strict syntax and that pushing a incorrect one can make AfterLogic XMail Server not work properly. You CANNOT use this command with indexed files!

[top]


Listing frozen messages

 "frozlist"<CR><LF>

The result is a RESSTRING. If successful (00100), a formatted list of frozen messages follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>). The format of the listing is:

 "msgfile"[tab]"lev0"[TAB]"lev1"[TAB]"from"[TAB]"to"[TAB]"time"[TAB]"size"<CR><LF>

Where:

msgfile

message name or id.

lev0

queue fs level 0 (first level directory index).

lev1

queue fs level 1 (second level directory index).

from

message sender.

to

message destination.

time

message time (''YYYY-MM-DD HH:MM:SS'').

size

message size in bytes.

[top]


Rescheduling frozen message

 "frozsubmit"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"<CR><LF>

where:

msgfile

message name or id.

lev0

queue fs level 0 (first level directory index).

lev1

queue fs level 1 (second level directory index).

You can get this information from the frozlist command. After a message has been successfully rescheduled it is deleted from the frozen fs path. The result is a RESSTRING.

[top]


Deleting frozen message

 "frozdel"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"<CR><LF>

where:

msgfile

message name or id.

lev0

queue fs level 0 (first level directory index).

lev1

queue fs level 1 (second level directory index).

You can get this information from the frozlist command. The result is a RESSTRING.

[top]


Getting frozen message log file

 "frozgetlog"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"<CR><LF>

where:

msgfile

message name or id.

lev0

queue fs level 0 (first level directory index).

lev1

queue fs level 1 (second level directory index).

You can get this information from the frozlist command. The result is a RESSTRING. If successful (00100), the frozen message log file follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>).

[top]


Getting frozen message

 "frozgetmsg"[TAB]"lev0"[TAB]"lev1"[TAB]"msgfile"<CR><LF>

where:

msgfile

message name or id.

lev0

queue fs level 0 (first level directory index).

lev1

queue fs level 1 (second level directory index).

You can get this information from the frozlist command. The result is a RESSTRING. If successful (00100), the frozen message file follows, terminated by a line containing a single dot (<CR><LF>.<CR><LF>).

[top]


Starting a queue flush

 "etrn"[TAB]"email-match0"...<CR><LF>

where:

email-match0

wild card email matching for destination address.

Example:

 "etrn"  "*@*.mydomain.com"  "your-domain.org"

starts queueing all messages with a matching destination address.

[top]


Do nothing command

''noop''<CR><LF>

The result is a RESSTRING.

[top]


Quit the connection

 "quit"<CR><LF>

The result is a RESSTRING.

[top]


Do you want...?

Do you want to build GUI configuration tools using common scripting languages (Java, TCL/Tk, etc) and AfterLogic XMail Server controller protocol? Do you want to build any of Web configuration tools? Please let us know <support@afterlogic.com>.

[top]