WebAdmin API - REST - Version 6.0 > 7.5.0 – atmail help centre

PROBLEM

How can I use the atmail WebAdmin API?

ENVIRONMENT

On-Premise Server + WebMail Installations: Version 6.0 > 7.5.0
Webmail Only Installations: Version 6.0 > 7.5.0

CAUSE

WebAdmin API requirement.

RESOLUTION

REST

REST (representational state transfer) is an approach for getting information content from a Web site by reading a designated Web page that contains an XML (Extensible Markup Language) file that describes and includes the desired content.

Below is the full documentation on adding, modifying, deleting user accounts, domains, admins and more from the Atmail API.

API Calls

XML format

<?xml version="1.0" encoding="UTF-8"?>

Using REST will generally accept GET or POST but should also support standard request types

Authentication via HTTP ( like CalDAV, htaccess, etc )
HTTP GET - Read
HTTP POST - Create
HTTP PUT - Update, Create
HTTP DELETE - Delete

HTTP response headers will be one of the following:

100 Continue
200 OK
201 Created
202 Accepted
304 Not Modified
400 Bad Request
401 Authorization required
403 Forbidden
404 Not Found
405 Method Not Allowed
412 Precondition Failed
500 Internal Server Error
501 Not Implemented

Examples

Authenticate

Auth an admin users

The API is stateless and therefore sessionless. The HTTP Auth header must be sent with each request.

Example: In the browser, go to the atmail installation url: /index.php/api/login/authenticate
The browser will get challenged by the server with an HTTP Auth request and should request an Authentication username and password
This will automatically set this header in the browser and send this header with future requests
When writing an API CLIENT you will need to send this HTTP Auth header with each request

http://domain.com/mail/index.php/api/login/authenticate/

Parameters

Username
Password

Responses

User success

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<authenticate>
<response>
<message>Authentication success</message>
</response>
<status>success</status>
</authenticate>
</api>

User failure

HTTP Response: 401 (Authorization required)
 
<api generator="zend" version="1.0">
<authenticate>
<response>
<message>Authentication failed</message>
</response>
<status>failed</status>
</authenticate>
</api>

Add Domain

Add a new domain to the system

http://domain.com/mail/index.php/api/domain/create/name/domain.com

Parameters

name

Response

Add success

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<domainadd>
<message>domain.com added</message>
<status>success</status>
</domainadd>
</api>

Domain already exists

HTTP Response: 412 (Precondition Failed)
 
<api generator="zend" version="1.0">
<domainadd>
<message>domain.com already exists</message>
<status>failed</status>
</domainadd>
</api>

Domain cannot be added: No permission at that domain

HTTP Response: 403 (Forbidden)   
 
<api generator="zend" version="1.0">
<domainadd>
<message>Permission denied</message>
<status>failed</status>
</domainadd>
</api>

Domain cannot be added: No domain credits available

HTTP Response: 403 (Forbidden)   
 
<api generator="zend" version="1.0">
<domainadd>
<message>No domain credits</message>
<status>failed</status>
</domainadd>
</api>

Delete Domain

Delete a domain on the system

 http://domain.com/mail/index.php/api/domain/delete/name/domain.com

Parameters

name

Response

Add success

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<domaindelete>
<message>jim.com deleted</message>
<status>success</status>
</domaindelete>
</api>

Domain does not exist

HTTP Response: 404
 
<api generator="zend" version="1.0">
<domaindelete>
<message>jim.com does not exist</message>
<status>failed</status>
</domaindelete>
</api>

Check Domain

Check if a domain exists on the server

http://domain.com/mail/index.php/api/domain/check/name/domain.com

Parameters

name

Response

Domain exists

 HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<domaincheck>
<response>
<message>domain.com exists</message>
</response>
<status>success</status>
</domaincheck>
</api>

Domain does not exist

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<domaincheck>
<response>
<message>domain.com does not exist</message>
</response>
<status>failed</status>
</domaincheck>
</api>

Add User

Add a new user to the system

http://domain.com/mail/index.php/api/users/create/name/user@domain.com

Parameters

Password - Required, otherwise random password generated
UserFirstName - Used for Global addressbook entry
UserLastName - Used for Global addressbook entry
Ugroup - Custom User-group
UserQuota - Disk space in MB

Responses

User success

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<useradd>
<response>
<message>user@domain.com added</message>
<id>1</id>
</response>
<status>success</status>
</useradd>
</api>

User exists

HTTP Response: 412 (Precondition Failed)
 
