View source for Python API Wrapper Tutorial

__NOTOC__
<p class=msnote>'''Important notice:''' The Python API wrapper for the MailStore Server Administration API provided on this website, represents an example implementation of an API client. This wrapper should help system administrators and developers to quickly understand how the Administration API of MailStore Server works and how to use it in own scripts. Please understand that beyond this documentation no further support for the Python API wrapper is provided. Unless stated otherwise, the Pythin API wrapper as well as all related example scripts are released under the terms an conditions of the [[wikipedia:MIT_License|MIT License]].</p>

This document explains the installation and usage of the Python API wrapper for the MailStore Server Administration API. In order to prevent loss of data, service interruption or other problems, it is highly recommended to use a non-productive test environment for this tutorial as well as for script development in general. The 30-day-trial version of MailStore Server is perfectly suited for this.

== Installation ==
The API wrapper library is tested against Python 3.2 and newer and is compatible with 32bit and 64bit versions of Python. 

Python binaries for various operating systems can be downloaded from the [http://www.python.org/download/ Python download page] or installed using the package manager of most Linux distributions.

Additionally the <tt> mailstore</tt> folder of the [[Media:python-api-wrapper.zip|Python API wrapper library]] has to be installed in Python's site-packages directory.

In a UNIX like operating system the location of the site-packages directory can be found by executing the following command in a shell:

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
python3 -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
</source>

In Windows the location of the site-packages directory can be found by opening a ''cmd'', navigating in the Python3 installation directory and executing the following command:

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
</source>

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

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
 import mailstore
</source>

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

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)
</source>

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:

{| class="wikitable"
! width="150px" | Parameter
! width="100px" | Default Value
! Description
|-
| <tt>username</tt>
| admin
| Username used for connecting to the API.
|-
| <tt>password</tt>
| admin
| Password used for connecting to the API.
|-
| <tt>host</tt>
| 127.0.0.1
| Hostname or IP address of the MailStore Server computer.
|-
| <tt>port</tt>
| 8463
| TCP port on which MailStore Server is listening for API requests.
|-
| <tt>autoHandleToken</tt>
| True
| If set to ''True'', the caller does not need to handle tokens of long running tasks, but instead has to wait for the result. When set to ''False'' and the ''statusCode'' is ''running'', a status token is returned and must be handled appropriately by the caller of the method. Further details about token handling is described the corresponding section [[#Automatic Token Handling|Automatic Token Handling]] of this document.
|-
| <tt>waitTime</tt>
| 1000
| Specifies the number of milliseconds the API should wait for a final result. Otherwise the process is treated as ''running'', in which case token handling as defined by the status of ''autoHandleToken'' becomes necessary.
|-
| <tt>callbackStatus</tt>
| None
| Name of callback function to which interim statuses of long running tasks should be passed. This allows keeping track of the tasks' progress even if  ''autoHandleToken'' is enabled. This can be quite useful in order to notify users about the progress without having to deal with the token logic as a whole.
|-
| <tt>logLevel</tt>
| 2
| Has to be in the range ''0'' to ''4'', where 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''.
|-
| <tt>ignoreInvalidSSLCerts</tt>
| False
| Has to be set to ''True'' or ''False''. Has to be enabled if untrusted certificates are used, otherwise an error occurs when using recent Python versions (>= 3.4.3).
|}

== Invoking API Method ==
After the API client has been successfully instantiated, API methods can easily be invoked. When the method call was successful, the ''statusCode'' is ''succeeded'' and the result is stored in the dictionary ''result'' as shown in the following example:

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
print(serverClient.GetServerInfo()["result"])
 
{'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'machineName': 'WIN-2012-R2-X64', 'version': '9.0.3.9857'}, 'statusVersion': 2, 'statusCode': 'succeeded'}
</source>

If ''autoHandleToken'' was set to ''False'' and the ''statusCode'' returns ''running'', manual token handling is required as described in the [[#Auto Handle Token|Automatic Token Handling]] section.

For any other ''statusCode'' value than ''succeeded'' and ''running'' the occurrence of an error has to be assumed, in which further information such as the error message and error details are available in the dictionary ''error'' as shown below:

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
userInfo = serverClient.GetUserInfo("john.doe")

if userInfo["statusCode"] == 'succeeded':
    print(userInfo["result"]["emailAddresses"])
else:
    print(userInfo["error"]["message"])
</source>

=== Examples ===
Create a list of all email addresses assigned to MailStore users. 

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.server.Client()
emailAddresses = list()
for user in serverClient.GetUsers()["result"]:
	emailAddresses += serverClient.GetUserInfo(user["userName"])["result"]["emailAddresses"]
print(emailAddresses)
</source>

== Long Running Tasks ==
The execution of certain API methods like ''VerifyStore'' may take several minutes or even hours until it finishes. There are different options available to deal with these long running tasks:

# [[#Automatic Token Handling|Automatic Token Handling]]
# [[#Automatic Token Handling with Callback Function|Automatic Token Handling with Callback Function]]
# [[#Manual Token Handling|Manual Token Handling]]

Generally it is recommended to expect that every method call can become a long running task, as this depends on the ''waitTime'' value, the called method but also the overall load on the server. Thus it is not advisable to globally turn of automatic token handling when instantiating the API client.

If desired, automatic token handling can be enabled or disabled for each invoked method by adding ''autoHandleToken=True'' to the method's argument list.

Once a method has been invoked with manual token handling or a callback function, it can be cancelled by using the ''CancelAsync'' method as described in [[#Cancelling Long Running Tasks|Cancelling Long Running Tasks]].

=== Automatic Token Handling ===
When ''autoHandleToken'' is set to ''True'' (default), the wrapper polls the status of long running tasks automatically in the background and will return the final result when the process has ended.

==== Code ====
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
import mailstore

serverClient = mailstore.server.Client(autoHandleToken=True)
storeID = 1
print(serverClient.VerifyStore(storeID))
</source>

==== Output ====
<source lang="text" smart-tabs="true" toolbar="false" gutter="false">
{'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'd242d822a59bd4db308eef8b85af7d2a', 'result': None, 'statusVersion': 71, 'statusCode': 'succeeded'}
</source>

=== Automatic Token Handling with Callback Function ===
If a caller wants to keep track of the progress of a long running task (i.e. to inform the user about the progress), although automatic token handling was enabled, he could pass the name of a function as ''callbackStatus'' argument to the instance of the API client.

==== Code ====
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
import mailstore

def showProgress(progress):
   print(progress["logOutput"], end="", flush=True)

serverClient = mailstore.server.Client(autoHandleToken=True, callbackStatus=showProgress)
storeID = 3
print(serverClient.VerifyStore(storeID))
</source>

==== Output ====
<source lang="text" smart-tabs="true" toolbar="false" gutter="false">
Verifying file group #3...
Creating a list of messages to be verified...
1249 messages are about to be verified.
Verifying...
  100 messages verified...
  200 messages verified...
  300 messages verified...
  400 messages verified...
  500 messages verified...
  600 messages verified...
  700 messages verified...
  800 messages verified...
  900 messages verified...
  1000 messages verified...
  1100 messages verified...
  1200 messages verified...
  1249 messages verified.
Finished. No errors have been found.
{'error': None, 'result': None, 'logOutput': '  1000 messages verified...\r\n  1100 messages verified...\r\n  1200 messages verified...\r\n  1249 messages verified.\r\nFinished. No errors have been found.\r\n', 'token': 'c56f032d9db263133c1a413f79744b84', 'statusVersion': 71, 'statusText': None, 'percentProgress': 100, 'statusCode': 'succeeded'}
</source>

=== Manual Token Handling ===
If ''autoHandleToken'' is set to ''False'' the caller must handle long running tasks and the corresponding tokens all by itself. To poll for status updates, the ''GetStatus'' method must be called periodically passing the last returned result as parameter. ''GetStatus'' will extract the status token itself, poll for the latest update and return the received data to the caller again. The main call has finished when the ''statusCode'' changes to something different than ''running''. Calling ''GetStatus'' without passing a status token will result in an exception.

==== Code ====
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
import mailstore
import time

serverClient = mailstore.server.Client(autoHandleToken=False)
storeID = 3
status = serverClient.VerifyStore(storeID)

while True:
    if status["statusCode"] != "running":
        break
    print(status["logOutput"], end="", flush=True)
    status = serverClient.GetStatus(status)
    time.sleep(1)
</source>

==== Output ====
<source lang="text" smart-tabs="true" toolbar="false" gutter="false">
Verifying file group #3...
Creating a list of messages to be verified...
1249 messages are about to be verified.
Verifying...
  100 messages verified...
  200 messages verified...
  300 messages verified...
  400 messages verified...
  500 messages verified...
  600 messages verified...
  700 messages verified...
  800 messages verified...
  900 messages verified...
  1000 messages verified...
  1100 messages verified...
  1200 messages verified...
  1249 messages verified.
Finished. No errors have been found.
</source>

=== Cancelling Long Running Tasks ===
Tasks invoked by using the callback method or manual token handling, can be canceled at any time by using the ''CancelAsync'' method. Please notice that the API does not acknowledge the success of the cancellation request. Instead the caller must continue to monitor the ''statusCode'' of the canceled method.

==== Code ====
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
import mailstore
import time

serverClient = mailstore.server.Client(autoHandleToken=False)
storeID = 3
status = serverClient.VerifyStore(storeID)

while True:
    if status["statusCode"] != "running":
        break
    print(status["logOutput"], end="")
    status = serverClient.GetStatus(status)
    time.sleep(1)
    serverClient.CancelAsync(status)
</source>

==== Output ====
<source lang="text" smart-tabs="true" toolbar="false" gutter="false">
Verifying file group #3...
Creating a list of messages to be verified...
1249 messages are about to be verified.
Verifying...
  100 messages verified...
  200 messages verified...
  300 messages verified...
  400 messages verified...
  500 messages verified...
  600 messages verified...
  700 messages verified...
  800 messages verified...
  900 messages verified...
  1000 messages verified...
  1100 messages verified...
</source>

== Methods Overview ==
All methods listed in the [[Administration API - Function Reference|function reference]] are implemented in the Python API library. Use 

  pydoc3 mailstore.server

to access the build in documentation, which also includes an overview of all methods and their parameters.

[[de:Python API-Wrapper Tutorial]]
[[en:Python API Wrapper Tutorial]]