Exchange User Synchronisation

Instructions for Mailsphere on how to run the script.


  • PowerShell 3.0
  • .Net Framework 4.0 (required to install Powershell 3.0)
  • Access to exchange server (script must be run locally on exchange)
  • Login to the portal and get the User ID of the API User and define a password if you have not already done so.  The API User is automatically created when the Organisation is created.  Make sure you copy the User ID and not the Full Name as only the User ID will work.

Download the latest UserSync script

Steps to run user sync script

When you open the script copy this on to your Exchange server and open the Exchange Power Shell.

In the Exchange Power shell go to the folder where you stored the script and run the script by simply typing the following where [ENTER] is pressing the enter key to complete the command:



{answer either y or n for whether this is a test run}


{username of the API User for that Organisation}


{password for the API User for that Organisation}


This will synchronise the users with Mailsphere.  If you experience any errors then please report back to Mailsphere.


Powershell 2.0 Workaround


If the HTTP post fails (e.g. because an older powershell), there is a workaround:

The script will have created a file “getAllMailboxes.xml” in the local directory.

Use the following command in Terminal to uploade the XML output to Mailsphere.

If you are using this workaround, API's password should contain letters only.

curl -X POST -d @getAllMailboxes.xml\&password=PASSWORD --header "Content-Type:text/xml"

Running as a scheduled task

To keep Mailsphere up to date without having to run the user synchronisation script manually each time you update the mailboxes or distribution groups you can configure the script to run as a scheduled task using Windows Task Scheduler.

  • On the system that the task will be run from, open the Windows Task Scheduler. This can be found in the Start menu, under Start > Administrative Tools.
  • In the Task Scheduler, select the Create Task option under the Actions heading on the right-hand side.
  • Enter a name for the task, and give it a description (the description is optional and not required).
  • In the General tab, go to the Security options heading and specify the user account that the task should be run under. Change the settings so the task will run if the user is logged in or not.
  • Next, select the Triggers tab, and click New to add a new trigger for the scheduled task. This new task should use the On a schedule option. The start date can be set to a desired time, and the frequency and duration of the task can be set based on your specific needs. Click OK when your desired settings are entered. We recommend selecting a daily task outside of your business hours.
  • Next, go to the Actions tab and click New to set the action for this task to run. Set the Action to Start a program.
  • In the Program/script box enter
    In the Add arguments (optional) box enter the following value replacing the values in the curly brackets
-file "{script folder location}\GetAllMailboxes.ps1" n {api username} {api user password} 
    Then, in the Start in (optional) box, add the location of the folder that contains your PowerShell script.  This will be the same as the {script folder location} in the arguments field. Once you have added this click OK.
  • Next, set any other desired settings in the Conditions and Settings tabs. You can also set up additional actions, such as emailing an Administrator each time the script is run.
  • Once all the desired actions have been made (or added), click OK. The task will be immediately set, and is ready to run.