How can we help?
  1. atmail help centre
  2. atmail on-premises
  3. API

Follow

atmail mail server API documentation

Stewart -

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.

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>

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

 

 

Have more questions? Submit a request

Comments

Contact our support team

  +61 (7) 5357 6605       support@atmail.com


atmail

© Copyright 2020 atmail pty ltd | All Rights Reserved