How do I set up mail routing on Microsoft 365 when migrating users in batches?

When you are migrating to Microsoft 365, mailboxes need to be provisioned within the M365 tenant to be able to migrate content to them. The user must be exist within the destination tenant, as a fully licensed user, this includes a SKU and mailbox,

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

This can be further explained by way of an example:

James and Alex are being migrated to Microsoft 365. They are in different user batches. Batch 1 will be migrated first. Batch 2 will be migrated second.

James is in the first batch, gets migrated, and is using his Microsoft 365 mailbox.

Alex is in the second batch. This batch of users will be migrated later.

When migrating users within Batch 2,  users will need to be activated on Microsoft 365 prior to migration since, as explained above, the mailbox needs to be active in order to be able to migrate data into it.

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

If James sends an email to Alex, Microsoft 365 will internally route it to the new mailbox instead of the on-premises mailbox that Alex still uses. The email will not get lost, since the email is stored in a mailbox that eventually Alex will get, but Alex 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 Microsoft 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:

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

More information can be found here:

Step By Step

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

  1. Connect to Exchange Online PowerShell.
  2. Create the Distribution List (DL):
    New-DistributionGroup -Name "NotMigratedUsers"
  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 Google Workspace, you would need to change the -SmartHosts entry to be the following: -SmartHosts “”
  • Create Rule:
    $result = New-TransportRule -Name "PilotInABoxRule" -SentAlexemberOf "NotMigratedUsers" -RouteMessageOutboundConnector "CBRConnector"

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



  • There must be a mail-enabled contact on-premises for each user that has been migrated.
  • The domain cannot be an authoritative accepted domain in Microsoft 365.
Was this article helpful?
0 out of 1 found this helpful