My activities New request

contact atmail support

PH: +61 (7) 5357-6605

support@atmail.com

Follow

WebAdmin API - REST

Mat -

PROBLEM

How can I use the atmail webadmin API?

ENVIRONMENT

  • atmail 7 cloud

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
  • HTTP GET - Read
  • HTTP POST - Create
  • HTTP PUT - Update, Create
  • HTTP DELETE - Delete

Examples

Authenticate

Auth an admin users

The API is stateless and therefore session-less. Authentication must be sent with each request.

If you are an atmail cloud user, just supply your webadmin username/password on the API REST calls.

curl -i -u "subscriptionname.atmailcloud.com:changeme" "https://subscriptionname.atmailcloud.com/mail/index.php/api/login/authenticate/"

Responses

User success
<api generator="zend" version="1.0">
<authenticate>
<response>
<message>Authentication success</message>
</response>
<status>success</status>
</authenticate>
</api>
User failure
<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

curl -i -u "subscriptionname.atmailcloud.com:changeme" "https://subscriptionname.atmailcloud.com/index.php/api/domain/create/name/domain.com" 

Parameters

  • name

Response

Add success
<api generator="zend" version="1.0">
<domainadd>
<message>domain.com added</message>
<status>success</status>
</domainadd>
</api>
Domain already exists
<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
<api generator="zend" version="1.0">
<domainadd>
<message>Permission denied</message>
<status>failed</status>
</domainadd>
</api>
Domain cannot be added: No domain credits available
<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

 curl -i -u "subscriptionname.atmailcloud.com:changeme" "https://subscriptionname.atmailcloud.com/index.php/api/domain/delete/name/domain.com"

Parameters

  • name

Response

Add success
<api generator="zend" version="1.0">
<domaindelete>
<message>jim.com deleted</message>
<status>success</status>
</domaindelete>
</api>
Domain does not exist
<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

curl -i -u "subscriptionname.atmailcloud.com:changeme" "https://subscriptionname.atmailcloud.com/index.php/api/domain/check/name/domain.com"

Parameters

  • name

Response

Domain exists
<api generator="zend" version="1.0">
<domaincheck>
<response>
<message>domain.com exists</message>
</response>
<status>success</status>
</domaincheck>
</api>
Domain does not exist
<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

curl -i -u "subscriptionname.atmailcloud.com:changeme" "https://subscriptionname.atmailcloud.com/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
  • UserQuota - Disk space in MB

Responses

User success
<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
<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
<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
<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
<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.

curl -i -u "subscriptionname.atmailcloud.com:changeme" "https://subscriptionname.atmailcloud.com/index.php/api/users/delete/name/user@domain.com" 

Parameters

  • name

Response

Delete success
<api generator="zend" version="1.0">
<userdelete>
<response>
<message>Account deleted</message>
</response>
<status>success</status>
</userdelete>
</api> 
User does not exist
<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
<api generator="zend" version="1.0">
<userdelete>
<response>
<message>Permission denied</message>
</response>
<status>failed</status>
</userdelete>
</api> 

Update User

Update an existing user

curl -i -u "subscriptionname.atmailcloud.com:changeme" "https://subscriptionname.atmailcloud.com/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 
  • UserFirstName
  • UserLastName
  • UserQuota - Disk space in MB
  • 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
<api generator="zend" version="1.0">
<userupdate>
<response>
<message>Account updated</message>
</response>
<status>success</status>
</userupdate>
</api> 
User does not exist
<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
<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.

curl -i -u "subscriptionname.atmailcloud.com:changeme" "https://subscriptionname.atmailcloud.com/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
<api generator="zend" version="1.0">
<aliasescreate>
<response>
<message>Success</message>
</response>
<status>success</status>
</aliasescreate>
</api>
Alias already exists
<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

curl -i -u "subscriptionname.atmailcloud.com:changeme" "https://subscriptionname.atmailcloud.com/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. https://domain.com/index.php/api/aliases/delete/?AliasMailDir=/some/path)

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.https://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
<api generator="zend" version="1.0">
<aliasesdelete>
<response>
<message>Alias(s) removed</message>
</response>
<status>success</status>
 
</aliasesdelete></api>
Alias does not exist
<api generator="zend" version="1.0">
<aliasesdelete>
<response>
<message>Alias does not exist</message>
</response>
<status>failed</status>
 
</aliasesdelete></api>
Illegal argument name passed
<api generator="zend" version="1.0">
<aliasesdelete>
<response>
<message>illegal argument name used: someArgName</message>
</response>
<status>failed</status>
 
</aliasesdelete></api>

Complete API method listing and required arguments

 

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

        /list
        /delete
            Optional (but at least one must be used)
            * AliasName
            * AliasTo
            * AliasMailDir
           
/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 /list /update * Username 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 /users /create * name * Password Optional: * Password * PasswordQuestion * PasswordMD5 * UserStatus * MailDir * Forward * AutoReply * UserQuota * FirstName * LastName /view * Username (name) or id (id) /list Optional filter arguments: * domain * start * volume /update * Username (name) * Most fields available in /create * enabled (true or false) * NewUsername (username part only, no domain)  /delete * name
Have more questions? Submit a request

Comments