Administration API - Using the API

In this chapter you can find a description of the MailStore Server Administration API. With the Administration API administrative tasks, such as managing users or storage locations, can be remote controlled from a central location. Communication with the Administration API is done using web requests through HTTPS.

For security reasons, the MailStore Server Administration API is deactivated by default and has to be activated using the MailStore Server Service Configuration.

MailStore API Test Application

To help you better understand the samples on this page, we provide a small tool that is able to send commands to the API HTTPS server and display its responses. Simply download the ZIP file provided below and run the included MailStoreApiTester.exe.

The download comes with the entire C# source code of the test application.

Download MailStoreApiTester.zip

General Information About Using the Administration API

The Administration API accepts commands under the following URLs:

/JSON/Invoke/MethodName

and

/XML/Invoke/MethodName

The first part of the path indicates the return format expected by the client (JSON or XML). JSON is the native return format of the MailStore Server Administration API and is therefore recommended. If XML is requested, an internal automatic conversion to XML is made.

Commands must be sent to the Administration API using the HTTP POST method. The parameters should be transferred in the HTTP body and encoding must always be done using UTF-8. The return value is always UTF-8 encoded respectively.

Please note: A list of all available Administration API commands is available in chapter MailStore Server Administration API Commands.

If the request cannot be processed, the server responds with HTTP error code 500, and the error message is returned as text/plain (not JSON or XML). An exception are asynchronous commands which use a special URL for status queries (as described below).

Example

The following is an example for retrieving the information of the user johndoe.

HTTP Request

POST /JSON/Invoke/GetUserInfo HTTP/1.1
...

userName=johndoe

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
...

{
   "userName": "johndoe",
   "fullName": "John Doe",
   "authentication": "integrated",
   "emailAddresses": [
       "[email protected]",
       "[email protected]"
       ],
   "privileges": "admin"
}

Asynchronously Executed Commands

Administration API commands, whose execution typically take more time, are executed asynchronously. The server does not return the actual return value but a URL under which the current status (e.g. the return value for fully executed requests) can be requested.

One example for an asynchronously executed API method is RebuildStoreIndex.

Sample Return Value

{
   "statusToken": "C467B22E-7057-43BA-B79B-C6140ED514BD",
   "statusUrl": "/JSON/Status/C467B22E-7057-43BA-B79B-C6140ED514BD"
}

If a JSON object is returned which contains a statusUrl value, this URL can be used to ask for the current status.

Structure of the Status Object

{
   "status": "running | succeeded | failed",
   "result": { JSON Object },
   "progressPercentage": 0..100,
   "messages": [
       {
           "type": "line | information | warning | error | unknown",
           "text": "..."
       }
   ]
}

If the returned status is succeeded or failed, each additional status query under the same URL will fail, because once the status is delivered, all internally stored status information is deleted.