Python API Wrapper Tutorial - Revision history

Ltalaschus: /* Installation */

2025-10-01T12:38:14Z

Installation

Ltalaschus: /* Installation */

2024-09-20T08:42:18Z

Installation

Ltalaschus: /* Installation */

2024-04-10T09:52:05Z

Installation

Ltalaschus: /* Installation */

2024-04-10T08:57:09Z

Installation

Ltalaschus at 13:45, 5 July 2023

2023-07-05T13:45:21Z

Ltalaschus at 13:57, 13 March 2023

2023-03-13T13:57:17Z

Ltalaschus at 16:30, 16 July 2018

2018-07-16T16:30:29Z

Ltalaschus at 16:28, 16 July 2018

2018-07-16T16:28:49Z

Ltalaschus: /* Installation */

2018-04-17T09:10:10Z

Installation

Ltalaschus at 09:09, 17 April 2018

2018-04-17T09:09:09Z

@@ Line 7: / Line 7: @@
 == Installation ==
-The API wrapper library is tested against Python 3.6 and newer and is compatible with 32bit and 64bit versions of Python.
+The API wrapper library is tested against Python 3.7 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.

@@ Line 7: / Line 7: @@
 == Installation ==
-The API wrapper library is tested against Python 3.4 and newer and is compatible with 32bit and 64bit versions of Python.
+The API wrapper library is tested against Python 3.6 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.

@@ Line 16: / Line 16: @@
 <source lang="python" smart-tabs="true" toolbar="false" gutter="false">
-python3 -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
+python3 -c "import site; print(site.getsitepackages())"
 </source>
@@ Line 22: / Line 22: @@
 <source lang="python" smart-tabs="true" toolbar="false" gutter="false">
-python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
+python -c "import site; print(site.getsitepackages())"
 </source>

@@ Line 7: / Line 7: @@
 == Installation ==
-The API wrapper library is tested against Python 3.2 and newer and is compatible with 32bit and 64bit versions of Python.
+The API wrapper library is tested against Python 3.4 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.

← Older revision		Revision as of 13:45, 5 July 2023
Line 3:		Line 3:

	This document explains the installation and usage of the Python API wrapper for the MailStore SPE Management 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.		This document explains the installation and usage of the Python API wrapper for the MailStore SPE Management 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.
		+
		+	{{Template:API Service Provider Access}}

	== Installation ==		== Installation ==

@@ Line 1: / Line 1: @@
 __NOTOC__
-<p class=msnote>'''Important notice:''' The Python API wrapper for the MailStore Service Provider Edition Management 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 Management API of MailStore SEP 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 Python API wrapper as well as all related example scripts are released under the terms an conditions of the [[wikipedia:MIT_License|MIT License]].</p>
+<p class=msnote>'''Important notice:''' The Python API wrapper for the MailStore Service Provider Edition Management 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 Management API of MailStore SPE 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 Python 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 SPE Management 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.

@@ Line 36: / Line 36: @@
 </source>
-Default values can be omitted. Credentials of an admin of the global SPE installation has to be used. Find a listing of all default values in the following table:
+Default values can be omitted. Credentials of an admin of the global SPE installation have to be used. Find a listing of all default values in the following table:
 {| class="wikitable"
@@ Line 81: / Line 81: @@
 | <tt>instanceID</tt>
 | None
-| The instance id of the instance for instance specific commands. Can be changed later by setting the setting the ''instanceID'' variable of the instantiated ''SPEClient''.
+| The instance id of the instance for instance specific commands. Can be changed between calls by setting the ''instanceID'' variable of the instantiated ''SPEClient''.
 |}

@@ Line 30: / Line 30: @@
 </source>
-Now the ''mailstore.spe.Client'' class can be instantiated as follows:
+Now the ''mailstore.mgmt.SPEClient'' class can be instantiated as follows:
 <source lang="python" smart-tabs="true" toolbar="false" gutter="false">
