Python API Wrapper Tutorial

This document explains the installation and usage of the Python API Wrapper library, which is meant to be an example implementation of a MailStore Server Administration API client. The Administration API allows developing scripts for the administration of MailStore Server.

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

The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python.

Python binaries for various operating systems can be downloaded from the Python download page or installed using the package manager of most Linux distributions.

Additionally need the Python API Wrapper library has to be installed in the mailstore subdirectory of Python's site-packages directory. The location of the site-packages directory can be found by executing the following command:

 python3 -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"

Instantiating the API Client

Before the API wrapper library can be used, it must first be imported with:

 import mailstore

Now the mailstore.server.Client class can be instantiated as follows:

 serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)

Default values can be omitted. The default admin credentials (username and password set to admin) are only usable when connecting from the MailStore Server computer itself to localhost. Find a listing of all default values in the following table:

Parameter	Default Value
username	admin
password	admin
host	127.0.0.1
port	8463
autoHandleToken	True
waitTime	1
logLevel	2

If autoHandleToken is enabled, you do not have to take care of long running processes. Instead wait for the result. When this value is set to False, a status token is returned must be handled appropriately by the calling script. Further details about long running processes are in the corresponding section of this document.

The waitTime value specifies the value that is passed to the get-status call. When calling a long running method like VerifyStore, this is the amount of seconds to wait for a status update.

logLevel has to be in the range 0 to 4 where loglevel 0 (NONE) has the lowest verbosity and 4 (DEBUG) the highest. The loglevels are defined in the following order (low to high verbosity) NONE, ERROR, WARNING, INFO and DEBUG.

Log entries will always be printed to stdout.

Invoking Simple Calls

Simple calls will always return immediately and no token handling is required.

 print(serverClient.GetServerInfo())
 
 {'machineName': 'WIN2012MS', 'version': '8.1.2.9268'}

When the call was successful the information is stored in the returned Python dictionary. When it failed, an error will be thrown (see Exception Handling for further details.

Examples

To get details of all users the following code snippet can be used:

 serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)
 for user in serverClient.GetUserList():
     print(serverClient.GetUserInfo(user["userName"]))

A list with all assigned email addresses can be retrieved with the following code:

 serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)
 emailaddresses = list()
 for user in serverClient.GetUserList():
     emailaddresses += serverClient.GetUserInfo(user["userName"])['emailAddresses']
 print(emailaddresses)

Long Running Calls

The execution of certain API methods like VerifyStore can take several minutes or even hours until it finishes. These long running calls are executed asynchronously in MailStore Server so you must decide whether to poll for status updates regularly and, in order to output the progress, process them in your own script or let the Python API library silently handle this while waiting for the call to finish.

Invoking

Automatic token handling can be controlled globally, but also turned on or off per method call. Learn more about token handling in the following sections.

Automatic Token Handling

When autoHandleToken is set to True (default), the API wrapper library polls the status automatically in the background and will return the final result when the process has ended.

 serverClient = mailstore.server.Client(autoHandleToken=True)
 storeID = 1
 print(serverClient.VerifyStore(storeID))
 
 {'status': 'succeeded', 'progressPercentage': 100, 'messages': [{'text': 'Verifying file group #2...', 'type': 'line'}, {'text': 'Creating a list of messages to be verified...', 'type': 'line'}, {'text': '234 messages are about to be verified.', 'type': 'line'}, {'text': 'Verifying...', 'type': 'line'}, {'text': '  100 messages verified...', 'type': 'line'}, {'text': '  200 messages verified...', 'type': 'line'}, {'text': '  234 messages verified.', 'type': 'line'}, {'text': 'Finished. No errors have been found.', 'type': 'line'}]}

Manual Token Handling

