Getting started with MailStore SPE's Management API

2023-01-01T00:00:00+00:00

🔗</a>Enable the API</h2>
The API might already be enabled, but let's check that it is enabled before proceeding:

Launch the MailStore Service Provider Edition Configuration tool. </li>

Stop the Management Server. </li>

Click Configure.... </li>

Ensure API HTTP Server Enabled is checked. </li>

Set Listeners to `:8474</code> (without the quotes). </li>`*
`Copy the Certificate field from Management Server Settings and paste it in to the Server Certificate field in the API section. </li>`
`Click OK. </li>`
`Start the Management Service </li> </ol>`🔗</a>Using the PowerShell wrapper</h2>
🔗</a>Wrapper and sample code</h2>
Referring to the PowerShell API Wrapper and sample code found in: https://help.mailstore.com/en/spe/PowerShell_API_Wrapper_Tutorial</a>
🔗</a>Set-ExecutionPolicy to run downloaded scripts</h3>

Launch PowerShell as administrator </li>

Run `Set-ExecutionPolicy -ExecutionPolicy Unrestricted</code> </li> </ol>`
🔗</a>Make our first API call</h3> Download MailStore PowerShell API Wrapper and tutorial example scripts from https://help.mailstore.com/en/spe/images/1/19/MailStore_SPE_Scripting_Tutorial.zip</a> </li> Unzip MailStore_SPE_Scripting_Tutorial.zip</code> </li> Open the MailStore SPE Scripting Tutorial\PowerShell\Scripts</code> directory. </li> Edit Example1.ps1. </li> Set the username/password. </li> Adjust the managementserver and port (if needed). If you're working on the management server itself then the defaults should be fine. </li> Run .\Example1.ps1</code> </li> </ol> The result I get is: error : token : statusVersion : 2 statusCode : succeeded percentProgress : statusText : result : @{version=22.4.0.21151; webClientVersion=22.4.0.21151; copyright=Copyright (c) 2005-2022 MailStore Software GmbH; licenseeName=ehemaliger Testaccount; licenseeID=10510; serverName=spe-server.example.com; username=admin; systemProperties=} logOutput : </code></pre> Example2.ps shows how to pass parameters using "GetInstances" @{instanceFilter = ""}</code>, and then it pulls the users from within each instance as an example of how to repeat an operation through different instances. It should just be a matter of updating the connection string in this script with your servername and credentials. 🔗</a>Call the HTTPS API directly</h2> 🔗</a>Install a browser extension</h3> I'm using RESTClient (Firefox-based extension to make API calls interactively from a browser): https://addons.mozilla.org/en-US/firefox/addon/restclient/</a> but other tools should be fine. For reference my server's API is available at: https://spe-server.example.com:8474</a> 🔗</a>Trust the certificate</h3> First access the URI and allow the untrusted certificate (if needed) </li> Do this by visiting https://spe-server.example.com:8474/</a> </li> Advanced -> Accept the certificate </li> Close the tab when prompted for credentials. </li> </ol> 🔗</a>Make a first call to the API</h3> Now launch RESTClient </li> Click the Authentication tab </li> Set the admin username/password. </li> Change the Method to Post </li> Call https://spe-server.example.com:8474/api/invoke/GetInstanceHosts</code> (without the quotes) </li> </ol> My response looks like this: { "error": null, "token": null, "statusVersion": 2, "statusCode": "succeeded", "percentProgress": null, "statusText": null, "result": [ { "serverName": "spe-server.example.com", "port": 8472, "serverCertificate": { "thumbprint": "A61597D8316DC39E26466F22C4C42B0C824ABE12" }, "baseDirectory": null } ], "logOutput": null } </code></pre> I used this API method because we can now add a body to test. 🔗</a>Add parameters to apply a filter</h3> I'll add the body serverNameFilter=doesnotexist</code> (again, without the quotes) and we see no errors, but also no servers were returned, so we know the server accepted the parameter as the behaviour changed from above: { "error": null, "token": null, "statusVersion": 2, "statusCode": "succeeded", "percentProgress": null, "statusText": null, "result": [], "logOutput": null } </code></pre> And now I'll change the body to: serverNameFilter=spe-server.example.com</code> Now we get the requested server again, confirming everything is working: { "error": null, "token": null, "statusVersion": 2, "statusCode": "succeeded", "percentProgress": null, "statusText": null, "result": [ { "serverName": "spe-server.example.com", "port": 8472, "serverCertificate": { "thumbprint": "A61597D8316DC39E26466F22C4C42B0C824ABE12" }, "baseDirectory": null } ], "logOutput": null } </code></pre> 🔗</a>Make a more complex API call</h3> Use CreateSystemAdministrator https://help.mailstore.com/en/spe/Management_API_-_Function_Reference#CreateSystemAdministrator</a> to create a new system administrator. I selected this example because we need both a json parameter, and a second parameter that is not part of the json block. Change the URI to: https://spe-server.example.com:8474/api/invoke/CreateSystemAdministrator</code> </li> Change the body: config={ "userName" : "bob", "fullName" : "Bob the Admin", "emailAddress" : "bob@example.com"}&password=Passw0rd!</code> </li> Submit to the server. </li> </ol> The result is "statusCode": "succeeded" { "error": null, "token": null, "statusVersion": 2, "statusCode": "succeeded", "percentProgress": null, "statusText": null, "result": null, "logOutput": null } </code></pre> And to confirm it really did work, I verified I can login with my newly created administrator "bob" using the management web interface port 8470) 🔗</a>curl</h2> We could do the same from curl using this command line: curl -X POST -k -H 'Authorization: Basic YWRtaW46UGFzc3cwcmQhIQ==' -i 'https://spe-server.example.com:8474/api/invoke/CreateSystemAdministrator' --data 'config={ "userName" : "joe", "fullName" : "Joe the Admin", "emailAddress" : "joe@example.com"}&password=Passw0rd!'</code>

