MailStore Server Help - User contributions [en]

Python API Wrapper Tutorial

2024-02-22T09:31:36Z

Chansen:

__NOTOC__
'''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 Python API wrapper as well as all related example scripts are released under the terms an conditions of the [[wikipedia:MIT_License|MIT License]].

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 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]] into this folder.

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.mgmt.ServerClient'' class can be instantiated as follows:

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient(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>callback</tt>
| None
| 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>
| 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())

{'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 and print a list of all email addresses assigned to MailStore users.

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient()
addresses = list()
for user in serverClient.GetUsers()["result"]:
addresses += serverClient.GetUserInfo(user["userName"])["result"]["emailAddresses"]
print("\n".join(sorted(set(addresses))))
</source>

Create and print a list of all regular users archive privileges

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient()

privileges_map = dict()
for user in serverClient.GetUsers()["result"]:
user_info = serverClient.GetUserInfo(user["userName"])["result"]
if "privilegesOnFolders" in user_info:
for privilege in user_info["privilegesOnFolders"]:
if privilege["folder"] not in privileges_map:
privileges_map[privilege["folder"]] = {user["userName"]: privilege["privileges"]}
else:
privileges_map[privilege["folder"]].update({user["userName"]: privilege["privileges"]})

for archive, user_dict in privileges_map.items():
print("Archive: {}".format(archive))
for username, priv in user_dict.items():
print("\tUser: {}: {}".format(username, ", ".join(priv)))
</source>

Create and print a list of all admin users.

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient()
admins = list()

for user in serverClient.GetUsers()["result"]:
if "admin" in serverClient.GetUserInfo(user["userName"])["result"]["privileges"]:
admins.append(user["userName"])

print("\n".join(admins))
</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 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/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]].

=== 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.mgmt.ServerClient(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 a function as ''callback'' 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.mgmt.ServerClient(autoHandleToken=True, callback=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.mgmt.ServerClient(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.mgmt.ServerClient(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.mgmt.ServerClient

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]]

Python API Wrapper Tutorial

2024-02-22T09:31:24Z

Chansen:

__NOTOC__
'''Important notice:''' Thee 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 Python API wrapper as well as all related example scripts are released under the terms an conditions of the [[wikipedia:MIT_License|MIT License]].

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 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]] into this folder.

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.mgmt.ServerClient'' class can be instantiated as follows:

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient(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>callback</tt>
| None
| 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>
| 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())

{'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 and print a list of all email addresses assigned to MailStore users.

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient()
addresses = list()
for user in serverClient.GetUsers()["result"]:
addresses += serverClient.GetUserInfo(user["userName"])["result"]["emailAddresses"]
print("\n".join(sorted(set(addresses))))
</source>

Create and print a list of all regular users archive privileges

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient()

privileges_map = dict()
for user in serverClient.GetUsers()["result"]:
user_info = serverClient.GetUserInfo(user["userName"])["result"]
if "privilegesOnFolders" in user_info:
for privilege in user_info["privilegesOnFolders"]:
if privilege["folder"] not in privileges_map:
privileges_map[privilege["folder"]] = {user["userName"]: privilege["privileges"]}
else:
privileges_map[privilege["folder"]].update({user["userName"]: privilege["privileges"]})

for archive, user_dict in privileges_map.items():
print("Archive: {}".format(archive))
for username, priv in user_dict.items():
print("\tUser: {}: {}".format(username, ", ".join(priv)))
</source>

Create and print a list of all admin users.

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient()
admins = list()

for user in serverClient.GetUsers()["result"]:
if "admin" in serverClient.GetUserInfo(user["userName"])["result"]["privileges"]:
admins.append(user["userName"])

print("\n".join(admins))
</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 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/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]].

=== 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.mgmt.ServerClient(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 a function as ''callback'' 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.mgmt.ServerClient(autoHandleToken=True, callback=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.mgmt.ServerClient(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.mgmt.ServerClient(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.mgmt.ServerClient

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]]

Move Archiving Emails from Microsoft 365 - Modern Authentication

2022-11-10T17:41:23Z

Chansen: Redirected page to Archiving Emails from Microsoft 365 - Modern Authentication

#REDIRECT [[Archiving Emails from Microsoft 365 - Modern Authentication]]

Archiving Emails from Microsoft 365 (Modern Authentication)

2022-11-10T16:57:05Z

Chansen: Changed redirect target from Move Archiving Emails from Microsoft 365 - Modern Authentication to Archiving Emails from Microsoft 365 - Modern Authentication

#REDIRECT [[Archiving Emails from Microsoft 365 - Modern Authentication]]

Archiving Emails from Microsoft 365 - Modern Authentication

2022-11-10T16:55:07Z

Chansen: Created page with "{{Implementation Guide Preamble|Exchange Online / Microsoft 365|{{#ev:youtube|https://youtu.be/X0Um0cDWGg0|350|right|''Tech Tip: Microsoft 365 Archiving Profiles''}}..."

{{Implementation Guide Preamble|Exchange Online / Microsoft 365|{{#ev:youtube|https://youtu.be/X0Um0cDWGg0|350|right|''Tech Tip: Microsoft 365 Archiving Profiles''}}| Our Tech Tip video shows the essential configuration steps in this article.}}
 
{{Multiline Notices|Heading=Important Notices|MailStore Server supports archiving emails from Microsoft 365 (Modern Authentication) only with the global Microsoft Cloud. National clouds such as ''Microsoft Cloud for US Government'', ''Microsoft Cloud Germany'' (operated by T-Systems) and ''Azure and Microsoft 365 operated by 21Vianet in China'' are not supported. For archiving emails from ''Office 365 Germany'' and ''Office 365 operated by 21Vianet'', please refer to the [[Synchronizing_User_Accounts_with_Microsoft_365_(Basic_Authentication)|corresponding implementation guide]].|For better readability, the terms ''Microsoft 365'' and ''Exchange Online'' are used interchangeably hereinafter instead of ''Exchange Online / Microsoft 365''.}}

== App Registration & User Synchronization ==
Before archiving Microsoft 365 mailboxes, registering MailStore Server in your Microsoft 365 tenant is required. It is also highly recommended to synchronize users in MailStore Server directly with that tenant to fetch all information that is relevant for archiving such as email addresses. The registration and synchronization procedures are described in the chapter [[Synchronizing User Accounts with Microsoft 365 (Modern Authentication)]] of the MailStore Server manual.

'''Please note:''' MailStore Server runs as a [[MailStore Server Service Configuration|Windows service]] and thus must use ''Application Permissions'' to access user mailboxes in Microsoft 365. By design, on the Microsoft identity platform, which is at the heart of Microsoft 365 authentication and authorization, this permission scope encloses the full level of privileges implied by a permission. As a consequence, once registered as described above, MailStore Server has access to all mailboxes in your Microsoft 365 tenant. Therefore, with regard to security, access to the Microsoft 365 archiving profiles in MailStore Server is limited to MailStore Server administrators.

=== Including Microsoft 365 Shared Mailboxes ===
In Microsoft 365, shared mailboxes are special mailboxes that multiple users have access to. Unlike a normal mailbox, a shared mailbox is not associated to a licensed Microsoft 365 user. For MailStore Server to create user entries for shared mailboxes, you must therefore deactivate the option ''Synchronize licensed Microsoft Exchange Online users only'' in the section [[Synchronizing User Accounts with Microsoft 365 (Modern Authentication)#User_Database_Synchronization|User Database Synchronization]]. 
After synchronization you can grant MailStore Server users access to the archive of the shared mailbox by [[Users,_Folders_and_Settings#Folder_Access_.28e.g._Access_to_the_Emails_of_Other_Users.29|assigning privileges]]. For archiving shared mailboxes, just proceed as for individual or multiple mailboxes as detailed below.

== Archiving Individual Microsoft 365 Mailboxes ==
{{Archiving Single Mailbox Preamble|Microsoft 365}}
For each mailbox, please proceed as follows:

* Log on to MailStore Client as MailStore Server administrator.
* Click on ''Archive Email''.
* From the ''Email Servers'' list in the ''Create Profile'' area of the ''Archive Email'' page, select ''Microsoft 365'' to create a new archiving profile.
* A wizard opens to assist in specifying the archiving settings. 
*; [[File:Microsoft 365 mailbox 01.png|center|347px]]
* Select ''Single Mailbox'' and click on ''OK''.
*; [[File:Microsoft 365 mailbox 02.png|center|347px]]
* Select the Microsoft 365 credentials that you have created during the registration of MailStore Server with Microsoft 365 from the ''Credentials'' drop-down list. You can also use the button (…) to access the [[Synchronizing_User_Accounts_with_Microsoft_365_(Modern_Authentication)#Creating_Credentials_in_MailStore_Server|Credential Manager]].
* In the ''Mailbox'' field, enter the primary email address of the user whose mailbox you want to archive.
* Click on ''Test'' to verify that MailStore Server can access the mailbox.
* Click on ''Next''.
* If needed, adjust the settings for the [[Email_Archiving_with_MailStore_Basics#Archiving_Specific_Folders|List of Folders to be Archived]], the [[Email_Archiving_with_MailStore_Basics#Specifying_Filter_Criteria_for_Archiving|filter]] and the [[Email_Archiving_with_MailStore_Basics#Archiving_Specific_Folders|Deletion Rules]]. By default, no emails will be deleted from the mailbox. The ''Timeout'' value only has to be adjusted in specific cases (e.g. with very slow network connections).
*; [[File:Microsoft_365_mailbox_03.png|center|347px]]
* Click on ''Next'' to continue.
* Select the archive of the user for whom the selected mailbox is to be archived. If the user does not exist yet, click on ''Create a New User…''.
*; [[File:Microsoft_365_mailbox_04.png|center|347px]]
* Click on ''Next''.
* In the last step, a name for the archiving profile can be specified. After clicking ''Finish'', the archiving profile will be listed under ''Saved Profiles'' and, if desired, can be run immediately or automatically.

More information on how to execute archiving profiles can be found under the topic [[Email Archiving with MailStore Basics]]

== Archiving Multiple Microsoft 365 Mailboxes Centrally ==
{{Archiving Multiple Mailboxes Preamble|Microsoft 365}}
Please proceed as follows:

* Log on to MailStore Client as MailStore Server administrator.
* Click on ''Archive Email''.
* From the ''Email Servers'' list in the ''Create Profile'' area of the ''Archive Email'' page, select ''Microsoft 365'' to create a new archiving profile.
* A wizard opens to assist in specifying the archiving settings. 
*; [[File:Microsoft 365 mailboxes 01.png|center|347px]]
* Select ''Multiple Mailboxes'' and click ''OK''. 
*; {{Archiving_Multiple_or_Multidrop_Note|multiple mailboxes|[[#App_Registration_.26_User_Synchronization|directory synchronization]]}}
*; [[File:Microsoft 365 mailboxes 02.png|center|347px]]
* Select the Microsoft 365 credentials that you have created during the registration of MailStore Server with Microsoft 365 from the ''Credentials'' drop-down list. You can also use the button (…) to access the [[Synchronizing_User_Accounts_with_Microsoft_365_(Modern_Authentication)#Creating_Credentials_in_MailStore_Server|Credential Manager]].
* Click on ''Next'' to continue.
*; [[File:Microsoft 365 mailboxes 03.png|center|347px]]
* If needed, adjust the settings for the [[Email_Archiving_with_MailStore_Basics#Archiving_Specific_Folders|List of Folders to be Archived]], the [[Email_Archiving_with_MailStore_Basics#Specifying_Filter_Criteria_for_Archiving|filter]] and the [[Email_Archiving_with_MailStore_Basics#Archiving_Specific_Folders|Deletion Rules]]. By default, no emails will be deleted from the mailbox. The ''Timeout'' value only has to be adjusted in specific cases (e.g. with very slow network connections). Please keep in mind that these settings apply to all mailboxes to be archived, as specified in the next step.
*; {{Archiving_Multiple_Mailboxes_Centrally_Options|Microsoft_365_mailboxes_04.png|Microsoft 365}}

== Archiving Incoming and Outgoing Emails Directly ==
{{Archiving Exchange Journal Mailbox Preamble|Exchange Online}}

=== Step 1: Setup and Configure MailStore Gateway ===
Please refer to the [https://help.mailstore.com/en/gateway/ MailStore Gateway Manual] for detailed instructions about:

* Installation and Setup of MailStore Gateway
* Logging on to MailStore Gateway's Management Console
* Creating MailStore Gateway mailboxes

After these steps, a mailbox with an individual email address (e.g. mbx-dead1234beef5678@gateway.example.com) should exist.

=== Step 2: Configure MailStore Server ===
{{Archiving MailStore Gateway Mailbox|''In- and Outbound E-Mail Automatically''|Microsoft 365 journal 01.png|Arch_MailStore_Gateway_Office365_02.png|''Microsoft 365''|TargetFolderHint=DontShow|POP3Hint=DontShow|DSLink=[[#App_Registration_.26_User_Synchronization|directory synchronization]]}}

=== Step 3: Creating a Journal Rule ===
The following steps describe how to set up journaling for your Microsoft 365 account.

Since you are planning to use an external mailbox (MailStore Gateway) as the recipient for Journal reports, we highly recommend to first create an external contact with this mail address in your Exchange mailbox administration to prevent any later errors or warnings about an unknown recipient in the process.

* Sign in to the [https://admin.microsoft.com/ Microsoft 365 admin center] as an Exchange or Global Administrator for your Microsoft 365 tenant.
* Expand the left navigation menu by clicking ''Show all''.
* In the ''Admin centers'' section, either use this [https://compliance.microsoft.com/exchangeinformationgovernance?viewid=exoJournalRule direct link] or follow these steps:
** In the left navigation menu, click ''Compliance''. The Microsoft Purview compliance portal is opened.
** In the left navigation menu, select ''Data Lifecycle Management'', then select ''Exchange (legacy)''.
* Open the ''Settings'' on the top right.
* Enter a mailbox in the ''Send undeliverable journal reports to'' section. This mailbox should be a dedicated mailbox for this purpose. This mailbox receives None Delivery Reports (NDRs) for undeliverable journal reports in case the primary journal mailbox is unreachable.
* Return to the ''Exchange (legacy)'' settings.
* Open the page ''Journal rules''.
* Create a new journaling rule by clicking on ''+ (New rule)''.
*:[[File:Arch_office365_journal_01.png|center|550px]]
* Enter the email address of the previously created MailStore Gateway mailbox in the ''Send journal reports to:'' box.
* Enter a name for the journal rule, e.g. ''Journaling''.
* In the ''Journal messages sent or received from'' section, select whether the rule should apply to everyone or to specific users or groups.
* Under ''Type of message to journal'', choose whether to capture all messages, internal messages only, or external messages only.
* Click on ''Next'', then validate your settings, click ''Submit'' to activate the rule.

== Public Folders ==
{{Archiving Exchange Public Folders Preamble|Exchange Online|Microsoft 365}}
* Sign in to the [https://admin.microsoft.com/ Microsoft 365 admin center] as an Exchange or Global Administrator for your Microsoft 365 tenant.
* Expand the left navigation menu by clicking ''Show all''.
* In the ''Admin centers'' section, choose ''Exchange''.
* In the ''Exchange admin center'', navigate to ''public folders''.
* Click on the ''Ellipsis (…)'' and select ''Root permissions''.
*: [[File:Microsoft_365_pf_01.png|center|480px]]
* A new browser window opens. Click on ''+ (Add)''.
* Use ''Browse'' to choose the Microsoft 365 user you want to grant permissions.
* Choose ''Custom'' as ''Permission level'' and grant ''Read items'' and ''Delete all'' permissions.
*: [[File:Arch_office365_pf_02.png|center|347px]]
* Click on ''Save''.
* Enable the option ''Apply changes to this public folder and all its subfolders.''
* Click on ''Save''.
* Click on ''Close'' after saving has been completed successfully.

=== Step 3: Setting up the Archiving Process ===
* Log on to MailStore Client as MailStore Server administrator.
* Click on ''Archive Email''.
* From the ''Email Servers'' list in the ''Create Profile'' area of the ''Archive Email'' page, select ''Microsoft 365'' to create a new archiving profile.
* A wizard opens to assist in specifying the archiving settings. 
*; [[File:Microsoft 365 pf 03.png|center|347px]]
* Select ''Public Folders'' and click on ''OK''. 
*; [[File:Microsoft 365 pf 04.png|center|347px]]
* Select the Microsoft 365 credentials that you have created during the registration of MailStore Server with Microsoft 365 from the ''Credentials'' drop-down list. You can also use the button (…) to access the [[Synchronizing_User_Accounts_with_Microsoft_365_(Modern_Authentication)#Creating_Credentials_in_MailStore_Server|Credential Manager]].
* In the ''Mailbox'' field, enter the primary email address of the user that has access to the public folders as described above.
* The value of the ''Target Folder'' box defines the top level folder below which the public folder hierarchy will be created in the target archive. Usually, you can leave this value to its default.
* Click on ''Test'' to verify that MailStore can access the public folders.
* Click on ''Next'' to continue.
*; [[File:Microsoft 365 pf 05.png|center|347px]]
* Adjust the settings for the [[Email_Archiving_with_MailStore_Basics#Archiving_Specific_Folders|List of Folders to be Archived]]. By default, all public folders that contain emails will be archived.
* If needed, adjust [[Email_Archiving_with_MailStore_Basics#Specifying_Filter_Criteria_for_Archiving|the filter]] and the [[Email_Archiving_with_MailStore_Basics#Deleting_Emails_after_Archiving|Deletion Rules]]. By default, no emails will be deleted from the public folders. The ''Timeout'' value only has to be adjusted in specific cases (e.g. with very slow network connections).
* Click on ''Next'' to continue.
*; [[File:Microsoft 365 pf 06.png|center|347px]]
* In the next step, select the archive of the user you have prepared in step 1.
* In the last step, specify a name for the archiving profile. After clicking ''Finish'' the archiving profile will be listed under ''Saved Profiles'' and can be run immediately or automatically if desired.

[[de:E-Mail-Archivierung_von_Microsoft_365_(Modern_Authentication)]]
[[en:Archiving_Emails_from_Microsoft_365_(Modern_Authentication)]]

Python API Wrapper Tutorial

2022-11-08T16:21:38Z

Chansen: /* Installation */

__NOTOC__
'''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 Python API wrapper as well as all related example scripts are released under the terms an conditions of the [[wikipedia:MIT_License|MIT License]].

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 create a folder "mailstore" in the Python's site-packages directory and extract the files from the [[https://help.mailstore.com/en/server/images/c/cc/Python-api-wrapper.zip|Python API wrapper library]] into this folder.

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.mgmt.ServerClient'' class can be instantiated as follows:

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient(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>callback</tt>
| None
| 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>
| 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())

