Using Web API

Web API reference

Introduction

This API allows applications to communicate with backend code of MailSuite Pro. You can create your custom frontend which would interact with MailSuite Pro backend via Web API. Note that the application which uses Web API doesn't have to be written in JavaScript, it doesn't even have to be a web application, you can use this API in mobile, desktop and server applications as well.

Note that you can also use PHP API to integrate MailSuite Pro with your application, assuming both are installed on the same server.

Getting started

Below, please find an example of the code written in Javascript or C#, which performs a typical Web API request.

$.ajax({
    url: 'index.php?/Api/',
    type: 'POST',
    async: true,
    dataType: 'json',
    data: {
        Module: 'Core',
        Method: 'GetSettings'
    },
    success: function (oResponse) {
        if (oResponse)
        {
            var oSettings = oResponse.Result;
            console.log('oSettings', oSettings);
        }
    }
});

string url = "https://webmail.afterlogic.com/?/Api/";
using (var client = new WebClient())
{
    client.Headers.Add("Content-Type", "application/x-www-form-urlencoded");
    string strData = "Module=Core&Method=GetSettings";
    strData = client.UploadString(url, strData);
    Console.WriteLine(strData);
}

The following points are important in this regard:

1. The entry point for making all the Web API calls is MailSuite Pro installation URL with /?/Api/ appended.

2. All the Web API calls are to be performed using POST;

3. Installation contains a number of modules, therefore each request is processed by a specific module specified in POST data. Name of the method in this module is specified there as well.

Authentication

Some methods will only return useful data if you authenticate to an account. That can be done by sending Login request to Core module:

$.ajax({
    url: 'index.php?/Api/',
    type: 'POST',
    async: true,
    dataType: 'json',
    data: {
        Module: 'Core',
        Method: 'Login',
        Parameters: '{"Login":"login_value","Password":"pass_value"}'
    },
    success: function (oResponse) {
        if (oResponse && oResponse.Result)
        {
            var sAuthToken = oResponse.Result.AuthToken;
            console.log('sAuthToken', sAuthToken);
        }
    }
});

string url = "https://webmail.afterlogic.com/?/Api/";
using (var client = new WebClient())
{
        client.Headers.Add("Content-Type", "application/x-www-form-urlencoded");
        string strData = "Module=Core&Method=Login&Parameters={\"Login\":\"login_value\",\"Password\":\"password_value\"}";
        strData = client.UploadString(url, strData);
        Console.WriteLine(strData);
}

curl -d "Module=Core&Method=Login&Parameters={\"Login\":\"user@domain.com\",\"Password\":\"MyPassWord\"}" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://webmail.afterlogic.com/?/Api/

Successful request will result in JSON-formatted response of the following kind:

{
    Module: 'Core',
    Method: 'Login',
    Result: {
        AuthToken: 'token_value'
    }
}

To perform administrative tasks, you need to login as superadmin user. In version 9 of the product, that's done by calling LoginAsSuperadmin method of AdminAuth module.

Uploading files

Now that we have auth token, we can use it to perform various actions within user account. As an example, let's upload a file to Files storage:

<script type="text/javascript">
function UploadFile()
  {
    var
      oInput = document.getElementById('file-upload-input'),
      aFiles = (oInput && oInput.files && 0 < oInput.files.length) ? oInput.files : [],
      oXhr = new XMLHttpRequest(),
      oFormData = new FormData()
    ;
    if (aFiles.length > 0)
    {
      oXhr.open('POST', 'https://webmail.afterlogic.com/?/Api/', true);
      oXhr.setRequestHeader("Authorization", "Bearer " + sAuthToken)
      oFormData.append('Module', 'Files');
      oFormData.append('Method', 'UploadFile');
      oFormData.append('jua-uploader', aFiles[0]);
      oFormData.append('Parameters', '{ "Type": "personal", "Path": "" }');
      oXhr.send(oFormData);
    }
}
</script>
<input type="file" id="file-upload-input" />
<input type="button" onclick="UploadFile()" value="click" /> 

You can also do that via cURL as follows:

curl --location --request POST 'https://webmail.afterlogic.com/?/Api/' \
--header 'Authorization: Bearer ...' \
--form 'Module="Files"' \
--form 'Method="UploadFile"' \
--form 'Parameters="{\"Type\":\"personal\",\"SubPath\":\"\",\"Path\":\"\",\"Overwrite\":false}"' \
--form 'jua-post-type="ajax"' \
--form 'jua-uploader=@"image.png"'

It's assumed that authentication token is sent in Authorization header. The file that's being uploaded (image.png in this example) should be present in the current directory.

You can use cURL from PHP of course:

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://webmail.afterlogic.com/?/Api/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('Module' => 'Files','Method' => 'UploadFile','Parameters' => '{"Type":"personal","SubPath":"","Path":"","Overwrite":false}','jua-post-type' => 'ajax','jua-uploader'=> new CURLFILE('nature.jpg')),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer ...'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

CORS setup

If your application and MailSuite Pro are in different domains, web browser is likely to disallow sending requests between the two, due to same-origin policy.

To allow receiving requests from different domains, MailSuite Pro installation needs to be sending Access-Control-Allow-Origin response header.

The simplest approach assumes allowing requests from any domain. For Apache, it's done by adding the following line to configuration file:

Header set Access-Control-Allow-Origin "*"

or, if you're modifying .htaccess:

Header add Access-Control-Allow-Origin "*"

For Nginx webserver, it's done as follows:

add_header Access-Control-Allow-Origin *;

It can also be done for other web servers such as IIS as shown at: CORS Enabled

Error codes

The following ErrorCode values are supported:

• 101 - invalid token;
• 102 - authentication failure;
• 103 - invalid data;
• 104 - database error;
• 113 - module not found;
• 114 - method not found;
• 999 - unknown error.

Web API reference