Set up mail routing on Office 365 when migrating users in batches

When migrating to Office 365 using MigrationWiz, mailboxes need to be provisioned on Office 365 in order to be able to write the content, mail, contacts, calendar, etc. (the user must exist on Office 365 with an O365 license assigned to it, including a mailbox).

When a migration is performed in stages or batches, care must be taken to ensure that full mail flow continues for those migrated users.

This can be further explained by way of an example:

  • John and Tom need to be migrated to Office 365. They are in different user batches. Batch 1 will be migrated first. Batch 2 will be migrated second.
  • John is in the first batch, gets migrated, and is using his Office 365 mailbox.
  • Tom is in the second batch. This batch of users will be migrated at a later date.
  • When it comes to migrating users in Batch 2, these users will need to be activated on Office 365 prior to migration since, as explained above, the mailbox needs to be active in order for MigrationWiz to migrate data into it.

What will happen if mail is sent to this newly activated Office 365 mailbox while the migration is occurring?

If John sends an email to Tom, Office 365 will internally route it to the new mailbox instead of the on-premises mailbox that Tom still uses. The email will not get lost since the email is stored in a mailbox that eventually Tom will get, but Tom will not have access to the email until the migration is completed.

How do we fix this?
The default mail routing can be manipulated by a mechanism called Criteria-Based Routing (CBR). Instead of dropping the mail in the mailbox on Office 365, we can intercept the message and transfer it to the on-premises mail system, to be handled there. The interception is based on criteria similar to the membership of a specific Distribution List.

This is best explained by using the same example scenario:

  • John was migrated to Office 365 in the first batch.
  • Tom is part of a Distribution List (DL) called NotMigrated.
  • We have set up a CBR mechanism that defines the following:
    • If you are a part of the DL NotMigrated, your mail will be intercepted and will be sent to the on-premises environment.
  • This way, when John sends an email to Tom, it will not go into the Office 365 mailbox, but instead, be transferred to the On-Premises Exchange 2010+ environment.

More information can be found here: Scenario: Conditional mail routing

Step-by-step setup:
For the setup, use PowerShell, because it is faster and easier to set up than working through the Office 365 admin portal. If you need information about how to do this through the Office 365 admin portal, contact Microsoft Support.

  1. Connect to Exchange Online PowerShell.
  2. Create the Distribution List (DL):
    New-DistributionGroup -Name "BtNotMigratedUsers"
  3. Add All Users to this DL.
  4. Create the Connector:
    $result = New-OutboundConnector -Name "CBRConnector" -ConnectorType OnPremises -SmartHosts "<fill smart host to source environment>" -UseMXRecord $false -IsTransportRuleScoped $true
    • -SmartHosts entry needs to be set to the URL or IP Address of the Source environment server.
    • On Exchange 2003, 2007, and 2010, this will be the address of the Transport server.
    • On Exchange 2013 and 2016, this will be the address of the Mailbox server, not the Transport server.
    • If the Source environment is Hosted, you would need to obtain this address from the Hosted Provider.
    • If the Source environment is G Suite, you would need to change the -SmartHosts entry to be the following: -SmartHosts “”
    • Notes:
  5. Create Rule:
    $result = New-TransportRule -Name "PilotInABoxRule" -SentToMemberOf "BtNotMigratedUsers" -RouteMessageOutboundConnector "CBRConnector"

When a user is fully migrated, remove the user from the DL, and they will receive their email in their own Office 365 mailbox.


  • There must be a mail-enabled contact on-premises for each user that has been migrated.


Was this article helpful?
1 out of 3 found this helpful