{'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 and print a list of all email addresses assigned to MailStore users.

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient()
addresses = list()
for user in serverClient.GetUsers()["result"]:
addresses += serverClient.GetUserInfo(user["userName"])["result"]["emailAddresses"]
print("\n".join(sorted(set(addresses))))
</source>

Create and print a list of all regular users archive privileges

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient()

privileges_map = dict()
for user in serverClient.GetUsers()["result"]:
user_info = serverClient.GetUserInfo(user["userName"])["result"]
if "privilegesOnFolders" in user_info:
for privilege in user_info["privilegesOnFolders"]:
if privilege["folder"] not in privileges_map:
privileges_map[privilege["folder"]] = {user["userName"]: privilege["privileges"]}
else:
privileges_map[privilege["folder"]].update({user["userName"]: privilege["privileges"]})

for archive, user_dict in privileges_map.items():
print("Archive: {}".format(archive))
for username, priv in user_dict.items():
print("\tUser: {}: {}".format(username, ", ".join(priv)))
</source>

Create and print a list of all admin users.

<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
serverClient = mailstore.mgmt.ServerClient()
admins = list()

for user in serverClient.GetUsers()["result"]:
if "admin" in serverClient.GetUserInfo(user["userName"])["result"]["privileges"]:
admins.append(user["userName"])

print("\n".join(admins))
</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 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/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]].

