Multi Tenant Exchange User Synchronisation

Instructions for Mailsphere on how to run the script.


  • PowerShell 3.0 (the Multi Tenant user sync cannot be run on earlier versions)
  • .Net Framework 4.0 (required to install Powershell 3.0)
  • Access to exchange server (script must be run locally on exchange)

Download the latest Multi Tenant UserSync script

Mailsphere Administration

For each tenant ensure that the organisation has been configured, with the relevant domains and the API user password has been set.

Note:  It is possible to run the multi tenant script with a common API user password for each tenant or a unique password or any mix that is desired.  See the following section for more details.

Contents of the Multi Tenant User Sync

When you open the zip file you will notice it contains two PowerShell script files and one batch file.  

Copy all three on to your Exchange server into a dedicated folder.  When the script is executed it will generate a sub folder for each tenant where the results can be located after each run.  This will help with troubleshooting should it be required.

Contents of the batch file

The batch file runs the sync for each tenant.  This can receive the common password variable at runtime.  We recommend this so that no text files containing passwords are stored on the server.

To add a new tenant the following command must be added:

PowerShell.exe -ExecutionPolicy Bypass -Command "& '%PowershellPath%'" 'AD_ORGANISATIONAL_UNIT' 'MS_API_USER_ID' %arg1%;

You can see the two parameters in CAPITALS identify where the name of the organisational unit in the AD/Exchange is added and where the Mailsphere API User ID is added.

To run the Multi Tenant User Sync a single time:

  1. Open the command prompt
  2. Navigate to the folder housing the 3 files
  3. Type multitenantsync.bat COMMONPASSWORD (replacing common password with your chosen API User Password.
  4. Enter

The script will run and report the results to the console for each tenant.

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 the folder name and the batchfile name i.e.:
  • In the Add arguments (optional) box enter the common password you wish to use.
  • Then, in the Start in (optional) box, add the location of the folder that contains the batch file and PowerShell scripts.  This will be the same as the 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.