Introduction

In WebMail Pro, you can manipulate domains and accounts via PHP API. As of version 7.5, the same can be done via REST API.

Access to REST API is enabled by default. If you need to disable it, add the following item to array defined in data/settings/config.php file:

'labs.rest' => false,

Depending on the specific action to be performed, one of the following HTTP methods is utilized: GET, POST, PUT or DELETE. When using this API, the first thing to be done is obtaining a token using GET /token method. Token's lifetime is 1 hour.

For requesting a token, administrative credentials are supplied. That would be AdminPanel username and password, and in case if Aurora is used, tenant's credentials can be used there as well.

For most of the REST API methods, result is returned in JSON format. The only exception is the method for getting a token where the token itself is returned as string.

In case if the error has occured, JSON array will include errorCode item with its value denoting specific error, for example:

{"method":"GET /account/exists", "message":"token expired",
"result":false, "errorCode":716}

Note that while REST API allows for manipulating accounts and domains, you can use Web API to manage email account content, obtain list of folders, read and send mails, access the files, etc.

Sample requests

Below you can find a number of REST API calls performed using different approaches.

Request sent using JQuery AJAX (JavaScript)

$.ajax({
  type: "GET",
  dataType: 'json',
  contentType: "application/json",
  url: "http://yourdomain/rest.php/account/exists",
  data: {
     token:"fu36q7BKEg3wb54LJgYBFpwTXpbQFIT54mjT4hT6AX9B12WqEwjkWTTgOrcli71j93_Mb80bFEg5G-KydDlNCkMeFhLo8i5xqvKkNrxjhWKson4SxCaar-K68D9OALyDf_AL0hkquGmVzJ7_8M7FjWktH_7KfGDo",
     email:"user@domain.com"
  },
  success: function(oResult) { console.log(oResult); },
});

Request sent via cURL from command line

curl -X GET -d "email=user@domain.com&
token=fu36q7BKEg3wb54LJgYBFpwTXpbQFIT54mjT4hT6AX9B12WqEwjkWTTgOrcli71j93
_Mb80bFEg5G-KydDlNCkMeFhLo8i5xqvKkNrxjhWKson4SxCaar-K68D9OALyDf_AL0hkquGmVzJ7_8M7FjWktH_7KfGDo"
http://yourdomain/rest.php/account/exists

Request sent via cURL from PHP

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'http://yourdomain/rest.php/account/exists?'.http_build_query(array(
     'token' => 'fu36q7BKEg3wb54LJgYBFpwTXpbQFIT54mjT4hT6AX9B12WqEwjkWTTgOrcli71j93_Mb80bFEg5G-KydDlNCkMeFhLo8i5xqvKkNrxjhWKson4SxCaar-K68D9OALyDf_AL0hkquGmVzJ7_8M7FjWktH_7KfGDo',
     'email' => 'user@domain.com'
  )),
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_SSL_VERIFYPEER => false,
  CURLOPT_RETURNTRANSFER => true
));
$resp = curl_exec($curl);
curl_close($curl);
var_dump(json_decode($resp));

Note that you'll need to set CURLOPT_SSL_VERIFYPEER to false if you're using https URL.

Error codes

• 710 - other error
• 711 - rest api disabled
• 712 - unknown method
• 713 - invalid input parameters
• 714 - incorrect login or password
• 715 - invalid token
• 716 - token expired
• 717 - cannot find account
• 718 - cannot find domain
• 719 - cannot find tenant

Methods

GET /token

Returns authentication token.

Required parameters:

• string login - administrative login
• string password - administrative password

Return: string

Sample request:

http://yourdomain/rest.php/token?login=yourLogin&password=yourPassword

curl -X GET -d "login=yourLogin&password=yourPassword"
http://yourdomain/rest.php/token

Sample response:

"74eb69dc18eeee9debbd96a8785fc2cc"

POST /account

Creates a new account, or adds to an existing one if parent parameter is specified.

When creating an account, domain lookup is performed in the database, based on domain part of email address of the account. If domain was previously added, account will be added there; otherwise, it's added to default domain (equivalent of "Users not in domain" section in Users tab). Thus, the behavior is the same as if the account is created on first login from main page of the product.

NB: In case if mailserver bundle is used (MailSuite Pro, or Aurora bundled with MTA) and parent value is not specified, the account will be created on mail server as well.

Upon creating an account, you can log user into it by sending login credentials via POST.

If parent value is specified, this new account will be added to primary account of the user denoted by this "parent" email address.

