The examples demonstrated here use the MailStore PowerShell API Wrapper and are compatible with Windows PowerShell 3.0 and higher. Depending on your version of Windows it might be necessary to download and install a compatible version of PowerShell first. You can find the components necessary for this tutorial here:

The examples demonstrated here use the MailStore PowerShell API Wrapper and are compatible with Windows PowerShell 3.0 and higher. Depending on your version of Windows it might be necessary to download and install a compatible version of PowerShell first. You can find the components necessary for this tutorial here:

Revision as of 13:38, 25 August 2014

This tutorial aims to explain the usage of the MailStore Server Administration API through simple Windows PowerShell example scripts. Basic knowledge of MailStore Server, Windows and PowerShell is a necessary precondition.

The API wrapper used in this tutorial is an example implementation of a MailStore Server Administration API client. As communication with the Administration API is done via web requests, it is possible to create different implementations that use the corresponding PowerShell cmdlets. However, such implementations are out of scope of this tutorial.

Please note: It is strongly recommended to use a non-productive test environment for this tutorial as well as for script development in general, in order to prevent loss of data or other problems. For example, the 30-day-trial version of MailStore Server is perfectly suited for this.

Installation of Necessary Components

The examples demonstrated here use the MailStore PowerShell API Wrapper and are compatible with Windows PowerShell 3.0 and higher. Depending on your version of Windows it might be necessary to download and install a compatible version of PowerShell first. You can find the components necessary for this tutorial here:

Please take note of the system requirements and further notices for the respective version of the Windows Management Framework.

Important Notice: Installation of a Windows Management Framework on systems that require a specific version of Windows PowerShell, such as Microsoft Exchange Servers, is not supported and may lead to massive system failures and data loss.

Neither the MailStore PowerShell API Wrapper nor the example scripts are digitally signed, therefore execution of such scripts has to be enabled in an administrative PowerShell session using

Set-ExecutionPolicy-ExecutionPolicyUnrestricted

Importing the MailStore PowerShell API Wrapper

The MailStore PowerShell API Wrapper is implemented as a PowerShell Script Module (MSS.PS.Lib.psm1) and can thus be imported in a PowerShell session via its manifest (MSS.PS.Lib.psd1) by using Import-Module.

Please open a PowerShell session and import the API wrapper module using this command:

Getting Information about the MailStore PowerShell API Wrapper

The MailStore PowerShell API Wrapper provides several functions and variables to access the MailStore Server Administration API, following PowerShell conventions. Enter the following command to get information about these features:

Get-ModuleMSS.PS.Lib|fl

More detailed information is available through the module's properties. For example,

(Get-ModuleMSS.PS.Lib).ExportedVariables

returns the variables provided by the module. Via

Get-Help*MSS*

the MailStore PowerShell API Wrapper returns inline help for all its functions.

Calling API Wrapper Functions

The following example script (Example1.ps1 in the tutorial package) explains the basic usage of MailStore PowerShell API Wrapper functions.

The function New-MSSApiClient creates a new API client object which the Invoke-MSSApiCall function uses for API calls. The values for -Username, -Password, -MailStoreServer, -Port and -Code used in the script are the function's defaults, only the switch -IgnoreInvalidSSLCerts has to be set if untrusted certificates are used; otherwise an error occurs.

Apart from the API client object, Invoke-MSSApiCall needs an API command and its parameters if applicable. The command GetServerInfo in the script does not have any parameters and returns an object as follows:

Type : JSON
Token :
Data : @{version=8.1.2.9268; machineName=DEMO}

The object's Type property corresponds either to the -Code parameter of the API client object ("JSON" or "XML") or has the value "JOB" for asynchronous API commands (see below); it characterizes the type of the object contained in the Data property. The Token property is also only relevant for asynchronous API commands.

The Data property contains the result returned by MailStore Server, in this case as a JSON object:

Calling API Wrapper Functions with Parameters

For most MailStore Server Administration API commands you need to provide parameters. Of course, the MailStore PowerShell API Wrapper's Invoke-MSSApiCall function can submit these parameters, as demonstrated by the following script (Example2.ps1 in the tutorial package):

The scripts lists details about the users created in MailStore Server. Because the MailStore PowerShell API Wrapper converts MailStore Server Management API responses into objects, their properties can be used directly in the script's workflow.

As can be seen in the privilegesOnFolders property, returned objects may be nested and may also contain further objects.

Calling API Wrapper Functions for Asynchronous API Commands

Administration API commands, whose execution typically take more time, are executed asynchronously on the server. The MailStore PowerShell API Wrapper identifies calls of such asynchronously executed API commands and executes them as PowerShell Jobs in the background.

Processing API Wrapper PowerShell Jobs Synchronously

A script's execution can be interrupted until a PowerShell Job created by the API wrapper terminates as demonstrated by the following script (Example3.ps1 in the tutorial package):

In contrast to objects returned by synchronous API command calls, the Token property now contains a unique ID returned by the server that identifies the server process; it is important for event handling (see below). The Data property contains the PowerShell Job which processes the status objects returned by the server in the background.

This PowerShell Job requests the status of its corresponding server process in regular intervalls (500ms by default) and is terminated when that process is finished. Through the PowerShell cmdlet Wait-Job the scripts waits until the job has been completed, getting the job's results through Receive-Job:

Please note: The RunspaceId is generated by the PowerShell automatically and can be ignored here.

Processing API Wrapper PowerShell Jobs Asynchronously

Instead of interrupting a script's execution, the PowerShell Jobs created by the API wrapper can be reacted to while they are running in the background. These jobs trigger a PowerShell EngineEvent with each status request that the script can subscribe to execute further code on each occurrence. To demonstrate this, the previous script needs to be adapted only a bit (Example4.ps1 in the tutorial package):

Here the script subscribes to the event that is triggered by the background job via Register-EngineEvent, using the return object's Token property as SourceIdentifier. By that property the event relates to the triggering PowerShell Job and thus to the server process. The Action script block is itself created as a PowerShell Job that is executed with each triggering of the event. Through the MessageData property of the $eventautomatic variable the script block can access the return object provided by the background job. That object's Data property contains the status of the server process: