Management API - Using the API

Revision as of 13:43, 5 July 2023 by Ltalaschus (talk | contribs)


Access to the Management API is provided by the HTTP server of the MailStore Service Provider Edition Management Server which listens on TCP port 8474 by default. All communication is SSL encrypted.

Each request to the Management API must be authenticated by sending username and password following the standards for HTTP basic authentication as defined in RFC 2617.

In case MFA has been enabled for the user that access the API, the API password of the user has to be given here. More about MFA can be found on the Your MFA Settings documentation page.

When a function needs additional data, this data must be send urlencoded in the body of the request. The HTTP header Content-Type: application/x-www-form-urlencoded should be set.

Refer to Function Reference for a full list of available API functions.

In order to run API commands that work on an instance, service provider access must be enabled for that instance. This includes all API commands that require an instanceID argument, except those that affect archive stores and search indexes. These can be run using the API without service provider access.

Please note: Depending on the scope of the called function, the URL may vary (/api/ or /api/invoke). Please carefully check to which URL you are sending your requests in case of unexpected results.

Executing Regular API Functions

To execute regular Management API functions, send HTTP POST request to the following URL:

https://<mgmt-server>:8474/api/invoke/<function>

Example

HTTP Request

POST /api/invoke/GetEnvironmentInfo HTTP/1.1
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
User-Agent: curl/7.35.0
Host: spe.example.com:8474
Accept: */*
Content-Length: 0

HTTP Response

HTTP/1.1 200 OK
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
Pragma: no-cache
Content-Length: 798
Content-Type: application/json
Expires: Wed, 25 Jun 2014 13:50:53 GMT
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 26 Jun 2014 13:50:53 GMT
 
{
  "error": null,
  "token": null,
  "statusVersion": 2,
  "statusCode": "succeeded",
  "percentProgress": null,
  "statusText": null,
  "result": {
    "version": "9.0.0.9672",
    "copyright": "Copyright (c) 2005-2014 MailStore Software GmbH",
    "licenseeName": "MailStore Software GmbH",
    "licenseeID": 10510,
    "serverName": "spe.example.com",
    "userName": "admin",
    "systemProperties": {
      "processors": [
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz",
        "Intel(R) Xeon(R) CPU E5645 @ 2.40GHz"
      ],
      "totalPhysicalMemory": 12884430848,
      "operatingSystem": "Microsoft Windows Server 2012 Standard"
     }
  },
  "logOutput": null
}

The response includes a UTF-8 BOM.

To get a list of all available functions, send a POST request to https://<mgmt-server>:8474/api/get-metadata.

Long Running Processes

Some API functions start a long running process that may take several minutes or even hours to complete. To keep track of the progress a unique token is returned upon initial request, which can be used to periodically poll for status updates.

The overall process is as follows:

  1. Send HTTP POST to https://<mgmt-server>:8474/api/invoke/VerifyStore in order to execute the function.
  2. Check the server's response for the keys token, statusCode and statusVersion.
  3. To retrieve status updates, send periodic requests to https://<mgmt-server>:8474/api/get-status with the following parameters:
Name Description
token The received unique token for the process.
lastKnownStatusVersion Value of statusVersion from last response.
millisecondsTimeout Time in milliseconds until the the server stops waiting for a new status update to send. If a new status update is available it will be sent to the client immediately, otherwise the last status is repeated.
4. The process finished when the statusCode is not running.

Example

Initial HTTP Request

POST /api/invoke/VerifyStore HTTP/1.1
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
User-Agent: curl/7.35.0
Host: spe.example.com:8474
Accept: */*
Content-Length: 24
Content-Type: application/x-www-form-urlencoded
 
instanceID=adsolver&id=1

Initial HTTP Response

HTTP/1.1 200 OK
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,postcheck=0,pre-check=0
Pragma: no-cache
Content-Length: 291
Content-Type: application/json
Expires: Wed, 25 Jun 2014 14:03:45 GMT
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 26 Jun 2014 14:03:45 GMT
 
{
  "error": null,
  "token": "sa46594cd64b35f62796c405c0ed155ee8",
  "statusVersion": 3,
  "statusCode": "running",
  "percentProgress": 0,
  "statusText": null,
  "result": null,
  "logOutput": "Verifying file group #1...\r\nCreating a list of messages to be verified...\r\n"
}

Periodic HTTP Request of Progress

POST /api/get-status HTTP/1.1
Authorization: Basic YWRtaW46UGFzc3cwcmQ=
User-Agent: curl/7.35.0
Host: spe.example.com:8474
Accept: */*
Content-Length: 90
Content-Type: application/x-www-form-urlencoded
 
token=sa46594cd64b35f62796c405c0ed155ee8&lastKnownStatusVersion=3&millisecondsTimeout=5000

HTTP Response to Periodic Progress Requests

HTTP/1.1 200 OK
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
Pragma: no-cache
Content-Length: 242
Content-Type: application/json
Expires: Wed, 25 Jun 2014 14:08:15 GMT
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 26 Jun 2014 14:08:15 GMT
 
{
  "error": null,
  "token": "sa46594cd64b35f62796c405c0ed155ee8",
  "statusVersion": 9,
  "statusCode": "running",
  "percentProgress": 0,
  "statusText": null,
  "result": null,
  "logOutput": "  400 messages verified...\r\n"
}

Final HTTP Response

HTTP/1.1 200 OK
Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0
Pragma: no-cache
Content-Length: 242
Content-Type: application/json
Expires: Wed, 25 Jun 2014 15:08:15 GMT
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 26 Jun 2014 15:08:15 GMT

{
  "error": null,
  "token": null,
  "statusVersion": 269,
  "statusCode": "succeeded",
  "percentProgress": null,
  "statusText": null,
  "result": null,
  "logOutput": null
}

Error Handling

Additionally to handling protocol specific issues such as HTTP or TCP errors, developers receive detailed information from the API itself in case the request did not succeed,

In case the request was successfully be processed, the response will contain: 

 "error": null

Otherwise in the event of a failure the error key will have the following structure 

 "error": {
   "message": string,
   "details": string
 }

allowing developers to display a meaningful error message and further technical details.

Retrieved from "https://help.mailstore.com/en/spe/index.php?title=Management_API_-_Using_the_API&oldid=2027"