-speClient = mailstore.spe.Client(username="admin", password="admin", host="127.0.0.1", port=8474)
+speClient = mailstore.mgmt.SPEClient(username="admin", password="admin", host="127.0.0.1", port=8474, instanceID="example")
 </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:
+Default values can be omitted. Credentials of an admin of the global SPE installation has to be used. Find a listing of all default values in the following table:
 {| class="wikitable"
@@ Line 67: / Line 67: @@
 | 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>
+| <tt>callback</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.
+| A 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>
@@ Line 78: / Line 78: @@
 | 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 ==
@@ Line 94: / Line 99: @@
 <source lang="python" smart-tabs="true" toolbar="false" gutter="false">
-userInfo = speClient.GetUserInfo("example", "john.doe")
 if userInfo["statusCode"] == 'succeeded':
@@ Line 106: / Line 113: @@
 <source lang="python" smart-tabs="true" toolbar="false" gutter="false">
-instanceID = "example"
+speClient = mailstore.mgmt.SPEClient()
 emailAddresses = list()
-for user in speClient.GetUsers(instanceID)["result"]:
+for user in speClient.GetUsers()["result"]:
-	emailAddresses += speClient.GetUserInfo(instanceID, user["userName"])["result"]["emailAddresses"]
+	emailAddresses += speClient.GetUserInfo(user["userName"])["result"]["emailAddresses"]
 print(emailAddresses)
 </source>
@@ Line 122: / Line 143: @@
 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 off 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.
+If desired, automatic token handling can be enabled or disabled for each invoked method by adding ''autoHandleToken=True/False'' 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]].
@@ Line 133: / Line 154: @@
 import mailstore
-speClient = mailstore.spe.Client(autoHandleToken=True)
+speClient = mailstore.mgmt.SPEClient(autoHandleToken=True)
-instanceID = "example"
+speClient.instanceID = "example"
 storeID = 1
-print(speClient.VerifyStore(instanceID, storeID))
+print(speClient.VerifyStore(storeID))
 </source>
@@ Line 145: / Line 166: @@
 === 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.
+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 a function as ''callback'' argument to the instance of the API client.
 ==== Code ====
@@ Line 154: / Line 175: @@
     print(progress["logOutput"], end="", flush=True)
-speClient = mailstore.spe.Client(autoHandleToken=True, callbackStatus=showProgress)
+speClient = mailstore.mgmt.SPEClient(autoHandleToken=True, callback=showProgress, instanceID="example")
 storeID = 2
-print(speClient.VerifyStore(instanceID, storeID))
+print(speClient.VerifyStore(storeID))
 </source>
@@ Line 191: / Line 211: @@
 import time
-speClient = mailstore.server.Client(autoHandleToken=False)
+speClient = mailstore.mgmt.SPEClient(autoHandleToken=False)
 storeID = 3
-status = speClient.VerifyStore(instanceID, storeID)
+status = speClient.VerifyStore(storeID)
 while True:
@@ Line 233: / Line 254: @@
 import time
-speClient = mailstore.spe.Client(autoHandleToken=False)
+speClient = mailstore.mgmt.SPEClient(autoHandleToken=False)
-instanceID = "example"
+speClient.instanceID = "example"
 storeID = 3
-status = speClient.VerifyStore(instanceID, storeID)
+status = speClient.VerifyStore(storeID)
 while True:
@@ Line 269: / Line 290: @@
 All methods listed in the [[Management API - Function Reference|function reference]] are implemented in the Python API library. Use
-   pydoc3 mailstore.spe
+   pydoc3 mailstore.mgmt.SPEClient
 to access the build in documentation, which also includes an overview of all methods and their parameters.

@@ Line 11: / Line 11: @@
 Additionally create a folder "mailstore" in the Python's site-packages directory and extract the files from the [[Media:python-api-wrapper.zip|Python API wrapper library]] into this folder.
-The location of the site-packages directory can be found by executing the following command:
+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>