https://help.mailstore.com/en/spe/api.php?action=feedcontributions&user=Admin&feedformat=atomMailStore SPE Help - User contributions [en]2024-03-28T16:55:12ZUser contributionsMediaWiki 1.35.10https://help.mailstore.com/en/spe/index.php?title=MediaWiki:Sidebar&diff=1893MediaWiki:Sidebar2021-02-11T22:59:17Z<p>Admin: </p>
<hr />
<div>* navigation<br />
** mainpage|mainpage-description<br />
** https://help.mailstore.com/en/server |MailStore Server Help<br />
** https://cs.mailstore.com |Customer Service Center<br />
* TOOLBOX<br />
* BANNER</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Instance_Management&diff=1440Instance Management2016-11-29T16:42:39Z<p>Admin: </p>
<hr />
<div>For each instance further individual administrative functions exist. These functions are accessible through the instance details, which appear in pane below the instance list (''General'' > ''Instances'') of the Management Console when clicking on a started instance in the list.<br />
<br />
All these functions are group by tabs, for which further details are provided below.<br />
<br />
== Overview ==<br />
On the ''Overview'' tab of the instance details a summary of the configuration is shown.<br />
<br />
[[File:Ms_spe_instance_overview.png|center]]<br />
<br />
== Archive Stores ==<br />
The ''Archive Stores'' tab allows the administration of the instance storage as well as the search indexes. New archive stores are automatically created in the base directory of the instance every 5.000.000 messages.<br />
<br />
=== Creating Archive Stores ===<br />
Although MailStore Service Provider Edition creates new archive stores automatically, this can also be done manually as described in the following:<br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click on ''General'' > ''Instances''.<br />
* Open the instance details by clicking on a started instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Click ''Create Store''.<br />
* Fill out the ''Create Archive Store'' form:<br />
*: [[File:Ms_spe_create_archivestore_01.png|center]]<br />
:* '''Name:''' Meaningful name for the archive store.<br />
:* '''Archive new messages here:''' If checked, new message will be archived in the newly created archive store (default: checked). <br />
:* '''Use different directories for database, content and search index:''' If checked, a non-default directory structure can be used. E.g. the database and index directory may reside on a fast storage, while the content resides in on a slower storage.<br />
:* '''Directory:''' Directory in which the new archive store will be created. A proposal is created from the ''Name'' of the archive store and the base directory of the instance. Use the swung dash to point to a directory relative to the base directory of the instance, e.g. <tt>~\Messages-2013-10</tt><br />
* Click ''OK'' to create the new archive store.<br />
<br />
=== Attach Existing Archive Store ===<br />
Archive stores from MailStore Service Provider Edition instances or from on-premises MailStore Servers can be attached to an instance as described below: <br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by clicking on a started instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Click ''Attach Store''.<br />
* Fill out the ''Attach Archive Store'' form:<br />
*: [[File:Ms_spe_attach_archivestore_01.png|center]]<br />
:* '''Name:''' Meaningful name for the archive store<br />
:* '''Archive new messages here:''' If checked, new message will be archived in the newly created archive store. (default: unchecked)<br />
:* '''Use different directories for database, content and search index:''' If checked, a non-default directory structure can be used. E.g. archive stores created before MailStore SPE/Server 10 do have the search index files located in the same directory as the database.<br />
:* '''Base Directory:''' Directory of the archive store to attach. This directory must contain the file "MailStoreFileGroup.fdb". Use the tilde to point to a directory relative to the base directory of the instance, e.g. <tt>~/2016-12</tt>.<br />
* Click ''OK'' to attach the archive store.<br />
<br />
In case the archive store was migrated from MailStore Server 10 or newer to MailStore SPE, additional steps are required.<br />
<br />
==== The archive store is protected with a recovery key ====<br />
* The archive store cannot be loaded successfully and the note ''Unable to unlock archive store (Identifier: <identifier>)'' appears.<br />
* To finalize the migration of this archive store you need to know the recovery key identified by <identifier>, the instanceID of the instance where the archive store is attached to and the ID of the attached archive store.<br />
* Navigate to ''Navigation'' > ''DEVELOPER'' > ''Management API''. Select ''UnlockStore'' from the drop down menu and enter the ''instanceID'' of the instance, the ''ID'' of the archive store and the recovery key. The recovery key must be entered in lowercase letters.<br />
* Click ''Invoke'', ''true'' should appear below the text fields.<br />
* Verify that the archive store was attached successfully.<br />
<br />
==== The archive store is protected with a product key ====<br />
* The archive store cannot be loaded successfully and the note ''Unable to open the archive store <name>. Can't decrypt encryption key.'' appears.<br />
* To finalize the migration of this archive store you need to know the product key of the installation where the archive store was attached to last, the instanceID of the instance where the archive store is attached to and the ID of the attached archive store.<br />
* Navigate to ''Navigation'' > ''DEVELOPER'' > ''Management API''. Select ''UnlockStore'' from the drop down menu and enter the ''instanceID'' of the instance, the ''ID'' of the archive store and the product key. The product key must be entered in uppercase letters.<br />
* Click ''Invoke'', ''true'' should appear.<br />
* Verify that the archive store was attached successfully.<br />
<br />
More information about archive security can be found in the [https://help.mailstore.com/en/server/MailStore_Server_Service_Configuration MailStore Server Service Configuration article].<br />
<br />
=== Maintain FS Databases ===<br />
For storing meta data of the archive store's content embedded Firebird databases exist in every archive store. Under certain circumstances (e.g. after a disaster recovery of the server or storage) it might become necessary to perform a maintenance task on those databases. This can easily be done for all archive stores of a particular instance be following the instructions below:<br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by clicking on a started instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Click ''Maintain FS Databases'' to start the maintenance.<br />
* A progress windows will appear.<br />
* Wait until the process is completed successfully and click ''OK''. Otherwise click ''Cancel'' to interrupt maintenance process at any time.<br />
<br />
=== Auto-Create Stores ===<br />
MailStore Service Provider Edition automatically creates new archive stores every 5.000.000 messages. This setting can be adjusted to your need: <br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by clicking on a started instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Click ''Auto-create''.<br />
* Adjust the settings in the ''Auto-Create Archive Stores'' dialog.<br />
*: [[File: Ms_spe_autocreate_stores_01.png|center]]<br />
*: '''Important notice:''' Non-optimal settings can have a negative impact on the overall performance of the instance.<br />
* Click ''OK'' to save the settings.<br />
<br />
=== Store Commands ===<br />
Advanced store commands are accessible by following these steps:<br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by clicking on a started instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Select an archive store and click on ''Store Commands'' or right-click on an archive store to open a context menu.<br />
<br />
A summary of the available store commands can be found in the tables below:<br />
<br />
==== Requested State ====<br />
<br />
{| class="wikitable"<br />
! width="150px" | State<br />
! Description <br />
|-<br />
| Disabled<br />
| Disabled archive stores are not in use but the instance still knows about their existence. The content is not available to users or administrators while the archive store is disabled. This state is useful when moving archive stores to a new directory.<br />
|-<br />
| Write Protected<br />
| The content of write protected archive stores is available to users, but cannot be modified (e.g. delete or move messages, rename or move folders) <br />
|-<br />
| Normal<br />
| The content of archives store is available to users and can be modified if the user has the appropriate permission.<br />
|-<br />
| Current<br />
| Same as ''Normal'' but new messages will be archived in the archive store that is set to ''Current''. <br />
|}<br />
<br />
==== Commands ====<br />
<br />
{| class="wikitable"<br />
! width="150px" | Command<br />
! Description<br />
|-<br />
| Detach<br />
| Detaches the selected archive store. The archive store can be re-attached by using the ''Attach'' function. Please note that the archive store's name and ID will not be retained when detaching and re-attaching. Therefore, when moving an archive store to a new location, disabling the the archive store and using ''Set Path'' afterwards is preferred over re-attaching. <br />
|-<br />
| Rename<br />
| Specify a new name for the archive store.<br />
|-<br />
| Set Path<br />
| Change the path of the archive store. The archive store must be disabled before changing the path. Please note that the file system directory must be moved manually to the new location before re-enabling the archive store.<br />
|- <br />
| Compact<br />
| Optimizes the data structures.<br />
|- <br />
| Upgrade <br />
| If an archive store from a MailStore Server 5 or older was attached to an instance, it is highly recommended to upgrade the archive store to the latest format by using this function. Upgrade process can be interrupted and continued at any time.<br />
|- <br />
| Verify<br />
| Verification of the data integrity between folder information and meta data as well as email headers and content.<br />
|}<br />
<br />
=== Search Indexes ===<br />
Additionally to container files storing the actual email content and the embedded Firebird databases used for storing meta information, a full-text index file is created for each archive that has emails stored in an archive store. By default the full-text index only included email bodies, but virtually any file type is supported (see ''Configure''). <br />
<br />
To access these functions, follow the instructions below:<br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by clicking on a started instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Click ''Search Indexes''.<br />
<br />
The below functions are available in the search index menu to configure and maintain the full-text indexes of an instance. <br />
<br />
==== Rebuild Broken Indexes ====<br />
Starts a rebuild of all search indexes across all archive stores that are marked a broken.<br />
<br />
==== Rebuild All Indexes ====<br />
Starts a rebuild of all search indexes in all archives stores.<br />
This is usually only required after making changes to the list of attachment extensions to be included in the full-text index.<br />
<br />
==== Configure ====<br />
Specify a list of file extensions for attachments to be included in the full-text index. MailStore Service Provider Edition can index all file types for which a so-called IFilter driver is installed on the instance host on which the MailStore Server instance is running. The list of file extensions has to be separated by space.<br />
<br />
[[File: Ms_spe_file_extensions.png|center]]<br />
<br />
Under the name [http://www.microsoft.com/en-us/download/details.aspx?id=17062|Microsoft Office 2010 Filter Packs] Microsoft offers a package that, additionally to all legacy as well as recent Microsoft Office Formats, supports the Open Document Format (OpenOffice/LibreOffice). For indexing PDF files the Adobe Reader or [http://www.adobe.com/support/downloads/detail.jsp?ftpID=5542 Adobe PDF iFilter] must be installed on the MailStore Server machine. Further background information about the IFilter system itself as well as links to additional IFilter drivers can be found in the corresponding Wikipedia article [[wikipedia:IFilter|IFilter]]. <br />
<br />
For reasons of stability and performance, MailStore Server processes the following file types directly, regardless of the IFilter drivers that are installed:<br />
<br />
* Text files (TXT)<br />
* HTML files (HTM and HTML)<br />
<br />
== Archive Access ==<br />
The ''Archive Access'' tab provides access to the service provider archive access as well as download links for MailStore Client and MailStore Outlook Add-in.<br />
<br />
'''Please note:''' Details about the logon process for end customers can be found in the article [[End Customer Access]].<br />
<br />
=== Enable or Disable Service Provider Archive Access ===<br />
Service provider archive access is only necessary if the administration of the instance is not done by the end customers or if the end customer requests support from the service provider. To enable or disable service provider archive access follow these instructions:<br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by clicking on a started instance in the list.<br />
* Click on the ''Archive Access'' tab.<br />
* Click either ''Enable'' or ''Disable''<br />
* When enabling click ''OK'' to confirm that the service provider archive access really should be enabled.<br />
*: '''Please notice:''' Enabling the service provider archive access is logged in the audit log of the instance.<br />
<br />
=== Using Service Provider Archive Access ===<br />
Before the service provider archive access can be used, this access method must be enabled (see previous section) and the MailStore Client must be installed on the computer from where you want to connect. <br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by clicking on a started instance in the list.<br />
* Click on the ''Archive Access'' tab.<br />
* Click ''Open MailStore Client'' <br />
* Depending on your web browser's settings further security related questions may appear. <br />
* Afterwards MailStore Client will automatically log on to the instance using the special ''$archiveadmin'' system account and a one-time password.<br />
<br />
=== Inside the Instance ===<br />
No matter whether logging on to an instance as the end customer's administrator or as service provider via service provider archive access, the available functions of the MailStore Client are nearly the same. Only modification of the archive content (e.g. creating folders, deleting messages,..) is prohibited for the ''$archiveadmin'' user. <br />
<br />
As each instance of the MailStore Service Provider Edition has the same capabilities in terms of managing users, archiving and exporting email, etc. the instructions from the [http://en.help.mailstore.com MailStore Server Help] also apply to instances. Therefore no further documentation is provided here.<br />
<br />
== Live Statistics ==<br />
The ''Live Statistics'' tab shows real time graphics about the instance activity such as I/O, memory and CPU usage as well as number of Remote Procedure Calls (RPC) and the number of emails verified and archived by the instance's archiving mechanism.</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Working_with_SSL_Certificates&diff=1323Working with SSL Certificates2015-03-26T12:27:21Z<p>Admin: </p>
<hr />
<div>== Generating a CSR and importing the certificate with certreq ==<br />
__NOTOC__<br />
* Log on on the host which runs the ''Client Access Server''.<br />
* Prepare a text file ''request.inf'' with the following content<br />
<br />
;----------------- request.inf -----------------<br />
[Version]<br />
Signature="$Windows NT$"<br />
<br />
[NewRequest]<br />
; replace Subject attributes in the line below with real values<br />
Subject = "CN=hostname, OU=Department, O=Organisation, L=Locality, S=State, C=Country"<br />
KeySpec = 1<br />
KeyLength = 2048<br />
Exportable = TRUE<br />
FriendlyName = hostname<br />
MachineKeySet = TRUE<br />
SMIME = False<br />
PrivateKeyArchive = FALSE<br />
UserProtected = FALSE<br />
UseExistingKeySet = FALSE<br />
ProviderName = "Microsoft RSA SChannel Cryptographic Provider"<br />
ProviderType = 12<br />
RequestType = PKCS10<br />
KeyUsage = 0xa0<br />
<br />
[EnhancedKeyUsageExtension]<br />
OID = 1.3.6.1.5.5.7.3.1 ; this is for Server Authentication<br />
<br />
[Extensions]<br />
2.5.29.17 = "{text}"<br />
_continue_ = "dns=hostname.local&"<br />
_continue_ = "dns=mailstore&"<br />
;-----------------------------------------------<br />
<br />
* Adjust the ''Subject'', ''FriendlyName'' and ''Extensions'' fields according to you infrastructure. Remove the entire ''[Extensions]'' section, if you do not need SANs. Save the file.<br />
<br />
<p class="msnote">'''Hint:''' When there are any SANs defined, the CN in the ''Subject'' field will be ignored by clients, therefore you have to add all possible hostnames to the SAN extensions.</p><br />
<br />
* Open an elevated command prompt and navigate into the directory where the ''request.inf'' is stored. <br />
<br />
''' Creating the CSR '''<br />
certreq -new request.inf request.csr<br />
<br />
''' Validating the CSR '''<br />
certutil -dump request.csr<br />
or<br />
openssl.exe req -in request.csr -text -noout<br />
<br />
* Submit the CSR to your CA. You will get a signed certificate in return.<br />
<br />
''' Importing the certificate '''<br />
certreq -accept certificate.cer<br />
<br />
* Verify with ''certlm.msc'' or ''mmc'' that the certificate is imported properly in the host's ''Personal'' store and that a matching private key can be found.<br />
<br />
* [[Replace_Self-signed_SSL_Certificates|Replace]] the self-signed certificates in the ''Client Access Server''.<br />
<br />
== Creating a self signed certificate == <br />
<br />
The ''makecert.exe'' utility is included in the SPE's installation directory. It can be used to create self-signed certificate.<br />
<br />
makecert.exe -r -pe -n "CN=hostname" -b 01/01/2000 -e 01/01/2036 -eku 1.3.6.1.5.5.7.3.1 -ss my -sr localMachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 -a sha1 -len 2048<br />
<br />
Replace ''hostname'' with your hostname. The certificate will be stored in the host's personal certificate store and can be used in the ''Client Access Server'' configuration.<br />
<br />
== Converting a PEM file into a PFX container with OpenSSL == <br />
<br />
When the CSR was created with OpenSSL, the private key is not stored in the hosts private key archive automatically. You have to merge private key, certificate and the certificate chain into one PFX container, and import this container into the host's personal certificate store.<br />
<br />
''' Merging the files '''<br />
openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt<br />
<br />
''' Importing the certificate '''<br />
certutil -importpfx certificate.pfx<br />
<br />
== Weblinks ==<br />
<br />
[https://technet.microsoft.com/de-de/library/ff625722.aspx Microsoft Technet: How to Request a Certificate With a Custom Subject Alternative Name]<br />
<br />
[https://technet.microsoft.com/en-us/library/dn296456.aspx Microsoft Technet: Certreq]<br />
<br />
[https://technet.microsoft.com/en-us/library/cc732443.aspx Microsoft Technet: Certutil]<br />
<br />
[https://msdn.microsoft.com/en-us/library/bfsktky3.aspx Microsoft MSDN: makecert]<br />
<br />
[https://www.sslshopper.com/csr-decoder.html SSL Shopper CSR Decoder]<br />
<br />
[https://ssltools.websecurity.symantec.com/checker/views/csrCheck.jsp Symantec CSR Decoder]<br />
<br />
[https://www.openssl.org/ OpenSSL]</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Working_with_SSL_Certificates&diff=1322Working with SSL Certificates2015-03-26T12:24:25Z<p>Admin: /* Generating a CSR and importing the certificate with certreq */</p>
<hr />
<div>== Generating a CSR and importing the certificate with certreq ==<br />
__NOTOC__<br />
* Log on on the host which runs the ''Client Access Server''.<br />
* Prepare a text file ''request.inf'' with the following content<br />
<br />
;----------------- request.inf -----------------<br />
[Version]<br />
Signature="$Windows NT$"<br />
<br />
[NewRequest]<br />
; replace Subject attributes in the line below with real values<br />
Subject = "CN=hostname, OU=Department, O=Organisation, L=Locality, S=State, C=Country"<br />
KeySpec = 1<br />
KeyLength = 2048<br />
Exportable = TRUE<br />
FriendlyName = hostname<br />
MachineKeySet = TRUE<br />
SMIME = False<br />
PrivateKeyArchive = FALSE<br />
UserProtected = FALSE<br />
UseExistingKeySet = FALSE<br />
ProviderName = "Microsoft RSA SChannel Cryptographic Provider"<br />
ProviderType = 12<br />
RequestType = PKCS10<br />
KeyUsage = 0xa0<br />
<br />
[EnhancedKeyUsageExtension]<br />
OID = 1.3.6.1.5.5.7.3.1 ; this is for Server Authentication<br />
<br />
[Extensions]<br />
2.5.29.17 = "{text}"<br />
_continue_ = "dns=hostname.local&"<br />
_continue_ = "dns=mailstore&"<br />
;-----------------------------------------------<br />
<br />
* Adjust the ''Subject'', ''FriendlyName'' and ''Extensions'' fields according to you infrastructure. Remove the entire ''[Extensions]'' section, if you do not need SANs. Save the file.<br />
<br />
<p class="msnote">'''Hint:''' When there are any SANs defined, the CN in the ''Subject'' field will be ignored by clients, therefore you have to add all possible hostnames to the SAN extensions.</p><br />
<br />
* Open an elevated command prompt and navigate into the directory where the ''request.inf'' is stored. <br />
<br />
''' Creating the CSR '''<br />
certreq -new request.inf request.csr<br />
<br />
''' Validating the CSR '''<br />
certutil -dump request.csr<br />
or<br />
openssl.exe req -in request.csr -text -noout<br />
<br />
* Submit the CSR to your CA. You will get a signed certificate in return.<br />
<br />
''' Importing the certificate '''<br />
certreq -accept certificate.cer<br />
<br />
* Verify with ''certlm.msc'' or ''mmc'' that the certificate is imported properly in the hosts ''Personal'' store and that a matching private key can be found.<br />
<br />
* [[Replace_Self-signed_SSL_Certificates|Replace]] the self-signed certificates in the ''Client Access Server''.<br />
<br />
== Creating a self signed certificate == <br />
<br />
The ''makecert.exe'' utility is included in the SPE's installation directory. It can be used to create self-signed certificate.<br />
<br />
makecert.exe -r -pe -n "CN=hostname" -b 01/01/2000 -e 01/01/2036 -eku 1.3.6.1.5.5.7.3.1 -ss my -sr localMachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 -a sha1 -len 2048<br />
<br />
Replace ''hostname'' with your hostname. The certificate will be stored in the host's personal certificate store and can be used in the ''Client Access Server'' configuration.<br />
<br />
== Converting a PEM file into a PFX container with OpenSSL == <br />
<br />
When the CSR was created with OpenSSL, the private key is not stored in the hosts private key archive automatically. You have to merge private key, certificate and the certificate chain into one PFX container, and import this container into the host's personal certificate store.<br />
<br />
''' Merging the files '''<br />
openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt<br />
<br />
''' Importing the certificate '''<br />
certutil -importpfx certificate.pfx<br />
<br />
== Weblinks ==<br />
<br />
[https://technet.microsoft.com/de-de/library/ff625722.aspx Microsoft Technet: How to Request a Certificate With a Custom Subject Alternative Name]<br />
<br />
[https://technet.microsoft.com/en-us/library/dn296456.aspx Microsoft Technet: Certreq]<br />
<br />
[https://technet.microsoft.com/en-us/library/cc732443.aspx Microsoft Technet: Certutil]<br />
<br />
[https://msdn.microsoft.com/en-us/library/bfsktky3.aspx Microsoft MSDN: makecert]<br />
<br />
[https://www.sslshopper.com/csr-decoder.html SSL Shopper CSR Decoder]<br />
<br />
[https://ssltools.websecurity.symantec.com/checker/views/csrCheck.jsp Symantec CSR Decoder]<br />
<br />
[https://www.openssl.org/ OpenSSL]</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=PowerShell_API_Wrapper_Tutorial&diff=1289PowerShell API Wrapper Tutorial2015-03-20T12:02:29Z<p>Admin: /* Installation of Necessary Components */</p>
<hr />
<div>__NOTOC__<br />
<br />
<div class=msnote>'''Important notice:''' The PowerShell API wrapper for the MailStore Server Administration API provided on this website is to be regarded as an example implementation of an API client. This wrapper should help system administrators and developers to quickly understand how MailStore Server Administration API calls work and how to use them in their own scripts.<br/><br />
Please understand that beyond this documentation no further support for the Powershell API wrapper is provided. Unless stated otherwise, the PowerShell API wrapper as well as all related example scripts are released under the terms and conditions of the [[wikipedia:MIT_License|MIT License]].</div><br />
<br />
<br />
This tutorial aims to explain the usage of the [[Management_API_-_Using_the_API|MailStore Service Provider Edition Management API]] through simple Windows PowerShell example scripts. Basic knowledge of MailStore Server, Windows and PowerShell is a necessary precondition. 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.<br />
<br />
== Installation of Necessary Components ==<br />
The examples demonstrated here use the MailStore PowerShell API Wrapper and are compatible with Windows PowerShell 3.0 and higher. Depending on your version of Windows it might be necessary to download and install a compatible version of PowerShell first. You can find the components necessary for this tutorial here:<br />
<br />
* [ftp://ftp.mailstore.com/pub/Scripts/PowerShell/v9/MailStore_SPE_Scripting_Tutorial.zip MailStore PowerShell API Wrapper and tutorial example scripts]<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=34595 Windows Management Framework 3.0] (contains PowerShell 3.0)<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=40855 Windows Management Framework 4.0] (alternatively, contains PowerShell 4.0)<br />
<br />
Please take note of the system requirements and further notices for the respective version of the Windows Management Framework.<br />
<br />
<p class=msnote><span class=mswarning>'''Important Notice:''' Installation of a Windows Management Framework on systems that require a specific version of Windows PowerShell, such as Microsoft Exchange Servers, is not supported and may lead to massive system failures and data loss.</span></p><br />
<br />
After downloading and installing Windows PowerShell (if necessary) please unzip the MailStore PowerShell API Wrapper and the example scripts (to ''C:\MailStore SPE Scripting Tutorial\PowerShell\'' by default).<br />
<br />
Neither the MailStore PowerShell API Wrapper nor the example scripts are digitally signed, therefore execution of such scripts has to be enabled in an administrative PowerShell session using<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Set-ExecutionPolicy -ExecutionPolicy Unrestricted<br />
</source><br />
<br />
== Importing the MailStore PowerShell API Wrapper ==<br />
The MailStore PowerShell API Wrapper is implemented as a PowerShell Script Module (''MS.PS.Lib.psm1'') and can thus be imported in a PowerShell session via its manifest (''MS.PS.Lib.psd1'') by using ''Import-Module''.<br />
<br />
Please open a PowerShell session and import the API wrapper module using this command:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module "C:\MailStore SPE Scripting Tutorial\PowerShell\API-Wrapper\MS.PS.Lib.psd1"<br />
</source><br />
<br />
=== Getting Information about the MailStore PowerShell API Wrapper ===<br />
The MailStore PowerShell API Wrapper provides several functions to access the MailStore SPE Management API, following PowerShell conventions. Enter the following command to get information about these features:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Module MS.PS.Lib | fl<br />
</source><br />
<br />
More detailed information is available via the module's properties. For example,<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
(Get-Module MS.PS.Lib).ExportedFunctions<br />
</source><br />
<br />
returns the functions provided by the module. Via<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Help *MSApi*<br />
</source><br />
<br />
the MailStore PowerShell API Wrapper returns inline help for all its functions.<br />
<br />
== Calling API Wrapper Functions ==<br />
The following example script (''Example1.ps1'' in the tutorial package) explains the basic usage of MailStore PowerShell API Wrapper functions.<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiClient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$return = Invoke-MSApiCall $MSApiClient "GetEnvironmentInfo"<br />
$return | fl<br />
</source><br />
<br />
The function ''New-MSApiClient'' creates a new API client object, which is used by the ''Invoke-MSApiCall'' function for API calls. The values for ''-Username'' and ''-Password'' have to be supplied, while ''-ManagementServer'' defaults to "localhost" and ''-Port'' defaults to "8474". The switch ''-IgnoreInvalidSSLCerts'' has to be set if untrusted certificates are used; otherwise an error occurs.<br />
<br />
Apart from the API client object, ''Invoke-MSApiCall'' needs an [[Management_API_-_Function_Reference|API command]] and its parameters if applicable. The command ''[[Management_API_-_Function_Reference#GetEnvironmentInfo|GetEnvironmentInfo]]'' in the script does not have any parameters and returns a JSON object as follows:<br />
<br />
error : <br />
token : <br />
statusVersion : 2<br />
statusCode : succeeded<br />
percentProgress : <br />
statusText : <br />
result : @{version=9.1.0.10258; copyright=Copyright (c) 2005-2014 MailStore Software GmbH; licenseeName=MailStore; licenseeID=23634; serverName=tutorial.mailstore.test; userName=admin; systemProperties=}<br />
logOutput : <br />
<br />
The ''result'' property of that object has the actual return value if the request succeeded as indicated by the ''statusCode'':<br />
<br />
version : 9.1.0.10258<br />
copyright : Copyright (c) 2005-2014 MailStore Software GmbH<br />
licenseeName : MailStore Software GmbH<br />
licenseeID : 23634<br />
serverName : tutorial.mailstore.test<br />
userName : admin<br />
systemProperties : @{processors=System.Object[]; totalPhysicalMemory=2146947072; operatingSystem=Microsoft Windows Server 2012 Standard}<br />
<br />
=== Calling API Wrapper Functions with Parameters ===<br />
For most MailStore SPE Management API commands you need to provide parameters. Of course, the MailStore PowerShell API Wrapper's ''Invoke-MSApiCall'' function can submit these parameters, as demonstrated by the following script (''Example2.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
foreach ($instance in $instances) {<br />
$users = (Invoke-MSApiCall $MSapiclient "GetUsers" @{instanceID = $instance.instanceID}).result<br />
foreach ($user in $users) {<br />
(Invoke-MSApiCall $MSapiclient "GetUserInfo" @{instanceID = $instance.instanceID; userName = $user.userName}).result | fl<br />
}<br />
}<br />
</source><br />
<br />
The scripts lists details about the users created in the MailStore SPE instances. Because the MailStore PowerShell API Wrapper converts API responses into objects, their properties can be used directly in the script's workflow. The function ''Invoke-MSApiCall'' expects parameters as a hashtable, e.g. ''@{parametername1 = value1; parametername2 = value2;...}''. Parameter names are case sensitive.<br />
<br />
First, a list of all MailStore SPE instances is requested with the API command ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]''. This command returns an array of instances as follows:<br />
<br />
instanceID : test01<br />
alias : tutorial<br />
displayName : Tutorial Test Instance<br />
instanceHost : tutorial.mailstore.test<br />
startMode : automatic<br />
processID : 3140<br />
status : running<br />
startStopError : <br />
<br />
The script now iterates over this array using the ''instanceID'' property of each entry as a parameter for the API command ''[[Management_API_-_Function_Reference#GetUsers|GetUsers]]''. The list of users of each instance is then also iterated over and each user's properties are requested via ''[[Management_API_-_Function_Reference#GetUserInfo|GetUserInfo]]''.<br />
<br />
For the entry listed above the result could be as follows:<br />
<br />
userName : johndoe<br />
fullName : John Doe<br />
distinguishedName : <br />
authentication : integrated<br />
emailAddresses : {}<br />
pop3UserNames : {}<br />
privileges : {login, changePassword}<br />
privilegesOnFolders : {@{folder=johndoe; privileges=System.Object[]}}<br />
<br />
As can be seen in the ''privilegesOnFolders'' property, returned objects may be nested and may also contain further objects.<br />
<br />
=== Handling Asynchronous API Calls ===<br />
The server may decide to execute Management API commands asynchronously if their execution takes more time. The MailStore PowerShell API Wrapper identifies calls of such [[Management_API_-_Using_the_API#Long_Running_Processes|asynchronously executed API commands]] and executes them as [http://technet.microsoft.com/en-us/library/hh847783%28v=wps.620%29.aspx PowerShell Jobs] in the background.<br />
<br />
==== Waiting for Asynchronous API Calls to Complete ====<br />
A script's execution can be interrupted until a PowerShell Job created by the API wrapper terminates as demonstrated by the following script (''Example3.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Invoke-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
$return | fl<br />
</source><br />
<br />
The API commands ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]'' and ''[[Management_API_-_Function_Reference#VerifyStore|VerifyStore]]'' called in the script are regularly run asynchronously by the server. By using ''Invoke-MSApiCall'' the API wrapper waits for an API command that is executed asynchronously and simply returns its final result:<br />
<br />
error : <br />
token : sa4c1dd3dcf56da32e44b29215b4d60b2b<br />
statusVersion : 152<br />
statusCode : succeeded<br />
percentProgress : 100<br />
statusText : <br />
result : <br />
logOutput : <br />
<br />
==== Subscribing to Events Triggered by Asynchronous API Calls ====<br />
Instead of interrupting a script's execution, the PowerShell Jobs created by the API wrapper can be reacted to while they are running in the background. These jobs trigger a PowerShell EngineEvent with each status request that the script can subscribe to in order to execute further code on each occurrence. To demonstrate this, the previous script needs to be adapted only a bit (''Example4.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Start-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
if ($return.statusCode -eq "running") {<br />
$mssevent = Register-EngineEvent -SourceIdentifier $return.Token -Action {write-host $event.MessageData}<br />
} else {<br />
$return | fl<br />
}<br />
</source><br />
By using ''Start-MSApiCall'' the API wrapper runs an API command that is executed asynchronously by the server in the background and returns its first result. The script subscribes to the event that is triggered by the background job via [http://technet.microsoft.com/en-us/library/hh849967.aspx Register-EngineEvent], using the return object's ''Token'' property as ''SourceIdentifier''. By that property the event relates to the triggering PowerShell Job and thus to the server process. The ''Action'' script block is itself created as a PowerShell Job that is executed with each triggering of the event. Through the ''MessageData'' property of the ''$event'' [http://technet.microsoft.com/en-us/library/hh847768.aspx automatic variable] the script block can access the JSON object provided by the background job. That object contains the status of the server process:<br />
<br />
@{error=; token=sae8b8eaa3f645d11ee0207797cebbc0b1; statusVersion=8;<br />
statusCode=running; percentProgress=1; statusText=; result=;<br />
logOutput= 300 messages verified...<br />
}<br />
<br />
Via these mechanisms the script can execute further tasks while monitoring the server process in the background. Execution and handling of multiple asynchronous API commands is also possible this way.<br />
<br />
==== Cancelling Asynchronous API Wrapper PowerShell Jobs ====<br />
To cancel the execution of an asynchronous API command, use ''Stop-MSApiCall'' with either the token or the JSON object. For the example above the call would be:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Stop-MSApiCall $MSApiclient -AsyncReturnObject $return<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=PowerShell_API_Wrapper_Tutorial&diff=1220PowerShell API Wrapper Tutorial2015-01-23T08:29:41Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
<br />
<div class=msnote>'''Important notice:''' The PowerShell API wrapper for the MailStore Server Administration API provided on this website is to be regarded as an example implementation of an API client. This wrapper should help system administrators and developers to quickly understand how MailStore Server Administration API calls work and how to use them in their own scripts.<br/><br />
Please understand that beyond this documentation no further support for the Powershell API wrapper is provided. Unless stated otherwise, the PowerShell API wrapper as well as all related example scripts are released under the terms and conditions of the [[wikipedia:MIT_License|MIT License]].</div><br />
<br />
<br />
This tutorial aims to explain the usage of the [[Management_API_-_Using_the_API|MailStore Service Provider Edition Management API]] through simple Windows PowerShell example scripts. Basic knowledge of MailStore Server, Windows and PowerShell is a necessary precondition. 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.<br />
<br />
== Installation of Necessary Components ==<br />
The examples demonstrated here use the MailStore PowerShell API Wrapper and are compatible with Windows PowerShell 3.0 and higher. Depending on your version of Windows it might be necessary to download and install a compatible version of PowerShell first. You can find the components necessary for this tutorial here:<br />
<br />
* [ftp://ftp.mailstore.com/pub/Scripts/PowerShell/v9.1/MailStore_SPE_Scripting_Tutorial.zip MailStore PowerShell API Wrapper and tutorial example scripts]<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=34595 Windows Management Framework 3.0] (contains PowerShell 3.0)<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=40855 Windows Management Framework 4.0] (alternatively, contains PowerShell 4.0)<br />
<br />
Please take note of the system requirements and further notices for the respective version of the Windows Management Framework.<br />
<br />
<p class=msnote><span class=mswarning>'''Important Notice:''' Installation of a Windows Management Framework on systems that require a specific version of Windows PowerShell, such as Microsoft Exchange Servers, is not supported and may lead to massive system failures and data loss.</span></p><br />
<br />
After downloading and installing Windows PowerShell (if necessary) please unzip the MailStore PowerShell API Wrapper and the example scripts (to ''C:\MailStore SPE Scripting Tutorial\PowerShell\'' by default).<br />
<br />
Neither the MailStore PowerShell API Wrapper nor the example scripts are digitally signed, therefore execution of such scripts has to be enabled in an administrative PowerShell session using<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Set-ExecutionPolicy -ExecutionPolicy Unrestricted<br />
</source><br />
<br />
== Importing the MailStore PowerShell API Wrapper ==<br />
The MailStore PowerShell API Wrapper is implemented as a PowerShell Script Module (''MS.PS.Lib.psm1'') and can thus be imported in a PowerShell session via its manifest (''MS.PS.Lib.psd1'') by using ''Import-Module''.<br />
<br />
Please open a PowerShell session and import the API wrapper module using this command:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module "C:\MailStore SPE Scripting Tutorial\PowerShell\API-Wrapper\MS.PS.Lib.psd1"<br />
</source><br />
<br />
=== Getting Information about the MailStore PowerShell API Wrapper ===<br />
The MailStore PowerShell API Wrapper provides several functions to access the MailStore SPE Management API, following PowerShell conventions. Enter the following command to get information about these features:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Module MS.PS.Lib | fl<br />
</source><br />
<br />
More detailed information is available via the module's properties. For example,<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
(Get-Module MS.PS.Lib).ExportedFunctions<br />
</source><br />
<br />
returns the functions provided by the module. Via<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Help *MSApi*<br />
</source><br />
<br />
the MailStore PowerShell API Wrapper returns inline help for all its functions.<br />
<br />
== Calling API Wrapper Functions ==<br />
The following example script (''Example1.ps1'' in the tutorial package) explains the basic usage of MailStore PowerShell API Wrapper functions.<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiClient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$return = Invoke-MSApiCall $MSApiClient "GetEnvironmentInfo"<br />
$return | fl<br />
</source><br />
<br />
The function ''New-MSApiClient'' creates a new API client object, which is used by the ''Invoke-MSApiCall'' function for API calls. The values for ''-Username'' and ''-Password'' have to be supplied, while ''-ManagementServer'' defaults to "localhost" and ''-Port'' defaults to "8474". The switch ''-IgnoreInvalidSSLCerts'' has to be set if untrusted certificates are used; otherwise an error occurs.<br />
<br />
Apart from the API client object, ''Invoke-MSApiCall'' needs an [[Management_API_-_Function_Reference|API command]] and its parameters if applicable. The command ''[[Management_API_-_Function_Reference#GetEnvironmentInfo|GetEnvironmentInfo]]'' in the script does not have any parameters and returns a JSON object as follows:<br />
<br />
error : <br />
token : <br />
statusVersion : 2<br />
statusCode : succeeded<br />
percentProgress : <br />
statusText : <br />
result : @{version=9.1.0.10258; copyright=Copyright (c) 2005-2014 MailStore Software GmbH; licenseeName=MailStore; licenseeID=23634; serverName=tutorial.mailstore.test; userName=admin; systemProperties=}<br />
logOutput : <br />
<br />
The ''result'' property of that object has the actual return value if the request succeeded as indicated by the ''statusCode'':<br />
<br />
version : 9.1.0.10258<br />
copyright : Copyright (c) 2005-2014 MailStore Software GmbH<br />
licenseeName : MailStore Software GmbH<br />
licenseeID : 23634<br />
serverName : tutorial.mailstore.test<br />
userName : admin<br />
systemProperties : @{processors=System.Object[]; totalPhysicalMemory=2146947072; operatingSystem=Microsoft Windows Server 2012 Standard}<br />
<br />
=== Calling API Wrapper Functions with Parameters ===<br />
For most MailStore SPE Management API commands you need to provide parameters. Of course, the MailStore PowerShell API Wrapper's ''Invoke-MSApiCall'' function can submit these parameters, as demonstrated by the following script (''Example2.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
foreach ($instance in $instances) {<br />
$users = (Invoke-MSApiCall $MSapiclient "GetUsers" @{instanceID = $instance.instanceID}).result<br />
foreach ($user in $users) {<br />
(Invoke-MSApiCall $MSapiclient "GetUserInfo" @{instanceID = $instance.instanceID; userName = $user.userName}).result | fl<br />
}<br />
}<br />
</source><br />
<br />
The scripts lists details about the users created in the MailStore SPE instances. Because the MailStore PowerShell API Wrapper converts API responses into objects, their properties can be used directly in the script's workflow. The function ''Invoke-MSApiCall'' expects parameters as a hashtable, e.g. ''@{parametername1 = value1; parametername2 = value2;...}''. Parameter names are case sensitive.<br />
<br />
First, a list of all MailStore SPE instances is requested with the API command ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]''. This command returns an array of instances as follows:<br />
<br />
instanceID : test01<br />
alias : tutorial<br />
displayName : Tutorial Test Instance<br />
instanceHost : tutorial.mailstore.test<br />
startMode : automatic<br />
processID : 3140<br />
status : running<br />
startStopError : <br />
<br />
The script now iterates over this array using the ''instanceID'' property of each entry as a parameter for the API command ''[[Management_API_-_Function_Reference#GetUsers|GetUsers]]''. The list of users of each instance is then also iterated over and each user's properties are requested via ''[[Management_API_-_Function_Reference#GetUserInfo|GetUserInfo]]''.<br />
<br />
For the entry listed above the result could be as follows:<br />
<br />
userName : johndoe<br />
fullName : John Doe<br />
distinguishedName : <br />
authentication : integrated<br />
emailAddresses : {}<br />
pop3UserNames : {}<br />
privileges : {login, changePassword}<br />
privilegesOnFolders : {@{folder=johndoe; privileges=System.Object[]}}<br />
<br />
As can be seen in the ''privilegesOnFolders'' property, returned objects may be nested and may also contain further objects.<br />
<br />
=== Handling Asynchronous API Calls ===<br />
The server may decide to execute Management API commands asynchronously if their execution takes more time. The MailStore PowerShell API Wrapper identifies calls of such [[Management_API_-_Using_the_API#Long_Running_Processes|asynchronously executed API commands]] and executes them as [http://technet.microsoft.com/en-us/library/hh847783%28v=wps.620%29.aspx PowerShell Jobs] in the background.<br />
<br />
==== Waiting for Asynchronous API Calls to Complete ====<br />
A script's execution can be interrupted until a PowerShell Job created by the API wrapper terminates as demonstrated by the following script (''Example3.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Invoke-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
$return | fl<br />
</source><br />
<br />
The API commands ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]'' and ''[[Management_API_-_Function_Reference#VerifyStore|VerifyStore]]'' called in the script are regularly run asynchronously by the server. By using ''Invoke-MSApiCall'' the API wrapper waits for an API command that is executed asynchronously and simply returns its final result:<br />
<br />
error : <br />
token : sa4c1dd3dcf56da32e44b29215b4d60b2b<br />
statusVersion : 152<br />
statusCode : succeeded<br />
percentProgress : 100<br />
statusText : <br />
result : <br />
logOutput : <br />
<br />
==== Subscribing to Events Triggered by Asynchronous API Calls ====<br />
Instead of interrupting a script's execution, the PowerShell Jobs created by the API wrapper can be reacted to while they are running in the background. These jobs trigger a PowerShell EngineEvent with each status request that the script can subscribe to in order to execute further code on each occurrence. To demonstrate this, the previous script needs to be adapted only a bit (''Example4.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Start-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
if ($return.statusCode -eq "running") {<br />
$mssevent = Register-EngineEvent -SourceIdentifier $return.Token -Action {write-host $event.MessageData}<br />
} else {<br />
$return | fl<br />
}<br />
</source><br />
By using ''Start-MSApiCall'' the API wrapper runs an API command that is executed asynchronously by the server in the background and returns its first result. The script subscribes to the event that is triggered by the background job via [http://technet.microsoft.com/en-us/library/hh849967.aspx Register-EngineEvent], using the return object's ''Token'' property as ''SourceIdentifier''. By that property the event relates to the triggering PowerShell Job and thus to the server process. The ''Action'' script block is itself created as a PowerShell Job that is executed with each triggering of the event. Through the ''MessageData'' property of the ''$event'' [http://technet.microsoft.com/en-us/library/hh847768.aspx automatic variable] the script block can access the JSON object provided by the background job. That object contains the status of the server process:<br />
<br />
@{error=; token=sae8b8eaa3f645d11ee0207797cebbc0b1; statusVersion=8;<br />
statusCode=running; percentProgress=1; statusText=; result=;<br />
logOutput= 300 messages verified...<br />
}<br />
<br />
Via these mechanisms the script can execute further tasks while monitoring the server process in the background. Execution and handling of multiple asynchronous API commands is also possible this way.<br />
<br />
==== Cancelling Asynchronous API Wrapper PowerShell Jobs ====<br />
To cancel the execution of an asynchronous API command, use ''Stop-MSApiCall'' with either the token or the JSON object. For the example above the call would be:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Stop-MSApiCall $MSApiclient -AsyncReturnObject $return<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=PowerShell_API_Wrapper_Tutorial&diff=1219PowerShell API Wrapper Tutorial2015-01-23T08:27:22Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
<br />
<div class=msnote>'''Important notice:''' The PowerShell API wrapper for the MailStore Server Administration API provided on this website is to be regarded as an example implementation of an API client. This wrapper should help system administrators and developers to quickly understand how MailStore Server Administration API calls work and how to use them in their own scripts.<br/><br />
Please understand that beyond this documentation no further support for the Powershell API wrapper is provided. Unless stated otherwise, the PowerShell API wrapper as well as all related example scripts are released under the terms and conditions of the [[wikipedia:MIT_License|MIT License]].</div><br />
<br />
<br />
This tutorial aims to explain the usage of the [[Management_API_-_Using_the_API|MailStore Service Provider Edition Management API]] through simple Windows PowerShell example scripts. Basic knowledge of MailStore Server, Windows and PowerShell is a necessary precondition. 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.<br />
<br />
== Installation of Necessary Components ==<br />
The examples demonstrated here use the MailStore PowerShell API Wrapper and are compatible with Windows PowerShell 3.0 and higher. Depending on your version of Windows it might be necessary to download and install a compatible version of PowerShell first. You can find the components necessary for this tutorial here:<br />
<br />
* [ftp://ftp.mailstore.com/pub/Scripts/PowerShell/v9/MailStore_SPE_Scripting_Tutorial.zip MailStore PowerShell API Wrapper and tutorial example scripts]<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=34595 Windows Management Framework 3.0] (contains PowerShell 3.0)<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=40855 Windows Management Framework 4.0] (alternatively, contains PowerShell 4.0)<br />
<br />
Please take note of the system requirements and further notices for the respective version of the Windows Management Framework.<br />
<br />
<p class=msnote><span class=mswarning>'''Important Notice:''' Installation of a Windows Management Framework on systems that require a specific version of Windows PowerShell, such as Microsoft Exchange Servers, is not supported and may lead to massive system failures and data loss.</span></p><br />
<br />
After downloading and installing Windows PowerShell (if necessary) please unzip the MailStore PowerShell API Wrapper and the example scripts (to ''C:\MailStore SPE Scripting Tutorial\PowerShell\'' by default).<br />
<br />
Neither the MailStore PowerShell API Wrapper nor the example scripts are digitally signed, therefore execution of such scripts has to be enabled in an administrative PowerShell session using<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Set-ExecutionPolicy -ExecutionPolicy Unrestricted<br />
</source><br />
<br />
== Importing the MailStore PowerShell API Wrapper ==<br />
The MailStore PowerShell API Wrapper is implemented as a PowerShell Script Module (''MS.PS.Lib.psm1'') and can thus be imported in a PowerShell session via its manifest (''MS.PS.Lib.psd1'') by using ''Import-Module''.<br />
<br />
Please open a PowerShell session and import the API wrapper module using this command:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module "C:\MailStore SPE Scripting Tutorial\PowerShell\API-Wrapper\MS.PS.Lib.psd1"<br />
</source><br />
<br />
=== Getting Information about the MailStore PowerShell API Wrapper ===<br />
The MailStore PowerShell API Wrapper provides several functions to access the MailStore SPE Management API, following PowerShell conventions. Enter the following command to get information about these features:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Module MS.PS.Lib | fl<br />
</source><br />
<br />
More detailed information is available via the module's properties. For example,<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
(Get-Module MS.PS.Lib).ExportedFunctions<br />
</source><br />
<br />
returns the functions provided by the module. Via<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Help *MSApi*<br />
</source><br />
<br />
the MailStore PowerShell API Wrapper returns inline help for all its functions.<br />
<br />
== Calling API Wrapper Functions ==<br />
The following example script (''Example1.ps1'' in the tutorial package) explains the basic usage of MailStore PowerShell API Wrapper functions.<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiClient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$return = Invoke-MSApiCall $MSApiClient "GetEnvironmentInfo"<br />
$return | fl<br />
</source><br />
<br />
The function ''New-MSApiClient'' creates a new API client object, which is used by the ''Invoke-MSApiCall'' function for API calls. The values for ''-Username'' and ''-Password'' have to be supplied, while ''-ManagementServer'' defaults to "localhost" and ''-Port'' defaults to "8474". The switch ''-IgnoreInvalidSSLCerts'' has to be set if untrusted certificates are used; otherwise an error occurs.<br />
<br />
Apart from the API client object, ''Invoke-MSApiCall'' needs an [[Management_API_-_Function_Reference|API command]] and its parameters if applicable. The command ''[[Management_API_-_Function_Reference#GetEnvironmentInfo|GetEnvironmentInfo]]'' in the script does not have any parameters and returns a JSON object as follows:<br />
<br />
error : <br />
token : <br />
statusVersion : 2<br />
statusCode : succeeded<br />
percentProgress : <br />
statusText : <br />
result : @{version=9.1.0.10258; copyright=Copyright (c) 2005-2014 MailStore Software GmbH; licenseeName=MailStore; licenseeID=23634; serverName=tutorial.mailstore.test; userName=admin; systemProperties=}<br />
logOutput : <br />
<br />
The ''result'' property of that object has the actual return value if the request succeeded as indicated by the ''statusCode'':<br />
<br />
version : 9.1.0.10258<br />
copyright : Copyright (c) 2005-2014 MailStore Software GmbH<br />
licenseeName : MailStore Software GmbH<br />
licenseeID : 23634<br />
serverName : tutorial.mailstore.test<br />
userName : admin<br />
systemProperties : @{processors=System.Object[]; totalPhysicalMemory=2146947072; operatingSystem=Microsoft Windows Server 2012 Standard}<br />
<br />
=== Calling API Wrapper Functions with Parameters ===<br />
For most MailStore SPE Management API commands you need to provide parameters. Of course, the MailStore PowerShell API Wrapper's ''Invoke-MSApiCall'' function can submit these parameters, as demonstrated by the following script (''Example2.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
foreach ($instance in $instances) {<br />
$users = (Invoke-MSApiCall $MSapiclient "GetUsers" @{instanceID = $instance.instanceID}).result<br />
foreach ($user in $users) {<br />
(Invoke-MSApiCall $MSapiclient "GetUserInfo" @{instanceID = $instance.instanceID; userName = $user.userName}).result | fl<br />
}<br />
}<br />
</source><br />
<br />
The scripts lists details about the users created in the MailStore SPE instances. Because the MailStore PowerShell API Wrapper converts API responses into objects, their properties can be used directly in the script's workflow. The function ''Invoke-MSApiCall'' expects parameters as a hashtable, e.g. ''@{parametername1 = value1; parametername2 = value2;...}''. Parameter names are case sensitive.<br />
<br />
First, a list of all MailStore SPE instances is requested with the API command ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]''. This command returns an array of instances as follows:<br />
<br />
instanceID : test01<br />
alias : tutorial<br />
displayName : Tutorial Test Instance<br />
instanceHost : tutorial.mailstore.test<br />
startMode : automatic<br />
processID : 3140<br />
status : running<br />
startStopError : <br />
<br />
The script now iterates over this array using the ''instanceID'' property of each entry as a parameter for the API command ''[[Management_API_-_Function_Reference#GetUsers|GetUsers]]''. The list of users of each instance is then also iterated over and each user's properties are requested via ''[[Management_API_-_Function_Reference#GetUserInfo|GetUserInfo]]''.<br />
<br />
For the entry listed above the result could be as follows:<br />
<br />
userName : johndoe<br />
fullName : John Doe<br />
distinguishedName : <br />
authentication : integrated<br />
emailAddresses : {}<br />
pop3UserNames : {}<br />
privileges : {login, changePassword}<br />
privilegesOnFolders : {@{folder=johndoe; privileges=System.Object[]}}<br />
<br />
As can be seen in the ''privilegesOnFolders'' property, returned objects may be nested and may also contain further objects.<br />
<br />
=== Handling Asynchronous API Calls ===<br />
The server may decide to execute Management API commands asynchronously if their execution takes more time. The MailStore PowerShell API Wrapper identifies calls of such [[Management_API_-_Using_the_API#Long_Running_Processes|asynchronously executed API commands]] and executes them as [http://technet.microsoft.com/en-us/library/hh847783%28v=wps.620%29.aspx PowerShell Jobs] in the background.<br />
<br />
==== Waiting for Asynchronous API Calls to Complete ====<br />
A script's execution can be interrupted until a PowerShell Job created by the API wrapper terminates as demonstrated by the following script (''Example3.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Invoke-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
$return | fl<br />
</source><br />
<br />
The API commands ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]'' and ''[[Management_API_-_Function_Reference#VerifyStore|VerifyStore]]'' called in the script are regularly run asynchronously by the server. By using ''Invoke-MSApiCall'' the API wrapper waits for an API command that is executed asynchronously and simply returns its final result:<br />
<br />
error : <br />
token : sa4c1dd3dcf56da32e44b29215b4d60b2b<br />
statusVersion : 152<br />
statusCode : succeeded<br />
percentProgress : 100<br />
statusText : <br />
result : <br />
logOutput : <br />
<br />
==== Subscribing to Events Triggered by Asynchronous API Calls ====<br />
Instead of interrupting a script's execution, the PowerShell Jobs created by the API wrapper can be reacted to while they are running in the background. These jobs trigger a PowerShell EngineEvent with each status request that the script can subscribe to in order to execute further code on each occurrence. To demonstrate this, the previous script needs to be adapted only a bit (''Example4.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Start-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
if ($return.statusCode -eq "running") {<br />
$mssevent = Register-EngineEvent -SourceIdentifier $return.Token -Action {write-host $event.MessageData}<br />
} else {<br />
$return | fl<br />
}<br />
</source><br />
By using ''Start-MSApiCall'' the API wrapper runs an API command that is executed asynchronously by the server in the background and returns its first result. The script subscribes to the event that is triggered by the background job via [http://technet.microsoft.com/en-us/library/hh849967.aspx Register-EngineEvent], using the return object's ''Token'' property as ''SourceIdentifier''. By that property the event relates to the triggering PowerShell Job and thus to the server process. The ''Action'' script block is itself created as a PowerShell Job that is executed with each triggering of the event. Through the ''MessageData'' property of the ''$event'' [http://technet.microsoft.com/en-us/library/hh847768.aspx automatic variable] the script block can access the JSON object provided by the background job. That object contains the status of the server process:<br />
<br />
@{error=; token=sae8b8eaa3f645d11ee0207797cebbc0b1; statusVersion=8;<br />
statusCode=running; percentProgress=1; statusText=; result=;<br />
logOutput= 300 messages verified...<br />
}<br />
<br />
Via these mechanisms the script can execute further tasks while monitoring the server process in the background. Execution and handling of multiple asynchronous API commands is also possible this way.<br />
<br />
==== Cancelling Asynchronous API Wrapper PowerShell Jobs ====<br />
To cancel the execution of an asynchronous API command, use ''Stop-MSApiCall'' with either the token or the JSON object. For the example above the call would be:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Stop-MSApiCall $MSApiclient -AsyncReturnObject $return<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=PowerShell_API_Wrapper_Tutorial&diff=1218PowerShell API Wrapper Tutorial2015-01-23T08:27:09Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
<br />
<div class=msnote>'''Important notice:''' The PowerShell API wrapper for the MailStore Server Administration API provided on this website is to be regarded as an example implementation of an API client. This wrapper should help system administrators and developers to quickly understand how MailStore Server Administration API calls work and how to use them in their own scripts.<br/><br />
Please understand that beyond this documentation no further support for the Powershell API wrapper is provided. Unless stated otherwise, the PowerShell API wrapper as well as all related example scripts are released under the terms and conditions of the [[wikipedia:MIT_License|MIT License]].</div><br />
<br />
<br />
This tutorial aims to explain the usage of the [[Management_API_-_Using_the_API|MailStore Service Provider Edition Management API]] through simple Windows PowerShell example scripts. Basic knowledge of MailStore Server, Windows and PowerShell is a necessary precondition. 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.<br />
<br />
== Installation of Necessary Components ==<br />
The examples demonstrated here use the MailStore PowerShell API Wrapper and are compatible with Windows PowerShell 3.0 and higher. Depending on your version of Windows it might be necessary to download and install a compatible version of PowerShell first. You can find the components necessary for this tutorial here:<br />
<br />
* [ftp://ftp.mailstore.com/pub/Scripts/PowerShell/v9.1/MailStore_SPE_Scripting_Tutorial.zip MailStore PowerShell API Wrapper and tutorial example scripts]<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=34595 Windows Management Framework 3.0] (contains PowerShell 3.0)<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=40855 Windows Management Framework 4.0] (alternatively, contains PowerShell 4.0)<br />
<br />
Please take note of the system requirements and further notices for the respective version of the Windows Management Framework.<br />
<br />
<p class=msnote><span class=mswarning>'''Important Notice:''' Installation of a Windows Management Framework on systems that require a specific version of Windows PowerShell, such as Microsoft Exchange Servers, is not supported and may lead to massive system failures and data loss.</span></p><br />
<br />
After downloading and installing Windows PowerShell (if necessary) please unzip the MailStore PowerShell API Wrapper and the example scripts (to ''C:\MailStore SPE Scripting Tutorial\PowerShell\'' by default).<br />
<br />
Neither the MailStore PowerShell API Wrapper nor the example scripts are digitally signed, therefore execution of such scripts has to be enabled in an administrative PowerShell session using<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Set-ExecutionPolicy -ExecutionPolicy Unrestricted<br />
</source><br />
<br />
== Importing the MailStore PowerShell API Wrapper ==<br />
The MailStore PowerShell API Wrapper is implemented as a PowerShell Script Module (''MS.PS.Lib.psm1'') and can thus be imported in a PowerShell session via its manifest (''MS.PS.Lib.psd1'') by using ''Import-Module''.<br />
<br />
Please open a PowerShell session and import the API wrapper module using this command:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module "C:\MailStore SPE Scripting Tutorial\PowerShell\API-Wrapper\MS.PS.Lib.psd1"<br />
</source><br />
<br />
=== Getting Information about the MailStore PowerShell API Wrapper ===<br />
The MailStore PowerShell API Wrapper provides several functions to access the MailStore SPE Management API, following PowerShell conventions. Enter the following command to get information about these features:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Module MS.PS.Lib | fl<br />
</source><br />
<br />
More detailed information is available via the module's properties. For example,<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
(Get-Module MS.PS.Lib).ExportedFunctions<br />
</source><br />
<br />
returns the functions provided by the module. Via<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Help *MSApi*<br />
</source><br />
<br />
the MailStore PowerShell API Wrapper returns inline help for all its functions.<br />
<br />
== Calling API Wrapper Functions ==<br />
The following example script (''Example1.ps1'' in the tutorial package) explains the basic usage of MailStore PowerShell API Wrapper functions.<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiClient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$return = Invoke-MSApiCall $MSApiClient "GetEnvironmentInfo"<br />
$return | fl<br />
</source><br />
<br />
The function ''New-MSApiClient'' creates a new API client object, which is used by the ''Invoke-MSApiCall'' function for API calls. The values for ''-Username'' and ''-Password'' have to be supplied, while ''-ManagementServer'' defaults to "localhost" and ''-Port'' defaults to "8474". The switch ''-IgnoreInvalidSSLCerts'' has to be set if untrusted certificates are used; otherwise an error occurs.<br />
<br />
Apart from the API client object, ''Invoke-MSApiCall'' needs an [[Management_API_-_Function_Reference|API command]] and its parameters if applicable. The command ''[[Management_API_-_Function_Reference#GetEnvironmentInfo|GetEnvironmentInfo]]'' in the script does not have any parameters and returns a JSON object as follows:<br />
<br />
error : <br />
token : <br />
statusVersion : 2<br />
statusCode : succeeded<br />
percentProgress : <br />
statusText : <br />
result : @{version=9.1.0.10258; copyright=Copyright (c) 2005-2014 MailStore Software GmbH; licenseeName=MailStore; licenseeID=23634; serverName=tutorial.mailstore.test; userName=admin; systemProperties=}<br />
logOutput : <br />
<br />
The ''result'' property of that object has the actual return value if the request succeeded as indicated by the ''statusCode'':<br />
<br />
version : 9.1.0.10258<br />
copyright : Copyright (c) 2005-2014 MailStore Software GmbH<br />
licenseeName : MailStore Software GmbH<br />
licenseeID : 23634<br />
serverName : tutorial.mailstore.test<br />
userName : admin<br />
systemProperties : @{processors=System.Object[]; totalPhysicalMemory=2146947072; operatingSystem=Microsoft Windows Server 2012 Standard}<br />
<br />
=== Calling API Wrapper Functions with Parameters ===<br />
For most MailStore SPE Management API commands you need to provide parameters. Of course, the MailStore PowerShell API Wrapper's ''Invoke-MSApiCall'' function can submit these parameters, as demonstrated by the following script (''Example2.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
foreach ($instance in $instances) {<br />
$users = (Invoke-MSApiCall $MSapiclient "GetUsers" @{instanceID = $instance.instanceID}).result<br />
foreach ($user in $users) {<br />
(Invoke-MSApiCall $MSapiclient "GetUserInfo" @{instanceID = $instance.instanceID; userName = $user.userName}).result | fl<br />
}<br />
}<br />
</source><br />
<br />
The scripts lists details about the users created in the MailStore SPE instances. Because the MailStore PowerShell API Wrapper converts API responses into objects, their properties can be used directly in the script's workflow. The function ''Invoke-MSApiCall'' expects parameters as a hashtable, e.g. ''@{parametername1 = value1; parametername2 = value2;...}''. Parameter names are case sensitive.<br />
<br />
First, a list of all MailStore SPE instances is requested with the API command ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]''. This command returns an array of instances as follows:<br />
<br />
instanceID : test01<br />
alias : tutorial<br />
displayName : Tutorial Test Instance<br />
instanceHost : tutorial.mailstore.test<br />
startMode : automatic<br />
processID : 3140<br />
status : running<br />
startStopError : <br />
<br />
The script now iterates over this array using the ''instanceID'' property of each entry as a parameter for the API command ''[[Management_API_-_Function_Reference#GetUsers|GetUsers]]''. The list of users of each instance is then also iterated over and each user's properties are requested via ''[[Management_API_-_Function_Reference#GetUserInfo|GetUserInfo]]''.<br />
<br />
For the entry listed above the result could be as follows:<br />
<br />
userName : johndoe<br />
fullName : John Doe<br />
distinguishedName : <br />
authentication : integrated<br />
emailAddresses : {}<br />
pop3UserNames : {}<br />
privileges : {login, changePassword}<br />
privilegesOnFolders : {@{folder=johndoe; privileges=System.Object[]}}<br />
<br />
As can be seen in the ''privilegesOnFolders'' property, returned objects may be nested and may also contain further objects.<br />
<br />
=== Handling Asynchronous API Calls ===<br />
The server may decide to execute Management API commands asynchronously if their execution takes more time. The MailStore PowerShell API Wrapper identifies calls of such [[Management_API_-_Using_the_API#Long_Running_Processes|asynchronously executed API commands]] and executes them as [http://technet.microsoft.com/en-us/library/hh847783%28v=wps.620%29.aspx PowerShell Jobs] in the background.<br />
<br />
==== Waiting for Asynchronous API Calls to Complete ====<br />
A script's execution can be interrupted until a PowerShell Job created by the API wrapper terminates as demonstrated by the following script (''Example3.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Invoke-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
$return | fl<br />
</source><br />
<br />
The API commands ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]'' and ''[[Management_API_-_Function_Reference#VerifyStore|VerifyStore]]'' called in the script are regularly run asynchronously by the server. By using ''Invoke-MSApiCall'' the API wrapper waits for an API command that is executed asynchronously and simply returns its final result:<br />
<br />
error : <br />
token : sa4c1dd3dcf56da32e44b29215b4d60b2b<br />
statusVersion : 152<br />
statusCode : succeeded<br />
percentProgress : 100<br />
statusText : <br />
result : <br />
logOutput : <br />
<br />
==== Subscribing to Events Triggered by Asynchronous API Calls ====<br />
Instead of interrupting a script's execution, the PowerShell Jobs created by the API wrapper can be reacted to while they are running in the background. These jobs trigger a PowerShell EngineEvent with each status request that the script can subscribe to in order to execute further code on each occurrence. To demonstrate this, the previous script needs to be adapted only a bit (''Example4.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Start-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
if ($return.statusCode -eq "running") {<br />
$mssevent = Register-EngineEvent -SourceIdentifier $return.Token -Action {write-host $event.MessageData}<br />
} else {<br />
$return | fl<br />
}<br />
</source><br />
By using ''Start-MSApiCall'' the API wrapper runs an API command that is executed asynchronously by the server in the background and returns its first result. The script subscribes to the event that is triggered by the background job via [http://technet.microsoft.com/en-us/library/hh849967.aspx Register-EngineEvent], using the return object's ''Token'' property as ''SourceIdentifier''. By that property the event relates to the triggering PowerShell Job and thus to the server process. The ''Action'' script block is itself created as a PowerShell Job that is executed with each triggering of the event. Through the ''MessageData'' property of the ''$event'' [http://technet.microsoft.com/en-us/library/hh847768.aspx automatic variable] the script block can access the JSON object provided by the background job. That object contains the status of the server process:<br />
<br />
@{error=; token=sae8b8eaa3f645d11ee0207797cebbc0b1; statusVersion=8;<br />
statusCode=running; percentProgress=1; statusText=; result=;<br />
logOutput= 300 messages verified...<br />
}<br />
<br />
Via these mechanisms the script can execute further tasks while monitoring the server process in the background. Execution and handling of multiple asynchronous API commands is also possible this way.<br />
<br />
==== Cancelling Asynchronous API Wrapper PowerShell Jobs ====<br />
To cancel the execution of an asynchronous API command, use ''Stop-MSApiCall'' with either the token or the JSON object. For the example above the call would be:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Stop-MSApiCall $MSApiclient -AsyncReturnObject $return<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=PowerShell_API_Wrapper_Tutorial&diff=1214PowerShell API Wrapper Tutorial2015-01-22T12:36:49Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
<br />
<div class=msnote>'''Important notice:''' The PowerShell API wrapper for the MailStore Server Administration API provided on this website is to be regarded as an example implementation of an API client. This wrapper should help system administrators and developers to quickly understand how MailStore Server Administration API calls work and how to use them in their own scripts.<br/><br />
Please understand that beyond this documentation no further support for the Powershell API wrapper is provided. Unless stated otherwise, the PowerShell API wrapper as well as all related example scripts are released under the terms and conditions of the [[wikipedia:MIT_License|MIT License]].</div><br />
<br />
<br />
This tutorial aims to explain the usage of the [[Management_API_-_Using_the_API|MailStore Service Provider Edition Management API]] through simple Windows PowerShell example scripts. Basic knowledge of MailStore Server, Windows and PowerShell is a necessary precondition. 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.<br />
<br />
== Installation of Necessary Components ==<br />
The examples demonstrated here use the MailStore PowerShell API Wrapper and are compatible with Windows PowerShell 3.0 and higher. Depending on your version of Windows it might be necessary to download and install a compatible version of PowerShell first. You can find the components necessary for this tutorial here:<br />
<br />
* [ftp://ftp.mailstore.com/pub/Scripts/PowerShell/v9/MailStore_SPE_Scripting_Tutorial.zip MailStore PowerShell API Wrapper and tutorial example scripts]<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=34595 Windows Management Framework 3.0] (contains PowerShell 3.0)<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=40855 Windows Management Framework 4.0] (alternatively, contains PowerShell 4.0)<br />
<br />
Please take note of the system requirements and further notices for the respective version of the Windows Management Framework.<br />
<br />
<p class=msnote><span class=mswarning>'''Important Notice:''' Installation of a Windows Management Framework on systems that require a specific version of Windows PowerShell, such as Microsoft Exchange Servers, is not supported and may lead to massive system failures and data loss.</span></p><br />
<br />
After downloading and installing Windows PowerShell (if necessary) please unzip the MailStore PowerShell API Wrapper and the example scripts (to ''C:\MailStore SPE Scripting Tutorial\PowerShell\'' by default).<br />
<br />
Neither the MailStore PowerShell API Wrapper nor the example scripts are digitally signed, therefore execution of such scripts has to be enabled in an administrative PowerShell session using<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Set-ExecutionPolicy -ExecutionPolicy Unrestricted<br />
</source><br />
<br />
== Importing the MailStore PowerShell API Wrapper ==<br />
The MailStore PowerShell API Wrapper is implemented as a PowerShell Script Module (''MS.PS.Lib.psm1'') and can thus be imported in a PowerShell session via its manifest (''MS.PS.Lib.psd1'') by using ''Import-Module''.<br />
<br />
Please open a PowerShell session and import the API wrapper module using this command:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module "C:\MailStore SPE Scripting Tutorial\PowerShell\API-Wrapper\MS.PS.Lib.psd1"<br />
</source><br />
<br />
=== Getting Information about the MailStore PowerShell API Wrapper ===<br />
The MailStore PowerShell API Wrapper provides several functions to access the MailStore SPE Management API, following PowerShell conventions. Enter the following command to get information about these features:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Module MS.PS.Lib | fl<br />
</source><br />
<br />
More detailed information is available via the module's properties. For example,<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
(Get-Module MS.PS.Lib).ExportedFunctions<br />
</source><br />
<br />
returns the functions provided by the module. Via<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Help *MSApi*<br />
</source><br />
<br />
the MailStore PowerShell API Wrapper returns inline help for all its functions.<br />
<br />
== Calling API Wrapper Functions ==<br />
The following example script (''Example1.ps1'' in the tutorial package) explains the basic usage of MailStore PowerShell API Wrapper functions.<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiClient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$return = Invoke-MSApiCall $MSApiClient "GetEnvironmentInfo"<br />
$return | fl<br />
</source><br />
<br />
The function ''New-MSApiClient'' creates a new API client object, which is used by the ''Invoke-MSApiCall'' function for API calls. The values for ''-Username'' and ''-Password'' have to be supplied, while ''-ManagementServer'' defaults to "localhost" and ''-Port'' defaults to "8474". The switch ''-IgnoreInvalidSSLCerts'' has to be set if untrusted certificates are used; otherwise an error occurs.<br />
<br />
Apart from the API client object, ''Invoke-MSApiCall'' needs an [[Management_API_-_Function_Reference|API command]] and its parameters if applicable. The command ''[[Management_API_-_Function_Reference#GetEnvironmentInfo|GetEnvironmentInfo]]'' in the script does not have any parameters and returns a JSON object as follows:<br />
<br />
error : <br />
token : <br />
statusVersion : 2<br />
statusCode : succeeded<br />
percentProgress : <br />
statusText : <br />
result : @{version=9.1.0.10258; copyright=Copyright (c) 2005-2014 MailStore Software GmbH; licenseeName=MailStore; licenseeID=23634; serverName=tutorial.mailstore.test; userName=admin; systemProperties=}<br />
logOutput : <br />
<br />
The ''result'' property of that object has the actual return value if the request succeeded as indicated by the ''statusCode'':<br />
<br />
version : 9.1.0.10258<br />
copyright : Copyright (c) 2005-2014 MailStore Software GmbH<br />
licenseeName : MailStore Software GmbH<br />
licenseeID : 23634<br />
serverName : tutorial.mailstore.test<br />
userName : admin<br />
systemProperties : @{processors=System.Object[]; totalPhysicalMemory=2146947072; operatingSystem=Microsoft Windows Server 2012 Standard}<br />
<br />
=== Calling API Wrapper Functions with Parameters ===<br />
For most MailStore SPE Management API commands you need to provide parameters. Of course, the MailStore PowerShell API Wrapper's ''Invoke-MSApiCall'' function can submit these parameters, as demonstrated by the following script (''Example2.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
foreach ($instance in $instances) {<br />
$users = (Invoke-MSApiCall $MSapiclient "GetUsers" @{instanceID = $instance.instanceID}).result<br />
foreach ($user in $users) {<br />
(Invoke-MSApiCall $MSapiclient "GetUserInfo" @{instanceID = $instance.instanceID; userName = $user.userName}).result | fl<br />
}<br />
}<br />
</source><br />
<br />
The scripts lists details about the users created in the MailStore SPE instances. Because the MailStore PowerShell API Wrapper converts API responses into objects, their properties can be used directly in the script's workflow. The function ''Invoke-MSApiCall'' expects parameters as a hashtable, e.g. ''@{parametername1 = value1; parametername2 = value2;...}''. Parameter names are case sensitive.<br />
<br />
First, a list of all MailStore SPE instances is requested with the API command ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]''. This command returns an array of instances as follows:<br />
<br />
instanceID : test01<br />
alias : tutorial<br />
displayName : Tutorial Test Instance<br />
instanceHost : tutorial.mailstore.test<br />
startMode : automatic<br />
processID : 3140<br />
status : running<br />
startStopError : <br />
<br />
The script now iterates over this array using the ''instanceID'' property of each entry as a parameter for the API command ''[[Management_API_-_Function_Reference#GetUsers|GetUsers]]''. The list of users of each instance is then also iterated over and each user's properties are requested via ''[[Management_API_-_Function_Reference#GetUserInfo|GetUserInfo]]''.<br />
<br />
For the entry listed above the result could be as follows:<br />
<br />
userName : johndoe<br />
fullName : John Doe<br />
distinguishedName : <br />
authentication : integrated<br />
emailAddresses : {}<br />
pop3UserNames : {}<br />
privileges : {login, changePassword}<br />
privilegesOnFolders : {@{folder=johndoe; privileges=System.Object[]}}<br />
<br />
As can be seen in the ''privilegesOnFolders'' property, returned objects may be nested and may also contain further objects.<br />
<br />
=== Handling Asynchronous API Calls ===<br />
The server may decide to execute Management API commands asynchronously if their execution takes more time. The MailStore PowerShell API Wrapper identifies calls of such [[Management_API_-_Using_the_API#Long_Running_Processes|asynchronously executed API commands]] and executes them as [http://technet.microsoft.com/en-us/library/hh847783%28v=wps.620%29.aspx PowerShell Jobs] in the background.<br />
<br />
==== Waiting for Asynchronous API Calls to Complete ====<br />
A script's execution can be interrupted until a PowerShell Job created by the API wrapper terminates as demonstrated by the following script (''Example3.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Invoke-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
$return | fl<br />
</source><br />
<br />
The API commands ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]'' and ''[[Management_API_-_Function_Reference#VerifyStore|VerifyStore]]'' called in the script are regularly run asynchronously by the server. By using ''Invoke-MSApiCall'' the API wrapper waits for an API command that is executed asynchronously and simply returns its final result:<br />
<br />
error : <br />
token : sa4c1dd3dcf56da32e44b29215b4d60b2b<br />
statusVersion : 152<br />
statusCode : succeeded<br />
percentProgress : 100<br />
statusText : <br />
result : <br />
logOutput : <br />
<br />
==== Subscribing to Events Triggered by Asynchronous API Calls ====<br />
Instead of interrupting a script's execution, the PowerShell Jobs created by the API wrapper can be reacted to while they are running in the background. These jobs trigger a PowerShell EngineEvent with each status request that the script can subscribe to in order to execute further code on each occurrence. To demonstrate this, the previous script needs to be adapted only a bit (''Example4.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Start-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
if ($return.statusCode -eq "running") {<br />
$mssevent = Register-EngineEvent -SourceIdentifier $return.Token -Action {write-host $event.MessageData}<br />
} else {<br />
$return | fl<br />
}<br />
</source><br />
By using ''Start-MSApiCall'' the API wrapper runs an API command that is executed asynchronously by the server in the background and returns its first result. The script subscribes to the event that is triggered by the background job via [http://technet.microsoft.com/en-us/library/hh849967.aspx Register-EngineEvent], using the return object's ''Token'' property as ''SourceIdentifier''. By that property the event relates to the triggering PowerShell Job and thus to the server process. The ''Action'' script block is itself created as a PowerShell Job that is executed with each triggering of the event. Through the ''MessageData'' property of the ''$event'' [http://technet.microsoft.com/en-us/library/hh847768.aspx automatic variable] the script block can access the JSON object provided by the background job. That object contains the status of the server process:<br />
<br />
@{error=; token=sae8b8eaa3f645d11ee0207797cebbc0b1; statusVersion=8;<br />
statusCode=running; percentProgress=1; statusText=; result=;<br />
logOutput= 300 messages verified...<br />
}<br />
<br />
Via these mechanisms the script can execute further tasks while monitoring the server process in the background. Execution and handling of multiple asynchronous API commands is also possible this way.<br />
<br />
==== Cancelling Asynchronous API Wrapper PowerShell Jobs ====<br />
To cancel the execution of an asynchronous API command, use ''Stop-MSApiCall'' with either the token or the JSON object. For the example above the call would be:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Stop-MSApiCall $MSApiclient -AsyncReturnObject $return<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=PowerShell_API_Wrapper_Tutorial&diff=1212PowerShell API Wrapper Tutorial2015-01-20T09:20:18Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
<br />
<div class=msnote>'''Important notice:''' The PowerShell API wrapper for the MailStore Server Administration API provided on this website is to be regarded as an example implementation of an API client. This wrapper should help system administrators and developers to quickly understand how MailStore Server Administration API calls work and how to use them in their own scripts.<br/><br />
Please understand that beyond this documentation no further support for the Powershell API wrapper is provided. Unless stated otherwise, the PowerShell API wrapper as well as all related example scripts are released under the terms and conditions of the [[wikipedia:MIT_License|MIT License]].</div><br />
<br />
<br />
This tutorial aims to explain the usage of the [[Management_API_-_Using_the_API|MailStore Service Provider Edition Management API]] through simple Windows PowerShell example scripts. Basic knowledge of MailStore Server, Windows and PowerShell is a necessary precondition. 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.<br />
<br />
== Installation of Necessary Components ==<br />
The examples demonstrated here use the MailStore PowerShell API Wrapper and are compatible with Windows PowerShell 3.0 and higher. Depending on your version of Windows it might be necessary to download and install a compatible version of PowerShell first. You can find the components necessary for this tutorial here:<br />
<br />
* [ftp://ftp.mailstore.com/pub/Scripts/PowerShell/v9/MailStore_SPE_Scripting_Tutorial.zip MailStore PowerShell API Wrapper and tutorial example scripts]<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=34595 Windows Management Framework 3.0] (contains PowerShell 3.0)<br />
* [http://www.microsoft.com/en-us/download/details.aspx?id=40855 Windows Management Framework 4.0] (alternatively, contains PowerShell 4.0)<br />
<br />
Please take note of the system requirements and further notices for the respective version of the Windows Management Framework.<br />
<br />
<p class=msnote><span class=mswarning>'''Important Notice:''' Installation of a Windows Management Framework on systems that require a specific version of Windows PowerShell, such as Microsoft Exchange Servers, is not supported and may lead to massive system failures and data loss.</span></p><br />
<br />
After downloading and installing Windows PowerShell (if necessary) please unzip the MailStore PowerShell API Wrapper and the example scripts (to ''C:\MailStore SPE Scripting Tutorial\PowerShell\'' by default).<br />
<br />
Neither the MailStore PowerShell API Wrapper nor the example scripts are digitally signed, therefore execution of such scripts has to be enabled in an administrative PowerShell session using<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Set-ExecutionPolicy -ExecutionPolicy Unrestricted<br />
</source><br />
<br />
== Importing the MailStore PowerShell API Wrapper ==<br />
The MailStore PowerShell API Wrapper is implemented as a PowerShell Script Module (''MS.PS.Lib.psm1'') and can thus be imported in a PowerShell session via its manifest (''MS.PS.Lib.psd1'') by using ''Import-Module''.<br />
<br />
Please open a PowerShell session and import the API wrapper module using this command:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module "C:\MailStore SPE Scripting Tutorial\PowerShell\API-Wrapper\MS.PS.Lib.psd1"<br />
</source><br />
<br />
=== Getting Information about the MailStore PowerShell API Wrapper ===<br />
The MailStore PowerShell API Wrapper provides several functions to access the MailStore SPE Management API, following PowerShell conventions. Enter the following command to get information about these features:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Module MS.PS.Lib | fl<br />
</source><br />
<br />
More detailed information is available via the module's properties. For example,<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
(Get-Module MS.PS.Lib).ExportedFunctions<br />
</source><br />
<br />
returns the functions provided by the module. Via<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Get-Help *MSApi*<br />
</source><br />
<br />
the MailStore PowerShell API Wrapper returns inline help for all its functions.<br />
<br />
== Calling API Wrapper Functions ==<br />
The following example script (''Example1.ps1'' in the tutorial package) explains the basic usage of MailStore PowerShell API Wrapper functions.<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiClient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$return = Invoke-MSApiCall $MSApiClient "GetEnvironmentInfo"<br />
$return | fl<br />
</source><br />
<br />
The function ''New-MSApiClient'' creates a new API client object, which is used by the ''Invoke-MSApiCall'' function for API calls. The values for ''-Username'' and ''-Password'' have to be supplied, while ''-ManagementServer'' defaults to "localhost" and ''-Port'' defaults to "8474". The switch ''-IgnoreInvalidSSLCerts'' has to be set if untrusted certificates are used; otherwise an error occurs.<br />
<br />
Apart from the API client object, ''Invoke-MSApiCall'' needs an [[Management_API_-_Function_Reference|API command]] and its parameters if applicable. The command ''[[Management_API_-_Function_Reference#GetEnvironmentInfo|GetEnvironmentInfo]]'' in the script does not have any parameters and returns a JSON object as follows:<br />
<br />
error : <br />
token : <br />
statusVersion : 2<br />
statusCode : succeeded<br />
percentProgress : <br />
statusText : <br />
result : @{version=9.1.0.10241; copyright=Copyright (c) 2005-2014 MailStore Software GmbH; licenseeName=MailStore; licenseeID=23634; serverName=tutorial.mailstore.test; userName=admin; systemProperties=}<br />
logOutput : <br />
<br />
The ''result'' property of that object has the actual return value if the request succeeded as indicated by the ''statusCode'':<br />
<br />
version : 9.1.0.10241<br />
copyright : Copyright (c) 2005-2014 MailStore Software GmbH<br />
licenseeName : MailStore Software GmbH<br />
licenseeID : 23634<br />
serverName : tutorial.mailstore.test<br />
userName : admin<br />
systemProperties : @{processors=System.Object[]; totalPhysicalMemory=2146947072; operatingSystem=Microsoft Windows Server 2012 Standard}<br />
<br />
=== Calling API Wrapper Functions with Parameters ===<br />
For most MailStore SPE Management API commands you need to provide parameters. Of course, the MailStore PowerShell API Wrapper's ''Invoke-MSApiCall'' function can submit these parameters, as demonstrated by the following script (''Example2.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
foreach ($instance in $instances) {<br />
$users = (Invoke-MSApiCall $MSapiclient "GetUsers" @{instanceID = $instance.instanceID}).result<br />
foreach ($user in $users) {<br />
(Invoke-MSApiCall $MSapiclient "GetUserInfo" @{instanceID = $instance.instanceID; userName = $user.userName}).result | fl<br />
}<br />
}<br />
</source><br />
<br />
The scripts lists details about the users created in the MailStore SPE instances. Because the MailStore PowerShell API Wrapper converts API responses into objects, their properties can be used directly in the script's workflow. The function ''Invoke-MSApiCall'' expects parameters as a hashtable, e.g. ''@{parametername1 = value1; parametername2 = value2;...}''. Parameter names are case sensitive.<br />
<br />
First, a list of all MailStore SPE instances is requested with the API command ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]''. This command returns an array of instances as follows:<br />
<br />
instanceID : test01<br />
alias : tutorial<br />
displayName : Tutorial Test Instance<br />
instanceHost : tutorial.mailstore.test<br />
startMode : automatic<br />
processID : 3140<br />
status : running<br />
startStopError : <br />
<br />
The script now iterates over this array using the ''instanceID'' property of each entry as a parameter for the API command ''[[Management_API_-_Function_Reference#GetUsers|GetUsers]]''. The list of users of each instance is then also iterated over and each user's properties are requested via ''[[Management_API_-_Function_Reference#GetUserInfo|GetUserInfo]]''.<br />
<br />
For the entry listed above the result could be as follows:<br />
<br />
userName : johndoe<br />
fullName : John Doe<br />
distinguishedName : <br />
authentication : integrated<br />
emailAddresses : {}<br />
pop3UserNames : {}<br />
privileges : {login, changePassword}<br />
privilegesOnFolders : {@{folder=johndoe; privileges=System.Object[]}}<br />
<br />
As can be seen in the ''privilegesOnFolders'' property, returned objects may be nested and may also contain further objects.<br />
<br />
=== Handling Asynchronous API Calls ===<br />
The server may decide to execute Management API commands asynchronously if their execution takes more time. The MailStore PowerShell API Wrapper identifies calls of such [[Management_API_-_Using_the_API#Long_Running_Processes|asynchronously executed API commands]] and executes them as [http://technet.microsoft.com/en-us/library/hh847783%28v=wps.620%29.aspx PowerShell Jobs] in the background.<br />
<br />
==== Waiting for Asynchronous API Calls to Complete ====<br />
A script's execution can be interrupted until a PowerShell Job created by the API wrapper terminates as demonstrated by the following script (''Example3.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Invoke-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
$return | fl<br />
</source><br />
<br />
The API commands ''[[Management_API_-_Function_Reference#GetInstances|GetInstances]]'' and ''[[Management_API_-_Function_Reference#VerifyStore|VerifyStore]]'' called in the script are regularly run asynchronously by the server. By using ''Invoke-MSApiCall'' the API wrapper waits for an API command that is executed asynchronously and simply returns its final result:<br />
<br />
error : <br />
token : sa4c1dd3dcf56da32e44b29215b4d60b2b<br />
statusVersion : 152<br />
statusCode : succeeded<br />
percentProgress : 100<br />
statusText : <br />
result : <br />
logOutput : <br />
<br />
==== Subscribing to Events Triggered by Asynchronous API Calls ====<br />
Instead of interrupting a script's execution, the PowerShell Jobs created by the API wrapper can be reacted to while they are running in the background. These jobs trigger a PowerShell EngineEvent with each status request that the script can subscribe to in order to execute further code on each occurrence. To demonstrate this, the previous script needs to be adapted only a bit (''Example4.ps1'' in the tutorial package):<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'<br />
$MSApiclient = New-MSApiClient -Username "admin" -Password "admin" -ManagementServer "localhost" -Port 8474 -IgnoreInvalidSSLCerts<br />
$instances = (Invoke-MSApiCall $MSApiclient "GetInstances" @{instanceFilter = "*"}).result<br />
$return = Start-MSApiCall $MSApiclient "VerifyStore" @{instanceID = $instances[0].instanceID; id = "1"}<br />
if ($return.statusCode -eq "running") {<br />
$mssevent = Register-EngineEvent -SourceIdentifier $return.Token -Action {write-host $event.MessageData}<br />
} else {<br />
$return | fl<br />
}<br />
</source><br />
By using ''Start-MSApiCall'' the API wrapper runs an API command that is executed asynchronously by the server in the background and returns its first result. The script subscribes to the event that is triggered by the background job via [http://technet.microsoft.com/en-us/library/hh849967.aspx Register-EngineEvent], using the return object's ''Token'' property as ''SourceIdentifier''. By that property the event relates to the triggering PowerShell Job and thus to the server process. The ''Action'' script block is itself created as a PowerShell Job that is executed with each triggering of the event. Through the ''MessageData'' property of the ''$event'' [http://technet.microsoft.com/en-us/library/hh847768.aspx automatic variable] the script block can access the JSON object provided by the background job. That object contains the status of the server process:<br />
<br />
@{error=; token=sae8b8eaa3f645d11ee0207797cebbc0b1; statusVersion=8;<br />
statusCode=running; percentProgress=1; statusText=; result=;<br />
logOutput= 300 messages verified...<br />
}<br />
<br />
Via these mechanisms the script can execute further tasks while monitoring the server process in the background. Execution and handling of multiple asynchronous API commands is also possible this way.<br />
<br />
==== Cancelling Asynchronous API Wrapper PowerShell Jobs ====<br />
To cancel the execution of an asynchronous API command, use ''Stop-MSApiCall'' with either the token or the JSON object. For the example above the call would be:<br />
<br />
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"><br />
Stop-MSApiCall $MSApiclient -AsyncReturnObject $return<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Python_API_Wrapper_Tutorial&diff=959Python API Wrapper Tutorial2014-02-21T13:13:56Z<p>Admin: /* Long running calls */</p>
<hr />
<div>__NOTOC__<br />
<br />
This document introduces the Python API library which allows you to administer your MailStore Service Provider Edition via Python.<br />
<br />
= Installation =<br />
<br />
The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python. <br />
<br />
You can get your Python binary from the [http://www.python.org/download/ Python download page] or you can install it using the package manager of you distribution.<br />
<br />
Additionally you need the [ftp://ftp.mailstore.com/spe/python-api-library.zip MailStore API library] which has to be installed in your Python's site-packages directory. The location of the site-packages directory can be found with the following command<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"<br />
</source><br />
<br />
= Log in =<br />
<br />
The library can be imported with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import mailstore<br />
</source><br />
You are able to instantiate the class directly<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient = mailstore.spe.Client(username="admin", password="admin", host="127.0.0.1", port=8470)<br />
</source><br />
or by using the ''with'' statement (context manager)<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(password="S3cR3t!", host="spe.domain.eu") as speClient:<br />
do_something()<br />
</source><br />
Default values can be omitted.<br />
<br />
The available log in arguments and default values are<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
username = "admin"<br />
password = "admin"<br />
host = "127.0.0.1"<br />
port = 8470<br />
autoHandleToken = True<br />
waitTime = 2000<br />
logLevel = 2<br />
fileLogLevel = 0<br />
</source><br />
When autoHandleToken is enabled, you do not have to care about long running processes, you just have to wait for the result. When this value is set to ''False'', then the status token is returned and you have to handle the token manually. More about this later.<br />
<br />
The ''waitTime'' value specifies the value that is passed to the ''get-status'' call. When you call a long running method like ''VerifyStore'', this is the maximum amount of milliseconds you have to wait for a status update.<br />
<br />
''logLevel'' and ''fileLogLevel'' have to be in the range ''0'' to ''4''. The loglevels are defined as following<br />
0 : "NONE"<br />
1 : "ERROR"<br />
2 : "WARNING"<br />
3 : "INFO" <br />
4 : "DEBUG"<br />
<br />
Log entries will be printed to ''stdout''.<br />
The logfile will be created in the user's %temp% directory and starts with the prefix ''MailStorePyLib''. ''logLevel'' and ''fileLogLevel'' do not have to match.<br />
<br />
= Log out =<br />
<br />
When you prefer the first log in method, you have to log out afterwards manually. When using the context manager method, the log out is done automatically when exiting the ''with'' block. The ''logoutHandler'' will close open log files, if necessary.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient.logoutHandler()<br />
</source><br />
= Simple calls =<br />
<br />
Simple calls will return immediately<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
print(speClient.GetEnvironmentInfo())<br />
<br />
{'antiXsrfToken': 'dUubPmGWEANyDxGbBvejCu6qSRUlkQYSiunQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'userName': 'admin', 'copyright': 'Copyright (c) 2005-2013 MailStore Software GmbH', 'systemProperties': {'totalPhysicalMemory': 2146947072, 'processors': ['Intel(R) Core(TM) i5-2400 CPU @ 3.10GHz'], 'operatingSystem': 'Microsoft Windows Server 2012 Standard'}, 'serverName': 'win2012spe', 'version': '8.5.0.9288', 'licenseeName': 'MailStore Software GmbH', 'licenseeID': 1}, 'statusVersion': 2, 'statusCode': 'succeeded'}<br />
</source><br />
When the ''statusCode'' is ''succeeded'' the information is stored in the ''result'' field. When the process has ended with another status, like ''failed'' or ''cancelled'' the diagnosis information is stored in the ''error'' field.<br />
<br />
When there are no HTTP errors, the returned value is always a python dictionary.<br />
<br />
= Simple examples =<br />
<br />
To get all user's detailed information you could<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client():<br />
instance = "test01"<br />
for user in speClient.GetUsers(instance)["result"]:<br />
print(speClient.GetUserInfo(instance, user["userName"])["result"])<br />
</source><br />
<br />
A list with all assigned email address can be retrieved with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client() as client:<br />
instID = "test01"<br />
emailaddresses = list()<br />
for user in client.GetUsers(instID)["result"]:<br />
info = client.GetUserInfo(instID, user["userName"])["result"]<br />
emailaddresses += info['emailAddresses']<br />
print(emailaddresses)<br />
</source><br />
<br />
= Long running calls =<br />
<br />
Long running calls like ''VerifyStore'' are running asynchronous on the instance. When ''autoHandleToken'' is set to ''True'' (default), the library polls the status in the background automatically and will return the final result when the process has ended. Set ''autoHandleToken'' to ''False'' to get the token. In this case you have to handle the token by youself. There are helper methods available.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
print(client.VerifyStore(instID, storeID))<br />
<br />
{'antiXsrfToken': '6h8HV67XSak+jpQ/e6X1ehLOrt9cPUGicfHQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': 'sa6431dcd1b3e48c4719cfe8a75612b88a', 'result': None, 'statusVersion': 0, 'statusCode': 'running'}<br />
</source><br />
<br />
You are able to update the status manually by passing the token to the ''GetStatus'' method. The call has finished, when the ''statusCode'' has changed from ''running'' to something else.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
token = client.VerifyStore(instID, storeID))<br />
time.sleep(5)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': '+MKktayBhloqEsqk3xNTssdwTHRxL5+UaPTQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 400 messages verified...\r\n 500 messages verified...\r\n 600 messages verified...\r\n 700 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 17, 'token': 'sa92c717e75db26fa57fc09c5e95f7096d', 'result': None, 'statusVersion': 29, 'statusCode': 'running'}<br />
</source><br />
One could pass the token to the ''HandleToken'' method, then the behavior is exactly the same, as when you would have set ''autoHandleToken=True''.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
print(client.HandleToken(token))<br />
<br />
{'antiXsrfToken': 'KIMJdCpjcuD8O5+xPislG8OysJ0fPgXQcvHQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 389 messages verified...\r\nFinished. No errors have been found.\r\n', 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'sa8e56590b28b3c57f076168d5913840df', 'result': None, 'statusVersion': 147, 'statusCode': 'succeeded'}<br />
</source><br />
Alternatively one could pass the token to the ''HandleTokenIter'' method, then every status update is yielded.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
for status in client.HandleTokenIter(client.VerifyStore(instID, storeID)):<br />
print(status)<br />
<br />
{'antiXsrfToken': 'DEF2dWnoNl7hkgsHqApPZmpsUqEgpih6c/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n', 'statusText': None, 'error': None, 'percentProgress': 0, 'token': 'safd22a51408925dd787ef43a5adc3772c', 'result': None, 'statusVersion': 5, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'a3NMb7VdnLaTOOnfyJnZWEutbmlzPXd6c/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 6, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'mi8qpqTdw6hoH+/+o6h65Rx0jiuPR4p6c/HQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 7, 'statusCode': 'running'}<br />
[...]<br />
MaintainFileSystemDatabases(self, autoHandleToken=False)<br />
</source><br />
<br />
You are able to set the token handling behavior globally and locally. When you instantiate the client with ''autoHandleToken=True'' you still are able to call every long running method with ''autoHandleToken=False'' and vice versa. Methods that do not return a token, do not accecpt the ''autoHandleToken'' parameter.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=True) as client:<br />
instID= "test01"<br />
client.MaintainFileSystemDatabases(instID, autoHandleToken=False)<br />
</source><br />
<br />
= Cancelling long running calls =<br />
<br />
If you want to cancel a long running call, you have to pass the token of that call to the ''CancelAsync'' method<br />
<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import time<br />
<br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
time.sleep(2)<br />
print(client.CancelAsync(token))<br />
time.sleep(2)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': 'DUs5EO8ZZ9A8S6lUB/uYwIsAFwTufVpCd/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': None, 'statusVersion': None, 'statusCode': None}<br />
{'antiXsrfToken': 'fYO6hoP7eKr1X1SDj++6hhwI9pTwD45Dd/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n3893 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 7, 'token': None, 'result': None, 'statusVersion': 17, 'statusCode': 'cancelled'}<br />
</source><br />
<br />
= Pretty Printing the output =<br />
<br />
There is a helper function that formats the returned values in more readable manner.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
mailstore.spe.pprint(client.GetUserInfo("test01","admin"))<br />
<br />
antiXsrfToken lVKkLrjBXeg7KcjdZ/n6050bpfdAILI9F/3QCGFkbWlu<br />
result<br />
userName admin<br />
privileges<br />
admin<br />
authentication integrated<br />
fullName admin<br />
statusVersion 2<br />
statusCode succeeded<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Python_API_Wrapper_Tutorial&diff=958Python API Wrapper Tutorial2014-02-21T13:12:47Z<p>Admin: /* Long running calls */</p>
<hr />
<div>__NOTOC__<br />
<br />
This document introduces the Python API library which allows you to administer your MailStore Service Provider Edition via Python.<br />
<br />
= Installation =<br />
<br />
The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python. <br />
<br />
You can get your Python binary from the [http://www.python.org/download/ Python download page] or you can install it using the package manager of you distribution.<br />
<br />
Additionally you need the [ftp://ftp.mailstore.com/spe/python-api-library.zip MailStore API library] which has to be installed in your Python's site-packages directory. The location of the site-packages directory can be found with the following command<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"<br />
</source><br />
<br />
= Log in =<br />
<br />
The library can be imported with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import mailstore<br />
</source><br />
You are able to instantiate the class directly<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient = mailstore.spe.Client(username="admin", password="admin", host="127.0.0.1", port=8470)<br />
</source><br />
or by using the ''with'' statement (context manager)<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(password="S3cR3t!", host="spe.domain.eu") as speClient:<br />
do_something()<br />
</source><br />
Default values can be omitted.<br />
<br />
The available log in arguments and default values are<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
username = "admin"<br />
password = "admin"<br />
host = "127.0.0.1"<br />
port = 8470<br />
autoHandleToken = True<br />
waitTime = 2000<br />
logLevel = 2<br />
fileLogLevel = 0<br />
</source><br />
When autoHandleToken is enabled, you do not have to care about long running processes, you just have to wait for the result. When this value is set to ''False'', then the status token is returned and you have to handle the token manually. More about this later.<br />
<br />
The ''waitTime'' value specifies the value that is passed to the ''get-status'' call. When you call a long running method like ''VerifyStore'', this is the maximum amount of milliseconds you have to wait for a status update.<br />
<br />
''logLevel'' and ''fileLogLevel'' have to be in the range ''0'' to ''4''. The loglevels are defined as following<br />
0 : "NONE"<br />
1 : "ERROR"<br />
2 : "WARNING"<br />
3 : "INFO" <br />
4 : "DEBUG"<br />
<br />
Log entries will be printed to ''stdout''.<br />
The logfile will be created in the user's %temp% directory and starts with the prefix ''MailStorePyLib''. ''logLevel'' and ''fileLogLevel'' do not have to match.<br />
<br />
= Log out =<br />
<br />
When you prefer the first log in method, you have to log out afterwards manually. When using the context manager method, the log out is done automatically when exiting the ''with'' block. The ''logoutHandler'' will close open log files, if necessary.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient.logoutHandler()<br />
</source><br />
= Simple calls =<br />
<br />
Simple calls will return immediately<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
print(speClient.GetEnvironmentInfo())<br />
<br />
{'antiXsrfToken': 'dUubPmGWEANyDxGbBvejCu6qSRUlkQYSiunQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'userName': 'admin', 'copyright': 'Copyright (c) 2005-2013 MailStore Software GmbH', 'systemProperties': {'totalPhysicalMemory': 2146947072, 'processors': ['Intel(R) Core(TM) i5-2400 CPU @ 3.10GHz'], 'operatingSystem': 'Microsoft Windows Server 2012 Standard'}, 'serverName': 'win2012spe', 'version': '8.5.0.9288', 'licenseeName': 'MailStore Software GmbH', 'licenseeID': 1}, 'statusVersion': 2, 'statusCode': 'succeeded'}<br />
</source><br />
When the ''statusCode'' is ''succeeded'' the information is stored in the ''result'' field. When the process has ended with another status, like ''failed'' or ''cancelled'' the diagnosis information is stored in the ''error'' field.<br />
<br />
When there are no HTTP errors, the returned value is always a python dictionary.<br />
<br />
= Simple examples =<br />
<br />
To get all user's detailed information you could<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client():<br />
instance = "test01"<br />
for user in speClient.GetUsers(instance)["result"]:<br />
print(speClient.GetUserInfo(instance, user["userName"])["result"])<br />
</source><br />
<br />
A list with all assigned email address can be retrieved with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client() as client:<br />
instID = "test01"<br />
emailaddresses = list()<br />
for user in client.GetUsers(instID)["result"]:<br />
info = client.GetUserInfo(instID, user["userName"])["result"]<br />
emailaddresses += info['emailAddresses']<br />
print(emailaddresses)<br />
</source><br />
<br />
= Long running calls =<br />
<br />
Long running calls like ''VerifyStore'' are running asynchronous on the instance. When ''autoHandleToken'' is set to ''True'' (default), the library polls the status in the background automatically and will return the final result when the process has ended. Set ''autoHandleToken'' to ''False'' to get the token. In this case you have to handle the token by youself. There are helper methods available.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
print(client.VerifyStore(instID, storeID))<br />
<br />
{'antiXsrfToken': '6h8HV67XSak+jpQ/e6X1ehLOrt9cPUGicfHQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': 'sa6431dcd1b3e48c4719cfe8a75612b88a', 'result': None, 'statusVersion': 0, 'statusCode': 'running'}<br />
</source><br />
<br />
You are able to update the status manually by passing the token to the ''GetStatus'' method. The call has finished, when the ''statusCode'' has changed from ''running'' to something else.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
token = client.VerifyStore(instID, storeID))<br />
time.sleep(5)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': '+MKktayBhloqEsqk3xNTssdwTHRxL5+UaPTQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 400 messages verified...\r\n 500 messages verified...\r\n 600 messages verified...\r\n 700 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 17, 'token': 'sa92c717e75db26fa57fc09c5e95f7096d', 'result': None, 'statusVersion': 29, 'statusCode': 'running'}<br />
</source><br />
One could pass the token to the ''HandleToken'' method, then the behavior is exactly the same, as when you would have set ''autoHandleToken=True''.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
print(client.HandleToken(token))<br />
<br />
{'antiXsrfToken': 'KIMJdCpjcuD8O5+xPislG8OysJ0fPgXQcvHQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 389 messages verified...\r\nFinished. No errors have been found.\r\n', 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'sa8e56590b28b3c57f076168d5913840df', 'result': None, 'statusVersion': 147, 'statusCode': 'succeeded'}<br />
</source><br />
Alternatively one could pass the token to the ''HandleTokenIter'' method, then every status update is yielded.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
for status in client.HandleTokenIter(client.VerifyStore(instID, storeID)):<br />
print(status)<br />
<br />
{'antiXsrfToken': 'DEF2dWnoNl7hkgsHqApPZmpsUqEgpih6c/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n', 'statusText': None, 'error': None, 'percentProgress': 0, 'token': 'safd22a51408925dd787ef43a5adc3772c', 'result': None, 'statusVersion': 5, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'a3NMb7VdnLaTOOnfyJnZWEutbmlzPXd6c/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 6, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'mi8qpqTdw6hoH+/+o6h65Rx0jiuPR4p6c/HQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 7, 'statusCode': 'running'}<br />
[...]<br />
MaintainFileSystemDatabases(self, autoHandleToken=False)<br />
</source><br />
<br />
You are able to set the token handling behavior globally and locally. When you instantiate the client with ''autoHandleToken=True'' you still are able to call every method with ''autoHandleToken=False'' and vice versa.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=True) as client:<br />
instID= "test01"<br />
client.MaintainFileSystemDatabases(instID, autoHandleToken=False)<br />
</source><br />
<br />
= Cancelling long running calls =<br />
<br />
If you want to cancel a long running call, you have to pass the token of that call to the ''CancelAsync'' method<br />
<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import time<br />
<br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
time.sleep(2)<br />
print(client.CancelAsync(token))<br />
time.sleep(2)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': 'DUs5EO8ZZ9A8S6lUB/uYwIsAFwTufVpCd/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': None, 'statusVersion': None, 'statusCode': None}<br />
{'antiXsrfToken': 'fYO6hoP7eKr1X1SDj++6hhwI9pTwD45Dd/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n3893 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 7, 'token': None, 'result': None, 'statusVersion': 17, 'statusCode': 'cancelled'}<br />
</source><br />
<br />
= Pretty Printing the output =<br />
<br />
There is a helper function that formats the returned values in more readable manner.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
mailstore.spe.pprint(client.GetUserInfo("test01","admin"))<br />
<br />
antiXsrfToken lVKkLrjBXeg7KcjdZ/n6050bpfdAILI9F/3QCGFkbWlu<br />
result<br />
userName admin<br />
privileges<br />
admin<br />
authentication integrated<br />
fullName admin<br />
statusVersion 2<br />
statusCode succeeded<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Python_API_Wrapper_Tutorial&diff=957Python API Wrapper Tutorial2014-02-21T13:10:45Z<p>Admin: /* Long running calls */</p>
<hr />
<div>__NOTOC__<br />
<br />
This document introduces the Python API library which allows you to administer your MailStore Service Provider Edition via Python.<br />
<br />
= Installation =<br />
<br />
The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python. <br />
<br />
You can get your Python binary from the [http://www.python.org/download/ Python download page] or you can install it using the package manager of you distribution.<br />
<br />
Additionally you need the [ftp://ftp.mailstore.com/spe/python-api-library.zip MailStore API library] which has to be installed in your Python's site-packages directory. The location of the site-packages directory can be found with the following command<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"<br />
</source><br />
<br />
= Log in =<br />
<br />
The library can be imported with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import mailstore<br />
</source><br />
You are able to instantiate the class directly<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient = mailstore.spe.Client(username="admin", password="admin", host="127.0.0.1", port=8470)<br />
</source><br />
or by using the ''with'' statement (context manager)<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(password="S3cR3t!", host="spe.domain.eu") as speClient:<br />
do_something()<br />
</source><br />
Default values can be omitted.<br />
<br />
The available log in arguments and default values are<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
username = "admin"<br />
password = "admin"<br />
host = "127.0.0.1"<br />
port = 8470<br />
autoHandleToken = True<br />
waitTime = 2000<br />
logLevel = 2<br />
fileLogLevel = 0<br />
</source><br />
When autoHandleToken is enabled, you do not have to care about long running processes, you just have to wait for the result. When this value is set to ''False'', then the status token is returned and you have to handle the token manually. More about this later.<br />
<br />
The ''waitTime'' value specifies the value that is passed to the ''get-status'' call. When you call a long running method like ''VerifyStore'', this is the maximum amount of milliseconds you have to wait for a status update.<br />
<br />
''logLevel'' and ''fileLogLevel'' have to be in the range ''0'' to ''4''. The loglevels are defined as following<br />
0 : "NONE"<br />
1 : "ERROR"<br />
2 : "WARNING"<br />
3 : "INFO" <br />
4 : "DEBUG"<br />
<br />
Log entries will be printed to ''stdout''.<br />
The logfile will be created in the user's %temp% directory and starts with the prefix ''MailStorePyLib''. ''logLevel'' and ''fileLogLevel'' do not have to match.<br />
<br />
= Log out =<br />
<br />
When you prefer the first log in method, you have to log out afterwards manually. When using the context manager method, the log out is done automatically when exiting the ''with'' block. The ''logoutHandler'' will close open log files, if necessary.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient.logoutHandler()<br />
</source><br />
= Simple calls =<br />
<br />
Simple calls will return immediately<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
print(speClient.GetEnvironmentInfo())<br />
<br />
{'antiXsrfToken': 'dUubPmGWEANyDxGbBvejCu6qSRUlkQYSiunQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'userName': 'admin', 'copyright': 'Copyright (c) 2005-2013 MailStore Software GmbH', 'systemProperties': {'totalPhysicalMemory': 2146947072, 'processors': ['Intel(R) Core(TM) i5-2400 CPU @ 3.10GHz'], 'operatingSystem': 'Microsoft Windows Server 2012 Standard'}, 'serverName': 'win2012spe', 'version': '8.5.0.9288', 'licenseeName': 'MailStore Software GmbH', 'licenseeID': 1}, 'statusVersion': 2, 'statusCode': 'succeeded'}<br />
</source><br />
When the ''statusCode'' is ''succeeded'' the information is stored in the ''result'' field. When the process has ended with another status, like ''failed'' or ''cancelled'' the diagnosis information is stored in the ''error'' field.<br />
<br />
When there are no HTTP errors, the returned value is always a python dictionary.<br />
<br />
= Simple examples =<br />
<br />
To get all user's detailed information you could<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client():<br />
instance = "test01"<br />
for user in speClient.GetUsers(instance)["result"]:<br />
print(speClient.GetUserInfo(instance, user["userName"])["result"])<br />
</source><br />
<br />
A list with all assigned email address can be retrieved with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client() as client:<br />
instID = "test01"<br />
emailaddresses = list()<br />
for user in client.GetUsers(instID)["result"]:<br />
info = client.GetUserInfo(instID, user["userName"])["result"]<br />
emailaddresses += info['emailAddresses']<br />
print(emailaddresses)<br />
</source><br />
<br />
= Long running calls =<br />
<br />
Long running calls like ''VerifyStore'' are running asynchronous on the instance. When ''autoHandleToken'' is set to ''True'' (default), the library polls the status in the background automatically and will return the final result when the process has ended. Set ''autoHandleToken'' to ''False'' to get the token. In this case you have to handle the token by youself. There are helper methods available.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
print(client.VerifyStore(instID, storeID))<br />
<br />
{'antiXsrfToken': '6h8HV67XSak+jpQ/e6X1ehLOrt9cPUGicfHQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': 'sa6431dcd1b3e48c4719cfe8a75612b88a', 'result': None, 'statusVersion': 0, 'statusCode': 'running'}<br />
</source><br />
<br />
You are able to update the status manually by passing the token to the ''GetStatus'' method. The call has finished, when the ''statusCode'' has changed from ''running'' to something else.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
token = client.VerifyStore(instID, storeID))<br />
time.sleep(5)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': '+MKktayBhloqEsqk3xNTssdwTHRxL5+UaPTQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 400 messages verified...\r\n 500 messages verified...\r\n 600 messages verified...\r\n 700 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 17, 'token': 'sa92c717e75db26fa57fc09c5e95f7096d', 'result': None, 'statusVersion': 29, 'statusCode': 'running'}<br />
</source><br />
One could pass the token to the ''HandleToken'' method, then the behavior is exactly the same, as when you would have set ''autoHandleToken=True''.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
print(client.HandleToken(token))<br />
<br />
{'antiXsrfToken': 'KIMJdCpjcuD8O5+xPislG8OysJ0fPgXQcvHQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 389 messages verified...\r\nFinished. No errors have been found.\r\n', 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'sa8e56590b28b3c57f076168d5913840df', 'result': None, 'statusVersion': 147, 'statusCode': 'succeeded'}<br />
</source><br />
Alternatively one could pass the token to the ''HandleTokenIter'' method, then every status update is yielded.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
for status in client.HandleTokenIter(client.VerifyStore(instID, storeID)):<br />
print(status)<br />
<br />
{'antiXsrfToken': 'DEF2dWnoNl7hkgsHqApPZmpsUqEgpih6c/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n', 'statusText': None, 'error': None, 'percentProgress': 0, 'token': 'safd22a51408925dd787ef43a5adc3772c', 'result': None, 'statusVersion': 5, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'a3NMb7VdnLaTOOnfyJnZWEutbmlzPXd6c/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 6, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'mi8qpqTdw6hoH+/+o6h65Rx0jiuPR4p6c/HQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 7, 'statusCode': 'running'}<br />
[...]<br />
MaintainFileSystemDatabases(self, autoHandleToken=False)<br />
</source><br />
<br />
You are able to set the token handling behavior globally and locally. When you instantiate the client with ''autoHandleToken=True'' you still are able to call every method with different behavior.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=True) as client:<br />
instID= "test01"<br />
client.MaintainFileSystemDatabases(instID, autoHandleToken=False)<br />
</source><br />
<br />
= Cancelling long running calls =<br />
<br />
If you want to cancel a long running call, you have to pass the token of that call to the ''CancelAsync'' method<br />
<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import time<br />
<br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
time.sleep(2)<br />
print(client.CancelAsync(token))<br />
time.sleep(2)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': 'DUs5EO8ZZ9A8S6lUB/uYwIsAFwTufVpCd/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': None, 'statusVersion': None, 'statusCode': None}<br />
{'antiXsrfToken': 'fYO6hoP7eKr1X1SDj++6hhwI9pTwD45Dd/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n3893 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 7, 'token': None, 'result': None, 'statusVersion': 17, 'statusCode': 'cancelled'}<br />
</source><br />
<br />
= Pretty Printing the output =<br />
<br />
There is a helper function that formats the returned values in more readable manner.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
mailstore.spe.pprint(client.GetUserInfo("test01","admin"))<br />
<br />
antiXsrfToken lVKkLrjBXeg7KcjdZ/n6050bpfdAILI9F/3QCGFkbWlu<br />
result<br />
userName admin<br />
privileges<br />
admin<br />
authentication integrated<br />
fullName admin<br />
statusVersion 2<br />
statusCode succeeded<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Python_API_Wrapper_Tutorial&diff=956Python API Wrapper Tutorial2014-02-21T13:09:45Z<p>Admin: /* Long running calls */</p>
<hr />
<div>__NOTOC__<br />
<br />
This document introduces the Python API library which allows you to administer your MailStore Service Provider Edition via Python.<br />
<br />
= Installation =<br />
<br />
The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python. <br />
<br />
You can get your Python binary from the [http://www.python.org/download/ Python download page] or you can install it using the package manager of you distribution.<br />
<br />
Additionally you need the [ftp://ftp.mailstore.com/spe/python-api-library.zip MailStore API library] which has to be installed in your Python's site-packages directory. The location of the site-packages directory can be found with the following command<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"<br />
</source><br />
<br />
= Log in =<br />
<br />
The library can be imported with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import mailstore<br />
</source><br />
You are able to instantiate the class directly<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient = mailstore.spe.Client(username="admin", password="admin", host="127.0.0.1", port=8470)<br />
</source><br />
or by using the ''with'' statement (context manager)<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(password="S3cR3t!", host="spe.domain.eu") as speClient:<br />
do_something()<br />
</source><br />
Default values can be omitted.<br />
<br />
The available log in arguments and default values are<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
username = "admin"<br />
password = "admin"<br />
host = "127.0.0.1"<br />
port = 8470<br />
autoHandleToken = True<br />
waitTime = 2000<br />
logLevel = 2<br />
fileLogLevel = 0<br />
</source><br />
When autoHandleToken is enabled, you do not have to care about long running processes, you just have to wait for the result. When this value is set to ''False'', then the status token is returned and you have to handle the token manually. More about this later.<br />
<br />
The ''waitTime'' value specifies the value that is passed to the ''get-status'' call. When you call a long running method like ''VerifyStore'', this is the maximum amount of milliseconds you have to wait for a status update.<br />
<br />
''logLevel'' and ''fileLogLevel'' have to be in the range ''0'' to ''4''. The loglevels are defined as following<br />
0 : "NONE"<br />
1 : "ERROR"<br />
2 : "WARNING"<br />
3 : "INFO" <br />
4 : "DEBUG"<br />
<br />
Log entries will be printed to ''stdout''.<br />
The logfile will be created in the user's %temp% directory and starts with the prefix ''MailStorePyLib''. ''logLevel'' and ''fileLogLevel'' do not have to match.<br />
<br />
= Log out =<br />
<br />
When you prefer the first log in method, you have to log out afterwards manually. When using the context manager method, the log out is done automatically when exiting the ''with'' block. The ''logoutHandler'' will close open log files, if necessary.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient.logoutHandler()<br />
</source><br />
= Simple calls =<br />
<br />
Simple calls will return immediately<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
print(speClient.GetEnvironmentInfo())<br />
<br />
{'antiXsrfToken': 'dUubPmGWEANyDxGbBvejCu6qSRUlkQYSiunQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'userName': 'admin', 'copyright': 'Copyright (c) 2005-2013 MailStore Software GmbH', 'systemProperties': {'totalPhysicalMemory': 2146947072, 'processors': ['Intel(R) Core(TM) i5-2400 CPU @ 3.10GHz'], 'operatingSystem': 'Microsoft Windows Server 2012 Standard'}, 'serverName': 'win2012spe', 'version': '8.5.0.9288', 'licenseeName': 'MailStore Software GmbH', 'licenseeID': 1}, 'statusVersion': 2, 'statusCode': 'succeeded'}<br />
</source><br />
When the ''statusCode'' is ''succeeded'' the information is stored in the ''result'' field. When the process has ended with another status, like ''failed'' or ''cancelled'' the diagnosis information is stored in the ''error'' field.<br />
<br />
When there are no HTTP errors, the returned value is always a python dictionary.<br />
<br />
= Simple examples =<br />
<br />
To get all user's detailed information you could<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client():<br />
instance = "test01"<br />
for user in speClient.GetUsers(instance)["result"]:<br />
print(speClient.GetUserInfo(instance, user["userName"])["result"])<br />
</source><br />
<br />
A list with all assigned email address can be retrieved with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client() as client:<br />
instID = "test01"<br />
emailaddresses = list()<br />
for user in client.GetUsers(instID)["result"]:<br />
info = client.GetUserInfo(instID, user["userName"])["result"]<br />
emailaddresses += info['emailAddresses']<br />
print(emailaddresses)<br />
</source><br />
<br />
= Long running calls =<br />
<br />
Long running calls like ''VerifyStore'' are running asynchronous on the instance. When ''autoHandleToken'' is set to ''True'' (default), the library polls the status in the background automatically and will return the final result when the process has ended. Set ''autoHandleToken'' to ''False'' to get the token. In this case you have to handle the token by youself. There are helper methods available.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
print(client.VerifyStore(instID, storeID))<br />
<br />
{'antiXsrfToken': '6h8HV67XSak+jpQ/e6X1ehLOrt9cPUGicfHQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': 'sa6431dcd1b3e48c4719cfe8a75612b88a', 'result': None, 'statusVersion': 0, 'statusCode': 'running'}<br />
</source><br />
<br />
You are able to update the status manually by passing the token to the ''GetStatus'' method. The call has finished, when the ''statusCode'' has changed from ''running'' to something else.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
token = client.VerifyStore(instID, storeID))<br />
time.sleep(5)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': '+MKktayBhloqEsqk3xNTssdwTHRxL5+UaPTQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 400 messages verified...\r\n 500 messages verified...\r\n 600 messages verified...\r\n 700 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 17, 'token': 'sa92c717e75db26fa57fc09c5e95f7096d', 'result': None, 'statusVersion': 29, 'statusCode': 'running'}<br />
</source><br />
One could pass the token to the ''HandleToken'' method, then the behavior is exactly the same, as when you would have set ''autoHandleToken=True''.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
print(client.HandleToken(token))<br />
<br />
{'antiXsrfToken': 'KIMJdCpjcuD8O5+xPislG8OysJ0fPgXQcvHQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 389 messages verified...\r\nFinished. No errors have been found.\r\n', 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'sa8e56590b28b3c57f076168d5913840df', 'result': None, 'statusVersion': 147, 'statusCode': 'succeeded'}<br />
</source><br />
Alternatively one could pass the token to the ''HandleTokenIter'' method, then every status update is yielded.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
for status in client.HandleTokenIter(client.VerifyStore(instID, storeID)):<br />
print(status)<br />
<br />
{'antiXsrfToken': 'DEF2dWnoNl7hkgsHqApPZmpsUqEgpih6c/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n', 'statusText': None, 'error': None, 'percentProgress': 0, 'token': 'safd22a51408925dd787ef43a5adc3772c', 'result': None, 'statusVersion': 5, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'a3NMb7VdnLaTOOnfyJnZWEutbmlzPXd6c/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 6, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'mi8qpqTdw6hoH+/+o6h65Rx0jiuPR4p6c/HQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 7, 'statusCode': 'running'}<br />
[...]<br />
MaintainFileSystemDatabases(self, autoHandleToken=False)<br />
</source><br />
<br />
You are able to set the token handling behavior globally and locally. When you instantiate the client with ''autoHandleToken=True'' you still are able to call ever with differnt behavior.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=True) as client:<br />
instID= "test01"<br />
client.MaintainFileSystemDatabases(instID, autoHandleToken=False)<br />
</source><br />
<br />
= Cancelling long running calls =<br />
<br />
If you want to cancel a long running call, you have to pass the token of that call to the ''CancelAsync'' method<br />
<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import time<br />
<br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
time.sleep(2)<br />
print(client.CancelAsync(token))<br />
time.sleep(2)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': 'DUs5EO8ZZ9A8S6lUB/uYwIsAFwTufVpCd/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': None, 'statusVersion': None, 'statusCode': None}<br />
{'antiXsrfToken': 'fYO6hoP7eKr1X1SDj++6hhwI9pTwD45Dd/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n3893 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 7, 'token': None, 'result': None, 'statusVersion': 17, 'statusCode': 'cancelled'}<br />
</source><br />
<br />
= Pretty Printing the output =<br />
<br />
There is a helper function that formats the returned values in more readable manner.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
mailstore.spe.pprint(client.GetUserInfo("test01","admin"))<br />
<br />
antiXsrfToken lVKkLrjBXeg7KcjdZ/n6050bpfdAILI9F/3QCGFkbWlu<br />
result<br />
userName admin<br />
privileges<br />
admin<br />
authentication integrated<br />
fullName admin<br />
statusVersion 2<br />
statusCode succeeded<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Python_API_Wrapper_Tutorial&diff=955Python API Wrapper Tutorial2014-02-21T12:34:43Z<p>Admin: /* Long running calls */</p>
<hr />
<div>__NOTOC__<br />
<br />
This document introduces the Python API library which allows you to administer your MailStore Service Provider Edition via Python.<br />
<br />
= Installation =<br />
<br />
The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python. <br />
<br />
You can get your Python binary from the [http://www.python.org/download/ Python download page] or you can install it using the package manager of you distribution.<br />
<br />
Additionally you need the [ftp://ftp.mailstore.com/spe/python-api-library.zip MailStore API library] which has to be installed in your Python's site-packages directory. The location of the site-packages directory can be found with the following command<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"<br />
</source><br />
<br />
= Log in =<br />
<br />
The library can be imported with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import mailstore<br />
</source><br />
You are able to instantiate the class directly<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient = mailstore.spe.Client(username="admin", password="admin", host="127.0.0.1", port=8470)<br />
</source><br />
or by using the ''with'' statement (context manager)<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(password="S3cR3t!", host="spe.domain.eu") as speClient:<br />
do_something()<br />
</source><br />
Default values can be omitted.<br />
<br />
The available log in arguments and default values are<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
username = "admin"<br />
password = "admin"<br />
host = "127.0.0.1"<br />
port = 8470<br />
autoHandleToken = True<br />
waitTime = 2000<br />
logLevel = 2<br />
fileLogLevel = 0<br />
</source><br />
When autoHandleToken is enabled, you do not have to care about long running processes, you just have to wait for the result. When this value is set to ''False'', then the status token is returned and you have to handle the token manually. More about this later.<br />
<br />
The ''waitTime'' value specifies the value that is passed to the ''get-status'' call. When you call a long running method like ''VerifyStore'', this is the maximum amount of milliseconds you have to wait for a status update.<br />
<br />
''logLevel'' and ''fileLogLevel'' have to be in the range ''0'' to ''4''. The loglevels are defined as following<br />
0 : "NONE"<br />
1 : "ERROR"<br />
2 : "WARNING"<br />
3 : "INFO" <br />
4 : "DEBUG"<br />
<br />
Log entries will be printed to ''stdout''.<br />
The logfile will be created in the user's %temp% directory and starts with the prefix ''MailStorePyLib''. ''logLevel'' and ''fileLogLevel'' do not have to match.<br />
<br />
= Log out =<br />
<br />
When you prefer the first log in method, you have to log out afterwards manually. When using the context manager method, the log out is done automatically when exiting the ''with'' block. The ''logoutHandler'' will close open log files, if necessary.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient.logoutHandler()<br />
</source><br />
= Simple calls =<br />
<br />
Simple calls will return immediately<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
print(speClient.GetEnvironmentInfo())<br />
<br />
{'antiXsrfToken': 'dUubPmGWEANyDxGbBvejCu6qSRUlkQYSiunQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'userName': 'admin', 'copyright': 'Copyright (c) 2005-2013 MailStore Software GmbH', 'systemProperties': {'totalPhysicalMemory': 2146947072, 'processors': ['Intel(R) Core(TM) i5-2400 CPU @ 3.10GHz'], 'operatingSystem': 'Microsoft Windows Server 2012 Standard'}, 'serverName': 'win2012spe', 'version': '8.5.0.9288', 'licenseeName': 'MailStore Software GmbH', 'licenseeID': 1}, 'statusVersion': 2, 'statusCode': 'succeeded'}<br />
</source><br />
When the ''statusCode'' is ''succeeded'' the information is stored in the ''result'' field. When the process has ended with another status, like ''failed'' or ''cancelled'' the diagnosis information is stored in the ''error'' field.<br />
<br />
When there are no HTTP errors, the returned value is always a python dictionary.<br />
<br />
= Simple examples =<br />
<br />
To get all user's detailed information you could<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client():<br />
instance = "test01"<br />
for user in speClient.GetUsers(instance)["result"]:<br />
print(speClient.GetUserInfo(instance, user["userName"])["result"])<br />
</source><br />
<br />
A list with all assigned email address can be retrieved with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client() as client:<br />
instID = "test01"<br />
emailaddresses = list()<br />
for user in client.GetUsers(instID)["result"]:<br />
info = client.GetUserInfo(instID, user["userName"])["result"]<br />
emailaddresses += info['emailAddresses']<br />
print(emailaddresses)<br />
</source><br />
<br />
= Long running calls =<br />
<br />
Long running calls like ''VerifyStore'' are running asynchronous on the instance. When ''autoHandleToken'' is set to ''True'' (default), the library polls the status in the background automatically and will return the final result when the process has ended. Set ''autoHandleToken'' to ''False'' to get the token. In this case you have to handle the token by youself. There are helper methods available.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
print(client.VerifyStore(instID, storeID))<br />
<br />
{'antiXsrfToken': '6h8HV67XSak+jpQ/e6X1ehLOrt9cPUGicfHQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': 'sa6431dcd1b3e48c4719cfe8a75612b88a', 'result': None, 'statusVersion': 0, 'statusCode': 'running'}<br />
</source><br />
<br />
You are able to update the status manually by passing the token to the ''GetStatus'' method. The call has finished, when the ''statusCode'' has changed from ''running'' to something else.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
token = client.VerifyStore(instID, storeID))<br />
time.sleep(5)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': '+MKktayBhloqEsqk3xNTssdwTHRxL5+UaPTQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 400 messages verified...\r\n 500 messages verified...\r\n 600 messages verified...\r\n 700 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 17, 'token': 'sa92c717e75db26fa57fc09c5e95f7096d', 'result': None, 'statusVersion': 29, 'statusCode': 'running'}<br />
</source><br />
One could pass the token to the ''HandleToken'' method, then the behavior is exactly the same, as when you would have set ''autoHandleToken=True''.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
print(client.HandleToken(token))<br />
<br />
{'antiXsrfToken': 'KIMJdCpjcuD8O5+xPislG8OysJ0fPgXQcvHQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 389 messages verified...\r\nFinished. No errors have been found.\r\n', 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'sa8e56590b28b3c57f076168d5913840df', 'result': None, 'statusVersion': 147, 'statusCode': 'succeeded'}<br />
</source><br />
Alternatively one could pass the token to the ''HandleTokenIter'' method, then every status update is yielded.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
for status in client.HandleTokenIter(client.VerifyStore(instID, storeID)):<br />
print(status)<br />
<br />
{'antiXsrfToken': 'DEF2dWnoNl7hkgsHqApPZmpsUqEgpih6c/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n', 'statusText': None, 'error': None, 'percentProgress': 0, 'token': 'safd22a51408925dd787ef43a5adc3772c', 'result': None, 'statusVersion': 5, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'a3NMb7VdnLaTOOnfyJnZWEutbmlzPXd6c/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 6, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'mi8qpqTdw6hoH+/+o6h65Rx0jiuPR4p6c/HQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 7, 'statusCode': 'running'}<br />
[...]<br />
</source><br />
<br />
= Cancelling long running calls =<br />
<br />
If you want to cancel a long running call, you have to pass the token of that call to the ''CancelAsync'' method<br />
<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import time<br />
<br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
time.sleep(2)<br />
print(client.CancelAsync(token))<br />
time.sleep(2)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': 'DUs5EO8ZZ9A8S6lUB/uYwIsAFwTufVpCd/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': None, 'statusVersion': None, 'statusCode': None}<br />
{'antiXsrfToken': 'fYO6hoP7eKr1X1SDj++6hhwI9pTwD45Dd/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n3893 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 7, 'token': None, 'result': None, 'statusVersion': 17, 'statusCode': 'cancelled'}<br />
</source><br />
<br />
= Pretty Printing the output =<br />
<br />
There is a helper function that formats the returned values in more readable manner.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
mailstore.spe.pprint(client.GetUserInfo("test01","admin"))<br />
<br />
antiXsrfToken lVKkLrjBXeg7KcjdZ/n6050bpfdAILI9F/3QCGFkbWlu<br />
result<br />
userName admin<br />
privileges<br />
admin<br />
authentication integrated<br />
fullName admin<br />
statusVersion 2<br />
statusCode succeeded<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Main_Page&diff=954Main Page2014-02-21T12:33:12Z<p>Admin: /* Management API */</p>
<hr />
<div>__NOTOC__<br />
{{DISPLAYTITLE:MailStore Service Provider Edition Help}}<br />
<br />
Service providers receive an unlimited, scalable software solution with MailStore Service Provider Edition, which they will be able to independently operate either on their existing IT infrastructures or those they have leased. This help website has an exclusive focus on installing and setting up the backend of the MailStore Service Provider Edition. For administration of MailStore Instances, which is comparable to the on-premises solution MailStore Server, please visit the [http://en.help.mailstore.com/ MailStore Server Help]<br />
<br />
{| <br />
| style="vertical-align: top; width: 50%" |<br />
= General Information =<br />
An introduction to the architecture, the most typical usage scenarios of the MailStore Service Provider Edition and further general yet important information are given by the following articles:<br />
<br />
* [[Overview]]<br />
* [[Performance and Scalability Guidelines]]<br />
* [[Frequently Asked Questions]]<br />
| style="vertical-align: top; width: 50%" |<br />
= Installation and Setup =<br />
The ''Installation and Setup'' chapter provides an entire walkthrough of installation and setup process of MailStore Service Provider Edition. Each article ends with a "What to do next" section that guides to the next step.<br />
<br />
* [[System Requirements]]<br />
* [[Installing MailStore Service Provider Edition]]<br />
* [[Firewall Configuration]]<br />
* [[Single Server Mode Setup]] or [[Multi Server Mode Setup]]<br />
* [[Replace Self-signed SSL Certificates]]<br />
* [[Branding]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Management Console =<br />
The MailStore Management Console is the primary, web based administration utility for MailStore Service Provider Edition administrators. The following articles provide a general overview of all available functions. Every function of the Management Console also has a corresponding [[Management API - Function Reference|Management API command]], which allows full, script-based control over MailStore Service Provider Edition.<br />
<br />
* [[Management_Console|Logging On & Navigation]]<br />
* [[Management_Console_-_General|General]]<br />
* [[Management_Console_-_Infrastructure|Infrastructure]]<br />
* [[Management_Console_-_Security|Security]]<br />
* [[Management_Console_-_Developer|Developer]]<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Instance Management =<br />
Managing MailStore Instances consist of two main areas: ''General Administration'' covers all aspects of creating, controlling and configuring instances, whereas ''Instance Administration'' deals with the administration of internal parameters for each instance such as archive stores, search indexes, user synchronization, archiving profiles, etc.<br />
<br />
* [[Instance Management - General Administration| General Administration]]<br />
* [[Instance Management - Instance Administration | Instance Administration]]<br />
<br />
= Related Articles =<br />
<br />
* [[Backup and Restore]]<br />
* [[Application Integration|Directory Service: Application Integration]]<br />
* [[Generic LDAP Integration|Directory Service: Generic LDAP Integration]]<br />
* [[End Customer Access]]<br />
* [[Startup Scripts]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Management API =<br />
The Management API extends the management capabilities of the MailStore Service Provider Edition by providing a HTTP based access to all management functions. This allows to fully automate the administration of MailStore Service Provider Edition 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.<br />
<br />
* [[Management API - Using the API|Using the API]]<br />
* [[Management API - Function Reference|Function Reference]]<br />
* [[Management API - Command Line Client|Command Line Client]]<br />
: '''Example Implementation of API Libraries'''<br />
:* [[PowerShell_API_Wrapper_Tutorial|PowerShell]]<br />
:* [[Python Library|Python]]<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Downloads =<br />
<br />
:'''Active Directory Group Policy Templates'''<br />
<br />
* [ftp://ftp.mailstore.com/spe/MailStoreSPE_ADM.zip ADM-Template]<br />
* [ftp://ftp.mailstore.com/spe/MailStoreSPE_ADMX.zip ADMX-Template]<br />
<br />
:'''Example API Libraries and Clients'''<br />
* [ftp://ftp.mailstore.com/pub/Scripts/PowerShell/MSSPE.PS.Lib.zip PowerShell Library]<br />
* Python Library<br />
* [ftp://ftp.mailstore.com/spe/MailStoreSPE_Linux_Management_API_Client.zip Linux Management API Client]<br />
|}</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Main_Page&diff=953Main Page2014-02-21T12:32:54Z<p>Admin: /* Management API */</p>
<hr />
<div>__NOTOC__<br />
{{DISPLAYTITLE:MailStore Service Provider Edition Help}}<br />
<br />
Service providers receive an unlimited, scalable software solution with MailStore Service Provider Edition, which they will be able to independently operate either on their existing IT infrastructures or those they have leased. This help website has an exclusive focus on installing and setting up the backend of the MailStore Service Provider Edition. For administration of MailStore Instances, which is comparable to the on-premises solution MailStore Server, please visit the [http://en.help.mailstore.com/ MailStore Server Help]<br />
<br />
{| <br />
| style="vertical-align: top; width: 50%" |<br />
= General Information =<br />
An introduction to the architecture, the most typical usage scenarios of the MailStore Service Provider Edition and further general yet important information are given by the following articles:<br />
<br />
* [[Overview]]<br />
* [[Performance and Scalability Guidelines]]<br />
* [[Frequently Asked Questions]]<br />
| style="vertical-align: top; width: 50%" |<br />
= Installation and Setup =<br />
The ''Installation and Setup'' chapter provides an entire walkthrough of installation and setup process of MailStore Service Provider Edition. Each article ends with a "What to do next" section that guides to the next step.<br />
<br />
* [[System Requirements]]<br />
* [[Installing MailStore Service Provider Edition]]<br />
* [[Firewall Configuration]]<br />
* [[Single Server Mode Setup]] or [[Multi Server Mode Setup]]<br />
* [[Replace Self-signed SSL Certificates]]<br />
* [[Branding]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Management Console =<br />
The MailStore Management Console is the primary, web based administration utility for MailStore Service Provider Edition administrators. The following articles provide a general overview of all available functions. Every function of the Management Console also has a corresponding [[Management API - Function Reference|Management API command]], which allows full, script-based control over MailStore Service Provider Edition.<br />
<br />
* [[Management_Console|Logging On & Navigation]]<br />
* [[Management_Console_-_General|General]]<br />
* [[Management_Console_-_Infrastructure|Infrastructure]]<br />
* [[Management_Console_-_Security|Security]]<br />
* [[Management_Console_-_Developer|Developer]]<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Instance Management =<br />
Managing MailStore Instances consist of two main areas: ''General Administration'' covers all aspects of creating, controlling and configuring instances, whereas ''Instance Administration'' deals with the administration of internal parameters for each instance such as archive stores, search indexes, user synchronization, archiving profiles, etc.<br />
<br />
* [[Instance Management - General Administration| General Administration]]<br />
* [[Instance Management - Instance Administration | Instance Administration]]<br />
<br />
= Related Articles =<br />
<br />
* [[Backup and Restore]]<br />
* [[Application Integration|Directory Service: Application Integration]]<br />
* [[Generic LDAP Integration|Directory Service: Generic LDAP Integration]]<br />
* [[End Customer Access]]<br />
* [[Startup Scripts]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Management API =<br />
The Management API extends the management capabilities of the MailStore Service Provider Edition by providing a HTTP based access to all management functions. This allows to fully automate the administration of MailStore Service Provider Edition 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.<br />
<br />
* [[Management API - Using the API|Using the API]]<br />
* [[Management API - Function Reference|Function Reference]]<br />
* [[Management API - Command Line Client|Command Line Client]]<br />
: '''Example Implementation of API Libraries'''<br />
:* [[PowerShell_API_Wrapper_Tutorial|PowerShell]]<br />
:* [[Python Library]]<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Downloads =<br />
<br />
:'''Active Directory Group Policy Templates'''<br />
<br />
* [ftp://ftp.mailstore.com/spe/MailStoreSPE_ADM.zip ADM-Template]<br />
* [ftp://ftp.mailstore.com/spe/MailStoreSPE_ADMX.zip ADMX-Template]<br />
<br />
:'''Example API Libraries and Clients'''<br />
* [ftp://ftp.mailstore.com/pub/Scripts/PowerShell/MSSPE.PS.Lib.zip PowerShell Library]<br />
* Python Library<br />
* [ftp://ftp.mailstore.com/spe/MailStoreSPE_Linux_Management_API_Client.zip Linux Management API Client]<br />
|}</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Python_API_Wrapper_Tutorial&diff=952Python API Wrapper Tutorial2014-02-21T12:31:21Z<p>Admin: Admin moved page Python Wrapper to Python Library without leaving a redirect</p>
<hr />
<div>__NOTOC__<br />
<br />
This document introduces the Python API library which allows you to administer your MailStore Service Provider Edition via Python.<br />
<br />
= Installation =<br />
<br />
The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python. <br />
<br />
You can get your Python binary from the [http://www.python.org/download/ Python download page] or you can install it using the package manager of you distribution.<br />
<br />
Additionally you need the [ftp://ftp.mailstore.com/spe/python-api-library.zip MailStore API library] which has to be installed in your Python's site-packages directory. The location of the site-packages directory can be found with the following command<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"<br />
</source><br />
<br />
= Log in =<br />
<br />
The library can be imported with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import mailstore<br />
</source><br />
You are able to instantiate the class directly<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient = mailstore.spe.Client(username="admin", password="admin", host="127.0.0.1", port=8470)<br />
</source><br />
or by using the ''with'' statement (context manager)<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(password="S3cR3t!", host="spe.domain.eu") as speClient:<br />
do_something()<br />
</source><br />
Default values can be omitted.<br />
<br />
The available log in arguments and default values are<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
username = "admin"<br />
password = "admin"<br />
host = "127.0.0.1"<br />
port = 8470<br />
autoHandleToken = True<br />
waitTime = 2000<br />
logLevel = 2<br />
fileLogLevel = 0<br />
</source><br />
When autoHandleToken is enabled, you do not have to care about long running processes, you just have to wait for the result. When this value is set to ''False'', then the status token is returned and you have to handle the token manually. More about this later.<br />
<br />
The ''waitTime'' value specifies the value that is passed to the ''get-status'' call. When you call a long running method like ''VerifyStore'', this is the maximum amount of milliseconds you have to wait for a status update.<br />
<br />
''logLevel'' and ''fileLogLevel'' have to be in the range ''0'' to ''4''. The loglevels are defined as following<br />
0 : "NONE"<br />
1 : "ERROR"<br />
2 : "WARNING"<br />
3 : "INFO" <br />
4 : "DEBUG"<br />
<br />
Log entries will be printed to ''stdout''.<br />
The logfile will be created in the user's %temp% directory and starts with the prefix ''MailStorePyLib''. ''logLevel'' and ''fileLogLevel'' do not have to match.<br />
<br />
= Log out =<br />
<br />
When you prefer the first log in method, you have to log out afterwards manually. When using the context manager method, the log out is done automatically when exiting the ''with'' block. The ''logoutHandler'' will close open log files, if necessary.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient.logoutHandler()<br />
</source><br />
= Simple calls =<br />
<br />
Simple calls will return immediately<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
print(speClient.GetEnvironmentInfo())<br />
<br />
{'antiXsrfToken': 'dUubPmGWEANyDxGbBvejCu6qSRUlkQYSiunQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'userName': 'admin', 'copyright': 'Copyright (c) 2005-2013 MailStore Software GmbH', 'systemProperties': {'totalPhysicalMemory': 2146947072, 'processors': ['Intel(R) Core(TM) i5-2400 CPU @ 3.10GHz'], 'operatingSystem': 'Microsoft Windows Server 2012 Standard'}, 'serverName': 'win2012spe', 'version': '8.5.0.9288', 'licenseeName': 'MailStore Software GmbH', 'licenseeID': 1}, 'statusVersion': 2, 'statusCode': 'succeeded'}<br />
</source><br />
When the ''statusCode'' is ''succeeded'' the information is stored in the ''result'' field. When the process has ended with another status, like ''failed'' or ''cancelled'' the diagnosis information is stored in the ''error'' field.<br />
<br />
When there are no HTTP errors, the returned value is always a python dictionary.<br />
<br />
= Simple examples =<br />
<br />
To get all user's detailed information you could<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client():<br />
instance = "test01"<br />
for user in speClient.GetUsers(instance)["result"]:<br />
print(speClient.GetUserInfo(instance, user["userName"])["result"])<br />
</source><br />
<br />
A list with all assigned email address can be retrieved with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client() as client:<br />
instID = "test01"<br />
emailaddresses = list()<br />
for user in client.GetUsers(instID)["result"]:<br />
info = client.GetUserInfo(instID, user["userName"])["result"]<br />
emailaddresses += info['emailAddresses']<br />
print(emailaddresses)<br />
</source><br />
<br />
= Long running calls =<br />
<br />
Long running calls like ''VerifyStore'' are running asynchronous on the instance. When ''autoHandleToken'' is set to ''True'' (default), the library polls the status in the background automatically and will return the final result when the process has ended. Set ''autoHandleToken'' to ''False'' to get the token. In this case you have to handle the token by youself. There are helper methods available.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
print(client.VerifyStore(instID, storeID))<br />
<br />
{'antiXsrfToken': '6h8HV67XSak+jpQ/e6X1ehLOrt9cPUGicfHQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': 'sa6431dcd1b3e48c4719cfe8a75612b88a', 'result': None, 'statusVersion': 0, 'statusCode': 'running'}<br />
</source><br />
<br />
You are able to update the status manually by passing the token to the ''GetStatus'' method.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
token = client.VerifyStore(instID, storeID))<br />
time.sleep(5)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': '+MKktayBhloqEsqk3xNTssdwTHRxL5+UaPTQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 400 messages verified...\r\n 500 messages verified...\r\n 600 messages verified...\r\n 700 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 17, 'token': 'sa92c717e75db26fa57fc09c5e95f7096d', 'result': None, 'statusVersion': 29, 'statusCode': 'running'}<br />
</source><br />
One could pass the token to the ''HandleToken'' method, then the behavior is exactly the same, as when you would have set ''autoHandleToken=True''.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
print(client.HandleToken(token))<br />
<br />
{'antiXsrfToken': 'KIMJdCpjcuD8O5+xPislG8OysJ0fPgXQcvHQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 389 messages verified...\r\nFinished. No errors have been found.\r\n', 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'sa8e56590b28b3c57f076168d5913840df', 'result': None, 'statusVersion': 147, 'statusCode': 'succeeded'}<br />
</source><br />
Alternatively one could pass the token to the ''HandleTokenIter'' method, then every status update is yielded.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
for status in client.HandleTokenIter(client.VerifyStore(instID, storeID)):<br />
print(status)<br />
<br />
{'antiXsrfToken': 'DEF2dWnoNl7hkgsHqApPZmpsUqEgpih6c/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n', 'statusText': None, 'error': None, 'percentProgress': 0, 'token': 'safd22a51408925dd787ef43a5adc3772c', 'result': None, 'statusVersion': 5, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'a3NMb7VdnLaTOOnfyJnZWEutbmlzPXd6c/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 6, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'mi8qpqTdw6hoH+/+o6h65Rx0jiuPR4p6c/HQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 7, 'statusCode': 'running'}<br />
[...]<br />
</source><br />
<br />
= Cancelling long running calls =<br />
<br />
If you want to cancel a long running call, you have to pass the token of that call to the ''CancelAsync'' method<br />
<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import time<br />
<br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
time.sleep(2)<br />
print(client.CancelAsync(token))<br />
time.sleep(2)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': 'DUs5EO8ZZ9A8S6lUB/uYwIsAFwTufVpCd/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': None, 'statusVersion': None, 'statusCode': None}<br />
{'antiXsrfToken': 'fYO6hoP7eKr1X1SDj++6hhwI9pTwD45Dd/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n3893 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 7, 'token': None, 'result': None, 'statusVersion': 17, 'statusCode': 'cancelled'}<br />
</source><br />
<br />
= Pretty Printing the output =<br />
<br />
There is a helper function that formats the returned values in more readable manner.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
mailstore.spe.pprint(client.GetUserInfo("test01","admin"))<br />
<br />
antiXsrfToken lVKkLrjBXeg7KcjdZ/n6050bpfdAILI9F/3QCGFkbWlu<br />
result<br />
userName admin<br />
privileges<br />
admin<br />
authentication integrated<br />
fullName admin<br />
statusVersion 2<br />
statusCode succeeded<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Python_API_Wrapper_Tutorial&diff=951Python API Wrapper Tutorial2014-02-21T12:22:38Z<p>Admin: /* Pretty Printing the output */</p>
<hr />
<div>__NOTOC__<br />
<br />
This document introduces the Python API library which allows you to administer your MailStore Service Provider Edition via Python.<br />
<br />
= Installation =<br />
<br />
The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python. <br />
<br />
You can get your Python binary from the [http://www.python.org/download/ Python download page] or you can install it using the package manager of you distribution.<br />
<br />
Additionally you need the [ftp://ftp.mailstore.com/spe/python-api-library.zip MailStore API library] which has to be installed in your Python's site-packages directory. The location of the site-packages directory can be found with the following command<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"<br />
</source><br />
<br />
= Log in =<br />
<br />
The library can be imported with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import mailstore<br />
</source><br />
You are able to instantiate the class directly<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient = mailstore.spe.Client(username="admin", password="admin", host="127.0.0.1", port=8470)<br />
</source><br />
or by using the ''with'' statement (context manager)<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(password="S3cR3t!", host="spe.domain.eu") as speClient:<br />
do_something()<br />
</source><br />
Default values can be omitted.<br />
<br />
The available log in arguments and default values are<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
username = "admin"<br />
password = "admin"<br />
host = "127.0.0.1"<br />
port = 8470<br />
autoHandleToken = True<br />
waitTime = 2000<br />
logLevel = 2<br />
fileLogLevel = 0<br />
</source><br />
When autoHandleToken is enabled, you do not have to care about long running processes, you just have to wait for the result. When this value is set to ''False'', then the status token is returned and you have to handle the token manually. More about this later.<br />
<br />
The ''waitTime'' value specifies the value that is passed to the ''get-status'' call. When you call a long running method like ''VerifyStore'', this is the maximum amount of milliseconds you have to wait for a status update.<br />
<br />
''logLevel'' and ''fileLogLevel'' have to be in the range ''0'' to ''4''. The loglevels are defined as following<br />
0 : "NONE"<br />
1 : "ERROR"<br />
2 : "WARNING"<br />
3 : "INFO" <br />
4 : "DEBUG"<br />
<br />
Log entries will be printed to ''stdout''.<br />
The logfile will be created in the user's %temp% directory and starts with the prefix ''MailStorePyLib''. ''logLevel'' and ''fileLogLevel'' do not have to match.<br />
<br />
= Log out =<br />
<br />
When you prefer the first log in method, you have to log out afterwards manually. When using the context manager method, the log out is done automatically when exiting the ''with'' block. The ''logoutHandler'' will close open log files, if necessary.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient.logoutHandler()<br />
</source><br />
= Simple calls =<br />
<br />
Simple calls will return immediately<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
print(speClient.GetEnvironmentInfo())<br />
<br />
{'antiXsrfToken': 'dUubPmGWEANyDxGbBvejCu6qSRUlkQYSiunQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'userName': 'admin', 'copyright': 'Copyright (c) 2005-2013 MailStore Software GmbH', 'systemProperties': {'totalPhysicalMemory': 2146947072, 'processors': ['Intel(R) Core(TM) i5-2400 CPU @ 3.10GHz'], 'operatingSystem': 'Microsoft Windows Server 2012 Standard'}, 'serverName': 'win2012spe', 'version': '8.5.0.9288', 'licenseeName': 'MailStore Software GmbH', 'licenseeID': 1}, 'statusVersion': 2, 'statusCode': 'succeeded'}<br />
</source><br />
When the ''statusCode'' is ''succeeded'' the information is stored in the ''result'' field. When the process has ended with another status, like ''failed'' or ''cancelled'' the diagnosis information is stored in the ''error'' field.<br />
<br />
When there are no HTTP errors, the returned value is always a python dictionary.<br />
<br />
= Simple examples =<br />
<br />
To get all user's detailed information you could<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client():<br />
instance = "test01"<br />
for user in speClient.GetUsers(instance)["result"]:<br />
print(speClient.GetUserInfo(instance, user["userName"])["result"])<br />
</source><br />
<br />
A list with all assigned email address can be retrieved with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client() as client:<br />
instID = "test01"<br />
emailaddresses = list()<br />
for user in client.GetUsers(instID)["result"]:<br />
info = client.GetUserInfo(instID, user["userName"])["result"]<br />
emailaddresses += info['emailAddresses']<br />
print(emailaddresses)<br />
</source><br />
<br />
= Long running calls =<br />
<br />
Long running calls like ''VerifyStore'' are running asynchronous on the instance. When ''autoHandleToken'' is set to ''True'' (default), the library polls the status in the background automatically and will return the final result when the process has ended. Set ''autoHandleToken'' to ''False'' to get the token. In this case you have to handle the token by youself. There are helper methods available.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
print(client.VerifyStore(instID, storeID))<br />
<br />
{'antiXsrfToken': '6h8HV67XSak+jpQ/e6X1ehLOrt9cPUGicfHQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': 'sa6431dcd1b3e48c4719cfe8a75612b88a', 'result': None, 'statusVersion': 0, 'statusCode': 'running'}<br />
</source><br />
<br />
You are able to update the status manually by passing the token to the ''GetStatus'' method.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
token = client.VerifyStore(instID, storeID))<br />
time.sleep(5)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': '+MKktayBhloqEsqk3xNTssdwTHRxL5+UaPTQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 400 messages verified...\r\n 500 messages verified...\r\n 600 messages verified...\r\n 700 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 17, 'token': 'sa92c717e75db26fa57fc09c5e95f7096d', 'result': None, 'statusVersion': 29, 'statusCode': 'running'}<br />
</source><br />
One could pass the token to the ''HandleToken'' method, then the behavior is exactly the same, as when you would have set ''autoHandleToken=True''.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
print(client.HandleToken(token))<br />
<br />
{'antiXsrfToken': 'KIMJdCpjcuD8O5+xPislG8OysJ0fPgXQcvHQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 389 messages verified...\r\nFinished. No errors have been found.\r\n', 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'sa8e56590b28b3c57f076168d5913840df', 'result': None, 'statusVersion': 147, 'statusCode': 'succeeded'}<br />
</source><br />
Alternatively one could pass the token to the ''HandleTokenIter'' method, then every status update is yielded.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
for status in client.HandleTokenIter(client.VerifyStore(instID, storeID)):<br />
print(status)<br />
<br />
{'antiXsrfToken': 'DEF2dWnoNl7hkgsHqApPZmpsUqEgpih6c/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n', 'statusText': None, 'error': None, 'percentProgress': 0, 'token': 'safd22a51408925dd787ef43a5adc3772c', 'result': None, 'statusVersion': 5, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'a3NMb7VdnLaTOOnfyJnZWEutbmlzPXd6c/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 6, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'mi8qpqTdw6hoH+/+o6h65Rx0jiuPR4p6c/HQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 7, 'statusCode': 'running'}<br />
[...]<br />
</source><br />
<br />
= Cancelling long running calls =<br />
<br />
If you want to cancel a long running call, you have to pass the token of that call to the ''CancelAsync'' method<br />
<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import time<br />
<br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
time.sleep(2)<br />
print(client.CancelAsync(token))<br />
time.sleep(2)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': 'DUs5EO8ZZ9A8S6lUB/uYwIsAFwTufVpCd/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': None, 'statusVersion': None, 'statusCode': None}<br />
{'antiXsrfToken': 'fYO6hoP7eKr1X1SDj++6hhwI9pTwD45Dd/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n3893 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 7, 'token': None, 'result': None, 'statusVersion': 17, 'statusCode': 'cancelled'}<br />
</source><br />
<br />
= Pretty Printing the output =<br />
<br />
There is a helper function that formats the returned values in more readable manner.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
mailstore.spe.pprint(client.GetUserInfo("test01","admin"))<br />
<br />
antiXsrfToken lVKkLrjBXeg7KcjdZ/n6050bpfdAILI9F/3QCGFkbWlu<br />
result<br />
userName admin<br />
privileges<br />
admin<br />
authentication integrated<br />
fullName admin<br />
statusVersion 2<br />
statusCode succeeded<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Python_API_Wrapper_Tutorial&diff=950Python API Wrapper Tutorial2014-02-21T12:19:45Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
<br />
This document introduces the Python API library which allows you to administer your MailStore Service Provider Edition via Python.<br />
<br />
= Installation =<br />
<br />
The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python. <br />
<br />
You can get your Python binary from the [http://www.python.org/download/ Python download page] or you can install it using the package manager of you distribution.<br />
<br />
Additionally you need the [ftp://ftp.mailstore.com/spe/python-api-library.zip MailStore API library] which has to be installed in your Python's site-packages directory. The location of the site-packages directory can be found with the following command<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"<br />
</source><br />
<br />
= Log in =<br />
<br />
The library can be imported with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import mailstore<br />
</source><br />
You are able to instantiate the class directly<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient = mailstore.spe.Client(username="admin", password="admin", host="127.0.0.1", port=8470)<br />
</source><br />
or by using the ''with'' statement (context manager)<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(password="S3cR3t!", host="spe.domain.eu") as speClient:<br />
do_something()<br />
</source><br />
Default values can be omitted.<br />
<br />
The available log in arguments and default values are<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
username = "admin"<br />
password = "admin"<br />
host = "127.0.0.1"<br />
port = 8470<br />
autoHandleToken = True<br />
waitTime = 2000<br />
logLevel = 2<br />
fileLogLevel = 0<br />
</source><br />
When autoHandleToken is enabled, you do not have to care about long running processes, you just have to wait for the result. When this value is set to ''False'', then the status token is returned and you have to handle the token manually. More about this later.<br />
<br />
The ''waitTime'' value specifies the value that is passed to the ''get-status'' call. When you call a long running method like ''VerifyStore'', this is the maximum amount of milliseconds you have to wait for a status update.<br />
<br />
''logLevel'' and ''fileLogLevel'' have to be in the range ''0'' to ''4''. The loglevels are defined as following<br />
0 : "NONE"<br />
1 : "ERROR"<br />
2 : "WARNING"<br />
3 : "INFO" <br />
4 : "DEBUG"<br />
<br />
Log entries will be printed to ''stdout''.<br />
The logfile will be created in the user's %temp% directory and starts with the prefix ''MailStorePyLib''. ''logLevel'' and ''fileLogLevel'' do not have to match.<br />
<br />
= Log out =<br />
<br />
When you prefer the first log in method, you have to log out afterwards manually. When using the context manager method, the log out is done automatically when exiting the ''with'' block. The ''logoutHandler'' will close open log files, if necessary.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient.logoutHandler()<br />
</source><br />
= Simple calls =<br />
<br />
Simple calls will return immediately<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
print(speClient.GetEnvironmentInfo())<br />
<br />
{'antiXsrfToken': 'dUubPmGWEANyDxGbBvejCu6qSRUlkQYSiunQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'userName': 'admin', 'copyright': 'Copyright (c) 2005-2013 MailStore Software GmbH', 'systemProperties': {'totalPhysicalMemory': 2146947072, 'processors': ['Intel(R) Core(TM) i5-2400 CPU @ 3.10GHz'], 'operatingSystem': 'Microsoft Windows Server 2012 Standard'}, 'serverName': 'win2012spe', 'version': '8.5.0.9288', 'licenseeName': 'MailStore Software GmbH', 'licenseeID': 1}, 'statusVersion': 2, 'statusCode': 'succeeded'}<br />
</source><br />
When the ''statusCode'' is ''succeeded'' the information is stored in the ''result'' field. When the process has ended with another status, like ''failed'' or ''cancelled'' the diagnosis information is stored in the ''error'' field.<br />
<br />
When there are no HTTP errors, the returned value is always a python dictionary.<br />
<br />
= Simple examples =<br />
<br />
To get all user's detailed information you could<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client():<br />
instance = "test01"<br />
for user in speClient.GetUsers(instance)["result"]:<br />
print(speClient.GetUserInfo(instance, user["userName"])["result"])<br />
</source><br />
<br />
A list with all assigned email address can be retrieved with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client() as client:<br />
instID = "test01"<br />
emailaddresses = list()<br />
for user in client.GetUsers(instID)["result"]:<br />
info = client.GetUserInfo(instID, user["userName"])["result"]<br />
emailaddresses += info['emailAddresses']<br />
print(emailaddresses)<br />
</source><br />
<br />
= Long running calls =<br />
<br />
Long running calls like ''VerifyStore'' are running asynchronous on the instance. When ''autoHandleToken'' is set to ''True'' (default), the library polls the status in the background automatically and will return the final result when the process has ended. Set ''autoHandleToken'' to ''False'' to get the token. In this case you have to handle the token by youself. There are helper methods available.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
print(client.VerifyStore(instID, storeID))<br />
<br />
{'antiXsrfToken': '6h8HV67XSak+jpQ/e6X1ehLOrt9cPUGicfHQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': 'sa6431dcd1b3e48c4719cfe8a75612b88a', 'result': None, 'statusVersion': 0, 'statusCode': 'running'}<br />
</source><br />
<br />
You are able to update the status manually by passing the token to the ''GetStatus'' method.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
token = client.VerifyStore(instID, storeID))<br />
time.sleep(5)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': '+MKktayBhloqEsqk3xNTssdwTHRxL5+UaPTQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 400 messages verified...\r\n 500 messages verified...\r\n 600 messages verified...\r\n 700 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 17, 'token': 'sa92c717e75db26fa57fc09c5e95f7096d', 'result': None, 'statusVersion': 29, 'statusCode': 'running'}<br />
</source><br />
One could pass the token to the ''HandleToken'' method, then the behavior is exactly the same, as when you would have set ''autoHandleToken=True''.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
print(client.HandleToken(token))<br />
<br />
{'antiXsrfToken': 'KIMJdCpjcuD8O5+xPislG8OysJ0fPgXQcvHQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 389 messages verified...\r\nFinished. No errors have been found.\r\n', 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'sa8e56590b28b3c57f076168d5913840df', 'result': None, 'statusVersion': 147, 'statusCode': 'succeeded'}<br />
</source><br />
Alternatively one could pass the token to the ''HandleTokenIter'' method, then every status update is yielded.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
for status in client.HandleTokenIter(client.VerifyStore(instID, storeID)):<br />
print(status)<br />
<br />
{'antiXsrfToken': 'DEF2dWnoNl7hkgsHqApPZmpsUqEgpih6c/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n', 'statusText': None, 'error': None, 'percentProgress': 0, 'token': 'safd22a51408925dd787ef43a5adc3772c', 'result': None, 'statusVersion': 5, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'a3NMb7VdnLaTOOnfyJnZWEutbmlzPXd6c/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 6, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'mi8qpqTdw6hoH+/+o6h65Rx0jiuPR4p6c/HQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 7, 'statusCode': 'running'}<br />
[...]<br />
</source><br />
<br />
= Cancelling long running calls =<br />
<br />
If you want to cancel a long running call, you have to pass the token of that call to the ''CancelAsync'' method<br />
<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import time<br />
<br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
time.sleep(2)<br />
print(client.CancelAsync(token))<br />
time.sleep(2)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': 'DUs5EO8ZZ9A8S6lUB/uYwIsAFwTufVpCd/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': None, 'statusVersion': None, 'statusCode': None}<br />
{'antiXsrfToken': 'fYO6hoP7eKr1X1SDj++6hhwI9pTwD45Dd/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n3893 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 7, 'token': None, 'result': None, 'statusVersion': 17, 'statusCode': 'cancelled'}<br />
</source><br />
<br />
= Pretty Printing the output =<br />
<br />
There is a helper function that formats the returned values in more readable manner.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
mailstore.spe.pprint(client.GetUserInfo("test01","admin"))<br />
<br />
antiXsrfToken Z6IzO2cvf2lb6PVPCKoN6U8R8Jgmtub+Fv3QCGFkbWlu<br />
result<br />
userName admin<br />
privileges<br />
admin<br />
pop3UserNames<br />
authentication integrated<br />
fullName admin<br />
emailAddresses<br />
statusVersion 2<br />
statusCode succeeded<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Python_API_Wrapper_Tutorial&diff=949Python API Wrapper Tutorial2014-02-21T12:15:12Z<p>Admin: /* Simple examples */</p>
<hr />
<div>__NOTOC__<br />
<br />
This document introduces the Python API library which allows you to administer your MailStore Service Provider Edition via Python.<br />
<br />
= Installation =<br />
<br />
The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python. <br />
<br />
You can get your Python binary from the [http://www.python.org/download/ Python download page] or you can install it using the package manager of you distribution.<br />
<br />
Additionally you need the [ftp://ftp.mailstore.com/spe/python-api-library.zip MailStore API library] which has to be installed in your Python's site-packages directory. The location of the site-packages directory can be found with the following command<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"<br />
</source><br />
<br />
= Log in =<br />
<br />
The library can be imported with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import mailstore<br />
</source><br />
You are able to instantiate the class directly<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient = mailstore.spe.Client(username="admin", password="admin", host="127.0.0.1", port=8470)<br />
</source><br />
or by using the ''with'' statement (context manager)<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(password="S3cR3t!", host="spe.domain.eu") as speClient:<br />
do_something()<br />
</source><br />
Default values can be omitted.<br />
<br />
The available log in arguments and default values are<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
username = "admin"<br />
password = "admin"<br />
host = "127.0.0.1"<br />
port = 8470<br />
autoHandleToken = True<br />
waitTime = 2000<br />
logLevel = 2<br />
fileLogLevel = 0<br />
</source><br />
When autoHandleToken is enabled, you do not have to care about long running processes, you just have to wait for the result. When this value is set to ''False'', then the status token is returned and you have to handle the token manually. More about this later.<br />
<br />
The ''waitTime'' value specifies the value that is passed to the ''get-status'' call. When you call a long running method like ''VerifyStore'', this is the maximum amount of milliseconds you have to wait for a status update.<br />
<br />
''logLevel'' and ''fileLogLevel'' have to be in the range ''0'' to ''4''. The loglevels are defined as following<br />
0 : "NONE"<br />
1 : "ERROR"<br />
2 : "WARNING"<br />
3 : "INFO" <br />
4 : "DEBUG"<br />
<br />
Log entries will be printed to ''stdout''.<br />
The logfile will be created in the user's %temp% directory and starts with the prefix ''MailStorePyLib''. ''logLevel'' and ''fileLogLevel'' do not have to match.<br />
<br />
= Log out =<br />
<br />
When you prefer the first log in method, you have to log out afterwards manually. When using the context manager method, the log out is done automatically when exiting the ''with'' block. The ''logoutHandler'' will close open log files, if necessary.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
speClient.logoutHandler()<br />
</source><br />
= Simple calls =<br />
<br />
Simple calls will return immediately<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
print(speClient.GetEnvironmentInfo())<br />
<br />
{'antiXsrfToken': 'dUubPmGWEANyDxGbBvejCu6qSRUlkQYSiunQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'userName': 'admin', 'copyright': 'Copyright (c) 2005-2013 MailStore Software GmbH', 'systemProperties': {'totalPhysicalMemory': 2146947072, 'processors': ['Intel(R) Core(TM) i5-2400 CPU @ 3.10GHz'], 'operatingSystem': 'Microsoft Windows Server 2012 Standard'}, 'serverName': 'win2012spe', 'version': '8.5.0.9288', 'licenseeName': 'MailStore Software GmbH', 'licenseeID': 1}, 'statusVersion': 2, 'statusCode': 'succeeded'}<br />
</source><br />
When the ''statusCode'' is ''succeeded'' the information is stored in the ''result'' field. When the process has ended with another status, like ''failed'' or ''cancelled'' the diagnosis information is stored in the ''error'' field.<br />
<br />
When there are no HTTP errors, the returned value is always a python dictionary.<br />
<br />
= Simple examples =<br />
<br />
To get all user's detailed information you could<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client():<br />
instance = "test01"<br />
for user in speClient.GetUsers(instance)["result"]:<br />
print(speClient.GetUserInfo(instance, user["userName"])["result"])<br />
</source><br />
<br />
A list with all assigned email address can be retrieved with<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client() as client:<br />
instID = "test01"<br />
emailaddresses = list()<br />
for user in client.GetUsers(instID)["result"]:<br />
info = client.GetUserInfo(instID, user["userName"])["result"]<br />
emailaddresses += info['emailAddresses']<br />
print(emailaddresses)<br />
</source><br />
<br />
= Long running calls =<br />
<br />
Long running calls like ''VerifyStore'' are running asynchronous on the instance. When ''autoHandleToken'' is set to ''True'' (default), the library polls the status in the background automatically and will return the final result when the process has ended. Set ''autoHandleToken'' to ''False'' to get the token. In this case you have to handle the token by youself. There are helper methods available.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
print(client.VerifyStore(instID, storeID))<br />
<br />
{'antiXsrfToken': '6h8HV67XSak+jpQ/e6X1ehLOrt9cPUGicfHQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': 'sa6431dcd1b3e48c4719cfe8a75612b88a', 'result': None, 'statusVersion': 0, 'statusCode': 'running'}<br />
</source><br />
<br />
You are able to update the status manually by passing the token to the ''GetStatus'' method.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 1<br />
token = client.VerifyStore(instID, storeID))<br />
time.sleep(5)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': '+MKktayBhloqEsqk3xNTssdwTHRxL5+UaPTQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 400 messages verified...\r\n 500 messages verified...\r\n 600 messages verified...\r\n 700 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 17, 'token': 'sa92c717e75db26fa57fc09c5e95f7096d', 'result': None, 'statusVersion': 29, 'statusCode': 'running'}<br />
</source><br />
One could pass the token to the ''HandleToken'' method, then the behavior is exactly the same, as when you would have set ''autoHandleToken=True''.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
print(client.HandleToken(token))<br />
<br />
{'antiXsrfToken': 'KIMJdCpjcuD8O5+xPislG8OysJ0fPgXQcvHQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n 389 messages verified...\r\nFinished. No errors have been found.\r\n', 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'sa8e56590b28b3c57f076168d5913840df', 'result': None, 'statusVersion': 147, 'statusCode': 'succeeded'}<br />
</source><br />
Alternatively one could pass the token to the ''HandleTokenIter'' method, then every status update is yielded.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
for status in client.HandleTokenIter(client.VerifyStore(instID, storeID)):<br />
print(status)<br />
<br />
{'antiXsrfToken': 'DEF2dWnoNl7hkgsHqApPZmpsUqEgpih6c/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n', 'statusText': None, 'error': None, 'percentProgress': 0, 'token': 'safd22a51408925dd787ef43a5adc3772c', 'result': None, 'statusVersion': 5, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'a3NMb7VdnLaTOOnfyJnZWEutbmlzPXd6c/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 6, 'statusCode': 'running'}<br />
{'antiXsrfToken': 'mi8qpqTdw6hoH+/+o6h65Rx0jiuPR4p6c/HQCGFkbWlu', 'logOutput': ' 100 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 7, 'statusCode': 'running'}<br />
[...]<br />
</source><br />
<br />
= Cancelling long running calls =<br />
<br />
If you want to cancel a long running call, you have to pass the token of that call to the ''CancelAsync'' method<br />
<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
import time<br />
<br />
with mailstore.spe.Client(autoHandleToken=False) as client:<br />
instID = "test01"<br />
storeID = 38<br />
token = client.VerifyStore(instID, storeID)<br />
time.sleep(2)<br />
print(client.CancelAsync(token))<br />
time.sleep(2)<br />
print(client.GetStatus(token))<br />
<br />
{'antiXsrfToken': 'DUs5EO8ZZ9A8S6lUB/uYwIsAFwTufVpCd/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': None, 'statusVersion': None, 'statusCode': None}<br />
{'antiXsrfToken': 'fYO6hoP7eKr1X1SDj++6hhwI9pTwD45Dd/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n3893 messages are about to be verified.\r\nVerifying...\r\n 100 messages verified...\r\n 200 messages verified...\r\n 300 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 7, 'token': None, 'result': None, 'statusVersion': 17, 'statusCode': 'cancelled'}<br />
</source><br />
<br />
= Pretty Printing the output =<br />
<br />
There is a helper function that formats the returned values in more readable manner.<br />
<source lang="python" smart-tabs="true" toolbar="false" gutter="false"><br />
mailstore.spe.pprint(client.GetUserInfo("test01","admin"))<br />
<br />
antiXsrfToken tfrgvinkGOkjWgSCSV72UZY/1qkfwEGIdfHQCGFkbWlu<br />
logOutput None<br />
statusText None<br />
error None<br />
percentProgress None<br />
token None<br />
result userName admin<br />
distinguishedName None<br />
privileges admin<br />
pop3UserNames authentication integrated<br />
fullName admin<br />
emailAddresses statusVersion 2<br />
statusCode succeeded<br />
</source></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=MediaWiki:Sidebar-banner1&diff=900MediaWiki:Sidebar-banner12014-02-14T09:40:47Z<p>Admin: </p>
<hr />
<div><a href="http://www.mailstore.com/en/mailstore-cloud-email-archiving.aspx"><img src="img/mailstore-spe-box-140x180.png" /></a><br/><br />
<a href="http://www.mailstore.com/en/mailstore-cloud-email-archiving.aspx">MailStore Service Provider Edition</a> Email Archiving Software For Service Providers.</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Branding&diff=899Branding2014-02-14T09:25:12Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
The appearance of MailStore Client, MailStore Web Access, and MailStore Outlook Add-in can all be easily customized to match your corporate design. <br />
<br />
= Modify and Activate Branding =<br />
Follow the instructions below to apply your own branding:<br />
<br />
* Open Windows Explorer on the Management Server.<br />
* Navigate to the ''config'' subdirectory of the MailStore Service Provider Edition installation. (Default: <tt>%PROGRAMFILES%\MailStore Infrastructure\config</tt>).<br />
* Create a new folder named <tt>Branding</tt>.<br />
* Store all files necessary for branding in this newly created folder. Find further details about the branding parameters in [[#Client Branding|Client Branding]] and [[#Web Branding|Web Branding]] below.<br />
*: '''Important notice:''' The dimensions of the images must remain unchanged and no syntax errors must be made when editing JSON files. If necessary, test the JSON files at http://jsonlint.com/. Sample files can be found in the ‘Branding.sample’ folder located in the ''config'' subdirectory. <br />
* Restart the Management Server service to activate the new branding.<br />
* Finally restart all the Client Access Server service on all server to refresh their local caches.<br />
<br />
== Client Branding ==<br />
<br />
The following table provides information about the fields available for MailStore Client branding stored in <tt>ClientBranding.json</tt>.<br />
<br />
{| class="wikitable"<br />
! width=250px | Name<br />
! Description<br />
|-<br />
| <tt>clientName</tt><br />
| Name of the client application, e.g. "YOURCOMPANY - EMAIL ARCHIVE"<br />
|-<br />
| <tt>helpUrl</tt><br />
| URL to be opened when clicking on help in client.<br />
|-<br />
| <tt>loginHeaderImage_410x81_png</tt><br />
| Header image for login dialog. Required dimension: width: 410px; height: 81px<br />
|-<br />
| <tt>headerBackgroundColor</tt><br />
| Background color of header, e.g. "#126d9c"<br />
|-<br />
| <tt>headerLeftImage_autox95_png</tt><br />
| Left header image. Required dimension: width: auto; height: 95px<br />
|-<br />
| <tt>headerRightImage_autox95_png</tt><br />
| Right header image. Required dimension: width: auto; height: 95px<br />
|-<br />
| <tt>about_html</tt><br />
| HTML file containing the about site.<br />
|-<br />
| <tt>watermarkImage_300x150_png</tt><br />
| Watermark image. Required dimension: width: 300px; height: 150px<br />
|}<br />
<br />
== Web Branding ==<br />
<br />
The following table provides information about the fields available for MailStore Web Access and MailStore Outlook Add-in branding stored in <tt>WebBranding.json</tt>.<br />
<br />
{| class="wikitable"<br />
! width=250px | Name<br />
! Description<br />
|-<br />
| <tt>webName</tt><br />
| Name of the web application, e.g. "YOURCOMPANY - EMAIL ARCHIVE WEB ACCESS"<br />
|-<br />
| <tt>webAbout_html</tt><br />
| HTML file containing the about site.<br />
|-<br />
| <tt>webHelpUrl</tt><br />
| URL to be opened when clicking on help in web access.<br />
|-<br />
| <tt>webLoginHeaderImage_410x81_png</tt><br />
| Header image for login dialog. Required dimension: width: 410px; height: 81px<br />
|-<br />
| <tt>webHeaderBackgroundColor</tt><br />
| Background color of header, e.g. "#126d9c"<br />
|-<br />
| <tt>webHeaderBackgroundImage_autox36_png</tt><br />
| Header header image. Required dimension: width: auto; height: 36px<br />
|-<br />
| <tt>outlookAddinName</tt><br />
| Name of the Outlook Add-in, e.g. "YOURCOMPANY - EMAIL ARCHIVE ADD-IN"<br />
|-<br />
| <tt>outlookAddinHelpUrl</tt><br />
| URL to be opened when clicking on help in Outlook Add-in.<br />
|-<br />
| <tt>watermarkImage_300x150_png</tt><br />
| Watermark image. Required dimension: width: 300px; height: 150px<br />
|}<br />
<br />
= What to do next =<br />
<br />
Hereby the installation and setup process of the MailStore Service Provider Edition is finished. All other administrative tasks are carried out through the web-based [[Management_Console_-_General| MailStore Management Console]].</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Replace_Self-signed_SSL_Certificates&diff=898Replace Self-signed SSL Certificates2014-02-14T09:24:53Z<p>Admin: </p>
<hr />
<div>MailStore Service Provider Edition automatically creates self-signed certificates when adding a new role to a server. While these certificates are suitable for authenticating MailStore Service Provider Edition's own services against each other by storing and verifying the unique fingerprints of the used certificates, self-signed certificates are not suitable for public internet services like email or web servers.<br />
<br />
Therefore it is recommended to replace the SSL certificates used by the Client Access Servers for offering IMAP and web based access to the archives with certificates signed by an official certificate authority.<br />
<br />
= Prerequisites =<br />
<br />
Before a certificate can be used by the Client Access Server service, the certificate and its private key must be store in the computer's personal certificate store ('''not''' Administrator's or any other user's).<br />
<br />
= Installing New Certificates =<br />
<br />
* Start the MailStore Service Provider Edition Configuration tool on a server that is a Client Access Server by double-clicking it's desktop icon. On Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.<br />
* Stop the ''Client Access Server''.<br />
* Click ''Configure..''.<br />
* For each server (HTTP, IMAP, IMAPS) click on the button behind the ''Server 'Certificate'' field to select the new certificate from the certificate store.<br />
* Click ''OK'' to save changes or ''Cancel'' to discard.<br />
* Start the Client Access Server.<br />
<br />
Repeat the above on each Client Access Server in your MailStore Service Provider Edition infrastructure.<br />
<br />
= What to do next =<br />
<br />
The last step of the installation and setup process is optional, but allows to give your MailStore Service Provider Edition a unique look: Read more about customizing the appearance of MailStore Client, MailStore Web Access and MailStore Outlook Add-in in [[Branding]]<br />
<br />
If the appearance of MailStore Client, MailStore Web Access and MailStore Outlook Add-in does not need to be modified, the installation and setup process is of MailStore Service Provider Edition is finished. All other administrative tasks are carried out through the web-based [[Management_Console_-_General| MailStore Management Console]].</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Multi_Server_Mode_Setup&diff=897Multi Server Mode Setup2014-02-14T09:24:13Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
= Multi Server Mode Setup =<br />
<br />
When setting up MailStore Service Provider Edition in multi server mode, the first role to set up must always be the Management Server role. Afterwards one or multiple Instance Hosts and Client Access Servers can be set up. Each server in a multi server mode setup can host one or multiple roles.<br />
<br />
== Set Up Management Server ==<br />
<br />
* If not executed automatically by the installation program, start the MailStore Service Provider Edition Configuration tool by double-clicking its desktop icon. On a Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.<br />
* If no configuration files and services are found, the ''MailStore Service Provider Edition Configuration'' will ask for the desired mode. Select ''Multi Server Mode'' and click ''OK''. <br />
*: [[File:ms_spe_config_multi_01.png|center]]<br />
* Click ''Add Server Role''<br />
* Select ''Management Server''<br />
* Enter your product key into the Product Key field and change Server Name to the fully qualified host name of the server (e.g. mgmt.ms-spe.test). Finally enter and confirm the admin password that will be used to log on to the Management Console.<br />
*: [[File:ms_spe_config_mgmt_01.png|center]]<br />
* Fill out the ''Configure Management Server Role'' form.<br />
*: [[File:ms_spe_config_mgmt_02.png|center]]<br />
:* '''Server Name:''' Fully qualified host name (FQHN) of the server <br />
:* '''TCP Server Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections from the Management Server (Default: *:8471)<br />
:* '''TCP Server Certificate: ''' Fingerprint of the SSL certificate used by the Management Server to authenticate against Instance Hosts and Client Access Serves. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
:* '''HTTP Server Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections to the Management Console and Management API (Default: *:8470)<br />
:* '''HTTP Server Certificate: ''' Fingerprint of the SSL certificate used by the Management Server's HTTP server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store.<br />
* Click ''OK'' to add the Management Server role.<br />
* Click '''Start'' to start the Management Server service.<br />
*: '''Please note:'' As the startup process of the services is asynchronous, please wait up to 30 seconds. A service shown as running may still switch back to stopped during that period if an error occurred.<br />
* It is now safe to close the MailStore Service Provider Edition Configuration tool<br />
<br />
== Set Up Instance Host ==<br />
<br />
* If not executed automatically by the installation program, start the MailStore Service Provider Edition Configuration tool by double-clicking its desktop icon. On a Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.<br />
* If no configuration files and services are found, the ''MailStore Service Provider Edition Configuration'' will ask for the desired mode. Select ''Multi Server Mode'' and click ''OK''. <br />
*: [[File:ms_spe_config_multi_01.png|center]]<br />
* Click ''Add Server Role''<br />
* Select ''Instance Host''<br />
* Fill out the ''Configure Instance Host Role'' form.<br />
*: [[File:ms_spe_config_ih_01.png|center]]<br />
:* '''Server Name:''' Fully qualified host name (FQHN) of the server <br />
:* '''TCP Server Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections from the Management Server (Default: *:8472)<br />
:* '''TCP Server Certificate: ''' Fingerprint of the SSL certificate used by the Instance Host to authenticate against Management Server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
:* '''Management Server:''' Fully qualified host name (FQHN) of the Management Server to connect to.<br />
:* '''Port:''' TCP port where the above Management Server accepts incoming connections.<br />
:* '''Management Server Cert''' Fingerprint of the SSL certificate used by the Management Server to authenticate against Instance Host. This value is set automatically when [[Multi_Server_Mode_Setup#Pairing with Management Server|Pairing with Management Server]]<br />
* Click ''OK'' to add the Instance Host role.<br />
* Click '''Start'' to start the Instance Host service.<br />
*: '''Please note:'' As the startup process of the services is asynchronous, please wait up to 30 seconds. A service shown as running may still switch back to stopped during that period if an error occurred.<br />
* It is now safe to close the MailStore Service Provider Edition Configuration tool<br />
<br />
== Set Up Client Access Server ==<br />
<br />
* If not executed automatically by the installation program, start the MailStore Service Provider Edition Configuration tool by double-clicking its desktop icon. On a Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.<br />
* If no configuration files and services are found, the ''MailStore Service Provider Edition Configuration'' will ask for the desired mode. Select ''Multi Server Mode'' and click ''OK''. <br />
*: [[File:ms_spe_config_multi_01.png|center]]<br />
* Click ''Add Server Role'' .<br />
* Select ''Client Access Server''.<br />
* Fill out the ''Configure Client Access Server Role'' form.<br />
*: [[File:ms_spe_config_cas_01.png|center]]<br />
:* '''Server Name:''' Fully qualified host name (FQHN) of the server <br />
:* '''TCP Server Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections from the Management Server (Default: *:8473)<br />
:* '''TCP Server Certificate: ''' Fingerprint of the SSL certificate used by the Client Access Server to authenticate against Management Server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
:* '''Management Server:''' Fully qualified host name (FQHN) of the Management Server to connect to.<br />
:* '''Port:''' TCP port where the above Management Server accepts incoming connections.<br />
:* '''Management Server Cert''' Fingerprint of the SSL certificate used by the Management Server to authenticate against Client Access Server. This value is set automatically when [[Multi_Server_Mode_Setup#Pairing with Management Server|Pairing with Management Server]]<br />
:* '''HTTP Server Enabled:''' If enabled the Client Access Server provides access to archives via MailStore Client, MailStore Outlook Add-in and MailStore Web Access.<br />
:*: '''Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections (Default: *:443)<br />
:*: '''Server Certificate:''' Fingerprint of the SSL certificate used by the HTTP Server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
:* '''IMAP Server with explicit TLS Enabled:''' If enabled the Client Access Server provides access to archives via IMAP protocol. Connection can either be unencrypted or secured via STARTTLS.<br />
:*: '''Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections (Default: *:143)<br />
:*: '''Server Certificate:''' Fingerprint of the SSL certificate used by the IMAP Server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
:* '''IMAP Server with implicit TLS Enabled:''' If enabled the Client Access Server provides access to archives via IMAP protocol. Connection is encrypted via SSL/TLS.<br />
:*: '''Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections (Default: *:993)<br />
:*: '''Server Certificate:''' Fingerprint of the SSL certificate used by the IMAP Server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
* Click ''OK'' to add the Client Access Server role.<br />
* Click '''Start'' to start the Client Access Server service.<br />
*: '''Please note:'' As the startup process of the services is asynchronous, please wait up to 30 seconds. A service shown as running may still switch back to stopped during that period if an error occurred.<br />
* It is now safe to close the MailStore Service Provider Edition Configuration tool<br />
<br />
== Pairing with Management Server ==<br />
<br />
Before Client Access Servers and Instance Hosts are able to communicate with the Management Server, SSL certificate fingerprints must be exchanged to establish a trust relationship. Additionally the Instance Hosts and Client Access Servers must be registered in the Management Server with its server name and TCP port. <br />
<br />
This process can simply be performed by using the pairing function as described in the following:<br />
<br />
* Enter the fully qualified host name of the ''Management Server'' in the corresponding field while configuring an Instance Host or Client Access Server.<br />
* Click ''Pair with this server''.<br />
* Enter the user name and password of a MailStore Service Provider Edition administrator.<br />
* Click ''OK'' to pair with Management Server<br />
<br />
'''Please note:''' Pairing is carried out through the Management API. Therefore the Instance Hosts and Client Access Servers must be able to establish a connection to the HTTP server on the Management Server (Default TCP port: 8470).<br />
<br />
If your security policy does not permit establishing such a connection, pairing must be performed manually. Please refer to [[Management Console - Infrastructure#Add New Instance Host|Add New Instance Host]] or [[Management Console - Infrastructure#Add New Client Access Server|Add New Client Access Server]] for further details.<br />
<br />
= What to do next =<br />
<br />
In production environments it is recommended to replace the self-signed certificates used by the Client Access Server's IMAP and HTTP server with certificates signed by a trusted root certificate authority. Further details can be found in [[Replace Self-signed SSL Certificates]]</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Multi_Server_Mode_Setup&diff=896Multi Server Mode Setup2014-02-14T09:23:58Z<p>Admin: </p>
<hr />
<div>= Multi Server Mode Setup =<br />
<br />
When setting up MailStore Service Provider Edition in multi server mode, the first role to set up must always be the Management Server role. Afterwards one or multiple Instance Hosts and Client Access Servers can be set up. Each server in a multi server mode setup can host one or multiple roles.<br />
<br />
== Set Up Management Server ==<br />
<br />
* If not executed automatically by the installation program, start the MailStore Service Provider Edition Configuration tool by double-clicking its desktop icon. On a Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.<br />
* If no configuration files and services are found, the ''MailStore Service Provider Edition Configuration'' will ask for the desired mode. Select ''Multi Server Mode'' and click ''OK''. <br />
*: [[File:ms_spe_config_multi_01.png|center]]<br />
* Click ''Add Server Role''<br />
* Select ''Management Server''<br />
* Enter your product key into the Product Key field and change Server Name to the fully qualified host name of the server (e.g. mgmt.ms-spe.test). Finally enter and confirm the admin password that will be used to log on to the Management Console.<br />
*: [[File:ms_spe_config_mgmt_01.png|center]]<br />
* Fill out the ''Configure Management Server Role'' form.<br />
*: [[File:ms_spe_config_mgmt_02.png|center]]<br />
:* '''Server Name:''' Fully qualified host name (FQHN) of the server <br />
:* '''TCP Server Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections from the Management Server (Default: *:8471)<br />
:* '''TCP Server Certificate: ''' Fingerprint of the SSL certificate used by the Management Server to authenticate against Instance Hosts and Client Access Serves. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
:* '''HTTP Server Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections to the Management Console and Management API (Default: *:8470)<br />
:* '''HTTP Server Certificate: ''' Fingerprint of the SSL certificate used by the Management Server's HTTP server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store.<br />
* Click ''OK'' to add the Management Server role.<br />
* Click '''Start'' to start the Management Server service.<br />
*: '''Please note:'' As the startup process of the services is asynchronous, please wait up to 30 seconds. A service shown as running may still switch back to stopped during that period if an error occurred.<br />
* It is now safe to close the MailStore Service Provider Edition Configuration tool<br />
<br />
== Set Up Instance Host ==<br />
<br />
* If not executed automatically by the installation program, start the MailStore Service Provider Edition Configuration tool by double-clicking its desktop icon. On a Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.<br />
* If no configuration files and services are found, the ''MailStore Service Provider Edition Configuration'' will ask for the desired mode. Select ''Multi Server Mode'' and click ''OK''. <br />
*: [[File:ms_spe_config_multi_01.png|center]]<br />
* Click ''Add Server Role''<br />
* Select ''Instance Host''<br />
* Fill out the ''Configure Instance Host Role'' form.<br />
*: [[File:ms_spe_config_ih_01.png|center]]<br />
:* '''Server Name:''' Fully qualified host name (FQHN) of the server <br />
:* '''TCP Server Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections from the Management Server (Default: *:8472)<br />
:* '''TCP Server Certificate: ''' Fingerprint of the SSL certificate used by the Instance Host to authenticate against Management Server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
:* '''Management Server:''' Fully qualified host name (FQHN) of the Management Server to connect to.<br />
:* '''Port:''' TCP port where the above Management Server accepts incoming connections.<br />
:* '''Management Server Cert''' Fingerprint of the SSL certificate used by the Management Server to authenticate against Instance Host. This value is set automatically when [[Multi_Server_Mode_Setup#Pairing with Management Server|Pairing with Management Server]]<br />
* Click ''OK'' to add the Instance Host role.<br />
* Click '''Start'' to start the Instance Host service.<br />
*: '''Please note:'' As the startup process of the services is asynchronous, please wait up to 30 seconds. A service shown as running may still switch back to stopped during that period if an error occurred.<br />
* It is now safe to close the MailStore Service Provider Edition Configuration tool<br />
<br />
== Set Up Client Access Server ==<br />
<br />
* If not executed automatically by the installation program, start the MailStore Service Provider Edition Configuration tool by double-clicking its desktop icon. On a Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.<br />
* If no configuration files and services are found, the ''MailStore Service Provider Edition Configuration'' will ask for the desired mode. Select ''Multi Server Mode'' and click ''OK''. <br />
*: [[File:ms_spe_config_multi_01.png|center]]<br />
* Click ''Add Server Role'' .<br />
* Select ''Client Access Server''.<br />
* Fill out the ''Configure Client Access Server Role'' form.<br />
*: [[File:ms_spe_config_cas_01.png|center]]<br />
:* '''Server Name:''' Fully qualified host name (FQHN) of the server <br />
:* '''TCP Server Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections from the Management Server (Default: *:8473)<br />
:* '''TCP Server Certificate: ''' Fingerprint of the SSL certificate used by the Client Access Server to authenticate against Management Server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
:* '''Management Server:''' Fully qualified host name (FQHN) of the Management Server to connect to.<br />
:* '''Port:''' TCP port where the above Management Server accepts incoming connections.<br />
:* '''Management Server Cert''' Fingerprint of the SSL certificate used by the Management Server to authenticate against Client Access Server. This value is set automatically when [[Multi_Server_Mode_Setup#Pairing with Management Server|Pairing with Management Server]]<br />
:* '''HTTP Server Enabled:''' If enabled the Client Access Server provides access to archives via MailStore Client, MailStore Outlook Add-in and MailStore Web Access.<br />
:*: '''Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections (Default: *:443)<br />
:*: '''Server Certificate:''' Fingerprint of the SSL certificate used by the HTTP Server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
:* '''IMAP Server with explicit TLS Enabled:''' If enabled the Client Access Server provides access to archives via IMAP protocol. Connection can either be unencrypted or secured via STARTTLS.<br />
:*: '''Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections (Default: *:143)<br />
:*: '''Server Certificate:''' Fingerprint of the SSL certificate used by the IMAP Server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
:* '''IMAP Server with implicit TLS Enabled:''' If enabled the Client Access Server provides access to archives via IMAP protocol. Connection is encrypted via SSL/TLS.<br />
:*: '''Listeners:''' If the server is multihomed you can specify on which IP address and TCP port to listen for incoming connections (Default: *:993)<br />
:*: '''Server Certificate:''' Fingerprint of the SSL certificate used by the IMAP Server. Use the button next to the fingerprint to select a different certificate from the computer's certificate store. <br />
* Click ''OK'' to add the Client Access Server role.<br />
* Click '''Start'' to start the Client Access Server service.<br />
*: '''Please note:'' As the startup process of the services is asynchronous, please wait up to 30 seconds. A service shown as running may still switch back to stopped during that period if an error occurred.<br />
* It is now safe to close the MailStore Service Provider Edition Configuration tool<br />
<br />
== Pairing with Management Server ==<br />
<br />
Before Client Access Servers and Instance Hosts are able to communicate with the Management Server, SSL certificate fingerprints must be exchanged to establish a trust relationship. Additionally the Instance Hosts and Client Access Servers must be registered in the Management Server with its server name and TCP port. <br />
<br />
This process can simply be performed by using the pairing function as described in the following:<br />
<br />
* Enter the fully qualified host name of the ''Management Server'' in the corresponding field while configuring an Instance Host or Client Access Server.<br />
* Click ''Pair with this server''.<br />
* Enter the user name and password of a MailStore Service Provider Edition administrator.<br />
* Click ''OK'' to pair with Management Server<br />
<br />
'''Please note:''' Pairing is carried out through the Management API. Therefore the Instance Hosts and Client Access Servers must be able to establish a connection to the HTTP server on the Management Server (Default TCP port: 8470).<br />
<br />
If your security policy does not permit establishing such a connection, pairing must be performed manually. Please refer to [[Management Console - Infrastructure#Add New Instance Host|Add New Instance Host]] or [[Management Console - Infrastructure#Add New Client Access Server|Add New Client Access Server]] for further details.<br />
<br />
= What to do next =<br />
<br />
In production environments it is recommended to replace the self-signed certificates used by the Client Access Server's IMAP and HTTP server with certificates signed by a trusted root certificate authority. Further details can be found in [[Replace Self-signed SSL Certificates]]</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Single_Server_Mode_Setup&diff=895Single Server Mode Setup2014-02-14T09:23:33Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
= Set Up Single Server Mode =<br />
<br />
* If not executed automatically by the installation program, start the MailStore Service Provider Edition Configuration tool by double-clicking its desktop icon. On a Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.<br />
* If no configuration files and services are found, the MailStore Service Provider Edition Configuration tool will ask for the desired mode. Select ''Single Server Mode'' and click ''OK''.<br />
*: [[File:ms_spe_config_01.png|center]]<br />
* Enter your product key into the ''Product Key'' field and change ''Server Name'' to the fully qualified host name of the server (e.g. <tt>server.ms-spe.test</tt>). Finally enter and confirm the ''admin'' password that will be used to log on to the Management Console.<br />
*: [[File:ms_spe_config_02.png|center]]<br />
* Click ''OK''.<br />
* The MailStore Service Provider Edition Configuration tool will now create the configuration files for the ''Management Server'', ''Instance Host'' and ''Client Access Server'' roles. After the configuration has been successfully created, a Windows service is registered and started for each role. It takes about 10-15 seconds until the roles show up in the MailStore Service Provider Edition Configuration tool.<br/><br/>'''Important notice:''' Unless a different target directory was specified during installation, the configuration files are stored in <tt>%PROGRAMFILES%\MailStore Infrastructure\config</tt>. Although these files are in text format (JSON), please do not attempt to modify any of these files without using the MailStore Service Provider Edition Configuration tool. <br />
*: [[File:ms_spe_config_status_all_roles.png|550px|center]]<br />
* The startup process of the services takes place in the background. Therefore a service shown as ''running'' may still revert to ''stopped'' during a period of about 30 seconds in the event of an error.<br />
<br />
= What to do next =<br />
<br />
In production environments it is recommended to replace the self-signed certificates used by the Client Access Server's IMAP and HTTP server with certificates signed by a trusted root certificate authority. Further details can be found in [[Replace Self-signed SSL Certificates]]<br />
<br />
If the self-signed certificates should remain, the basic configuration of the MailStore Service Provider Edition is finished. All other administrative tasks are performed through the web-based [[Management_Console_-_General|MailStore Management Console]].</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Firewall_Configuration_for_Single_Server_Mode&diff=894Firewall Configuration for Single Server Mode2014-02-14T09:23:19Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
It is highly recommended to protect any MailStore Service Provider Edition service with appropriate firewall rules. This document should help with setting up the required rules.<br />
<br />
'''Important Notices:''' <br />
* The communication channels described below MUST NOT be intercepted by any kind of email or web proxies that are provided as part of antivirus software or unified threat management gateways. <br />
* The Windows Advanced Firewall is activated on any Windows Server installation by default. In order to connect to services (e.g. MailStore Management Console) of the MailStore Service Provider Edition, it is required that the appropriate firewall rules are added (see below).<br />
<br />
= Firewall Rules For Single Server Mode =<br />
<br />
The table below lists all TCP ports that need to be opened in the firewall when using MailStore Service Provider Edition in single server mode. The following abbreviations are used in the source and target columns of that table:<br />
<br />
* ANY = Any computer from private or public networks <br />
* ADM = Computer or network used for administration<br />
* SERVER = Server that hosts MailStore Service Provider Edition<br />
<br />
A list of all TCP ports used by MailStore Service Provider Edition is available in the [[System Requirements#Required Ports|System Requirements]]<br />
<br />
{| class="wikitable sortable"<br />
! width="80px" | Port<br />
! width="80px" | Source <br />
! width="80px" | Target<br />
! class="unsortable"| Description<br />
|-<br />
| align="center" | 110<br />
| align="center" | SERVER<br />
| align="center" | ANY<br />
| Access to email servers for archiving via POP3 (Unencrypted/STARTTLS). <br />
|-<br />
| align="center" | 143<br />
| align="center" | SERVER<br />
| align="center" | ANY<br />
| Access to email servers for archiving via IMAP (Unencrypted/STARTTLS). <br />
|-<br />
| align="center" | 143<br />
| align="center" | ANY<br />
| align="center" | SERVER<br />
| IMAP access to archives secured by TLS (STARTTLS) encryption. <br />
|-<br />
| align="center" | 443<br />
| align="center" | SERVER<br />
| align="center" | ANY<br />
| Access to Microsoft Exchange servers for archiving via Exchange Web Services (EWS) secured by SSL encryption.<br />
|-<br />
| align="center" | 443<br />
| align="center" | SERVER<br />
| align="center" | my.mailstore.com<br />
| Usage reporting and license update<br />
|-<br />
| align="center" | 443<br />
| align="center" | ANY<br />
| align="center" | SERVER<br />
| HTTPS access to instances used by MailStore Client, MailStore Outlook Add-in, MailStore Web Access and MailStore Mobile Web Access.<br />
|-<br />
| align="center" | 993<br />
| align="center" | SERVER<br />
| align="center" | ANY<br />
| Access to email servers for archiving via IMAP (SSL). <br />
|-<br />
| align="center" | 993 <br />
| align="center" | ANY<br />
| align="center" | SERVER<br />
| IMAP access to archives secured by TLS (SSL) encryption. <br />
|-<br />
| align="center" | 995<br />
| align="center" | SERVER<br />
| align="center" | ANY<br />
| Access to email servers for archiving via POP3 (SSL). <br />
|-<br />
| align="center" | 8470<br />
| align="center" | ADM<br />
| align="center" | SERVER<br />
| Web-based access to the MailStore Management Console.<br />
|}<br />
<br />
== Windows Advanced Firewall ==<br />
<br />
The Windows Advanced Firewall can easily be re-configured for Single Server Mode. By executing the following commands in the Windows PowerShell command prompt, the required TCP ports are opened for inbound connections. Outbound connections to any destination are allowed by default. <br />
<br />
<source lang="powershell" toolbar="false" gutter="false"><br />
# Allow access to CAS ports from everwhere<br />
netsh advfirewall firewall add rule name="MailStore Service Provider Edition (CAS)" `<br />
action=ALLOW dir=IN protocol=TCP localport="143,443,993" profile=ANY<br />
<br />
# Allow access to MailStore Service Provider Management Console from adminstrator network 192.0.2.0/24<br />
netsh advfirewall firewall add rule name="MailStore Service Provider Edition (MGMT)" `<br />
action=ALLOW dir=IN protocol=TCP localport="8470" remoteip="192.0.2.0/24" profile=ANY<br />
</source><br />
<br />
= Firewall Rules For Multi Server Mode =<br />
<br />
The below table lists all TCP ports that need to be opened in the firewall when using MailStore Service Provider Edition in multi server mode. The following abbreviations are used in the source and target columns: <br />
<br />
* ANY = Any computer from private or public networks<br />
* ADM = Computer or network used for administration<br />
* CAS = Server hosting Client Access Server role<br />
* IH = Server hosting Instance Host role<br />
* MGMT = Server hosting Management Server role<br />
<br />
A list of all TCP ports used by MailStore Service Provider Edition is available in [[System Requirements#Required Ports|System Requirements]]<br />
<br />
{| class="wikitable sortable"<br />
! width="80px" | Port<br />
! width="80px" | Source<br />
! width="80px" | Target<br />
! class="unsortable" | Description<br />
|-<br />
| align="center" | 110<br />
| align="center" | IH<br />
| align="center" | ANY<br />
| Access to email servers for archiving via POP3 (Unencrypted/STARTTLS). <br />
|-<br />
| align="center" | 143<br />
| align="center" | IH<br />
| align="center" | ANY<br />
| Access to email servers for archiving via IMAP (Unencrypted/STARTTLS). <br />
|-<br />
| align="center" | 143<br />
| align="center" | ANY<br />
| align="center" | CAS<br />
| IMAP access to archives secured by TLS (STARTTLS) encryption.<br />
|-<br />
| align="center" | 443<br />
| align="center" | IH<br />
| align="center" | ANY<br />
| Access to Microsoft Exchange Server for archiving via Exchange Web Services (EWS) secured by SSL encryption. <br />
|-<br />
| align="center" | 443<br />
| align="center" | ANY<br />
| align="center" | CAS<br />
| HTTPS access to instances used by MailStore Client, MailStore Outlook Add-in, MailStore Web Access and MailStore Mobile Web Access.<br />
|-<br />
| align="center" | 443<br />
| align="center" | MGMT<br />
| align="center" | my.mailstore.com<br />
| Usage reporting and license update<br />
|-<br />
| align="center" | 993 <br />
| align="center" | ANY<br />
| align="center" | CAS<br />
| IMAP access to archives secured by TLS (SSL) encryption.<br />
|-<br />
| align="center" | 993<br />
| align="center" | IH<br />
| align="center" | ANY<br />
| Access to email servers for archiving via IMAP (SSL). <br />
|-<br />
| align="center" | 995<br />
| align="center" | IH<br />
| align="center" | ANY<br />
| Access to email servers for archiving via POP3 (SSL). <br />
|-<br />
| align="center" | 8470<br />
| align="center" | ADM<br />
| align="center" | MGMT<br />
| Web-based access to the MailStore Management Console.<br />
|-<br />
| align="center" | 8470<br />
| align="center" | IH, CAS<br />
| align="center" | MGMT<br />
| Optional: Required for initial pairing with Management Server. If not available, manual registration of Instance Hosts and Client Access Servers in Management Server is required.<br />
|-<br />
| align="center" | 8471<br />
| align="center" | CAS, IH<br />
| align="center" | MGMT<br />
| Internal communication with Management Server<br />
|-<br />
| align="center" | 8472<br />
| align="center" | MGMT, CAS<br />
| align="center" | IH<br />
| Internal communication with Instance Hosts<br />
|-<br />
| align="center" | 8473<br />
| align="center" | MGMT<br />
| align="center" | CAS<br />
| Internal communication with Client Access Servers<br />
|}<br />
<br />
= What to do next =<br />
<br />
In environments where the single server mode is sufficient, the setup procedure continues with configuration of MailStore Service Provider Edition as described in [[Single Server Mode Setup]]. <br />
<br />
In environments where a multi server mode setup is planned, deploy and install MailStore Service Provider Edition as described above on all other machines before continuing the setup process with the configuration of the Management Server role as described in [[Multi Server Mode Setup]].</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Installing_MailStore_Service_Provider_Edition&diff=893Installing MailStore Service Provider Edition2014-02-14T09:22:54Z<p>Admin: </p>
<hr />
<div>This setup file of MailStore Service Provider Edition includes all necessary data to deploy an arbitrary MailStore Service Provider Edition role. After the installation of the program files has been finished, the roles of the server are to be specified in the initial setup process. There is no difference in the actual installation process for a single server or multi server mode setup. Furthermore the same setup file is used to install MailStore Service Provider Edition on a normal Windows Server or Windows Server Core without graphical user interface.<br />
<br />
= Installation Procedure =<br />
<br />
* Start the installation process by double-clicking on the downloaded setup file or, when installing on a Windows Server Core, use the command line prompt to navigate to the location of the setup file and execute it.<br />
* Read the license agreement.<br />
* Select ''Accept the agreement'' and click ''Next''.<br />
* Specify the target directory for the program files (default: <tt>C:\Program Files\MailStore Infrastructure</tt>) and click ''Next''.<br />
* The setup program now extracts all program files into the given target directory.<br />
* Leave the option ''Launch MailStore Service Provider Edition Configuration'' checked and click ''Next'' to start the configuration program. Otherwise deselect the option and click ''Next''. The MailStore Service Provider Edition Configuration can be executed manually at any time by using the appropriate link on the desktop or from the Windows start menu.<br />
<br />
= What to do next =<br />
<br />
It is recommended to adjust the [[Firewall Configuration]] of your servers and network before continuing the setup procedure with creating a [[Single Server Mode Setup]] or [[Multi Server Mode Setup]],</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=System_Requirements&diff=892System Requirements2014-02-14T09:22:39Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
<br />
Before beginning the installation of MailStore Service Provider Edition it needs to be ensured that all system requirements are met.<br />
<br />
= Hardware =<br />
<br />
== Single Server Mode or Individual Instance Hosts ==<br />
<br />
The table below shows the recommended hardware configuration for a single server mode setup or an individual Instance Host in a multi-server mode setup with a maximum of 1000 users in total. Reduce the number of CPU cores and amount of main memory for smaller installations.<br />
<br />
'''Important:''' Please also carefully read the [[Performance and Scalability Guidelines]] to understand the impact of network, storage and other hardware components as well as configuration options and usage scenarios on overall performance.<br />
<br />
{| class="wikitable" width="100%"<br />
! width="150" scope="row" | '''Processor'''<br />
| Intel Xeon Quad Core or compatible CPU @ 2.4GHz<br />
|-<br />
! width="150" scope="row" | '''Main Memory'''<br />
| 1024 MB + INSTANCES &times; 256 MB + USERS &times; 5 MB + 10%<br/><small>(e.g. ''1024 MB + 20 &times; 256 MB + 1000 &times; 5 MB + 10% = 12258 MB'')</small><br />
|-<br />
! width="150" scope="row" | '''Hard Disk'''<br />
| 150 MB disk space required for installation. A minimum of two separate disks is recommended:<br/>Disk 1) Operating system, program files and temporary files. <br/>Disk 2) Dedicated disk for archive data<br />
|-<br />
! width="150" scope="row" | '''Storage Configuration'''<br />
| Hardware RAID 10 (SAS/10.000 RPM or faster)<br />
|}<br />
<br />
== Management Server ==<br />
<br />
This information only applies to an individual Management Server in a multi-server setup. <br />
<br />
{| class="wikitable" width="100%"<br />
! width="150" scope="row" | '''Processor'''<br />
| Any x64 compatible CPU <br />
|-<br />
! width="150" scope="row" | '''Main Memory'''<br />
| 1 GB<br />
|-<br />
! width="150" scope="row" | '''Hard Disk'''<br />
| 150 MB available disk space<br />
|}<br />
<br />
== Client Access Server ==<br />
<br />
This information only applies to an individual Client Access Server in a multi-server setup. <br />
<br />
{| class="wikitable" width="100%"<br />
! width="150" scope="row" | '''Processor'''<br />
| Any x64 compatible CPU <br />
|-<br />
! width="150" scope="row" | '''Main Memory'''<br />
| 1 GB<br />
|-<br />
! width="150" scope="row" | '''Hard Disk'''<br />
| 150 MB available disk space<br />
|}<br />
<br />
= Software Requirements =<br />
* Following operating systems are supported<br />
** Windows Server 2008 R2 Standard, Enterprise or Datacenter (Server Core Installation)<br />
** Windows Server 2008 R2 Standard, Enterprise or Datacenter (Server with a GUI)<br />
** Windows Server 2012 Standard or Datacenter (Server Core Installation)<br />
** Windows Server 2012 Standard or Datacenter (Server with a GUI)<br />
** Windows Server 2012 R2 Standard or Datacenter (Server Core Installation)<br />
** Windows Server 2012 R2 Standard or Datacenter (Server with a GUI)<br />
* Following web browsers are supported by the Management Console:<br />
** Internet Explorer 10 or higher<br />
** Google Chome 18 or higher<br />
** Mozilla Firefox 18 or higher<br />
** Apple Safari 6 or higher<br />
* '''.NET Framework 3.5 SP1'''<br/>The appropriate Windows Server feature will be enabled automatically by the MailStore Service Provider Edition installer. In environments with centrally managed Windows updates the automatic installation may not succeed. In such cases the installation of the .NET Framework 3.5 SP1 feature must be done manually before executing the MailStore Service Provider Edition setup file.<br />
* '''Microsoft Office 2010 Filter Packs''' ''(optional)''<br/>For indexing email attachments other than TXT, PDF and HTML files, additional libraries are required. For Microsoft Office documents (legacy and recent formats) or documents in Open Document Format ((OpenOffice/LibreOffice) the [http://www.microsoft.com/en-us/download/details.aspx?id=17062|Microsoft Office 2010 Filter Packs] have to be installed manually on each server hosting an Instance Host. Please refer to [[Instance_Management_-_Instance_Administration#Search_Indexes|Search Index]] for further details about attachment indexing.<br />
* It is not recommended to install MailStore Service Provider Edition on servers that already provide other network services. Especially with email or web servers TCP port conflicts are likely to occur. Specifically, Microsoft's Internet Information Server (IIS) MUST NOT be installed on any server that hosts the Client Access Server role.<br />
<br />
= Network Requirements =<br />
<br />
* Verify that the DNS name of the MailStore Service Provider Edition servers match their actual computer name and that all servers have a proper forward and reverse DNS resolution configured.<br />
* Do not intercept connections from or to MailStore Service Provider Edition servers with web or email proxies. Read [[msserver:Notes_on_Antivirus_Software|Notes on Antivirus Software]] in the MailStore Server help for further details.<br />
* For communication between MailStore Service Provider Edition services, access to the MailStore Management Console and end user access to instances, the following TCP ports are opened by the MailStore Service Provider Edition services and must therefore not be used by any other service.<br />
<br />
{| class="wikitable"<br />
! width="100px" | Port<br />
! width="150px" | Role<br />
! Description<br />
|-<br />
| align="center"| 143<br />
| align="center"| Client Access Server<br />
| The standard IMAP port is used to provide read-only access to archived emails via IMAP protocol. The IMAP server on this port supports unencrypted as well as TLS secured connections (recommended) that have been initiated by the email client via STARTTLS command.<br />
|-<br />
| align="center"| 443<br />
| align="center"| Client Access Server<br />
| The standard HTTTPS port is used to provide SSL encrypted access to MailStore Instances via MailStore Client, MailStore Outlook Add-in, MailStore Web Access and MailStore Mobile Web Access.<br />
|-<br />
| align="center"| 993<br />
| align="center"| Client Access Server<br />
| The standard IMAPS port is used to provide read-only access to archived emails via IMAP protocol. The IMAP server on this port support SSL/TLS encrypted connections only.<br />
|-<br />
| align="center"| 8470<br />
| align="center"| Management Server<br />
| This port is used to provide administrators access to the Management Console via web browser. The HTTP server on this port support SSL/TLS encrypted connections only, also known as HTTPS.<br />
|-<br />
| align="center"| 8471<br />
| align="center"| Management Server<br />
| Instance Hosts and Client Access Servers connect to the Management Server through this port.<br />
|-<br />
| align="center"| 8472<br />
| align="center"| Instance Host<br />
| Client Access Servers and the Management Server connect to the Instance Hosts through this port. <br />
|-<br />
| align="center"| 8473<br />
| align="center"| Client Access Server<br />
| Management Server connects to Client Access Servers through this port.<br />
|}<br />
<br />
= What to do next =<br />
<br />
After ensuring that the environment fulfils the system requirements, proceed with [[Installing MailStore Service Provider Edition]].</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Frequently_Asked_Questions&diff=891Frequently Asked Questions2014-02-14T09:21:55Z<p>Admin: </p>
<hr />
<div>= System Requirements =<br />
* '''What are the system requirements of MailStore Service Provider Edition?'''<br/>A comprehensive overview of all system requirements can be found on the [[System Requirements]] page.<br />
* '''What are the recommendations for a persistent, high performance operation?'''<br/>Such recommendations are available in our [[Performance and Scalability Guidelines]].<br />
* '''What is the maximum number of user archives per instance?'''<br/>The maximum recommended number of users per instance is 300. For further details, refer to our [[Performance and Scalability Guidelines]].<br />
* '''What is the maximum number of instances (respectively end-customers) that can be created?'''<br/>An infinite number of instances can be deployed on an unlimited number of Instance Hosts. Please refer to our [[Performance and Scalability Guidelines]] or contact our [https://cs.mailstore.com technical support] directly for further inquiries.<br />
* '''Will there be a Linux version?'''<br/>Due to being fully dependent on Microsoft’s .NET Framework, it is unlikely that a Linux version will exist in the future.<br />
<br />
= Use Scenarios =<br />
<br />
* '''How can I switch from single server to multi server mode?'''<br/>Any single server mode setup where Management Server, Instance Host and Client Access Server roles are installed on the same server, can be turned easily into a multi server mode setup by adding additional Instance Hosts or Client Access Servers. Further information can be found in the [[Multi Server Mode Setup]] chapter.<br />
* '''As a large organization (end customer), can I run MailStore Service Provider Edition in my own Private Cloud?'''<br/>Generally, the MailStore Service Provider Edition can be used in Private Clouds. Please [https://cs.mailstore.com contact us] for further details.<br />
* '''As a Service Provider, can I use MailStore Service Provider Edition in Virtual Private Clouds that I am hosting for my end customers?'''<br/>Using MailStore Service Provider Edition in Virtual Private Clouds is absolutely possible. Please refer to the [[Overview]] to learn more about the different supported scenarios.<br />
* ''' Can MailStore Service Provider Edition run on Amazon EC2, Windows Azure or similar infrastructure?'''<br/>Due to its storage technology and the required disk I/O throughput, it is not recommended to run MailStore Service Provider Edition on such infrastructure.</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Main_Page&diff=890Main Page2014-02-13T17:12:56Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
{{DISPLAYTITLE:MailStore Service Provider Edition Help}}<br />
<br />
Service providers receive an unlimited, scalable software solution with MailStore Service Provider Edition, which they will be able to independently operate either on their existing IT infrastructures or those they have leased. This help website has an exclusive focus on installing and setting up the backend of the MailStore Service Provider Edition. For administration of MailStore Instances, which is comparable to the on-premises solution MailStore Server, please visit the [http://en.help.mailstore.com/ MailStore Server Help]<br />
<br />
{| <br />
| style="vertical-align: top; width: 50%" |<br />
= General Information =<br />
An introduction to the architecture, the most typical usage scenarios of the MailStore Service Provider Edition and further general yet important information are given by the following articles:<br />
<br />
* [[Overview]]<br />
* [[Performance and Scalability Guidelines]]<br />
* [[Frequently Asked Questions]]<br />
| style="vertical-align: top; width: 50%" |<br />
= Installation and Setup =<br />
The ''Installation and Setup'' chapter provides an entire walkthrough of installation and setup process of MailStore Service Provider Edition. Each article ends with a "What to do next" section that guides to the next step.<br />
<br />
* [[System Requirements]]<br />
* [[Installing MailStore Service Provider Edition]]<br />
* [[Firewall Configuration]]<br />
* [[Single Server Mode Setup]] or [[Multi Server Mode Setup]]<br />
* [[Replace Self-signed SSL Certificates]]<br />
* [[Branding]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Management Console =<br />
The MailStore Management Console is the primary, web based administration utility for MailStore Service Provider Edition administrators. The following articles provide a general overview of all available functions. Every function of the Management Console also has a corresponding [[Management API - Function Reference|Management API command]], which allows full, script-based control over MailStore Service Provider Edition.<br />
<br />
* [[Management_Console|Logging On & Navigation]]<br />
* [[Management_Console_-_General|General]]<br />
* [[Management_Console_-_Infrastructure|Infrastructure]]<br />
* [[Management_Console_-_Security|Security]]<br />
* [[Management_Console_-_Developer|Developer]]<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Instance Management =<br />
Managing MailStore Instances consist of two main areas: ''General Administration'' covers all aspects of creating, controlling and configuring instances, whereas ''Instance Administration'' deals with the administration of internal parameters for each instance such as archive stores, search indexes, user synchronization, archiving profiles, etc.<br />
<br />
* [[Instance Management - General Administration| General Administration]]<br />
* [[Instance Management - Instance Administration | Instance Administration]]<br />
<br />
= Related Articles =<br />
<br />
* [[End Customer Access]]<br />
* [[Startup Scripts]]<br />
* [[Backup and Restore]]<br />
* [[Application Integration|Directory Service: Application Integration]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Management API =<br />
The Management API extends the management capabilities of the MailStore Service Provider Edition by providing a HTTP based access to all management functions. This allows to fully automate the administration of MailStore Service Provider Edition 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.<br />
<br />
* [[Management API - Using the API|Using the API]]<br />
* [[Management API - Function Reference|Function Reference]]<br />
* [[Management API - Command Line Client|Command Line Client]]<br />
: '''Example Implementation of API Libraries'''<br />
:* PowerShell<br />
:* Python<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
= Downloads =<br />
<br />
:'''Active Directory Group Policy Templates'''<br />
<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_ADM.zip ADM-Template]<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_ADMX.zip ADMX-Template]<br />
<br />
:'''Example API Libraries and Clients'''<br />
* PowerShell Library<br />
* Python Library<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_Linux_Management_API_Client.zip Linux Management API Client]<br />
|}</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Main_Page&diff=889Main Page2014-02-13T16:56:33Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
{{DISPLAYTITLE:MailStore Service Provider Edition Help}}<br />
<br />
Service providers receive an unlimited, scalable software solution with MailStore Service Provider Edition, which they will be able to independently operate either on their existing IT infrastructures or those they have leased. This help website has an exclusive focus on installing and setting up the backend of the MailStore Service Provider Edition. For administration of MailStore Instances, which is comparable to the on-premises solution MailStore Server, please visit the [http://en.help.mailstore.com/ MailStore Server Help]<br />
<br />
{| <br />
| style="vertical-align: top; width: 50%" |<br />
== General Information ==<br />
An introduction to the architecture, the most typical usage scenarios of the MailStore Service Provider Edition and further general yet important information are given by the following articles:<br />
<br />
* [[Overview]]<br />
* [[Performance and Scalability Guidelines]]<br />
* [[Frequently Asked Questions]]<br />
| style="vertical-align: top; width: 50%" |<br />
== Installation and Setup ==<br />
The ''Installation and Setup'' chapter provides an entire walkthrough of installation and setup process of MailStore Service Provider Edition. Each article ends with a "What to do next" section that guides to the next step.<br />
<br />
* [[System Requirements]]<br />
* [[Installing MailStore Service Provider Edition]]<br />
* [[Firewall Configuration]]<br />
* [[Single Server Mode Setup]] or [[Multi Server Mode Setup]]<br />
* [[Replace Self-signed SSL Certificates]]<br />
* [[Branding]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Management Console ==<br />
The MailStore Management Console is the primary, web based administration utility for MailStore Service Provider Edition administrators. The following articles provide a general overview of all available functions. Every function of the Management Console also has a corresponding [[Management API - Function Reference|Management API command]], which allows full, script-based control over MailStore Service Provider Edition.<br />
<br />
* [[Management_Console|Logging On & Navigation]]<br />
* [[Management_Console_-_General|General]]<br />
* [[Management_Console_-_Infrastructure|Infrastructure]]<br />
* [[Management_Console_-_Security|Security]]<br />
* [[Management_Console_-_Developer|Developer]]<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Instance Management ==<br />
Managing MailStore Instances consist of two main areas: ''General Administration'' covers all aspects of creating, controlling and configuring instances, whereas ''Instance Administration'' deals with the administration of internal parameters for each instance such as archive stores, search indexes, user synchronization, archiving profiles, etc.<br />
<br />
* [[Instance Management - General Administration| General Administration]]<br />
* [[Instance Management - Instance Administration | Instance Administration]]<br />
<br />
== Related Articles ==<br />
<br />
* [[End Customer Access]]<br />
* [[Startup Scripts]]<br />
* [[Backup and Restore]]<br />
* [[Application Integration|Directory Service: Application Integration]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Management API ==<br />
The Management API extends the management capabilities of the MailStore Service Provider Edition by providing a HTTP based access to all management functions. This allows to fully automate the administration of MailStore Service Provider Edition 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.<br />
<br />
* [[Management API - Using the API|Using the API]]<br />
* [[Management API - Function Reference|Function Reference]]<br />
* [[Management API - Command Line Client|Command Line Client]]<br />
: '''Example Implementation of API Libraries'''<br />
:* PowerShell<br />
:* Python<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Downloads ==<br />
<br />
:'''Active Directory Group Policy Templates'''<br />
<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_ADM.zip ADM-Template]<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_ADMX.zip ADMX-Template]<br />
<br />
:'''Example API Libraries and Clients'''<br />
* PowerShell Library<br />
* Python Library<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_Linux_Management_API_Client.zip Linux Management API Client]<br />
<br />
<br />
|}</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=MediaWiki:Sidebar-banner1&diff=888MediaWiki:Sidebar-banner12014-02-13T16:56:01Z<p>Admin: </p>
<hr />
<div><a href="http://www.mailstore.com/en/mailstore-cloud-email-archiving.aspx"><img src="../mailstore-spe-box-140x180.png" /></a><br/><br />
<a href="http://www.mailstore.com/en/mailstore-cloud-email-archiving.aspx">MailStore Service Provider Edition</a> Email Archiving Software For Service Providers.</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Main_Page&diff=887Main Page2014-02-13T15:54:13Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
{{DISPLAYTITLE:MailStore Service Provider Edition Help}}<br />
<br />
Service providers receive an unlimited, scalable software solution with MailStore Service Provider Edition, which they will be able to independently operate either on their existing IT infrastructures or those they have leased. This help website has an exclusive focus on installing and setting up the backend of the MailStore Service Provider Edition. For administration of MailStore Instances, which is comparable to the on-premises solution MailStore Server, please visit the [http://en.help.mailstore.com/ MailStore Server Help]<br />
<br />
{| <br />
| style="vertical-align: top; width: 50%" |<br />
== General Information ==<br />
An introduction to the architecture, the most typical usage scenarios of the MailStore Service Provider Edition and further general yet important information are given by the following articles:<br />
<br />
* [[Overview]]<br />
* [[Performance and Scalability Guidelines]]<br />
* [[Frequently Asked Questions]]<br />
| style="vertical-align: top; width: 50%" |<br />
== Installation and Setup ==<br />
The ''Installation and Setup'' chapter provides an entire walkthrough of installation and setup process of MailStore Service Provider Edition. Each article ends with a "What to do next" section that guides to the next step.<br />
<br />
* [[System Requirements]]<br />
* [[Installing MailStore Service Provider Edition]]<br />
* [[Firewall Configuration]]<br />
* [[Single Server Mode Setup]] or [[Multi Server Mode Setup]]<br />
* [[Replace Self-signed SSL Certificates]]<br />
* [[Branding]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Management Console ==<br />
The MailStore Management Console is the primary, web based administration utility for MailStore Service Provider Edition administrators. The following articles provide a general overview of all available functions. Every function of the Management Console also has a corresponding [[Management API - Function Reference|Management API command]], which allows full, script-based control over MailStore Service Provider Edition.<br />
<br />
* [[Management_Console|Logging On & Navigation]]<br />
* [[Management_Console_-_General|General]]<br />
* [[Management_Console_-_Infrastructure|Infrastructure]]<br />
* [[Management_Console_-_Security|Security]]<br />
* [[Management_Console_-_Developer|Developer]]<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Instance Management ==<br />
Managing MailStore Instances consist of two main areas: ''General Administration'' covers all aspects of creating, controlling and configuring instances, whereas ''Instance Administration'' deals with the administration of internal parameters for each instance such as archive stores, search indexes, user synchronization, archiving profiles, etc.<br />
<br />
* [[Instance Management - General Administration| General Administration]]<br />
* [[Instance Management - Instance Administration | Instance Administration]]<br />
<br />
== Related Articles ==<br />
<br />
* [[End Customer Access]]<br />
* [[Startup Scripts]]<br />
* [[Backup and Restore]]<br />
* [[Application Integration|Directory Service: Application Integration]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Management API ==<br />
The Management API extends the management capabilities of the MailStore Service Provider Edition by providing a HTTP based access to all management functions. This allows to fully automate the administration of MailStore Service Provider Edition 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.<br />
<br />
* [[Management API - Using the API|Using the API]]<br />
* [[Management API - Function Reference|Function Reference]]<br />
* [[Management API - Command Line Client|Command Line Client]]<br />
: '''Example Implementation of API Libraries'''<br />
:* PowerShell<br />
:* Python<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Downloads ==<br />
<br />
:'''Active Directory Group Policy Templates'''<br />
<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_ADM.zip ADM-Template]<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_ADMX.zip ADMX-Template]<br />
<br />
:'''Example API Libraries and Clients'''<br />
* PowerShell Library<br />
* Python Library<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_Linux_Management_API_Client.zip Linux Management API Client]<br />
<br />
<br />
|}<br />
<br />
[[en:Main_Page]]</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Main_Page&diff=886Main Page2014-02-13T15:53:59Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
{{DISPLAYTITLE:MailStore Service Provider Edition Help}}<br />
<br />
Service providers receive an unlimited, scalable software solution with MailStore Service Provider Edition, which they will be able to independently operate either on their existing IT infrastructures or those they have leased. This help website has an exclusive focus on installing and setting up the backend of the MailStore Service Provider Edition. For administration of MailStore Instances, which is comparable to the on-premises solution MailStore Server, please visit the [http://en.help.mailstore.com/ MailStore Server Help]<br />
<br />
{| <br />
| style="vertical-align: top; width: 50%" |<br />
== General Information ==<br />
An introduction to the architecture, the most typical usage scenarios of the MailStore Service Provider Edition and further general yet important information are given by the following articles:<br />
<br />
* [[Overview]]<br />
* [[Performance and Scalability Guidelines]]<br />
* [[Frequently Asked Questions]]<br />
| style="vertical-align: top; width: 50%" |<br />
== Installation and Setup ==<br />
The ''Installation and Setup'' chapter provides an entire walkthrough of installation and setup process of MailStore Service Provider Edition. Each article ends with a "What to do next" section that guides to the next step.<br />
<br />
* [[System Requirements]]<br />
* [[Installing MailStore Service Provider Edition]]<br />
* [[Firewall Configuration]]<br />
* [[Single Server Mode Setup]] or [[Multi Server Mode Setup]]<br />
* [[Replace Self-signed SSL Certificates]]<br />
* [[Branding]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Management Console ==<br />
The MailStore Management Console is the primary, web based administration utility for MailStore Service Provider Edition administrators. The following articles provide a general overview of all available functions. Every function of the Management Console also has a corresponding [[Management API - Function Reference|Management API command]], which allows full, script-based control over MailStore Service Provider Edition.<br />
<br />
* [[Management_Console|Logging On & Navigation]]<br />
* [[Management_Console_-_General|General]]<br />
* [[Management_Console_-_Infrastructure|Infrastructure]]<br />
* [[Management_Console_-_Security|Security]]<br />
* [[Management_Console_-_Developer|Developer]]<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Instance Management ==<br />
Managing MailStore Instances consist of two main areas: ''General Administration'' covers all aspects of creating, controlling and configuring instances, whereas ''Instance Administration'' deals with the administration of internal parameters for each instance such as archive stores, search indexes, user synchronization, archiving profiles, etc.<br />
<br />
* [[Instance Management - General Administration| General Administration]]<br />
* [[Instance Management - Instance Administration | Instance Administration]]<br />
<br />
== Related Articles ==<br />
<br />
* [[End Customer Access]]<br />
* [[Startup Scripts]]<br />
* [[Backup and Restore]]<br />
* [[Application Integration|Directory Service: Application Integration]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Management API ==<br />
The Management API extends the management capabilities of the MailStore Service Provider Edition by providing a HTTP based access to all management functions. This allows to fully automate the administration of MailStore Service Provider Edition 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.<br />
<br />
* [[Management API - Using the API|Using the API]]<br />
* [[Management API - Function Reference|Function Reference]]<br />
* [[Management API - Command Line Client|Command Line Client]]<br />
: '''Example Implementation of API Libraries'''<br />
:* PowerShell<br />
:* Python<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Downloads ==<br />
<br />
:'''Active Directory Group Policy Templates'''<br />
<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_ADM.zip ADM-Template]<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_ADMX.zip ADMX-Template]<br />
<br />
:'''Example API Libraries and Clients'''<br />
* PowerShell Library<br />
* Python Library<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_Linux_Management_API_Client.zip Linux Management API Client]<br />
<br />
<br />
|}<br />
<br />
[en:Main Page]</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Main_Page&diff=885Main Page2014-02-13T15:53:42Z<p>Admin: </p>
<hr />
<div>__NOTOC__<br />
{{DISPLAYTITLE:MailStore Service Provider Edition Help}}<br />
<br />
Service providers receive an unlimited, scalable software solution with MailStore Service Provider Edition, which they will be able to independently operate either on their existing IT infrastructures or those they have leased. This help website has an exclusive focus on installing and setting up the backend of the MailStore Service Provider Edition. For administration of MailStore Instances, which is comparable to the on-premises solution MailStore Server, please visit the [http://en.help.mailstore.com/ MailStore Server Help]<br />
<br />
{| <br />
| style="vertical-align: top; width: 50%" |<br />
== General Information ==<br />
An introduction to the architecture, the most typical usage scenarios of the MailStore Service Provider Edition and further general yet important information are given by the following articles:<br />
<br />
* [[Overview]]<br />
* [[Performance and Scalability Guidelines]]<br />
* [[Frequently Asked Questions]]<br />
| style="vertical-align: top; width: 50%" |<br />
== Installation and Setup ==<br />
The ''Installation and Setup'' chapter provides an entire walkthrough of installation and setup process of MailStore Service Provider Edition. Each article ends with a "What to do next" section that guides to the next step.<br />
<br />
* [[System Requirements]]<br />
* [[Installing MailStore Service Provider Edition]]<br />
* [[Firewall Configuration]]<br />
* [[Single Server Mode Setup]] or [[Multi Server Mode Setup]]<br />
* [[Replace Self-signed SSL Certificates]]<br />
* [[Branding]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Management Console ==<br />
The MailStore Management Console is the primary, web based administration utility for MailStore Service Provider Edition administrators. The following articles provide a general overview of all available functions. Every function of the Management Console also has a corresponding [[Management API - Function Reference|Management API command]], which allows full, script-based control over MailStore Service Provider Edition.<br />
<br />
* [[Management_Console|Logging On & Navigation]]<br />
* [[Management_Console_-_General|General]]<br />
* [[Management_Console_-_Infrastructure|Infrastructure]]<br />
* [[Management_Console_-_Security|Security]]<br />
* [[Management_Console_-_Developer|Developer]]<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Instance Management ==<br />
Managing MailStore Instances consist of two main areas: ''General Administration'' covers all aspects of creating, controlling and configuring instances, whereas ''Instance Administration'' deals with the administration of internal parameters for each instance such as archive stores, search indexes, user synchronization, archiving profiles, etc.<br />
<br />
* [[Instance Management - General Administration| General Administration]]<br />
* [[Instance Management - Instance Administration | Instance Administration]]<br />
<br />
== Related Articles ==<br />
<br />
* [[End Customer Access]]<br />
* [[Startup Scripts]]<br />
* [[Backup and Restore]]<br />
* [[Application Integration|Directory Service: Application Integration]]<br />
|-<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Management API ==<br />
The Management API extends the management capabilities of the MailStore Service Provider Edition by providing a HTTP based access to all management functions. This allows to fully automate the administration of MailStore Service Provider Edition 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.<br />
<br />
* [[Management API - Using the API|Using the API]]<br />
* [[Management API - Function Reference|Function Reference]]<br />
* [[Management API - Command Line Client|Command Line Client]]<br />
: '''Example Implementation of API Libraries'''<br />
:* PowerShell<br />
:* Python<br />
| style="vertical-align: top; width: 50%" |<br />
<br />
== Downloads ==<br />
<br />
:'''Active Directory Group Policy Templates'''<br />
<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_ADM.zip ADM-Template]<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_ADMX.zip ADMX-Template]<br />
<br />
:'''Example API Libraries and Clients'''<br />
* PowerShell Library<br />
* Python Library<br />
* [http://ftp.mailstore.com/spe/MailStoreSPE_Linux_Management_API_Client.zip Linux Management API Client]<br />
<br />
<br />
|}<br />
<br />
[[en:Main Page]]</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=MediaWiki:Sidebar&diff=884MediaWiki:Sidebar2014-02-13T15:53:03Z<p>Admin: </p>
<hr />
<div>* navigation<br />
** mainpage|mainpage-description<br />
** http://en.help.mailstore.com|MailStore Server Help<br />
** https://cs.mailstore.com|Customer Service Center<br />
* TOOLBOX</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=MediaWiki:MetaNavigation&diff=883MediaWiki:MetaNavigation2014-02-13T15:52:12Z<p>Admin: Created page with "<li><a href="http://blog.mailstore.com/en/" target="_blank">MailStore Blog</a></li> <li><a href="http://www.facebook.com/mailstore.international" target="_blank">Facebook</a><..."</p>
<hr />
<div><li><a href="http://blog.mailstore.com/en/" target="_blank">MailStore Blog</a></li><br />
<li><a href="http://www.facebook.com/mailstore.international" target="_blank">Facebook</a></li></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=File:Ms_spe_access_client_02.png&diff=808File:Ms spe access client 02.png2014-01-22T17:43:33Z<p>Admin: </p>
<hr />
<div></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=End_User_Access&diff=807End User Access2014-01-22T17:43:14Z<p>Admin: /* MailStore Client */</p>
<hr />
<div>__NOTOC__<br />
<br />
The logon process for end customers to administrate their MailStore Server instance or to access their archives varies slightly from the logon process of an on-premises MailStore Server.<br />
<br />
Find detailed information about logging in with MailStore Client and MailStore Outlook Add-in below. Additionally find information about how to log on to MailStore Web Access using a web browser or the integrated IMAP server using any IMAP capable email client.<br />
<br />
= MailStore Client =<br />
<br />
End customer administrators can access their own MailStore Server Instance with MailStore Client by using the credentials received from their service provider. End user can use the same client to archive or export email or to access their archived email. Follow the instructions below for logging on with MailStore Client:<br />
<br />
* Open ''MailStore Client''.<br />
* Select the preferred language from the ''Language'' drop down list and enter the URL to connect to in the ''Server Name'' field. The URL must be in the format <tt><nowiki>https://<ip_or_hostname_of_cas>/<instance_id_or_alias></nowiki></tt>. <br />
*:[[File:Ms_spe_access_client_01.png|center]]<br />
*: '''Hint:''' The language and server name can be saved to skip this step in the future by activating the ''Always connect to this server'' option. To change the settings again, start MailStore Client while keeping the <tt>SHIFT</tt>-key pressed.<br />
* Click ''OK'' to connect.<br />
* MailStore Client will update itself to become compatible with the provider's version of MailStore Service Provider Edition if necessary.<br />
* Enter your username and password.<br />
*:[[File:Ms_spe_access_client_02.png|center]]<br />
* Click ''OK'' to log on.<br />
<br />
= MailStore Outlook Add-in =<br />
<br />
* Open Microsoft Outlook.<br />
* If the MailStore Outlook Add-in is not pre-configured, you will be asked to log in to your MailStore Server instance as soon as you click any button in the MailStore Outlook Add-in. <br />
* Enter the URL to connect to in the ''Server Name'' field. The URL must be in the format <tt><nowiki>https://<ip_or_hostname_of_cas>/<instance_id_or_alias></nowiki></tt>. <br />
* Enter your username and password.<br />
* Click ''OK'' to log on.<br />
<br />
= MailStore Web Access =<br />
<br />
End users can access their archived email easily via any [[System Requirements|supported web browser]], by following the instructions below.<br />
<br />
* Open a web browser<br />
* Navigate to MailStore Web Access. The URL is <tt><nowiki>https://<ip_or_hostname_of_cas>/<instance_id_or_alias></nowiki></tt>.<br />
* Enter your username and password.<br />
* Click ''Log on''.<br />
<br />
= IMAP Client =<br />
<br />
Archived emails can be accessed via an integrated IMAP server with any IMAP capable email client using the following settings:<br />
<br />
* '''Incoming Mail Server''' - Host name or IP address of a Client Access Server<br />
* '''Port''' - For unencrypted or TLS-encrypted connections standard IMAP port 143 is used. For SSL-encrypted connections standard IMAP port 993 is used.<br />
* '''User Name''' - Name of the MailStore user prepended by his instance id or alias, e.g. <tt>jdcorp/jon.doe</tt>.<br />
* '''Password''' - Password which is required for accessing the MailStore server.<br />
<br />
'''Please note:''' In addition to configuring the incoming mail server, email clients often require configuring the outgoing mail server as well. In this case, using the same data as for an existing email account will facilitate further processing emails from the email archive.</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=File:Ms_spe_access_client_01.png&diff=806File:Ms spe access client 01.png2014-01-22T17:41:13Z<p>Admin: </p>
<hr />
<div></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=File:Ms_spe_autocreate_stores_01.png&diff=804File:Ms spe autocreate stores 01.png2014-01-22T17:35:15Z<p>Admin: </p>
<hr />
<div></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=Instance_Management&diff=803Instance Management2014-01-22T17:35:00Z<p>Admin: /* Auto-Create Stores */</p>
<hr />
<div>For each instance further individual administrative functions exist. These functions are accessible through the instance details, which appear in pane below the instance list (''General'' > ''Instances'') of the Management Console when double-clicking on an entry in the list.<br />
<br />
All these functions are group by tabs, for which further details are provided below.<br />
<br />
= Overview =<br />
<br />
On the ''Overview'' tab of the instance details a summary of the configuration is shown along with a diagram that shows the distribution of used instance storage by indexes, content files and databases.<br />
<br />
[[File:Ms_spe_instance_overview.png|550px|center]]<br />
<br />
= Archive Stores =<br />
<br />
The ''Archive Stores'' tab allows the administration of the instance storage as well as the search indexes. New archive stores are automatically created in the base directory of the instance every 500.000 messages.<br />
<br />
== Creating Archive Stores ==<br />
<br />
Although MailStore Service Provider Edition creates new archive stores automatically, this can also be done manually as described in the following:<br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click on ''General'' > ''Instances''.<br />
* Open the instance details by double-clicking on an instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Click ''Create Store''.<br />
* Fill out the ''Create Archive Store'' form:<br />
*: [[File:Ms_spe_create_archivestore_01.png|center]]<br />
:* '''Name:''' Meaningful name for the archive store.<br />
:* '''Archive new messages here:''' If checked, new message will be archived in the newly created archive store (default: checked). <br />
:* '''Directory:''' Directory in which the new archive store will be created. A proposal is created from the ''Name'' of the archive store and the base directory of the instance. Use the swung dash to point to a directory relative to the base directory of the instance, e.g. <tt>~/Messages-2013-10</tt><br />
* Click ''OK'' to create the new archive store.<br />
<br />
== Attach Existing Archive Store ==<br />
<br />
Archive stores from MailStore Service Provider Edition instances or from on-premises MailStore Servers can be attached to an instance as described below: <br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by double-clicking on an instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Click ''Attach Store''.<br />
* Fill out the ''Attach Archive Store'' form:<br />
*: [[File:Ms_spe_attach_archivestore_01.png|center]]<br />
:* '''Name:''' Meaningful name for the archive store<br />
:* '''Archive new messages here:''' If checked, new message will be archived in the newly created archive store. (default: unchecked) <br />
:* '''Directory:''' Directory of the archive store to attach. This directory must contain the file "MailStoreFileGroup.fdb". Use the tilde to point to a directory relative to the base directory of the instance, e.g. <tt>~/Messages-2013-10</tt>.<br />
* Click ''OK'' to attach the archive store.<br />
<br />
== Maintain FS Databases ==<br />
<br />
For storing meta data of the archive store's content embedded Firebird databases exist in every archive store. Under certain circumstances (e.g. after a disaster recovery of the server or storage) it might become necessary to perform a maintenance task on those databases. This can easily be done for all archive stores of a particular instance be following the instructions below:<br />
<br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by double-clicking on an instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Click ''Maintain FS Databases'' to start the maintenance.<br />
* A progress windows will appear.<br />
* Wait until the process is completed successfully and click ''OK''. Otherwise click ''Cancel'' to interrupt maintenance process at any time.<br />
<br />
== Auto-Create Stores ==<br />
<br />
MailStore Service Provider Edition automatically creates new archive stores every 500.000 messages. This setting can be adjusted to your need: <br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by double-clicking on an instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Click ''Auto-create''.<br />
* Adjust the settings in the ''Auto-Create Archive Stores'' dialog.<br />
*: [[File: Ms_spe_autocreate_stores_01.png|center]]<br />
*: '''Important notice:''' Non-optimal settings can have a negative impact on the overall performance of the instance.<br />
* Click ''OK'' to save the settings.<br />
<br />
== Store Commands ==<br />
<br />
Advanced store commands are accessible by following these steps:<br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by double-clicking on an instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Select an archive store and click on ''Store Commands'' or right-click on an archive store to open a context menu.<br />
<br />
A summary of the available store commands can be found in the tables below:<br />
<br />
=== Requested State ===<br />
<br />
{| class="wikitable"<br />
! width="150px" | State<br />
! Description <br />
|-<br />
| Disabled<br />
| Disabled archive stores are not in use but the instance still knows about their existence. The content is not available to users or administrators while the archive store is disabled. This state is useful when moving archive stores to a new directory.<br />
|-<br />
| Write Protected<br />
| The content of write protected archive stores is available to users, but cannot be modified (e.g. delete or move messages, rename or move folders) <br />
|-<br />
| Normal<br />
| The content of archives store is available to users and can be modified if the user has the appropriate permission.<br />
|-<br />
| Current<br />
| Same as ''Normal'' but new messages will be archived in the archive store that is set to ''Current''. <br />
|}<br />
<br />
=== Commands ===<br />
<br />
{| class="wikitable"<br />
! width="150px" | Command<br />
! Description<br />
|-<br />
| Detach<br />
| Detaches the selected archive store. The archive store can be re-attached by using the ''Attach'' function. Please note that the archive store's name and ID will not be retained when detaching and re-attaching. Therefore, when moving an archive store to a new location, disabling the the archive store and using ''Set Path'' afterwards is preferred over re-attaching. <br />
|-<br />
| Rename<br />
| Specify a new name for the archive store.<br />
|-<br />
| Set Path<br />
| Change the path of the archive store. The archive store must be disabled before changing the path. Please note that the file system directory must be moved manually to the new location before re-enabling the archive store.<br />
|- <br />
| Compact<br />
| Optimizes the data structures.<br />
|- <br />
| Upgrade <br />
| If an archive store from a MailStore Server 5 or older was attached to an instance, it is highly recommended to upgrade the archive store to the latest format by using this function. Upgrade process can be interrupted and continued at any time.<br />
|- <br />
| Verify<br />
| Verification of the data integrity between folder information and meta data as well as email headers and content.<br />
|}<br />
<br />
== Search Indexes ==<br />
<br />
Additionally to container files storing the actual email content and the embedded Firebird databases used for storing meta information, a full-text index file is created for each archive that has emails stored in an archive store. By default the full-text index only included email bodies, but virtually any file type is supported (see ''Configure''). <br />
<br />
To access these functions, follow the instructions below:<br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by double-clicking on an instance in the list.<br />
* Click on the ''Archive Stores'' tab.<br />
* Click ''Search Indexes''.<br />
<br />
The below functions are available in the search index menu to configure and maintain the full-text indexes of an instance. <br />
<br />
=== Rebuild Broken Indexes ===<br />
<br />
Starts a rebuild of all search indexes across all archive stores that are marked a broken.<br />
<br />
=== Rebuild All Indexes ===<br />
<br />
Starts a rebuild of all search indexes in all archives stores.<br />
This is usually only required after making changes to the list of attachment extensions to be included in the full-text index.<br />
<br />
=== Configure ===<br />
<br />
Specify a list of file extensions for attachments to be included in the full-text index. MailStore Service Provider Edition can index all file types for which a so-called IFilter driver is installed on the instance host on which the MailStore Server instance is running.<br />
<br />
Under the name [http://www.microsoft.com/en-us/download/details.aspx?id=17062|Microsoft Office 2010 Filter Packs] Microsoft offers a package that, additionally to all legacy as well as recent Microsoft Office Formats, supports the Open Document Format (OpenOffice/LibreOffice).<br />
<br />
For reasons of stability and performance, MailStore Server processes the following file types directly, regardless of the IFilter drivers that are installed:<br />
<br />
* Text files (TXT)<br />
* HTML files (HTM and HTML)<br />
* PDF files (PDF)<br />
<br />
= Archive Access =<br />
<br />
The ''Archive Access'' tab provides access to the service provider archive access as well as download links for MailStore Client and MailStore Outlook Add-in.<br />
<br />
'''Please note:''' Details about the logon process for end customers can be found in the article [[End Customer Access]].<br />
<br />
== Enable or Disable Service Provider Archive Access ==<br />
Service provider archive access is only necessary if the administration of the instance is not done by the end customers or if the end customer requests support from the service provider. To enable or disable service provider archive access follow these instructions:<br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by double-clicking on an instance in the list.<br />
* Click on the ''Archive Access'' tab.<br />
* Click either ''Enable'' or ''Disable''<br />
* When enabling click ''OK'' to confirm that the service provider archive access really should be enabled.<br />
*: '''Please notice:''' Enabling the service provider archive access is logged in the audit log of the instance.<br />
<br />
== Using Service Provider Archive Access ==<br />
<br />
Before the service provider archive access can be used, this access method must be enabled (see previous section) and the MailStore Client must be installed on the computer from where you want to connect. <br />
<br />
* [[Management Console#Logging On|Log on]] to the Management Console.<br />
* Click ''General'' > ''Instances''.<br />
* Open the instance details by double-clicking on an instance in the list.<br />
* Click on the ''Archive Access'' tab.<br />
* Click ''Open MailStore Client'' <br />
* Depending on your web browser's settings further security related questions may appear. <br />
* Afterwards MailStore Client will automatically log on to the instance using the special ''$archiveadmin'' system account and a one-time password.<br />
<br />
== Inside the Instance ==<br />
No matter whether logging on to an instance as the end customer's administrator or as service provider via service provider archive access, the available functions of the MailStore Client are always the same. Only email content preview is always blocked for the ''$archiveadmin'' user. <br />
<br />
As each instance of the MailStore Service Provider Edition has the same capabilities in terms of managing users, archiving and exporting email, etc. the instructions from the [http://en.help.mailstore.com MailStore Server Help] also apply to instances.<br />
<br />
<p style="text-align: center; color: red; font-weight: bold; letter-spacing: 2px; font-size: 14px">Therefore no further documentation is provided here.</p><br />
<br />
<p class="msnote">As MailStore Service Provider Edition's development is currently ahead of MailStore Server's, please understand that certain features like scheduling of server side archiving profiles may work slightly different than described in the MailStore Server Help. This differences will remain until the next major release of MailStore Server. Please do not hesitate to contact our support if you have further questions regarding these differences.</p><br />
<br />
= Live Statistics =<br />
<br />
The ''Live Statistics'' tab shows real time graphics about the instance activity such as I/O, memory and CPU usage as well as number of Remote Procedure Calls (RPC) and the number of emails verified and archived by the instance's archiving mechanism.</div>Adminhttps://help.mailstore.com/en/spe/index.php?title=File:Ms_spe_attach_archivestore_01.png&diff=802File:Ms spe attach archivestore 01.png2014-01-22T17:34:01Z<p>Admin: </p>
<hr />
<div></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=File:Ms_spe_create_archivestore_01.png&diff=800File:Ms spe create archivestore 01.png2014-01-22T17:32:11Z<p>Admin: </p>
<hr />
<div></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=File:Ms_spe_instance_overview.png&diff=798File:Ms spe instance overview.png2014-01-22T17:30:24Z<p>Admin: </p>
<hr />
<div></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=File:Ms_spe_create_instance_02.png&diff=796File:Ms spe create instance 02.png2014-01-22T17:28:19Z<p>Admin: Admin uploaded a new version of &quot;File:Ms spe create instance 02.png&quot;</p>
<hr />
<div></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=File:Ms_spe_create_instance_03.png&diff=794File:Ms spe create instance 03.png2014-01-22T17:26:24Z<p>Admin: </p>
<hr />
<div></div>Adminhttps://help.mailstore.com/en/spe/index.php?title=File:Ms_spe_create_instance_01.png&diff=787File:Ms spe create instance 01.png2014-01-22T17:04:09Z<p>Admin: </p>
<hr />
<div></div>Admin