<api generator="zend" version="1.0">
<useradd>
<response>
<message>User exists</message>
</response>
<status>failed</status>
</useradd>
</api>

User cannot be created: Domain does not exist

HTTP Response: 412 (Precondition Failed)
 
<api generator="zend" version="1.0">
<useradd>
<response>
<message>Local domain does not exist</message>
</response>
<status>failed</status>
</useradd>
</api>

User cannot be created: No permission at that domain

HTTP Response: 403 (Forbidden)
 
<api generator="zend" version="1.0">
<useradd>
<response>
<message>Permission denied</message>
</response>
<status>failed</status>
</useradd>
</api>

User cannot be created: No user credits

HTTP Response: 403 (Forbidden)
 
<api generator="zend" version="1.0">
<useradd>
<response>
<message>No user credits available</message>
</response>
<status>failed</status>
</useradd>
</api>

Delete User

Delete user from the system.

http://domain.com/mail/index.php/api/users/delete/name/user@domain.com

Parameters

name

Response

Delete success

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<userdelete>
<response>
<message>Account deleted</message>
</response>
<status>success</status>
</userdelete>
</api>

User does not exist

HTTP Response: 412 (Precondition Failed)
 
<api generator="zend" version="1.0">
<userdelete>
<response>
<message>User does not exist</message>
</response>
<status>failed</status>
</userdelete>
</api>

User cannot be deleted: No permission at that domain

HTTP Response: 403 (Forbidden)
 
<api generator="zend" version="1.0">
<userdelete>
<response>
<message>Permission denied</message>
</response>
<status>failed</status>
</userdelete>
</api>

Update User

Update an existing user

http://domain.com/mail/index.php/api/users/update/name/user@domain.com

Parameters

Any field can be specified, if a field is not defined value will not be updated in the DB. If a fieldname is defined without a value, the field is updated as null in the DB

name or userId (key field)
UserFirstName
UserLastName
Ugroup - Custom User-group
UserQuota - Disk space in MB
Any AddressBookField - as in Abook table
NewUsername - This will change the specified user's username to that which is passed as the value for the NewUsername parameter. Domain cannot be changed at this time therefore you should only pass the new username part only, no domain

Response

Update success

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<userupdate>
<response>
<message>Account updated</message>
</response>
<status>success</status>
</userupdate>
</api>

User does not exist

HTTP Response: 412 (Precondition Failed)
 
<api generator="zend" version="1.0">
<userupdate>
<response>
<message>Account does not exist</message>
</response>
<status>failed</status>
</userupdate>
</api>

User cannot be update: No permission at that domain

HTTP Response: 403 (Forbidden)
 
<api generator="zend" version="1.0">
<userupdate>
<response>
<message>Permission denied</message>
</response>
<status>failed</status>
</userupdate>
</api>

Create an Email Alias

Create an email alias, divert a local alias at a domain to another user.

http://domain.com/mail/index.php/api/aliases/create/

Parameters

AliasName - Required, the local address to divert. e.g abuse@localdomain.com
AliasTo - Required, the address to divert the email to. e.g admin@isp.com
AliasType - Required. Values are Local ( divert a local domain to another user) , Deliver ( Deliver to the local user and alias ) or Domain ( Divert one domain to another )

Response

Create success

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<aliasescreate>
<response>
<message>Success</message>
</response>
<status>success</status>
</aliasescreate>
</api>

Alias already exists

HTTP Response: 412 (Precondition Failed)
 
<api generator="zend" version="1.0">
<aliasescreate>
<response>
<message>Duplicate admin@isp.com</message>
</response>
<status>failed</status>
</aliasescreate>
</api>

Deleting Email Aliases

Delete an email alias according to arguments passed

http://domain.com/mail/index.php/api/aliases/delete/

Parameters