The method has multiple optional parameters. If not specified, their values are inherited from domain, or from default domain if matching domain isn't found. In case if the system is used with webmail module disabled, it's safe to omit all the optional parameters altogether.

Required parameters:

• string token - token
• string email - email
• string password - password

Optional parameters:

• string parent - if specified, the new account will be added to primary account of the user denoted by this "parent" email address
• string friendlyName - display name
• string incomingMailLogin - IMAP server username
• string incomingMailServer - IMAP server hostname
• int incomingMailPort - IMAP server port
• int outgoingMailUseSSL - Use SSL for IMAP
• string outgoingMailServer - SMTP server host
• int outgoingMailPort - SMTP server port
• int outgoingMailUseSSL - Use SSL for SMTP
• int outgoingMailAuth - specifies whether SMTP authentication should be used
• string outgoingMailLogin - SMTP server username
• string outgoingMailPassword - SMTP server password

Return: bool

Sample request:

curl -X POST -d "token=yourToken&login=yourLogin&password=yourPassword"
http://yourdomain/rest.php/account

Sample response:

"result": true

PUT /account/update

Updates account information. Parameters which are supplied will be updated, the rest will not be modified.

Required parameters:

• string token - token
• string email - email

Optional parameters:

• string friendlyName - display name
• string incomingMailLogin - mail server username
• string incomingMailServer - IMAP server hostname
• int incomingMailPort - IMAP server port
• string outgoingMailServer - SMTP server host
• int outgoingMailPort - SMTP server port
• int outgoingMailAuth - specifies whether SMTP authentication should be used
• string signature - signature
• string signatureType - signature type. Accepted values: plain / html
• int signatureOptions - denotes whether signature should be inserted
• string socialEmail - specifies additional email address which is related to social network and can be used to log into this account

Return: bool

Sample request:

curl -X PUT -d "token=yourToken&email=yourEmail&friendlyName=yourFriendlyName"
http://yourdomain/rest.php/account/update

Sample response:

"result": true

DELETE /account

Deletes the account.

NB: In case if mailserver bundle is used (MailSuite Pro, or Aurora bundled with MTA) and parent value is not specified, the account will be deleted on mail server as well!

Required parameters:

• string token - token
• string email - email

Optional parameters:

• string parent - if specified, account is removed and unlinked from one denoted by this email address

Return: bool

Sample request:

curl -X DELETE -d "token=yourToken&email=yourEmail"
http://yourdomain/rest.php/account

PUT /account/enable

Activates user account.

Required parameters:

• string token - token
• string email - email

Return: bool

Sample request:

curl -X PUT -d "token=yourToken&email=yourEmail"
http://yourdomain/rest.php/account/enable

Sample response:

"result": true

PUT /account/disable

Deactivates user account.

Required parameters:

• string token - token
• string email - email

Return: bool

Sample request:

curl -X PUT -d "token=yourToken&email=yourEmail"
http://yourdomain/rest.php/account/disable

Sample response:

"result": true

PUT /account/password

Changes account password. It's only changed in the database and will not affect actual email account password, unless mailserver bundle is used (MailSuite Pro, or Aurora bundled with MTA).

Required parameters:

• string token - token
• string email - email
• string password - new password

Return: bool

Sample request:

curl -X PUT -d "token=yourToken&email=yourEmail&password=accountPassword"
http://yourdomain/rest.php/account/password

Sample response:

"result": true

GET /account/list

Returns list of users.

Required parameters:

• string token - token

Optional parameters:

• int page - page number of the list. Default value: 1
• int usersPerPage - number of users per page. Default value: 100
• string orderBy - sorting field. Accepted values: email / name / last login
• string searchDesc - search string used for looking up specific account
• string domain - domain

Return: array

Sample request:

http://yourdomain/rest.php/account/list?token=yourToken

curl -X GET -d "token=yourToken" http://yourdomain/rest.php/account/list

Sample response:

"result":
[
  {
     "Id": 32,
     "Email": "yourName@yourdomain.com",
     "FriendlyName": "Name"
  },
  {
     "Id": 33,
     "Email": "yourOtherName@yourotherdomain.com",
     "FriendlyName": "OtherName"
  }
]

GET /account/exists

Checks if user account exists.

Required parameters:

• string token - token
• string email - email

Return: bool

Sample request:

http://yourdomain/rest.php/account/exists?token=yourToken&email=accountEmail

curl -X GET -d "token=yourToken&email=yourEmail"
http://yourdomain/rest.php/account/exists

