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.
Comments