Administration API - Using the API

Im Folgenden finden Sie eine Beschreibung der MailStore Server Management API. With the Management API administrative tasks, such as managing users or storage locations, can be telecontrolled from a central location. Communication with the Management API is done using web requests through HTTPS.

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

General Information about Using the Management API

The Management 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 Management API and is therefore recommended. If XML is requested, an internal automatic conversion in XML is made.

Befehle müssen über die HTTP-POST-Methode an die Management API gesendet werden. Die Parameter sind dabei im HTTP-Body zu übertragen und als Zeichencodierung muss immer UTF-8 verwendet werden. Der Rückgabewert ist entsprechend ebenfalls immer UTF-8 kodiert. Eine Übersicht aller zur Verfügung stehenden Management API-Befehle finden Sie unter MailStore Server Management API Commands.

Kann die Anfrage nicht erfolgreich bearbeitet werden, antwortet der Server mit dem HTTP-Fehlercode 500, die Rückgabe der Fehlermeldung erfolgt als text/plain (nicht als JSON oder XML). Ausnahme sind asynchrone Kommandos, bei denen eine Statusabfrage über eine spezielle URL erfolgt (siehe unten).

Beispiel

Im Folgenden ein Beispiel für das Abrufen der Informationen des Benutzers 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

Management 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.