Management API - Command Line Client

Revision as of 13:59, 14 November 2022 by Ltalaschus (talk | contribs) (MFA mentioned)

Besides the option to develop your own client for the Management API in any arbitrary programming or scripting language, MailStore Service Provider Edition provides a simple to use command line client in the form of the MailStoreManagementCmd.exe executable to be used in simple batch scripts or by backup software to remote control instances.

The syntax of the MailStoreManagementCmd.exe looks as follows:

  MailStoreManagementCmd.exe -s <server> -u <user> -p <password> -t <thumbprint> -c <command> [--param1=<value> --param2=<value> ...]

The below command line parameters are required followed by additional API command parameters if necessary.

Parameter Description
-s IP address or host name of the Management Server to connect to.
-t Thumbprint of the SSL certificate used by the Management Server.
-u Username of a MailStore Service Provider Edition Administrator
-p Password of the MailStore Service Provider Edition Administrator. In case MFA has been enabled, the API password of the user has to be given here. More about MFA can be found on the Your MFA Settings documentation page.
-c API command to be executed.

The output of the executed API command is returned to the standard output (STDOUT) comparable to the HTTP bodies as described in Using the API. Therefore a JSON parser is recommended for further processing of the output.

MailStoreManagementCmd.exe itself exits with error code 0 if no errors occurred, otherwise the exit code 1 is returned.

Examples

Backup Pre-Scripts

To stop instances run

MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c StopInstances --instanceFilter="instanceFilter"

or to freeze instances run

MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c FreezeInstances --instanceFilter="instanceFilter"

Backup Post-Scripts

To start instances run

MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c StartInstances --instanceFilter="instanceFilter"

or to thaw them run

MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c ThawInstances --instanceFilter="instanceFilter"


String Definition

instanceFilter

Value Affects
instance01 instance02 instance03 instance01, instance02 and instance03
* All instances
*instancehost01 *instancehost02 All instances on instancehost1 and instancehost2
* .running All running instances
* .safeMode All instances running in Safe Mode
* .safeMode .running All instances running in regular or Safe Mode
* .stopped All stopped instances

Other Examples

  MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7  -c GetEnvironmentInfo
 MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c GetProfiles --instanceID="test01" --raw="true"

Powershell

You are able to parse the result in the Powershell by converting the returned JSON values into Powershell objects. The ConvertFrom-Json cmdlet was introduced in Windows PowerShell 3.0.

(ConvertFrom-Json ([String](.\MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7  -c CreateLicenseRequest))).result.instanceData | where { $_.usedLicenseCount }