Use SetUserPrivilegesOnFolder from PowerShell

2023-01-01T00:00:00+00:00

First please refer to the MailStore PowerShell API Wrapper</a> article for instructions on the system requirements and basics of the PowerShell wrapper.

Once you have PowerShell installed and the API Wrapper downloaded, enter the commands from the documentation to load the module and establish a connection:

Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'</code>

$msapiclient = New-MSApiClient -Username admin -Password MyAdminPa$$W0rd -MailStoreServer localhost -Port 8463 -IgnoreInvalidSSLCerts</code>

And now we can verify the connection with GetServerInfo:

Invoke-MSApiCall $msapiclient "GetServerInfo" | fl</code>

This will only work if you are on the MailStore Server, if you are on your own workstation then update the "localhost" to point to the correct hostname or IP. Similarly, update the port "8463" if needed.

I can confirm the connection from there (including just the relevant line):

PS C:\> Invoke-MSApiCall $msapiclient "GetServerInfo" | fl</code>

error           :
token           :
statusVersion   : 2
statusCode      : succeeded
percentProgress :
statusText      :
result          : @{version=22.3.0.21002; machineName=EXCHANGEDC}
logOutput       :
</code></pre>
I then used this command to pull GetUserInfo</em>:</p>
(Invoke-MSApiCall $msapiclient "GetUserInfo" @{"userName" = "frank.clark"}).result | fl</code></p>
username            : frank.clark
fullName            : Frank Clark
distinguishedName   : CN=Frank Clark,OU=Seattle,DC=example, DC=com
authentication      : directoryServices
emailAddresses      : {frank.clark@example.com}
pop3UserNames       : {}
privileges          : {login}
privilegesOnFolders : {@{folder=frank.clark; privileges=System.Object[]}, @{folder=abby.hernandez; privileges=System.Object[]}}
</code></pre>
And next I added a permission:</p>
Invoke-MSApiCall $msapiclient "SetUserPrivilegesOnFolder" @{"userName" = "frank.clark"; "folder" = "alexis.page"; "privileges" = "read"}| fl</code></p>
error           :
token           :
statusVersion   : 2
statusCode      : succeeded
percentProgress :
statusText      :
result          :
logOutput       :
</code></pre>
And then check the permissions again to confirm the additional permission was added:</p>
(Invoke-MSApiCall $msapiclient "GetUserInfo" @{"userName" = "frank.clark"}).result | fl</code></p>
username            : frank.clark
fullName            : Frank Clark
distinguishedName   : CN=Frank Clark,OU=Seattle,DC=example, DC=com
authentication      : directoryServices
emailAddresses      : {frank.clark@example.com}
pop3UserNames       : {}
privileges          : {login}
privilegesOnFolders : {@{folder=frank.clark; privileges=System.Object[]}, @{folder=abby.hernandez; privileges=System.Object[]}, @{folder=alexis.page; privileges=System.Object[]}}
</code></pre>

🔗</a>Wrapper and sample code</h2>
Referring to the PowerShell API Wrapper and sample code found in: https://help.mailstore.com/en/spe/PowerShell_API_Wrapper_Tutorial</a></p>

mailstore-notes.dwlab.me - PowerShell

Getting started with MailStore SPE's Management API

Use SetUserPrivilegesOnFolder from PowerShell

mailstore-notes.dwlab.me - PowerShell

Getting started with MailStore SPE's Management API

🔗</a>Wrapper and sample code</h2> Referring to the PowerShell API Wrapper and sample code found in: https://help.mailstore.com/en/spe/PowerShell_API_Wrapper_Tutorial</a></p>

🔗</a>Set-ExecutionPolicy to run downloaded scripts</h3> Launch PowerShell as administrator</p> </li>

🔗</a>Trust the certificate</h3> First access the URI and allow the untrusted certificate (if needed)</p> </li>

🔗</a>Make a first call to the API</h3> Now launch RESTClient</p> </li> Click the Authentication tab</p> </li> Set the admin username/password.</p> </li> Change the Method</strong> to Post</em></p> </li>

Use SetUserPrivilegesOnFolder from PowerShell

🔗</a>Wrapper and sample code</h2>
Referring to the PowerShell API Wrapper and sample code found in: https://help.mailstore.com/en/spe/PowerShell_API_Wrapper_Tutorial</a></p>