PROBLEM
How can I use the mailserver API?
ENVIRONMENT
- atmail mailserver version 1.0.0+
CAUSE
mailserver 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 mail server API.
API Calls
XML format
<?xml version="1.0" encodeing="UTF-8"?>
Using REST will generally accept GET or POST but should also support standard request types
- HTTP GET - Read
- HTTP POST - Create
- HTTP PUT - Update, Create
- HTTP DELETE - Delete
Examples
AUTHENTICATE
Auth an admin user.
The API is stateless and therefore sessionless. Authentication must be sent with each request.
curl -i -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/users/authenticate/"
auto-cursor-target">Responses
User success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <authenticate> <status>success</status> <response> <message>Authentication success</message> <results></results> </response> </authenticate> </api>
User failure
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <authenticate> <status>failed</status> <response> <message>Authentication failed</message> <results></results> </response> </authenticate> </api>
LIST OF PERMISSIONS
List permissions with roles that have the permission.
curl -i -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/users/permissionlist/"
Responses
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <permissionlist> <status>success</status> <response> <message></message> <results> <key_0> <permissionId>1</permissionId> <permissionName>all</permissionName> <permissionDescription>Access to everything</permissionDescription> <roles> <key_1>SuperUser</key_1> </roles> </key_0> <key_1> <permissionId>2</permissionId> <permissionName>account.add</permissionName> <permissionDescription>Right to add accounts</permissionDescription> <roles> <key_1>SuperUser</key_1> </roles> </key_1> ... ... </results> </response> </permissionlist> </api>
LIST OF ROLES
List roles with their hierarchy structure.
curl -i -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/users/rolelist/"
Responses
Success
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
<rolelist>
<status>success</status>
<response>
<message></message>
<results>
<key_1>
<roleId>1</roleId>
<roleName>SuperUser</roleName>
<roleDescription>Special role with rights to everything</roleDescription>
<roleHierarchy></roleHierarchy>
<roleEnabled>1</roleEnabled>
<createdByUserId></createdByUserId>
<myRole>1</myRole>
<children>
<key_2>
<roleId>2</roleId>
<roleName>subadmin</roleName>
<roleDescription>subadmin role</roleDescription>
<roleHierarchy>|1|</roleHierarchy>
<roleEnabled>1</roleEnabled>
<createdByUserId>1</createdByUserId>
<myRole>0</myRole>
</key_2>
</children>
</key_1>
</results>
</response>
</rolelist>
</api>
CREATE USER
Create an admin user.
curl -i --data "username=user1&password=changeme&domainIds=1" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/users/create/"
Parameters(POST)
- username (string, required) - username for login
- password (string, required) - password for login
- fullname (string)
- company (string)
- emailAddress (string)
- numUsers (integer) - the maximum number of accounts the user can create. 16777215 - unlimited
- quota(integer) Required - the total disk quota allocated for accounts the user controls(MB). 0 - unlimited
- domainIds(array of integer) Required - domainIds that the user can edit.
- roleId(integer) Required - Set 0 if no role given.
- permissionIds(array of integer) - Required unless role set.
- parent(integer|string) - Optional - Username or userId of admin user that should become the parent of the user being created
Responses
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <usercreate> <status>success</status> <response> <message>2</message> <results>2</results> </response> </usercreate> </api>
UPDATE USER
Update an admin user.
curl -i --data "userId=2&password=changeme" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/users/update/"
Parameters(POST)
- userId (integer, required)
- password (string)
- fullname (string)
- company (string)
- emailAddress (string)
- numUsers (integer) - the maximum number of accounts the user can create. 16777215 - unlimited
- quota(integer) Required - the total disk quota allocated for accounts the user controls(MB). 0 - unlimited
- domainIds(array of integer) Required - domainIds that the user can edit.
- roleId(integer) Required - Set 0 if no role given.
- permissionIds(array of integer) - Required unless role set.
Responses
Failure - User not exist
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <userupdate> <status>failed</status> <response> <message>User does not exist</message> <results></results> </response> </userupdate> </api>
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <userupdate> <status>success</status> <response> <message></message> <results>119</results> </response> </userupdate> </api>
LIST USER
List all admin users.
curl -i -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/users/list/"
Responses
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <userlist> <status>success</status> <response> <message></message> <results> <key_0> <userId>2</userId> <leftEdge>1</leftEdge> <rightEdge>4</rightEdge> <createdByUserId>1</createdByUserId> <username>subadmin</username> <password>CHANGEME</password> <numUsers>500</numUsers> <company>company</company> <fullname>fullname</fullname> <emailAddress>email@yourdomain.com</emailAddress> <dateCreate>2017-01-01 00:00:00</dateCreate> <lastLogin>1498177834</lastLogin> <modified></modified> <ipAddress>192.168.10.1</ipAddress> <quota>1024</quota> <language>en</language> <cssColorTheme>darkblue</cssColorTheme> <welcomeDisplayed>1</welcomeDisplayed> </key_0> ... ... </results> </response> </userlist> </api>
VIEW USER
View admin user details.
curl -i --data "userId=1" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/users/view/"
Parameters(POST)
- userId (integer, required)
Responses
Failure - User not exist
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <userview> <status>failed</status> <response> <message>No matches found</message> <results></results> </response> </userview> </api>
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <userview> <status>success</status> <response> <message></message> <results> <userId>1</userId> <leftEdge>0</leftEdge> <rightEdge>207</rightEdge> <createdByUserId></createdByUserId> <username>admin</username> <password>CHANGEME</password> <numUsers></numUsers> <company>test</company> <fullname>Initial Admin User</fullname> <emailAddress>admin@yourdomain.com</emailAddress> <dateCreate></dateCreate> <lastLogin>1500432785</lastLogin> <modified></modified> <ipAddress>192.168.10.1</ipAddress> <quota></quota> <language>en</language> <cssColorTheme>darkblue</cssColorTheme> <welcomeDisplayed>0</welcomeDisplayed> <Domains> <key_0>domain1.yourdomain.com</key_0> <key_1>domain2.yourdomain.com</key_1> </Domains> </results> </response> </userview> </api>
VIEW USER PERMISSIONS AND ROLE
View an admin user permissions and roles.
curl -i --data "userId=1" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/users/userpermissionrole/"
Parameters(POST)
- userId (integer, required)
Responses
Success
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
<userpermissionrole>
<status>success</status>
<response>
<message></message>
<results>
<permission>
<key_0>all</key_0>
</permission>
<role>
<key_1>SuperUser</key_1>
</role>
</results>
</response>
</userpermissionrole>
</api>
DELETE USER
Delete an admin user.
curl -i --data "userId=2" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/users/delete/"
Parameters(POST)
- userId (integer, required)
Responses
Failure - User not exist
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <userdelete> <status>failed</status> <response> <message>No users selected.</message> <results></results> </response> </userdelete> </api>
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <userdelete> <status>success</status> <response> <message></message> <results>1</results> </response> </userdelete> </api>
CREATE ACCOUNT
Create an account (End user who will login to webmail)
curl -i --data "username=account1@yourdomain.com&password=changeme" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/accounts/create/"
Parameters(POST)
- username (string, required) - full email address
- password (string, required) - Randomly generated if empty - It is not possible to get the auto-generated password.
- firstName (string)
- lastName (string)
- quota (integer) - Disk space in MB
- oneTimePassword (integer) - 0: password is normal password. 1: password is one time password(OTP)
- forward (string)
- userStatus (integer) - 0: enabled, 1: disabled, 2: deleted, defaults to 0
- migrateStatus (string) - defaults to Migrated, unless otherwise desired, leave set as default
- billingCode (string) - defaults to blank - unless otherwise desired, leave set as default
Responses
Failure - Domain not exist
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
<accountcreate>
<status>failed</status>
<response>
<message>Local domain does not exist</message>
<results></results>
</response>
</accountcreate>
</api>
Success
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
<accountcreate>
<status>success</status>
<response>
<message>account1@yourdomain.com added</message>
<results>
<accounts>
<accountId>10</accountId>
<createdByUserId>1</createdByUserId>
<username>account1@yourdomain.com</username>
<password>CHANGEME</password>
<domainId>1</domainId>
<dateModified>2017-01-01 00:00:00</dateModified>
<dateCreate>2017-01-01 00:00:00</dateCreate>
<userStatus>0</userStatus>
<homeDir>/var/atmail/users/a/c/c/account1@yourdomain.com/</homeDir>
<forward></forward>
<autoReply></autoReply>
<quota>1024</quota>
<lastLogin></lastLogin>
<autoReplyEnabled>0</autoReplyEnabled>
<autoReplySubject></autoReplySubject>
<autoReplyStart></autoReplyStart>
<autoReplyEnd></autoReplyEnd>
<mboxServer>1</mboxServer>
<mboxType>Maildir</mboxType>
<groupId>1</groupId>
<firstName></firstName>
<lastName></lastName>
</accounts>
...
</results>
</response>
</accountcreate>
</api>
UPDATE ACCOUNT
Update an account
curl -i --data "username=account1@yourdomain.com&password=changeme" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/accounts/update/"
Parameters(POST)
- accountId(integer) or username (string)
- password (string)
- firstName (string)
- lastName (string)
- quota (integer) - Disk space in MB
- userStatus (integer) - 0: enabled, 1: disabled
- forward (string)
- oneTimePassword (integer) - 0: password is normal password. 1: password is one time password(OTP)
- userStatus (integer) - 0: enabled, 1: disabled, 2: deleted, defaults to 0
- migrateStatus (string) - defaults to Migrated, unless otherwise desired, leave set as default
- billingCode (string) - defaults to blank - unless otherwise desired, leave set as default
Responses
Failure - Account not exist
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
<accountUpdate>
<response>
<message>User does not exist</message>
</response>
<status>failed</status>
</accountUpdate>
</api>
Success
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
<accountupdate>
<status>success</status>
<response>
<message></message>
<results>
<accountId>10</accountId>
<username>account1@yourdomain.com</username>
</results>
</response>
</accountupdate>
</api>
VIEW ACCOUNT
View an accounts details.
curl -i --data "username=account1@yourdomain.com" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/accounts/view/"
Parameters(POST)
- accountId(integer) or username (string)
Responses
Failure - Account not exist
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <accountview> <status>failed</status> <response> <message>Account does not exist</message> <results></results> </response> </accountview> </api>
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <accountview> <status>success</status> <response> <message></message> <results> <accountId>10</accountId> <createdByUserId>1</createdByUserId> <username>account1@yourdomain.com</username> <password>CHANGEME</password> <domainId>1</domainId> <dateModified>2017-01-01 00:00:00</dateModified> <dateCreate>2017-01-01 00:00:00</dateCreate> <userStatus>0</userStatus> <homeDir>/var/atmail/users/a/c/c/account1@yourdomain.com/</homeDir> <forward></forward> <autoReply></autoReply> <quota>1024</quota> <lastLogin></lastLogin> <mboxServer>1</mboxServer> <mboxType>Maildir</mboxType> <groupId>1</groupId> <firstName></firstName> <lastName></lastName> <UsedQuota>0.0078125</UsedQuota> <TotalMessages>1</TotalMessages> </results> </response> </accountview> </api>
DELETE ACCOUNT
Delete a account.
curl -i --data "username=account1@yourdomain.com" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/accounts/delete/"
Parameters(POST)
- accountId(integer) or username (string)
Responses
Failure - Account not exist
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <accountdelete> <status>failed</status> <response> <message>Single match for User id was not found.</message> <results></results> </response> </accountdelete> </api>
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <accountdelete> <status>success</status> <response> <message>Account deleted</message> <results> <accountId>10</accountId> <createdByUserId>1</createdByUserId> <username>account1@yourdomain.com</username> <password>CHANGEME</password> <domainId>1</domainId> <dateModified>2017-01-01 00:00:00</dateModified> <dateCreate>2017-01-01 00:00:00</dateCreate> <userStatus>0</userStatus> <homeDir>/var/atmail/users/a/c/c/account1@yourdomain.com/</homeDir> <forward></forward> <autoReply></autoReply> <quota>1024</quota> <lastLogin></lastLogin> <mboxServer>1</mboxServer> <mboxType>Maildir</mboxType> <groupId>1</groupId> <firstName></firstName> <lastName></lastName> </results> </response> </accountdelete> </api>
PURGE ACCOUNT
curl -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/accounts/delete/" -d "username=deltest01@yourdomain.com&purgeNow=true"
<?xml version="1.0" encoding="UTF-8"?>
<api generator="zend" version="1.0">
<accountdelete>
<status>success</status>
<response>
<message>Account deleted</message>
<results>
<accountId>32281</accountId>
<createdByUserId>157</createdByUserId>
<username>deltest01@yourdomain.com</username>
<domainId>1</domainId>
<dateModified>2020-05-13 07:49:59</dateModified>
<dateCreate>2020-05-13 07:49:59</dateCreate>
<userStatus>0</userStatus>
<migrateStatus>Migrated</migrateStatus>
<forward></forward>
<quota>10240</quota>
<masterQuota>10240</masterQuota>
<lastLogin></lastLogin>
<groupId>1</groupId>
<firstName></firstName>
<lastName></lastName>
<homeDir>/var/atmail/users/vol1/b/c/1/58454912-94ee-11ea-b6e2-0eb4145c9ba8/</homeDir>
<mboxServer>3</mboxServer>
<mboxType>sdbox</mboxType>
<billingCode></billingCode>
</results>
</response>
</accountdelete>
</api>
LIST ACCOUNT
List all accounts.
curl -i -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/accounts/list/"
Parameters(POST)
- domainId (integer)
- start (integer) - Number of page
- volume (integer) - Number of page volume
Responses
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <accountlist> <status>success</status> <response> <message></message> <results> <key_0> <accountId>10</accountId> <createdByUserId>1</createdByUserId> <username>account1@yourdomain.com</username> <password>CHANGEME</password> <domainId>1</domainId> <dateModified>2017-01-01 00:00:00</dateModified> <dateCreate>2017-01-01 00:00:00</dateCreate> <userStatus>0</userStatus> <homeDir>/var/atmail/users/a/c/c/account1@yourdomain.com/</homeDir> <forward></forward> <autoReply></autoReply> <quota>1024</quota> <lastLogin></lastLogin> <mboxServer>1</mboxServer> <mboxType>Maildir</mboxType> <groupId>1</groupId> <firstName></firstName> <lastName></lastName> </key_0> ... ... </results> </response> </accountlist> </api>
CREATE ALIASES
Create an email alias. divert a local alias at a domain to another user.
curl -i --data "AliasName=test1@yourdomain.com&AliasTo=test2@yourdomain.com&AliasType=Local" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/aliases/create/"
Parameters(POST)
- AliasName (string, required) - The local address to divert. e.g abuse@yourdomain.com
- AliasTo (string, required) - the address to divert the email to. e.g admin@yourdomain.com
- AliasType (string, 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 )
Responses
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <aliasescreate> <status>success</status> <response> <message>Success</message> <results> <key_0> <id>20</id> </key_0> </results> </response> </aliasescreate> </api>
LIST ALIASES
List of email aliases.
curl -i -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/aliases/list/"
Parameters(POST)
- filter (string) - Find aliases matching like Domain, AliasName or AliasTo
- AliasName (string) - Find aliases matching like AliasName
- AliasTo (string) - Find aliases matching like AliasTo
- Domain (string) - Find aliases matching like Domain
Responses
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <aliaseslist> <status>success</status> <response> <message></message> <results> <key_0> <AliasName>test1@yourdomain.com</AliasName> <AliasTo>test2@yourdomain.com</AliasTo> <Domain></Domain> <DateCreate>2017-01-01 00:00:00</DateCreate> <id>283</id> <aliasType>Local</aliasType> <DomainPart>yourdomain.com</DomainPart> </key_0> </results> </response> </aliaseslist> </api>
DELETE ALIAS
Delete an email alias according to the arguments passed.
curl -i --data="AliasName=test1@yourdomain.com" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/aliases/delete/"
Parameters(POST)
- AliasName (string) - Delete entries that have the AliasName specified
- AliasTo (string) - Delete entries that have the AliasTo specified
- id(integer) - Delete the row with the specified id
Responses
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <aliasesdelete> <status>success</status> <response> <message>Alias(s) removed</message> <results></results> </response> </aliasesdelete> </api>
CREATE DOMAIN
Add a new domain to the system.
curl -i --data "domainName=yourdomain.com" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/domain/create/"
Parameters(POST)
- domainName(string, required)
Responses
Failure - Domain existing
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <domaincreate> <status>failed</status> <response> <message>yourdomain is already existing.</message> <results></results> </response> </domaincreate> </api>
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <domaincreate> <status>success</status> <response> <message>Domain added</message> <results>2</results> </response> </domaincreate> </api>
CHECK DOMAIN EXISTS
Check if a domain exists on the server.
curl -i -u --data "domainName=yourdomain.com" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/domain/check/"
Parameters(POST)
- domainName(string, required)
Responses
Failure - Domain not existing
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <domaincheck> <status>failed</status> <response> <message>yourdomain.com does not exist</message> <results></results> </response> </domaincheck> </api>
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <domaincheck> <status>success</status> <response> <message>yourdomain.com exists</message> <results></results> </response> </domaincheck> </api>
DELETE DOMAIN
Delete a domain from the system.
curl -i --data "domainName=yourdomain.com" -u "admin:changeme" "https://yourdomain.com/admin/index.php/api/domain/delete/"
Parameters(POST)
- domainName (string) or domainId (integer)
Responses
Failure - Domain not existing
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <domaindelete> <status>failed</status> <response> <message>Domain does not exist</message> <results></results> </response> </domaindelete> </api>
Success
<?xml version="1.0" encoding="UTF-8"?> <api generator="zend" version="1.0"> <domaindelete> <status>success</status> <response> <message>Domain with id 2 deleted</message> <results> <DeletedAccount>0</DeletedAccount> </results> </response> </domaindelete> </api>
Complete API method listing and required arguments
/api /users /authenticate /permissionlist /rolelist /create * username * password * quota * domainIds * roleId * permissionIds (Required unless roleId set) Optional * fullname * company * emailAddress * numUsers /update * userId Optional * password * fullname * company * emailAddress * numUsers * quota * domainIds * roleId * permissionIds /list /view * userId /userpermissionrole * userId /delete * userId /accounts /create * username * password Optional * firstName * lastName * quota /update * accountId or username Optional * passowrd * firstName * lastName * quota * userStatus /view * accountId or username /delete * accountId or username /list Optional * domainId * start * volume /alises /create * AliasName * AliasTo * AliasType /list Optional * filter * AliasName * AliasTo * Domain /delete * AliasName * AliasTo * id /domain /create * domainName /check * domainName /delete * domainName
Comments