If autoHandleToken is set to False the calling script receives the token and must handle it all by itself. To poll for status updates manually call the GetStatus method and use the status token as parameter. The main call has finished when the status changed to something else than running.

 import time

 serverClient = mailstore.server.Client(autoHandleToken=False)   
 storeID = 2
 token = serverClient.VerifyStore(storeID)
 print(token)
 while True:
     time.sleep(1)
     status = serverClient.GetStatus(token)
     print(status)
     if status["status"] != "running":
         break

 {'statusUrl': '/JSON/Status/243fc983-89c3-19ef-196a-dbe082894cc5', 'statusToken': '243fc983-89c3-19ef-196a-dbe082894cc5'}
 {'progressPercentage': 0, 'messages': [{'type': 'line', 'text': 'Verifying file group #2...'}, {'type': 'line', 'text': 'Creating a list of messages to be verified...'}, {'type': 'line', 'text': '234 messages are about to be verified.'}, {'type': 'line', 'text': 'Verifying...'}, {'type': 'line', 'text': '  100 messages verified...'}], 'status': 'running'}
 {'progressPercentage': 100, 'messages': [{'type': 'line', 'text': 'Verifying file group #2...'}, {'type': 'line', 'text': 'Creating a list of messages to be verified...'}, {'type': 'line', 'text': '234 messages are about to be verified.'}, {'type': 'line', 'text': 'Verifying...'}, {'type': 'line', 'text': '  100 messages verified...'}, {'type': 'line', 'text': '  200 messages verified...'}, {'type': 'line', 'text': '  234 messages verified.'}, {'type': 'line', 'text': 'Finished. No errors have been found.'}], 'status': 'succeeded'}

Passing the status token to the HandleToken method will result in exactly the same behavior as if autoHandleToken=True would have been set.

 serverClient = mailstore.server.Client(autoHandleToken=False)
 storeID = 2
 token = serverClient.VerifyStore(storeID)
 print(token)
 print(serverClient.HandleToken(token))

Selective Token Handling

The Token handling behavior can be modified globally and locally. If the API client was instantiated with autoHandleToken=True, each method can still be called with autoHandleToken=False and vice versa to disable or enable automatic token handling whenever necessary. Methods that do not return a token, do not accept the autoHandleToken parameter.

 serverClient = mailstore.server.Client(autoHandleToken=False)
 storeID = 2
 token = serverClient.VerifyStore(storeID, autoHandleToken=True)
 print(token)

 {'status': 'succeeded', 'messages': [{'text': 'Verifying file group #2...', 'type': 'line'}, {'text': 'Creating a list of messages to be verified...', 'type': 'line'}, {'text': '234 messages are about to be verified.', 'type': 'line'}, {'text': 'Verifying...', 'type': 'line'}, {'text': '  100 messages verified...', 'type': 'line'}, {'text': '  200 messages verified...', 'type': 'line'}, {'text': '  234 messages verified.', 'type': 'line'}, {'text': 'Finished. No errors have been found.', 'type': 'line'}], 'progressPercentage': 100}

Cancelling

Currently long running calls cannot be cancelled. This is not a limitation of the Python wrapper, but of the MailStore Management API itself. This will be changed in the next major release of MailStore Server.

Exception Handling

When there are no errors, the returned value is always a python dictionary.

In case an error occurred, the call will raise an Exception. All MailStore Exceptions are derived from mailstore.errors.MailStoreBaseError which itself is derived from Exception.

 try:
     print(serverClient.GetUserInfo("not_such_user"))
 except mailstore.errors.MailStoreBaseError as e:
     print(e)
 
 ERROR ('internal MailStore Server error',)
 500 Internal Server Error https://127.0.0.1:8463/JSON/Invoke/GetUserInfo POST userName=not_such_user Command in MethodList: True

Pretty Printing the Output

There is a helper function that formats the returned values in more readable manner.

 mailstore.pprint(serverClient.GetUserInfo("admin"))

 authentication integrated
 distinguishedName 
 privileges
    admin
 fullName Administrator
 userName admin

Methods Overview

All the methods listed in the method overview are implemented in the Python API library.

Additional (helper) methods available. Please refer to the source code of the API wrapper library for further details.