AliasName - Optional, delete entries that have the AliasName specified
AliasTo - Optional, delete entries that have the AliasTo specified
AliasMailDir - Otional. Delete entries that have the AliasMailDir specified. This argument should be passed in a query string (e.g. http://domain.com/index.php/api/aliases/delete/?AliasMailDir=/some/path)
id - Optional, delete the row with the specified id

While the above parameters are all optional, at least one of them must be used. The above parameters can also be combined in one call so as to be more specific about which row to delete from the DB table e.g. http://domain.com/index.php/api/aliases/delete/AliasTo/user@dom.com/AliasName/user2@dom.com. When multiple arguments are passed they are joined with an AND operator so all must match for the row to be deleted.

Response

Delete success

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<aliasesdelete>
<response>
<message>Alias(s) removed</message>
</response>
<status>success</status>
 
</aliasesdelete></api>

Alias does not exist

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<aliasesdelete>
<response>
<message>Alias does not exist</message>
</response>
<status>failed</status>
 
</aliasesdelete></api>

Illegal argument name passed

HTTP Response: 200 (OK)
 
<api generator="zend" version="1.0">
<aliasesdelete>
<response>
<message>illegal argument name used: someArgName</message>
</response>
<status>failed</status>
 
</aliasesdelete></api>

Example: Adding sample users

Add the domain first

http://domain.com/mail/index.php/api/domain/create/name/domain.com

or the equivalent SQL

mysql> insert into Domains (Hostname) VALUES('atmail7virgin.com');

Then the User

http://domain.com/mail/index.php/api/users/create/name/user1@domain.com/password/1234

or equivalent SQL quesies for Users, UserSession, and UserSettings tables

mysql> insert into Users (Account, UserQuota, MailDir) VALUES(', '20303022', /');
mysql> insert into UserSession (Account, Password) VALUES(', 'benben');
mysql> insert into UserSettings(Account, CalDavUrl) VALUES(', 'http://localhost:8008/calendars/users/');

Complete API method listing and required arguments

/api
    /admin
        /authenticate
        /setpassword 
            * id
            * Username
            * passwordOld
            * passwordNew

    /aliases
        /create 
            * AliasName
            * AliasTo
            * AliasMailDir
            * aliasType = Local, Divert, or Domain

        /view
            * AliasName
        /list
        /update
            * AliasName
        /delete

            Optional (but at least one must be used)
            * AliasName
            * AliasTo
            * AliasMailDir
            * id
    /domain
        /create
            * name
        /check
            * name
        /list
        /delete
            * name
    /subadmin
        /create
            * Username
            * Password

            Optional:
            * Domains - List of domains to delegate admin control over ( e.g. in URL .../Domains/domain1.com/Domains/domain2.com... )
            * UAdd - allowed to add users
            * UDelete - allowed to add users
            * UModify - allowed to add users
            * UPurge - allowed to add users
            * USearch - allowed to add users
            * UList - allowed to add users
            * UMigrate - allowed to add users
            * ULogs - allowed to add users
            * UAlias - allowed to add users
            * NumUsers - users allowed to create
            * Company
            * Fullname
            * NumQuota - Total user disk Quota to allocate
            * UMasterAdmin - allowed full administrator rights

        /view
            * Username or id
        /list
        /update
            * Username or id

            Optional:
            * Password
            * Domains[] - List of domains to delegate admin control over ( array )
            * UAdd - allowed to add users
            * UDelete - allowed to add users
            * UModify - allowed to add users
            * UPurge - allowed to add users
            * USearch - allowed to add users
            * UList - allowed to add users
            * UMigrate - allowed to add users
            * ULogs - allowed to add users
            * UAlias - allowed to add users
            * NumUsers - users allowed to create
            * Company
            * Fullname
            * NumQuota - Total user disk Quota to allocate
            * UMasterAdmin - allowed full administrator rights
        /delete
            * Username or id

    /users
        /create
            * name
            * Password

            Optional:
            * Password

            * PasswordQuestion
            * PasswordMD5
            * UserStatus
            * MailDir
            * Forward
            * AutoReply
            * UserQuota - Disk space in MB
            * FirstName
            * LastName
            * Ugroup - Custom User-group
            * Any AddressBookField - as in Abook table
            * more fields will become available through the API as features are added to the system
        /view
            * Username (name) or id (id)
        /list
            Optional filter arguments:
            * domain
            * start
            * volume
           
 * searchQuery (test to search all fields for, or lastLogin=x to search 
for all accounts who have not logged in in x days)
        /update
            * Username (name) or id (id)
            * Most fields available in /create
            * enabled (true or false)
	        * NewUsername (username part only, no domain)
	 /delete
            * name

    /groups
        /create
            * groupName
            * POP3Support // external pop3 access 1 = enabled, 0 = disabled
            * IMAPSupport // external imap access 1 = enabled, 0 = disabled
            * GroupwareZone // System, Domain, or Off
            * Sync // 1 = enabled, 0 = disabled
            * Webmail // Webmail access 1 = enabled, 0 = disabled
            * Calendar // Calendar access 1 = enabled, 0 = disabled
            * SharedAbook // SharedAbook 1 = enabled, 0 = disabled
        /get
            * groupName
        /exists
            * groupName
        /list

        /total
            * groupName

        /listtotals

        /update
            * groupName
            * POP3Support // external pop3 access 1 = enabled, 0 = disabled
            * IMAPSupport // external imap access 1 = enabled, 0 = disabled
            * GroupwareZone // System, Domain, or Off
            * Sync // 1 = enabled, 0 = disabled
            * Webmail // Webmail access 1 = enabled, 0 = disabled
            * Calendar // Calendar access 1 = enabled, 0 = disabled
            * SharedAbook // SharedAbook 1 = enabled, 0 = disabled

        /useradd // for assigning users to groups
            * groupName
            * Account


        /userdelete //for deleting users from groups (wont delete the user)
            * groupName
            * Account

        /delete
            * groupName

Product API Support

API Support Matrix
API Call		Server Version	WebMail Client Only
Admin	Set Password
Aliases	Create
Aliases	View
Aliases	List
Aliases	Update
Aliases	Delete
Domain	Create
Domain	Check
Domain	List
Domain	Delete
SubAdmin	Create
SubAdmin	View
SubAdmin	List
SubAdmin	Update
SubAdmin	Delete
Users	Create
Users	View
Users	List
Users	Update
Users	Delete
Groups	Create
Groups	Get
Groups	Exists
Groups	List
Groups	Total
Groups	List Totals
Groups	Update
Groups	User Add
Groups	User Delete
Groups	Delete

REST Client sample code

Below is some sample code intended to assist with getting up and running with a REST client accessing the API the code is written in PHP

Zend Framework Example

//Domain check
$serverURI = "http://www.yourdomain.com/";
$client = new Zend_Rest_Client( $serverURI );
Zend_Rest_Client::getHttpClient()->setAuth( $username, $password );
$method = "/mail/index.php/api/domain/check/name/" . $name;
$result = $this->client->get( $method );
//Result should contain XML Object
print_r( array('status' => (string)$result->status, 'response' => (string)$result->response->message) );

Simple PHP script example

The following example can be run on the command-line using PHP. The example creates a domain-name in the system, then assigns a Subadmin user to that account for control.

// Admin username/password
$adminuser = "admin";
$adminpass = "mypass";
$adminurl = "http://$adminuser:$adminpass@localhost/";
 
// Setup vars
$domain = "mydomain.com";
 
// Subadmin username and password to create
$password = "changeme";
$username = "subadminuser";
 
// Subadmin permissions
$numusers = "10";
 
// Subadmin user quota in MB
$numquota = "1024";
 
// Make the users Account, replace admin with your Webadmin username, and mypass with the administrator password
$url = $adminurl . "mail/index.php/api/domain/create/name/" . $domain;
$output = file_get_contents($url);
 
echo "Creating Domain\n";
echo $output;
 
// Add a Subadmin user, with full permissions over the selected domain
$url = $adminurl . "/mail/index.php/api/subadmin/create/?Username="
 . $username . "&Password=" . $password . "&Domains[]=" . 
$domain . 
"&UAdd=1&UDelete=1&UModify=1&USearch=1&UList=1&UMigrate=1&ULogs=1&UAlias=1&NumUsers=$numusers&NumQuota=$numquota&Company=Test";
$output = file_get_contents($url);
 
echo "Creating Subadmin User\n";
echo $output;

Should you find that you are needing additional functionality from the API please let us know, we are always keen to add functionality if it is in demand.

REST

API Calls

XML format

Using REST will generally accept GET or POST but should also support standard request types

HTTP response headers will be one of the following:

Examples

Authenticate

Responses

User success

User failure

Add Domain

Response

Add success

Domain already exists

Domain cannot be added: No permission at that domain

Domain cannot be added: No domain credits available

Delete Domain

Response

Add success

Domain does not exist

Check Domain

Response

Domain exists

Domain does not exist

Add User

Responses

User success

User exists

User cannot be created: Domain does not exist

User cannot be created: No permission at that domain

User cannot be created: No user credits

Delete User

Response

Delete success

User does not exist

User cannot be deleted: No permission at that domain

Update User

Response

Update success

User does not exist

User cannot be update: No permission at that domain

Create an Email Alias

Response

Create success

Alias already exists

Deleting Email Aliases

Response

Delete success

Alias does not exist

Illegal argument name passed

Example: Adding sample users

Complete API method listing and required arguments

Product API Support

REST Client sample code

Zend Framework Example

Simple PHP script example

Comments