Sample response:

"result": true

GET /account

Returns account details.

Required parameters:

• string token - token
• string email - email

Return: object

Sample request:

http://yourdomain/rest.php/account?token=yourToken&email=accountEmail

curl -X GET -d "token=yourToken&email=yourEmail"
http://yourdomain/rest.php/account

Sample response:

result:
{
friendlyName: "name",
incomingMailLogin: "yourName@yourdomain.com",
incomingMailPort: 143,
incomingMailServer: "imap.yourdomain.com",
outgoingMailAuth: 2,
outgoingMailPort: 25,
outgoingMailServer: "smtp.yourdomain.com",
signature: "yourSignature",
signatureOptions: 1,
signatureType: "html",
socialEmail: "yourOtherName@yourotherdomain.com"
}

POST /domain

Creates a domain.

Adding accounts doesn't require adding their domains, it's only needed if you'd like to have different settings (such as skin, language, etc.) for different domains. If domain wasn't added, account is added under default domain.

If domain configuration was changed, that configuration applies to all the accounts under this domain. NB: it doesn't apply to accounts under default domain.

Required parameters:

• string token - token
• string domain - domain

Optional parameters:

• string tenant - tenant (Aurora only)

Return: bool

Sample request:

curl -X POST -d "token=yourToken&domain=domainName"
http://yourdomain/rest.php/domain

Sample response:

"result": true

PUT /domain/update

Updates domain information. Parameters which are supplied will be updated, the rest will not be modified.

Required parameters:

• string token - token
• string domain - domain

Optional parameters:

• int allowUsersChangeEmailSettings - allow/disallow changing email access settings
• int allowWebMail - enable/disable webmail
• int allowContacts - enable/disable contacts
• int allowCalendar - enable/disable calendar (Pro/Aurora only)
• int allowFiles - enable/disable files (Pro/Aurora only)
• int allowHelpdesk - enable/disable helpdesk (Aurora only)
• int allowNewUsersRegister - only already registered users can access the installation
• int allowUsersChangeInterfaceSettings - allow users to access interface settings
• int allowUsersAddNewAccounts - allow users to add external mailboxes
• string siteName - site name
• string url - web domain
• int useThreads - use threading
• string defaultSkin - skin name
• string defaultTab (string) - default tab. Accepted values: mailbox, contacts, calendar, files, helpdesk.
• string defaultLanguage - language name

Return: bool

Sample request:

curl -X PUT -d "token=yourToken&domain=domainName"
http://yourdomain/rest.php/domain/update

Sample response:

"result": true

DELETE /domain

Deletes a domain.

Required parameters:

• string token - token
• string domain - domain

Return: bool

Sample request:

curl -X DELETE -d "token=yourToken&domain=domainName"
http://yourdomain/rest.php/domain

Sample response:

"result": true

GET /domain/list

Returns list of domains.

Required parameters:

• string token - token

Optional parameters:

• int page - page number of the list. Default value: 1
• int domainsPerPage - number of domains per page. Default value: 100
• string orderBy - sorting field. Accepted values: email / name
• string searchDesc - search string used for looking up specific domain
• string tenant - tenant (Aurora only)

Return: array

Sample request:

http://yourdomain/rest.php/domain/list?token=yourToken

curl -X GET -d "token=yourToken" http://yourdomain/rest.php/domain/list

Sample response:

"result": true

GET /domain/exists

Checks if domain exists.

Required parameters:

• string token - token
• string domain - domain

Return: bool

Sample request:

http://yourdomain/rest.php/domain/exists?token=yourToken&domain=domainName

curl -X GET -d "token=yourToken&domain=domainName"
http://yourdomain/rest.php/domain/exists

Sample response:

"result": true

GET /domain

Returns domain details.

Required parameters:

• string token - token
• string domain - domain

Return: object

Sample request:

http://yourdomain/rest.php/domain?token=yourToken&domain=domainName

curl -X GET -d "token=yourToken&domain=domainName"
http://yourdomain/rest.php/domain

Sample response:

result:
{
allowCalendar: true,
allowContacts: true,
allowFiles: true,
allowHelpdesk: true,
allowNewUsersRegister: true,
allowUsersAddNewAccounts: false,
allowUsersChangeEmailSettings: true,
allowUsersChangeInterfaceSettings: true,
allowWebMail: true,
defaultLanguage: "English",
defaultSkin: "Default",
defaultTab: "mailbox",
siteName: "AfterLogic WebMail",
url: "",
useThreads: true
}