=== 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.mgmt.ServerClient(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 a function as ''callback'' 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.mgmt.ServerClient(autoHandleToken=True, callback=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.mgmt.ServerClient(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.mgmt.ServerClient(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.mgmt.ServerClient

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]]

File:Python-api-wrapper.zip

2022-11-08T14:28:00Z

Chansen: Chansen uploaded a new version of File:Python-api-wrapper.zip

File:Python-api-wrapper.zip

2022-11-08T14:15:45Z

Chansen: Chansen uploaded a new version of File:Python-api-wrapper.zip

Archiving Emails from External Systems (File Import)

2022-11-03T16:17:48Z

Chansen: Chansen moved page Archiving Emails from External Systems (File Import) to Archiving Emails from External Systems - File Import

#REDIRECT [[Archiving Emails from External Systems - File Import]]

Archiving Emails from External Systems - File Import

2022-11-03T16:17:48Z

Chansen: Chansen moved page Archiving Emails from External Systems (File Import) to Archiving Emails from External Systems - File Import

MailStore Server can also archive the emails from applications that are not directly supported if they are available in a standardized format. With most applications it is necessary to export the emails to one of those formats first.

Using file import, MailStore Server can archive the following formats:

*'''EML''' - One file per email. Often called RFC 822 or MIME format.
*'''MSG''' - One file per email. Microsoft Outlook email files.
*'''PST''' - Microsoft Outlook personal folder files.
*'''MBOX''' - This file format is used by Mozilla Thunderbird, for example, although in this case the file ending is omitted. The MBOX file format is also used by many Unix mail servers.

== Procedure for Archiving PST Files ==
Archiving PST files is described separately in chapter [[Archiving_Outlook_PST_Files_Directly|Archiving Outlook PST Files Directly]].

== Procedure for Archiving EML and MSG Files ==
Setting up archiving processes for files from the file system is done using archiving profiles. General information about archiving profiles is available in chapter [[Email_Archiving_with_MailStore_Basics#Working_with_Archiving_Profiles|Working with Archiving Profiles]].

=== Archiving Emails of a Single User ===
'''Please note:''' If you do not want to archive email files in your personal user archive only, you'll have to be logged on to MailStore Client as a MailStore Server administrator. Only a MailStore Server administrator can archive emails for other users.

Please proceed as follows:

*In MailStore Server, click on ''Archive Email''.
*From the ''E-mail Files'' category in the ''Create Profile'' section select ''EML and MSG files''.
*A wizard opens, guiding you through the setup process.
*: [[File:arch_filesystem_00.png|center|350px]]
*Select ''Single User'' and click on ''OK''.
*The dialog window ''Archive EML and MSG files'' appears.
*: [[File:arch_filesystem_01.png|center|350px]]
*Select the folder to be archived. All email files in this folder will be archived.
*If desired, adjust the advanced settings or simply click ''Next''.
:*'''Include Subfolders:''' In addition to the emails in the selected folder also those located in any subfolders will be archived.
:*'''Read MailStore Headers:''' RFC 822 files created by the MailStore Server-specific export process contain additional information such as the source folder. Set the checkmark if this information should be taken into account.
:*'''Custom File Extensions:''' Here you can make appropriate entries if the files to be archived are in EML or MSG format but have a different file extension.
*If needed, adjust the settings for the [[Email_Archiving_with_MailStore_Basics#Archiving_Specific_Folders|List of Folders to be Archived]], the filter and the [[Email_Archiving_with_MailStore_Basics#Archiving_Specific_Folders|Deletion Rules]].
*:[[File:arch_filesystem_02.png|center|350px]]
*If logged on to MailStore Server as a MailStore Server-administrator, the target archive can be specified in the next step of the wizard. Select the archive of the user for whom the selected files are to be archived.
*: [[File:arch_filesystem_03.png|center|350px]]
*In the final step you can specify a name for the new archiving profile. After clicking on ''Finish'', the archiving profile will be listed under ''Saved Profiles'' and can be run immediately, if desired.

=== Archiving Emails of Multiple Users ===
'''Please note:''' In order to be able to select this archiving method, you'll have to be logged on to MailStore Client as a MailStore Server administrator. Only a MailStore Server administrator can archive emails for other users.

In addition to archiving email files of a single user, MailStore Server can archive email files of multiple users from a single directory; such emails may have been exported from a multidrop mailbox. 
To archive such emails please proceed as follows:

* In MailStore Server, click on ''Archive Email''.
* From the ''E-mail Files'' category in the ''Create Profile'' section select ''EML and MSG files''.
* A wizard opens, guiding you through the setup process.
*: [[File:arch_filesystem_04.png|center|350px]]
* Select ''Multiple Users'' and click on ''OK''.
*: {{Archiving_Multiple_or_Multidrop_Note|from a source that contains emails of multiple users}}
* The dialog window ''Archive Multidrop Mailbox (Filesystem)'' appears.
*: [[File:arch_filesystem_05.png|center|350px]]
* Select the folder with the email files to be archived.
* Adjust any further settings such as how to handle emails with unknown addresses or asking MailStore Server to delete email files after they have been archived.
* Click on ''Next''.
* In the final step you can specify a name for the new archiving profile. After clicking on ''Finish'', the archiving profile will be listed under ''Saved Profiles'' and can be run immediately, if desired.

=== Archiving Emails from a MailStore Export ===
'''Please note:''' In order to be able to select this archiving method, you'll have to be logged on to MailStore Client as a MailStore Server administrator. Only a MailStore Server administrator can archive emails for other users.

To archive EML files which have been created by a MailStore Export, the correct options have been pre-selected. This provides an easy way to file emails exported from MailStore Server into the correct user archives and folders again. 
Please proceed as follows:

*In MailStore Server, click on ''Archive Email''.
*From the ''E-mail Files'' category in the ''Create Profile'' section select ''EML and MSG files''.
*A wizard opens, guiding you through the setup process.
*: [[File:arch_filesystem_06.png|center|350px]]
*Select ''MailStore Export'' and click on ''OK''.
*The dialog window ''Archive EML and MSG files'' appears.
*: [[File:arch_filesystem_07.png|center|350px]]
*Select the folder to be archived. All email files in this folder will be archived.
*If desired, adjust the advanced settings or simply click ''Next''.
:*'''Include Subfolders:''' In addition to the emails in the selected folder also those located in any subfolders will be archived.
:*'''Read MailStore Headers:''' RFC 822 (EML) files created by the MailStore Server-specific export process contain additional information about the source archives and folders. This information allows to file emails exported from MailStore Server into the correct user archives and folders when being rearchived. Non-existent archives and folders will be created automatically.
:*'''Custom File Extensions:''' Here you can make appropriate entries if the files to be archived are in EML or MSG format but have a different file extension.
*If needed, adjust the settings for the [[Email_Archiving_with_MailStore_Basics#Archiving_Specific_Folders|List of Folders to be Archived]], the filter and the [[Email_Archiving_with_MailStore_Basics#Archiving_Specific_Folders|Deletion Rules]].
*:[[File:arch_filesystem_02.png|center|350px]]
*You can specify the target archive in the next step of the wizard. Select the archive of the user for whom the selected files are to be archived. The target archive will be ignored if the option ''Read MailStore Headers'' has been selected and the email to be archived contains such headers.
*: [[File:arch_filesystem_03.png|center|350px]]
*In the final step you can specify a name for the new archiving profile. After clicking on ''Finish'', the archiving profile will be listed under ''Saved Profiles'' and can be run immediately, if desired.

== Procedure for Archiving MBOX Files ==
Setting up the archiving process for files from the file system is done using archiving profiles. General information about archiving profiles is available in chapter [[Email_Archiving_with_MailStore_Basics#Working_with_Archiving_Profiles|Working with Archiving Profiles]].

'''Please note:''' If you do not want to archive email files in your personal user archive only, you'll have to be logged on to MailStore Client as a MailStore Server administrator. Only a MailStore Server administrator can archive emails for other users.

Please proceed as follows:

* In MailStore Server, click on ''Archive Email''.
* From the ''Email Files'' list in the ''Create Profile'' area of the application window select ''MBOX File''.
* A wizard opens, guiding you through the setup process.
* Select the MBOX file to be archived.
*: [[File:Arch_mbox_01.png|center|350px]]
* If logged on to MailStore Server as administrator, the target archive can be specified. Select the archive of the user for whom the selected file is to be archived.
*: [[File:Arch_mbox_02.png|center|350px]]
* In the final step you can specify a name for the new archiving profile. After clicking on ''Finish'', the archiving profile will be listed under ''Saved Profiles'' and can be run immediately, if desired.

== Archiving with Drag & Drop ==

Files can also be archived using Drag & Drop: Simply drag the appropriate folder containing EML files or the appropriate MBOX file into the list of saved settings to create an archiving profile for this process directly.

{{Starting the Archiving Process}}

[[de:E-Mails_aus_Fremdsystemen_archivieren_(Dateiimport)]]
[[en:Archiving Emails from External Systems (File Import)]]

Archiving Emails from Microsoft 365 (Basic Authentication)

2022-11-03T16:16:37Z

Chansen: Chansen moved page Archiving Emails from Microsoft 365 (Basic Authentication) to Archiving Emails from Microsoft 365 - Basic Authentication

#REDIRECT [[Archiving Emails from Microsoft 365 - Basic Authentication]]

Archiving Emails from Microsoft 365 - Basic Authentication

2022-11-03T16:16:37Z

Chansen: Chansen moved page Archiving Emails from Microsoft 365 (Basic Authentication) to Archiving Emails from Microsoft 365 - Basic Authentication

'''Information in this document is no longer maintained and may no longer be up-to-date.''' 
On September 23rd, 2021 [https://techcommunity.microsoft.com/t5/exchange-team-blog/basic-authentication-and-exchange-online-september-2021-update/ba-p/2772210 Microsoft announced] the end of support for Basic Authentication for Exchange Online APIs on '''October 1st, 2022'''. This affects any MailStore Server version prior to 13, which will then no longer be able to archive Microsoft 365 mailboxes.
 
 
In MailStore Server 13, support for modern authentication methods via OAuth 2.0 & OpenID Connect as per Microsoft's recommendation as well as corresponding archiving profiles were introduced. Therefore, for archiving Microsoft 365 mailboxes, please refer to the implementation guide [[Archiving Emails from Microsoft 365 (Modern Authentication)]].
{{Implementation Guide Preamble|Exchange Online / Office 365}}
'''Please note:''' For better readability the term ''Exchange Online / Office 365'' hereinafter is being referred to as ''Office 365''.

== Synchronizing Users ==
MailStore offers direct user synchronization support for Office 365. The setup procedure for the required service principal is described in the chapter [[Office 365 Integration]] of the MailStore Server manual.

Note that while Office 365 manages users in Azure Active Directory, this itself can be synchronized with on-premise user information. Even if Office 365 / Azure AD is not the primary source of user account information in your environment, it is highly recommended to synchronize MailStore directly with Office 365 to fetch all information that is relevant for archiving such as email addresses.

== Archiving Individual Office 365 Mailboxes ==
{{Archiving Single Mailbox Preamble|Office 365}}
'''Important notice:''' Archiving a single mailbox requires the Exchange Online feature ''EWS Application support''. Please make sure that your Office 365 plan supports this feature. More information is available in this [https://technet.microsoft.com/en-us/library/exchange-online-service-description.aspx TechNet article].
{{Archiving Exchange Single Mailbox|Office 365}}

== Archiving Multiple Office 365 Mailboxes Centrally ==
{{Archiving Multiple Mailboxes Preamble|Office 365}}
'''Important notice:''' Archiving multiple mailboxes requires the Exchange Online features ''EWS Application support'' and ''Role-Based Permissions''. Please make sure that your Office 365 plan supports these features. More information is available in this [https://technet.microsoft.com/en-us/library/exchange-online-service-description.aspx TechNet article].

=== Step 1: Setting up a service account for accessing mailboxes ===
To be able to archive multiple Office 365 mailboxes, you need to create an Office 365 user first. Afterwards follow these steps, to grant access permissions to the newly created user on all mailboxes:

* Log on to your Office 365 tenant through Microsoft's Online Portal with an admin account.
* In the ''Office 365 admin center'' choose ''ADMIN > Exchange''.
* Now, in the ''Exchange admin center'', navigate to ''permissions''.
* Under ''admin roles'' select ''+ (New)''.
*: [[Image:Arch_office365_multi_01.png|center|550px]]
* Enter a meaningful name (e.g. ''MailStore Impersonation'') and description for the new role group.
* Under ''Roles'' add the role ''ApplicationImpersonation''.
* Under ''Members'' add the user you want to give permission to access all mailboxes.
* Click on ''Save'' to create the new role group.

=== Step 2: Configuration of MailStore Server ===
{{Archiving Exchange Multiple Mailboxes|Office 365|DSLink=[[#Synchronizing_Users|directory synchronization]]}}

== Archiving Incoming and Outgoing Emails Directly ==
{{Archiving Exchange Journal Mailbox Preamble|Office 365}}

=== Step 1: Setup and Configure MailStore Gateway ===
Please refer to the [https://help.mailstore.com/en/gateway/ MailStore Gateway Manual] for detailed instructions about:

* Installation and Setup of MailStore Gateway
* Logging on to MailStore Gateway's Management Console
* Creating MailStore Gateway mailboxes

After these steps, a mailbox with an individual email address (e.g. mbx-dead1234beef5678@gateway.example.com) should exist.

=== Step 2: Creating a Journal Rule ===
The following steps describe how to set up journaling for your Microsoft Office 365 account.

* Log on to your Office 365 tenant through Microsoft's Online Portal with an admin account.
* In the ''Office 365 admin center'' choose ''ADMIN > Exchange''.
* Now, in the ''Exchange admin center'', navigate to ''compliance management''.
* Select ''journal rules''.
* Under ''Send undeliverable journal reports to'' select an alternate journaling mailbox that receives None Delivery Reports (NDRs) for undeliverable journal reports in case the primary journal mailbox is unreachable. This mailbox must be a dedicated mailbox, any mail sent directly to this mailbox won't be journaled.
* Click on ''+ (New)''.
*:The dialog window ''New Journal Rule'' opens:
*:[[File:Arch_office365_journal_01.png|center|550px]]
* Enter a name for the journal rule, e.g. ''Journaling''.
* In the ''If the message is sent to or received from...'' section select whether the rule should apply to all messages or to specific users or groups.
* Under ''Journal the following messages...'', choose whether to capture all messages, internally sent messages only, or only those messages with an external sender or recipient.
* Enter the email address of the previously created MailStore Gateway mailbox in the ''Send journal reports to:'' box.
* Click on ''save'' to activate the rule.

=== Step 3: Configuration of MailStore ===
{{Archiving MailStore Gateway Mailbox|TargetFolderHint=DontShow|POP3Hint=DontShow|DSLink=[[#Synchronizing_Users|directory synchronization]]}}

== Public Folders ==
{{Archiving Exchange Public Folders Preamble|Office 365}}
* Log on to your Office 365 tenant through Microsoft's Online Portal with an admin account.
* In the ''Office 365 admin center'' choose ''ADMIN > Exchange''.
* Now, in the ''Exchange admin center'', navigate to ''public folders''.
* Click on the ''Ellipsis (…)'' and select ''Root permissions''.
*: [[File:Arch_office365_pf_01.png|center|480px]]
* A new browser window opens. Click on ''+ (Add)''.
* Use ''Browse'' to choose the Office 365 user you want to grant permissions.
* Choose ''Custom'' as ''Permission level'' and grant ''Read items'' and ''Delete all'' permissions.
*: [[File:Arch_office365_pf_02.png|center|347px]]
* Click on ''Save''.
* Enable the option ''Apply changes to this public folder and all its subfolders.''
* Click on ''Save''.
* Click on ''Close'' after saving has been completed successfully.

=== Step 3: Setting up the Archiving Process ===
{{Archiving Exchange Public Folder|Office 365}}

== Shared Mailboxes ==
{{Template:Archiving_Exchange_Shared_Mailbox|Office 365}}

[[de:E-Mail-Archivierung von Microsoft Office 365]]
[[en:Archiving_Emails_from_Microsoft_Office_365]]

Using Network Attached Storage (NAS)

2022-11-03T16:16:18Z

Chansen: Chansen moved page Using Network Attached Storage (NAS) to Using Network Attached Storage - NAS

#REDIRECT [[Using Network Attached Storage - NAS]]

Using Network Attached Storage - NAS

2022-11-03T16:16:18Z

Chansen: Chansen moved page Using Network Attached Storage (NAS) to Using Network Attached Storage - NAS

Network Attached Storage (NAS) systems provide file-based access to their own local storage to remote clients via special network protocols. In Microsoft Windows environments, the SMB or CIFS protocol is typically used to access files on a remote system. Throughout this article, the term ''NAS'' represents any computer system that is capable of sharing its own local storage via SMB or CIFS protocol, may it be a traditional Windows file server, a Linux server with a running Samba service, or a dedicated physical or virtual appliance with its own operating system and management interface.

'''Please note:''' A storage system attached via FibreChannel, iSCSI, or other block-level storage protocols, is called Storage Area Network (SAN) storage. SAN storage is used like any other local disk (also referred to as Direct Attached Storage or DAS); no further configuration is needed to let MailStore Server store its data on it.

MailStore Server can utilize NAS systems to store its production data or as target for its backup data. In general, it is recommended to store production data locally for best performance, stability and reliability, and to use NAS systems for backup data.

Irregardless of where the production data is stored, the archive can always be accessed from other client computers by using MailStore Client, MailStore Web Access, MailStore Outlook Add-in, or IMAP compatible email clients via the integrated IMAP Server as described in [[Accessing the Archive]].

To ensure successful operation, the NAS should meet the following prerequisites:

* The NAS must not be turned off, disconnected or put into standby mode at any time, as long as there is a MailStore Server service accessing the data on the NAS. Otherwise, data corruption may occur, which can lead to irreparable loss of data.
* If possible, disable "Opportunistic Locking" for network shares on which production data is to be stored.
* The shared directories on the NAS should be excluded from any server-side anti-virus scanning, real-time backups, file level replication, or anything else that could prevent MailStore from accessing any file at any time.
* When moving an existing MailStore database, the available disk space should be twice the size of the current archive.

== Creating a Network Share ==
The follow three steps are needed to setup a network share that can be used by MailStore Server:

* Create a dedicated folder for the MailStore data to reside in on the NAS.
* Share that folder if it is not already inside a shared folder on the network, via SMB or CIFS protocol. Please consult the vendor's documentation on how to share a folder on the network.
* As described below, authorize either a computer or user object to access the network share and the data therein.

=== Authorizing a Computer Object ===
As the MailStore Server service runs under the account of the ''SYSTEM'' user on the Windows operating system, the ''SYSTEM'' user is identified by the computer object (e.g. SERVER01$) where MailStore Server is installed on when accessing network resources. Thus permissions to access the network share must be granted to the corresponding computer object.

'''Please note:''' Granting access to computer objects requires all involved systems to be part of an Active Directory domain. If this requirement cannot be satisfied, or the NAS system does not support granting access to computer objects at all, use the instructions in the [[Using_Network_Attached_Storage_(NAS)#Authorizing a User Object|Authorizing a User Object]] section instead.

* Grant the computer object full control over the network share. This enables the local system account of the computer on which MailStore Server is installed to access the network share.
*: [[File:Tech_netshares_01.png|center]]
* If file system permissions are required on the shared directory, grant the computer object full control here as well.
*: [[File:Tech_netshares_02.png|center]]

=== Authorizing a User Object ===
* Create a user object either locally on the NAS system or in a directory service (e.g. Active Directory) that is used by the NAS to authenticate users.
* Grant the user object full control over the directory share.
*: [[File:Tech_netshares_04.png|center]]
* If file system permissions are required, grant the user object full control here as well.
*: [[File:Tech_netshares_05.png|center]]

== Installing MailStore Server while using a NAS system ==
* Install MailStore Server on the desired machine. Detailed instructions can be found in the [[Installation]] section if the MailStore manual.
* Open the [[MailStore Server Service Configuration]].
* Stop the MailStore Server service.
* Navigate to ''General'' and enter the full path to a directory on the network share provided by the NAS system in UNC notation (<code>\\computer\sharename\directory</code>). In the example below, the name of the NAS system is NAS01, the name of the share is MailStore, and the directory is MailArchive.

[[File:Tech_netshares_06.png|center|550px]]

If a computer object was granted access to the network share, the MailStore service can be started by clicking on ''Start'' in the MailStore Server Service Configuration interface.

If a user object was granted access to the network share, proceed with the next section.

== Connecting to Network Shares ==
If a user object has been granted access on the network share, MailStore Server must establish a connection to the share during startup using this user object. Proceed as follows to configure access to the network share for the MailStore Server service:

* On the MailStore Server computer, open the [[MailStore Server Service Configuration]].
* Click on ''Network Shares''.
* Click on ''Add...''
* Enter the path for the network share on the NAS system into the ''Share Path'' field in UNC notation (<code>\\computer\sharename</code>).
* Enter the username and password of the corresponding user object that has access to the network share into the ''User Name'' and ''Password'' fields. <div class="msnote">'''Important notice:''' It is highly recommended to always put the corresponding computer or domain name in front of the username, e.g. <code>computer\username</code> where <code>computer</code> has to be the host name of the NAS, or, if applicable, <code>domain\username</code> where <code>domain</code> has to be the name of the Active Directory domain the NAS has joined and where the user object exists.</div>
*:[[File:Tech_netshares_07.png|center|550px]]
* Click on ''OK''.
* The MailStore Server service can now be started by clicking on ''Start'' in the MailStore Server Service Configuration interface.

'''Please note:''' Due to the different security contexts of the MailStore Server service and the MailStore Server Service Configuration application, the user interface does not provide any test functionality and thus checking the ''Event Viewer'' for potential error messages is recommended after starting the service.

== Moving the archive to a Network Share ==

Moving the archive to a network share is described in the article [[Moving_the_Archive#Moving_the_Archive_to_a_Network_Share|Moving the Archive]].

== Writing a backup to a Network Share ==

* [[#Creating_a_Network_Share|Create a network share]] on the NAS system first.
* If a user object has been granted permissions on the share, you have to configure a [[#Connecting_to_Network_Shares|connection to a network share]].
* Follow the instructions from the [[Backup_and_Restore#Using_the_MailStore_Integrated_Backup_Feature|backup article]].

== Troubleshooting ==
In case of errors or problems the [[MailStore_Server_Service_Configuration#Event_Viewer|event viewer]] or [[MailStore_Server_Service_Configuration#Debug_Log|debug log]] can be used to troubleshoot.

[https://cs.mailstore.com/index.php?/Knowledgebase/Article/View/73/10/debugging-nas-connection-issues Debugging NAS connection issues]

[https://cs.mailstore.com/index.php?/Knowledgebase/Article/View/99/10/a-mailstore-database-residing-on-a-network-share-cannot-be-opened Opportunistic Locking]

[[de:Verwendung_von_Network_Attached_Storage_(NAS)]]
[[en:Using Network Attached Storage (NAS)]]

Synchronizing User Accounts with Microsoft 365 (Modern Authentication)

2022-11-03T16:15:51Z

Chansen: Chansen moved page Synchronizing User Accounts with Microsoft 365 (Modern Authentication) to Synchronizing User Accounts with Microsoft 365 - Modern Authentication

#REDIRECT [[Synchronizing User Accounts with Microsoft 365 - Modern Authentication]]

Synchronizing User Accounts with Microsoft 365 - Modern Authentication

2022-11-03T16:15:51Z

Chansen: Chansen moved page Synchronizing User Accounts with Microsoft 365 (Modern Authentication) to Synchronizing User Accounts with Microsoft 365 - Modern Authentication

{{Directory Services Preamble|Microsoft 365 tenant|Microsoft 365|{{#ev:youtube|https://youtu.be/OtJx2EKEW0Y|350|right|''Tech Tip: Preparation of the Microsoft 365 Tenant and User Synchronization''}}| Our Tech Tip video shows the essential configuration steps in this article.}}
 
== Prerequisites, Recommendations and Limitations ==
* For best user experience, the certificate used by MailStore Server should be trusted by all clients and the used web browsers. Using a certificate that is signed by a trusted certificate authority or [[Using_Lets_Encrypt_Certificates|using Let's Encrypt certificates]] is highly recommended.
* If users are supposed to log in to MailStore Server from outside the organization's network without a VPN using [[Accessing_the_Archive_with_the_MailStore_Client_software|MailStore Client]], [[Accessing_the_Archive_with_the_Microsoft_Outlook_integration|MailStore Outlook Add-in]] or the [[Accessing_the_Archive_with_MailStore_Web_Access|Web Access]], the URIs mentioned in this article must be resolvable via DNS on the Internet and port-forwardings to the MailStore Server computer must be set up on the firewall or router if necessary.
* When using Microsoft 365 to authenticate users at login, [[Accessing_the_Archive_via_Integrated_IMAP_Server|accessing the archive via IMAP]] is not possible for technical reasons.
* MailStore Server supports synchronizing user accounts with Microsoft 365 (Modern Authentication) only with the global Microsoft Cloud. National clouds such as ''Microsoft Cloud for US Government'', ''Microsoft Cloud Germany'' (operated by T-Systems) and ''Azure and Microsoft 365 operated by 21Vianet in China'' are not supported. For synchronizing users with ''Office 365 Germany'' and ''Office 365 operated by 21Vianet'', please refer to the [[Synchronizing_User_Accounts_with_Microsoft_365_(Basic_Authentication)|corresponding manual chapter]].

== Connecting MailStore Server and Microsoft 365 ==
In order to synchronize user information from Microsoft 365, MailStore Server has to be connected to your Microsoft 365 tenant and been granted the required permissions. Microsoft 365 relies on Azure Active Directory as directory service. Each Microsoft 365 tenant corresponds to an Azure AD tenant that stores its user information.

=== Registering of MailStore Server as App in Azure AD ===
Through registration, MailStore Server gets an identity in Azure AD that makes it possible to authenticate to the tenant's services and use their resources.
* Sign in to the [https://portal.azure.com Azure Portal] as a Global Administrator for your Microsoft 365 tenant.
* In the navigation menu (☰), select the option ''Azure Active Directory''.
* On the next page, select ''App registrations'' in the ''Manage'' section of the left navigation menu.
* Select ''New Registration''. The ''Register an application'' page appears.
* In the ''Name'' field, enter a meaningful display name, e.g. ''MailStore Server''. This name will be shown to users on logon later on, for example.
* Leave all other settings on this page to their defaults.
* Click on ''Register''. If the registration has been successful, you are shown the overview page of the newly registered app.
The ''Application (client) ID'' shown on this page identifies MailStore Server in your Azure AD tenant and has to be copied into MailStore Server next, together with the ''Directory (tenant) ID''. Therefore, for the following steps, leave the overview page open in your web browser.

=== Creating Credentials in MailStore Server ===
Credentials for Microsoft 365 consist of the aforementioned IDs and a secret that MailStore Server uses to proof its identity to Azure AD. Microsoft recommends using certificates as secrets to identify apps in Azure AD. When creating credentials, such a certificate is generated automatically by MailStore Server but can also be recreated later on.
{{Directory Services Accessing Configuration|Microsoft 365 (Modern Authentication)|Microsoft 365 sync 01.png}}
* In the ''Connection'' section, click on the button (…) next to the ''Credentials'' drop-down list.
* In the ''Credential Manager'' that appears, click on ''Create…''
* In the ''Azure AD App Credentials'' dialog, enter the following information in the ''Settings'' section:
** '''Name''' A meaningful display name for the credentials, e.g. the name of your Microsoft 365 tenant.
** '''Application (client) ID''' The value of the corresponding field that you can copy from the Azure AD app overview page in your web browser.
** '''Directory (tenant) ID''' The value of the corresponding field that you can copy from the Azure AD app overview page in your web browser.
[[File:Microsoft 365 cred 01.png|center|347px]]
* In the ''Authentication'' section, click on the drop-down button next to the ''Certificate'' text box und select ''Download Certificate''. Save the certificate on your hard drive.
* Confirm your entries by clicking ''OK''.
* The newly created credentials are listed in the ''Credential Manager'' under the name you have entered with the type ''Microsoft 365''. Here you can also edit or delete existing credentials if necessary.
* Leave the ''Credential Manager'' by clicking ''Close''.
* The newly created credentials are selected in the corresponding drop-down list by default.

=== Publishing Credentials in Azure AD ===
For Azure AD to validate the identity of MailStore Server, the created certificate needs to be published in Azure AD.
* Switch to the Azure AD app overview page in your web browser.
* Select ''Certificates & secrets'' in the ''Manage'' section of the left navigation menu.
* Click on ''Upload certificate'' in the ''Certificates'' section. Select the certificate file that you have saved previously and upload it to Azure AD by clicking ''Add''.
* If uploading has been successful, the certificate's thumbprint as well as its start and expiry dates appear in the certificates list. You can compare the thumbprint and expiry date with those listed in the MailStore Credential Manager to check that you've uploaded the correct certificate.

=== Configuring App Authentication in Azure AD ===
For Azure AD to return the result of a user's authentication request to MailStore Server, the endpoint where MailStore Server expects authentication responses, the so-called ''Redirect URI'', has to be conveyed to Azure AD.
* In the Azure Portal in the web browser, select ''Authentication'' in the ''Manage'' section of the left navigation menu.
* Click on the ''Add a platform'' button in the ''Platform configurations'' section of the ''Authentication'' page.
* Select ''Web'' in the ''Web applications'' section of the ''Configure platforms'' menu page.
* In the field ''Redirect URI'', enter a URI in the format (without brackets)
*: <code>https://<fqdn>[:<port>]/oidc/signin</code>
*; with the following components<nowiki>:</nowiki>
*: '''https://''' Specifying the <code>https://</code> protocol is obligatory. To avoid certificate warnings during user logon, the web browsers on the client machines must trust the [[MailStore_Server_Service_Configuration#Certificate|certificate used by MailStore Server]].
*: '''FQDN''' The Fully Qualified Domain Name (FQDN) of your MailStore Server that consists of the machine name and the DNS domain, e.g. <code>mailstore.example.com</code>. This name must be resolvable by all clients from which users shall be able to log on to MailStore Server.
*: '''Port''' The TCP port of the MailStore Web Access (<code>8462</code> by default). This value must be equal to the port configured in the section ''Base Configuration > Network Settings > MailStore Web Access / Outlook Add-in (HTTPS)'' of the [[MailStore_Server_Service_Configuration#Services|MailStore Server Service Configuration]]. The TCP port has to be specified only if it is different from the default port of the HTTPS protocol (<code>443</code>).
*: '''/oidc/signin''' The endpoint where MailStore Server expects the authentication responses of Azure AD. This path has to be specified exactly as stated here at the end of the redirect URI.
* Leave the field ''Logout URL'' blank.
* Enable the ''ID tokens'' option in the ''Implicit grant'' section.
* Click on ''Configure'' to finish the configuration of the app authentication in Azure AD.
<div class="resp-table">
{| class="wikitable" style="font-size: 85%;"
|+ Examples for valid redirect URIs
|-
! style="width:80px;" | Product
! style="width:80px;" | FQDN
! style="width:40px;" | Port
! Resulting Redirect URI
|-
| align="center"| MailStore Server
| align="center"| mailstore.example.com
| align="center"| 8462
| <code><nowiki>https://mailstore.example.com:8462/oidc/signin</nowiki></code> Redirect URI with Fully Qualified Domain Name and MailStore Web Access default port
|-
| align="center"| MailStore Server
| align="center"| mailstore.example.com
| align="center"| 443
| <code><nowiki>https://mailstore.example.com/oidc/signin</nowiki></code> The port can be ommited if the HTTPS default port 443 has been configured for MailStore Web Access or as source port of a port-forwarding on the firewall or router.
|-
| align="center"| MailStore SPE
| align="center"| archive.example.com
| align="center"| 443
| <code><nowiki>https://archive.example.com/<instanceid>/oidc/signin</nowiki></code> The ''instanceid'' of the instance is part of the Redirect URI.
|-
|}
</div>
:: '''Important Notice:''' Please note that the redirect URI is case-sensitive. Also review the requirements on resolving URIs in the [[#Prerequisites, Recommendations and Limitations|Prerequisites, Recommendations and Limitations]] section.

=== Configuring the Redirect URI in MailStore Server ===
For MailStore Server to convey the redirect URI to requesting clients, it must be configured there, too.
* Switch to the ''Directory Services'' page in the MailStore Client.
* Enter the redirect URI in the corresponding field in the ''Authentication'' section. Just copy the value previously configured in Azure AD from the web browser.
[[File:Microsoft 365 sync 02.png|center|450px]]

=== Configuring API Permissions in Azure AD ===
* Switch again to Azure AD in your web browser.
* Select ''API permissions'' in the ''Manage'' section of the left navigation menu.
* Click on the ''Add a permission'' button in the ''Configured permissions'' section.
* On the ''Request API permissions'' menu page, select the API ''Microsoft Graph'' in the ''Commonly used Microsoft APIs'' section.
* Select the option ''Application permissions''.
* Enable the ''Directory > Directory.Read.All'' permission in the ''Select permissions'' section.
* Click on ''Add permissions''.
* The permissions are updated and the ''Directory.Read.All'' permission appears in the API permissions list under ''Microsoft Graph''.
* Click on the ''Add a permission'' button in the ''Configured permissions'' section again.
* On the ''Request API permissions'' menu page, select ''APIs my organization uses''.
* Search for ''Office 365 Exchange Online'' and click on the corresponding entry.
* Select the option ''Application permissions''.
* Enable the ''full_access_as_app'' permission in the ''Select permissions'' section.
* Click on ''Add permissions''.
* The permissions are updated and the ''full_access_as_app'' permission appears in the API permissions list under ''Exchange''.
* Now click on the ''Grant admin consent for <your tenant name>'' button in the ''Configured permissions'' section.
* Acknowledge the following notice with ''Yes''.
* The status of all granted permissions is updated to ''Granted for <your tenant name>''.
The configuration of MailStore Server's connection to Microsoft 365 within Azure AD is now complete. You can sign out of your Azure AD tenant and close the browser window. Switch to the ''Directory Services'' page in the MailStore Client again, all remaining configuration steps must be done there.

=== User Database Synchronization ===
After configuring the connection settings as described above, you can specify filter criteria for the Microsoft 365 synchronization in this section.
*'''Synchronize licensed Microsoft Exchange Online users only''' Only Microsoft 365 user accounts with a Microsoft Exchange Online license assigned to them will be taken into account by the synchronization.
*'''Synchronize enabled users only''' Only Microsoft 365 user accounts that do not have their login to Microsoft 365 blocked will be taken into account by the synchronization.
*'''Sync only these groups''' Choose one or several Microsoft 365 security groups if you only want their members to be created as MailStore Server users. That way it's possible to exclude certain users from being synchronized to MailStore Server.

{{Directory Services Options|Microsoft 365 tenant}}
{{Directory Services Assign Default Privileges|Microsoft 365}}
{{Directory Services Run Synchronization|Microsoft 365 tenant}}
[[File:Office365_sync_02.png|450px|center]]

{{Directory Services Test Authentication}}
[[de:Synchronisieren_von_Benutzerkonten_mit_Microsoft_365_(Modern_Authentication)]]
[[en:Synchronizing_User_Accounts_with_Microsoft_365_(Modern_Authentication)]]

Archiving Emails from Microsoft 365 (Modern Authentication)

2022-11-03T16:15:08Z

Chansen: Chansen moved page Archiving Emails from Microsoft 365 (Modern Authentication) to Move Archiving Emails from Microsoft 365 - Modern Authentication

#REDIRECT [[Move Archiving Emails from Microsoft 365 - Modern Authentication]]

Move Archiving Emails from Microsoft 365 - Modern Authentication

2022-11-03T16:15:08Z

Chansen: Chansen moved page Archiving Emails from Microsoft 365 (Modern Authentication) to Move Archiving Emails from Microsoft 365 - Modern Authentication

File:Python-api-wrapper.zip

2022-11-02T12:32:56Z

Chansen: Chansen uploaded a new version of File:Python-api-wrapper.zip

File:Python-api-wrapper.zip

2022-11-02T12:30:35Z

Chansen: Chansen reverted File:Python-api-wrapper.zip to an old version

File:Python-api-wrapper.zip

2022-11-02T12:29:42Z

Chansen: Chansen reverted File:Python-api-wrapper.zip to an old version

File:Python-api-wrapper.zip

2022-11-02T12:18:09Z

Chansen: Chansen uploaded a new version of File:Python-api-wrapper.zip

File:Python-api-wrapper.zip

2022-10-24T12:50:11Z

Chansen: Chansen uploaded a new version of File:Python-api-wrapper.zip

Privacy policy

2022-07-07T08:45:38Z

Chansen:

Click [https://www.opentext.com/about/privacy here] for privacy policy on our official website.

Moving the Archive

2022-06-21T15:54:58Z

Chansen: /* Moving the Archive to a New Machine */

It is possible to move a single archive store, its components or the complete MailStore Server archive to a new hard-disk, machine or network share at any time. What is required to successfully move an archive is described in the following sections.

== Moving an Entire Single Archive Store ==
To move an entire archive store to a different hard-disk or network share, follow the instructions below. The MailStore master database and all other archive stores remain unchanged.

When moving an archive store to a network share, the information from the article [[Using Network Attached Storage (NAS)]] are also applicable.

* Start the MailStore Client and log in as a MailStore user with administrative privileges.
* Navigate to ''Administrative Tools > Storage > Storage Locations''.
[[File:Tech_storageloc_01.png|center|550px]]
* Follow these steps for the archive store you want to move:
:* Make note of the status and the path on disk. You can find this information in the summary next to the archive store list.
:* Change the status to ''Disabled''.
:* In the file system, move the folder you've jotted down in the first step to the new location.
:* In the context menu or in the details pane, click on ''Edit...''
:* The ''Edit Archive Store Properties'' dialog opens.
:* Change the base directory to the new folder. If a network share is used, enter the UNC path of the share i.e. <code>\\computer\myshare\folder</code>.
:* Click on ''Finish''.
:* Change the status of the archive store back to the one you've noted in the first step.

== Moving Components of an Archive Store ==
In MailStore, archive stores always consist of the following three components:
{{Archive_Stores_Structure}}
These individual components can be moved to different physical storages. For example, you can move the database with folder information and meta data as well as the search index on a fast storage to accelerate folder operations and the MailStore search while leaving the email content files on a slower storage. 
To move parts of an archive store to another hard-disk or network share, follow the instructions below. The MailStore master database and all other archive stores remain unchanged.

When moving an archive store to a network share, the information from the article [[Using Network Attached Storage (NAS)]] are also applicable.

* Start the MailStore Client and log in as a MailStore user with administrative privileges.
* Navigate to ''Administrative Tools > Storage > Storage Locations''.
* Follow these steps for the archive store you want to move parts of:
:* Make note of the status. You can find this information in the summary next to the archive store list.
:* [[File:Tech_storageloc_03.png|right|350px]]Change the status to ''Disabled''.
:* In the context menu or in the details pane, click on ''Edit...''
:* The ''Edit Archive Store Properties'' dialog opens.
:* Enable the option ''Use different directories for database, content and search index''. The folders of the individual archive store components are shown.
:* In the file system, move the folders to their new locations.
:* In the dialog, change the base directories to the new folders. If network shares are used, enter the UNC paths of the shares i.e. <code>\\computer\myshare\folder</code>.
:* Click on ''Finish''.
:* Change the status of the archive store back to the one you've noted in the first step.

== Moving the Archive to a Different Hard-Disk ==
To move a MailStore Server installation, where all archive stores are located underneath the directory of the master database (default: <code>C:\MailArchive</code>), to a different hard-disk, follow the steps below. The MailStore program directory remains unchanged.

* Stop the MailStore Server service through the [[MailStore Server Service Configuration]].
* Move the master database directory (default: <code>C:\MailArchive</code>) and all subdirectories to the new location. The folder structure must remain unchanged.
* Use the MailStore Server Service Configuration to change the directory of the "Master Database" to the new location.
* Start the MailStore Server service again.

'''Notice:''' Please be aware that the throughput of an external hard-disk may have a negative impact on the performance of MailStore Server.

'''Please note:''' Archive stores that are not stored in a relative path to the master database may have to be re-attached or their paths edited after moving the archive. Details about managing archive stores are available in chapter [[Storage Locations]] of the MailStore Server manual.

== Moving the Archive to a New Machine ==
To move a MailStore Server archive, including all users, settings and emails, to a new machine, follow these steps:
{{#ev:youtube|https://youtu.be/3XZgBhFgya0|350|center|''Tech Tip: How to Move MailStore Server''}}
* Stop the MailStore Server service on the current machine through the [[MailStore Server Service Configuration]].
* Move the master database directory (default: <code>C:\MailArchive</code>), all of its subdirectories and all archive stores that exist on the current machine to the new machine. The folder structure must remain unchanged.
* Uninstall MailStore Server on the current machine.
* Transfer your MailStore Server license to the new machine through our [https://my.mailstore.com/TransferLicense license portal].
* [https://my.mailstore.com/downloads Install MailStore Server] on the new machine. You can install the latest version. Please note the [[Update_Notices_for_MailStore_Server|update notes]].
* If the location of the master database directory to use does not match the default path <code>C:\MailArchive</code>, run the MailStore Server Service Configuration, stop the MailStore Server service and change the directory of the "Master Database" to the new location.
* If you have any client-sided scheduled tasks and are using your own SSL certificate, export the SSL certificate and private key (usually packaged in a PKCS#12 file) which is used by MailStore Server from the machines certificate store and import it to the same location on the new machine. Refer to the Windows help for further information about managing SSL certificates.
* In case the new installation is using the same product key than the old installation and the product key is used as recovery key, nothing has to be done in regards to [[MailStore_Server_Service_Configuration#Security_and_Encryption|archive security]]. In case a different product key is used on the new machine or the archive was secured with a [[MailStore_Server_Service_Configuration#Set_Recovery_Key|generated random value]] the archive must be [[MailStore_Server_Service_Configuration#Reinitialize_Archive_Encryption|reinitialized]] before the first start.
* Start the MailStore Server service on the new machine if it's not running.

'''Please note:''' Archive stores that are not stored in a relative path to the master database may have to be re-attached or their paths edited after moving the archive. Details about managing archive stores are available in chapter [[Storage Locations]] of the MailStore Server manual.

== Moving the Archive to a Network Share ==
To move a MailStore Server archive, including all users, settings and emails, to a network share, follow the instructions below. The information from the article [[Using Network Attached Storage (NAS)]] are also applicable. The MailStore program directory remains unchanged.

* Stop the MailStore Server service through the [[MailStore Server Service Configuration]].
* Create a new share on the NAS-system.
* Either grant the MailStore Server machine account or a user read-/write-permissions on that newly created share.
* If you granted the permissions to a user object, configure MailStore Server as described in [[Using Network Attached Storage (NAS)]].
* Move all files from the original archive folder to the network share.
* Use the MailStore Server Service Configuration to set the path to the MailStore Server Master-Database to the UNC path of the share, i.e. <code>\\computer\myshare</code>.
* Start the MailStore Server service again.

'''Please note:''' Archive stores that are not stored in a relative path to the master database may have to be re-attached or their paths edited after moving the archive. Details about managing archive stores are available in chapter [[Storage Locations]] of the MailStore Server manual.

== Moving an Archive Store to a Different Installation ==
To move an archive store to a different installation, follow the instructions below. The product key or the recovery key of the installation where the archive store is coming from is required.

'''Please note:''' The archive store must be on version 7 or higher, so that it can move to a different archive. If that is not the case, the archive store and the associated Master Database have to be loaded once with MailStore Server 7 or higher, because then some necessary database upgrades will be performed.

* Start the MailStore Client and log in as a MailStore user with administrative privileges on the installation where the archive store is still attached to.
* Navigate to ''Administrative Tools > Storage > Storage Locations''.
* [[Storage_Locations#Detaching|Detach]] the archive store you want to move.
* Move the folder or folders of the archive store to the new location.
* Start the MailStore Client and log in as a MailStore user with administrative privileges on the installation where the archive store will be attached to.
* Navigate to ''Administrative Tools > Storage > Storage Locations''.
* [[Storage_Locations#Attaching|Attach]] the moved archive store.

[[de:Umziehen des Archivs]]
[[en:Moving the Archive]]

Google Workspace Integration

2022-05-14T10:31:50Z

Chansen: /* Create OAuth 2.0 Client for User Authentication */

{{DISPLAYTITLE:Synchronizing User Accounts with Google Workspace}}
{{Directory Services Preamble|Google Workspace account|Google Workspace}}

Please note that on December 16th 2019, [https://go.mailstore.com/?lang=en&target=gsuite-lsa-restriction Google announced] to limit access to Google Workspace accounts for less secure apps in the future. This affects any MailStore Server version prior to 13, which therefore will no longer be able to authenticate users against Google Workspace when trying to log into MailStore Server.
 
 
In MailStore Server 13, support for modern authentication methods via OAuth 2.0 & OpenID Connect as per Google's recommendation was introduced. Although MailStore Server 13 still comes with support for IMAP-based authentication, this document only covers the setup using modern authentication methods as required by Google in the future.

== Prerequisites, Recommendations, Limitations ==
* To comply with Google's requirements for ''Authorized redirect URIs'' of OAuth 2.0 clients, MailStore Server must be accessible via an URI that ends with a public top-level domain. This does not necessarily mean that it must indeed be accessible from the Internet. Google uses the list from https://publicsuffix.org for validation.
* For best user experience, the certificate used by MailStore Server should be trusted by all client and the used web browsers. Using a certificate that is signed by an trusted certificate authority or [[Using_Lets_Encrypt_Certificates|using Let's Encrypt certificates]] is highly recommended.
* If users are supposed to login to MailStore Server from outside the organization's network without a VPN, using [[Accessing_the_Archive_with_the_MailStore_Client_software|MailStore Client]], [[Accessing_the_Archive_with_the_Microsoft_Outlook_integration|MailStore Outlook Add-in]] or the [[Accessing_the_Archive_with_MailStore_Web_Access|Web Access]], the URIs mentioned in this article must be resolvable via DNS on the Internet and port-forwardings to the MailStore Server computer must be set up on the firewall or router if necessary.
* When using Google to authenticate users at login, [[Accessing_the_Archive_via_Integrated_IMAP_Server|accessing the archive via IMAP]] is not possible for technical reasons.

== Register Project with Google ==
Regardless of whether own or third-party applications such as MailStore Server are supposed to interact with a Google Workspace account through Google APIs, they must be registered as a project with Google first. This is necessary to ensure that access by external applications is limited to a necessary minimum and that each application uses its own set of credentials to authenticate with Google.

=== Create New Project ===
To register a project for MailStore Server with Google, proceed as follows:

* Go to the [https://console.cloud.google.com Google Cloud Platform Console].
* If prompted, login using a Google account of you Google Workspace organization. Logging in with a user that has admin privileges is highly recommended.
* If no project exists, click ''Create Project'' on the dashboard. Otherwise, open the project list by clicking on the project drop-down in the header bar and click ''New project''.
* Type in a meaningful name into the ''Project name'' field, e.g. <tt>MailStore Server</tt>.
* Verify that ''Organization'' matches the desired organization and adjust the ''Location'' if needed.
* Click on ''Create''.

Once the project has been created, make sure that it is selected in the project drop-down list before proceeding.

==== Add API Libraries ====
* Open the ''Navigation menu'' (☰) and select ''APIs & Services'' > ''Library''.
* In the ''API Library'', search and enable the following APIs and services:
*: <tt>Admin SDK API</tt>
*: <tt>Gmail API</tt>

==== Customize Consent Screen ====
* Open the ''Navigation menu'' (☰) and select ''APIs & Services'' > ''OAuth consent screen''.
* Under ''User Type'' select ''Internal''.
* Click ''Create''.
* Enter a meaningful name into the ''App name'' field, e.g. <tt>MailStore Server</tt>.
* Fill out the other fields according to the policies of your organization.
* Click ''Save and Continue''.
* In the next steps, directly click ''Save and Continue'' again as MailStore Server does not need users to authorize any scopes.

=== Create Service Account ===
A service account is required for MailStore Server to authenticate with Google and request authorization to use certain Google APIs for synchronizing users and accessing mailboxes. Follow these steps to create such a service account.

* Open the ''Navigation menu'' (☰) and select ''APIs & Services'' > ''Credentials''.
* Click ''+ Create Credentials'' and select ''Service account'' from the drop-down list.
* On the ''Create service account'' page, enter a name for the service account, e.g. <tt>MailStore Server Service</tt>.
* You can leave the the service account id at default settings or customize it.
* Enter a description such as: <tt>Service account for MailStore Server to synchronize users and access mailboxes</tt>.
* Click ''Create and Continue''.
* The service account does not require permissions on project level, therefore do not select a role. Also, users do not need access to the service account, so no changes are needed in the ''Grant users access to this service account'' step.
* Click ''Done''.
* In the list of service accounts that is now displayed, click on the newly created service account to open its properties.
* Under ''Keys'' click on ''Add Key'' and select ''Create new key''.
* Select ''JSON'' as key type and click ''Create''.
* The JSON file will be downloaded automatically. Save the JSON file in a secure location as it allows access to cloud resources of your organization.
* Click ''Close''.
* Back under ''Details'', click ''Show Advanced Settings''.
* In the ''Domain-wide Delegation'' section, copy the ''Client ID'' to the clipboard.
* Open the [https://admin.google.com/ Google Workspace Admin Console] by clicking on the button and log in with your Google Workspace domain admin credentials.
* Open the ''Navigation menu'' (☰) and select ''Security'' > ''Access and data control'' > ''API controls''.
* Under ''Domain wide delegation'', click ''Manage domain wide delegation''.
* On the ''Domain-wide delegation'' page, click ''Add new''.
* Copy the ''Client ID'' of the OAuth 2.0 Client that is linked with the service account from the clipboard.
* Under ''OAuth Scope'', add the following scopes:
*: <tt><nowiki>https://mail.google.com/, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly</nowiki></tt>
* Click ''Authorize''.

=== Create OAuth 2.0 Client for User Authentication ===
To allow users to log in to MailStore Server by authenticating with Google using the OpenID Connect mechanism, another OAuth 2.0 client must be created as described below.

* Go to the [https://console.cloud.google.com Google Cloud Platform Console].
* Open the ''Navigation menu'' (☰) and select ''APIs & Services'' > ''Credentials''.
* Click ''+ Create Credentials'' and select ''OAuth client ID'' from the drop-down list.
* Select ''Web application'' as ''Application type''.
* Enter a ''Name'', e.g. <tt>MailStore Server OpenID Connect</tt>.
* Click ''+ Add URI'' under ''Authorized redirect URIs''.
* Enter the URI that is reachable by clients in the ''URIs'' field using the the following scheme:
*:<tt>https://<fqdn>[:<port>]/oidc/signin</tt>
*; with the following components:
*: '''https://''' Specifying the protocol ''https://'' is mandatory. To prevent certificate warnings later at login, the [[MailStore_Server_Service_Configuration#Certificate|certificate used by MailStore Server]] must be trusted by all client and the used web browsers.
*: '''FQDN''' The fully qualified domain name of the MailStore Server computer, e.g. <tt>mailstore.example.com</tt>. This must be resolvable from all clients, from where users are supposed to log in to MailStore Server.
*: '''Port''' The TCP port of MailStore Web Access (default: <tt>8462</tt>). This must match the port configured in the [[MailStore Server Service Configuration#Services|MailStore Server Service Configuration]] at ''Network Settings'' > ''Services'' > ''MailStore Web Access / Outlook Add-in (HTTPS)''. The TCP port is only required if it is different from the default port of the HTTPS protocol (443).
*: '''/oidc/signin''' The path at which MailStore Server expects to receive the authentication response from Google via the web browser.
* Click ''Create'' to finish.
* Copy the client ID and client secret from the ''Your Client ID'' and ''Your Client Secret'' fields to a safe place (e.g. password safe or similar) and click ''OK''.
<div class="resp-table">
{| class="wikitable" style="font-size: 85%;"
|+ Examples of valid redirect URIs
|-
! style="width:80px;" | Product
! style="width:80px;" | FQDN
! style="width:40px;" | Port
! Resulting Redirect URI
|-
| align="center"| MailStore Server
| align="center"| mailstore.example.com
| align="center"| 8462
| <code><nowiki>https://mailstore.example.com:8462/oidc/signin</nowiki></code> Redirect URI with fully qualified domain name and MailStore Web Access default port.
|-
| align="center"| MailStore Server
| align="center"| mailstore.example.com
| align="center"| 443
| <code><nowiki>https://mailstore.example.com/oidc/signin</nowiki></code> If the HTTPS default port 443 is used for MailStore Web Access or as source of a port forwarding rule on a firewall, specifying the port as part of the redirect URI can be omitted.
|-
| align="center"| MailStore SPE
| align="center"| archive.example.com
| align="center"| 443
| <code><nowiki>https://archive.example.com/<instanceid>/oidc/signin</nowiki></code> The ''instanceid'' of the instance is part of the Redirect URI.
|-
|}
</div>

== Configure MailStore Server ==
After the project has been successfully set up on the Google side, MailStore Server can now be configured to synchronize and authenticate users with Google Workspace.

{{Directory Services Accessing Configuration|Google Workspace|gapps_sync_01.png}}

=== Connection ===
For synchronization, MailStore Server requires information on how to connect to the Google Workspace.

* '''Key ID''' To import the private key, select the JSON file hat has been generated by Google for the service account in the [[#Create_Service_Account|Create Service Account]] step.
* '''Service Account''' The service account is determined automatically from the JSON file.
* '''User Name''' The email address of a Google Workspace Administrator (e.g. admin@example.com).

=== User Database Synchronization ===
After configuring the connection settings as described above, you can specify filter criteria for the Google Workspace synchronization in this section.

* '''Sync only these groups''' Choose one or several Google Workspace groups if you only want their members to be created as MailStore Server users. That way it's possible to exclude certain users from being synchronized to MailStore Server.

=== Authentication ===
The authentication settings define how MailStore Server should authenticate users at login, that have been synchronized from Google Workspace.

* '''Method''' Ensure that ''OpenID Connect'' is selected. As mentioned in the introduction, the ''IMAP'' option is only available for backward compatibility.
* '''Client ID''' Enter the client ID from the [[#Create_OAuth_2.0_Client_for_User_Authentication|Create OAuth_2.0 Client…]] step.
* '''Client Secret''' Enter the client secret from the [[#Create_OAuth_2.0_Client_for_User_Authentication|Create OAuth_2.0 Client…]] step.
* '''Redirect URI''' Enter the same redirect URI as defined in the [[#Create_OAuth_2.0_Client_for_User_Authentication|Create OAuth 2.0 Client…]] step .

{{Directory Services Options|Google Workspace Account}}
{{Directory Services Assign Default Privileges|Google Workspace Account}}
{{Directory Services Run Synchronization|Google Workspace Account}}
[[File:ApplicationIntegration_sync_02.png|450px|center]]

{{Directory Services Test Authentication}}
[[de:Google Workspace-Integration]]
[[en:Google Workspace Integration]]

MailStore Help

2022-05-04T11:01:24Z

Chansen: /* Getting Started */

__NOTOC__
{{DISPLAYTITLE:{{Product Name}} Help}}

{| width="100%" cellspacing="3" cellpadding="4"
|-
| valign="top" width="100%" colspan="2" |
== Email Archiving with {{Product Name}} ==
In addition to the latest version of the {{Product Name}} manual, you can find important articles and instructions here, which will help you to set up email archiving. Please do not hesitate to contact our support team if you have any further questions.
|-
| valign="top" width="50%" |
== Getting Started ==
* [[Quick Start Guide]]
* [[System Requirements]]
* [[Choosing the Right Archiving Strategy]]

== What's New ==
* [https://go.mailstore.com?product=MailStore%20Server&target=changelog&lang=en Changelog]
* [[Update Notices for MailStore Server|Update Notices]]
| valign="top" width="50%"|
== Manual ==
* [[Installation]]
* [[Archiving Email]]
* [[Accessing the Archive]]
* [[Exporting Email]]
* [[Administration]]
* [[MailStore Server Service Configuration]]
* [https://help.mailstore.com/en/gateway MailStore Gateway Help]
|-
| valign="top" width="50%" |
== Implementation Guides ==
{{:Implementation}}
| valign="top" width="50% |
== Articles ==
==== Deployment ====
* [[MailStore Client Deployment|MailStore Client]]
* [[MailStore Outlook Add-in Deployment|MailStore Outlook Add-in]]
==== Operation ====
* [[Backup and Restore]]
* [[Maintenance and Repair]]
* [[Monitoring]]
==== Security ====
* [[Security Advisories]]
* [[Enhancing SSL Security]]
* [[Notes on Antivirus Software]]
* [[Using Your Own SSL Certificate]]
* [[Using_Lets_Encrypt_Certificates|Using Let's Encrypt Certificates]]
==== Automation & Scripting ====
* [[Scripting|Automation with scripts]]
* [[Bulk Import of Email Files]]
* [[Implementing an Application Integration Server]]
==== How-to ====
* [[Changing Archiving from Microsoft Exchange Server to Microsoft 365]]
* [[Moving the Archive]]
* [[Using Network Attached Storage (NAS)]]
* [[Verifying a Signed Export]]
|-
| valign="top" width="50%" |

== Troubleshooting ==
In the [https://cs.mailstore.com/index.php?/Knowledgebase/List/Index/8/en knowledgebase] of our [https://cs.mailstore.com/ Customer Service Centers] you can find many answers to the most often asked questions or reoccurring error messages. Detailed troubleshooting instructions are also available there. 
== Administration API ==
The Administration API extends the management capabilities of {{Product Name}} by providing command-line as well as HTTP based access to all management functions. This allows to fully automate the administration of {{Product Name}} via scripts or even integration into centralized management solutions. For an even faster development, example API libraries for different scripting and programming languages are provided.
* [[MailStore Server Management Shell]]
* [[Administration API - Using the API|Using the API]]
* [[Administration API - Function Reference|Function Reference]]
==== Example Implementations of API Libraries ====
* [[PowerShell API Wrapper Tutorial|PowerShell]]
* [[Python API Wrapper Tutorial|Python]]
| valign="top" width="50%" |
== Tech Tip Videos ==
In our [https://youtube.com/playlist?list=PLGTSLnfosYvSkdccnpMDv5fjqYhJ_asQp Tech Tip Videos on Youtube] we provide valuable information and useful insights from our technical support team. Our technical support engineers will showcase specific features of MailStore Server and feature common use cases of our clients.
== Downloads ==
<div class="plainlinks">
* [https://www.mailstore.com/en/products/mailstore-server/downloads/ MailStore Setup Files]
* [http://help.mailstore.com/manual/server13-manual-en.pdf MailStore Server 13 Manual]
==== Manuals of Older Versions ====
* [http://help.mailstore.com/manual/server12-manual-en.pdf MailStore Server 12]
* [http://help.mailstore.com/manual/server11-manual-en.pdf MailStore Server 11]
* [http://help.mailstore.com/manual/server10-manual-en.pdf MailStore Server 10]
* [http://help.mailstore.com/manual/server9-manual-en.pdf MailStore Server 9]
* [http://help.mailstore.com/manual/server8-manual-en.pdf MailStore Server 8]
* [http://help.mailstore.com/manual/server7-manual-en.pdf MailStore Server 7]
* [http://help.mailstore.com/manual/server6-manual-en.pdf MailStore Server 6]
* [http://help.mailstore.com/manual/server5-manual-en.pdf MailStore Server 5]
==== Active Directory Group Policy Templates ====
* [[Media:MailStore_ADMX.zip|ADMX-Template]]
</div>
|}

[[de:MailStore Hilfe]]
[[en:MailStore Help]]

MediaWiki:Sidebar-banner3

2022-05-04T09:29:38Z

Chansen:

Read in our <a href="https://www.mailstore.com/en/blog/mailstore-v22-1-usability-security-compliance/" target_blank">blog</a> about the most important changes and updates in MailStore 22.1. The complete list of technical changes can be read in the <a href="https://www.mailstore.com/en/products/mailstore-server/changelog/" target_blank>changelog</a>.

MediaWiki:Sidebar-banner3

2022-05-04T09:11:11Z

Chansen:

Read in our <a href="https://www.mailstore.com/en/blog/mailstore-v22-1-usability-security-compliance/" target_blank">blog</a> about the most important changes and updates in MailStore Server 22.1. The complete list of technical changes can be read in the <a href="https://www.mailstore.com/en/products/mailstore-server/changelog/" target_blank>changelog</a>.

MediaWiki:Sidebar-banner3

2022-05-04T08:32:40Z

Chansen: Created page with "Read in our <a href="https://www.mailstore.com/en/blog/mailstore-v22-1-usability-security-compliance/" target_blank">blog</a> about the most important changes and updates in M..."

Read in our <a href="https://www.mailstore.com/en/blog/mailstore-v22-1-usability-security-compliance/" target_blank">blog</a> about the most important changes and updates in MailStore Server 22.1. The complete list of technical changes can be read in the <a href="https://www.mailstore.com/en/blog/mailstore-v22-1-usability-security-compliance/" target_blank>changelog</a>.