Introduction to Cross-Tenant Mailbox Migrations (2024)

Cross-tenant mailbox migrations are typically used in mergers and acquisitions ('Company A' buys or merges with 'Company B'), divestitures (part of 'Company A' becomes 'Company B'), and rebranding ('Company A' becomes 'Company B'). Our built-in capabilities for these scenarios allows tenant admins to use well-known interfaces like Exchange Online PowerShell and the Mailbox Replication service (MRS) to natively migrate user mailboxes from one tenant to another.

This is Part 1 of a 2-part blog series. Part 1 covers the limits of and prerequisites for cross-tenant mailbox moves, as well as what happens when a cross-tenant move is initiated. Part 2 provides guidance on how to troubleshoot cross-tenant mailbox moves.

Migration Capabilities

Be aware of the following when using cross-tenant mailbox migration:

• When a mailbox is migrated to another tenant, only user-visible content in the mailbox (also known as ‘Top of Information Store’ - email, contacts, calendar, tasks, and notes) and the Recoverable Items folders (Deletions, Versions, and Purges) are migrated. Non-user-visible content (including Teams chats stored in the Exchange Online mailbox by the Teams service) is not migrated. More on this below.
• After migration has successfully completed, the source mailbox is converted to a Mail User object with a ComponentShared mailbox, and all visible data in the mailbox is deleted. Under no circ*mstances is the source mailbox data available, discoverable, or accessible in any way in the source tenant (except for non-Exchange data that is stored in a user’s mailbox, like Teams chat data and Copilot interactions which remain in the ComponentShared mailbox). Non-Exchange data refers to data stored in the mailbox by Microsoft 365 workloads other than Exchange Online.
• Mailboxes on any type of hold cannot be migrated.
• If the source tenant is in a hybrid configuration, the Source of Authority (SOA) for users will typically be on-premises Active Directory (AD). The cross-tenant mailbox migration process doesn’t touch on-premises environments at all, so you must manually update the ‘targetAddress’ (RemoteRoutingAddress / ExternalEmailAddress) for each source on-premises user after the source tenant mailbox is moved to the target tenant.
• While Teams meetings are moved, the meeting URL isn't updated for items migrated cross-tenant. Since the URL will be invalid in the target tenant, migrated users must remove and recreate Teams meetings.
• Since Teams chat folder content remains with the source tenant within the ComponentShared mailbox location type (and possibly in a SubstrateExtension mailbox, which might be present because of autosplitting a large ComponentShared mailbox), once the user data has been migrated, the Teams chat folder content is available for source tenant admins to search and export using Content Search.
• Send On Behalf Of permissions are not migrated, so you'll need to grant this permission on the target mailbox after the Mail-Enabled User (MEU) to Mailbox conversion completes in the target environment by runningSet-Mailbox <principal> -GrantSendOnBehalfTo <delegate>.
• Mailbox delegation permissions that are stored in the source mailbox will move and be functional in the target tenant after both the principal and the delegate have been moved to the target tenant.
• Source and target tenant domain names must be unique (e.g., “contoso.com” can't be added to the target tenant while still in use by the source tenant). Beware of NotAcceptedDomain errors that can happen if the other tenant domain email addresses are wrongly stamped on the users during migration or when you are performing a cross-tenant domain migration while moving mailboxes.
• Labels cannot be synced or shared between tenants. If the source tenant has labels configured, after the mailbox is migrated to the target tenant, you'll have to recreate the labels in the target tenant.
• Microsoft 365 Group and public folder mailboxes cannot be migrated.
• After a mailbox has been migrated cross-tenant, eDiscovery against the migrated user's mailbox in the source can no longer be performed. If a copy of the source mailbox needs to persist in the source tenant after migration, an admin in the source tenant can copy the mailbox contents to a second mailbox before migrating, which would allow future eDiscovery against the data.
• We support moving users with a maximum of 12 auxiliary archive mailboxes. If a user has more than 12 auxiliary archive mailboxes, the move will fail.

Prerequisites

A general rule when troubleshooting cross-tenant migrations, is to first ensure that all prerequisites are met:

• The source tenant object should be an active mailbox of type either regular, shared, resource, or room.
• The target tenant object should be a MailUser.
• The source user mailbox should not be on hold.
• A cross-tenant user data migration add-on license must be assigned either on the source or target object. You need one license for each user mailbox being migrated, along with any of the following pre-requisite licenses:
• Microsoft 365 Business Basic/Business Standard/Business Premium/F1/F3/E3/E5
• Office 365 F3/E1/E3/E5
• Exchange Online
• SharePoint Online
• OneDrive for Business

Here is how this license looks like in the GUI:

In PowerShell, you can see it as EXCHANGET2TMBXMOVE in PersistedCapabilities or Capabilties:

• If you decide to move a user back to the source tenant, the move will reuse the same license you used previously to move to the target tenant.
• Shared mailboxes and resource / room mailboxes don’t need to be licensed with either an Exchange Online license or a Cross-tenant user data migration license.

• At least onemail-enabled security groupis required in the source tenant, which is used to scope the list of mailboxes to be moved from the source tenant to the target tenant. This allows the source tenant admin to control which mailboxes are moved, preventing accidental or unintended migrations. Note that using nested groups (e.g., Group B is a member of Group A, and Group A is the group in scope) is strongly discouraged.

Be sure to follow and complete theConfiguration steps for cross-tenant mailbox migrations, and verify that the source tenant hasaccepted the migration application.

What happens during the move?

Cross-tenant mailbox migration uses the same MRS technology used by other Exchange mailbox moves (such as hybrid mailbox moves). From the target tenant perspective it is an onboarding process, and from the source tenant perspective it is offboarding.

The following image depicts the process:

Let’s explain the above:

1. When the migration batch gets created in the target tenant, we verify that there’s an Organization Relationship containing the source tenant Id for the value of the DomainNames property.
2. Then source tenant is reached via the migration endpoint that contains the ApplicationID registered in Entra ID and the app’s secret value.
3. Once the MRSProxy endpoint for the source mailbox (in the source tenant) is reached, we check if there’s an Organization Relationship present with the target tenant ID on the DomainNames property, and that MailboxMoveEnabled is set to “true”. The MailboxMoveCapability property is set to “RemoteOutbound” and the MailboxMovePublishedScopes security group identity (the security group in the source tenant with the mailboxes to be migrated that is checked during this step).
4. Next, MRS does a partial validation; it checks if the migrating user is present in the target tenant as a Mail Enabled User (MEU). The remaining validation is performed by MRS in step 7.
5. If partial validation is successful, MRS in the target tenant creates the Migration User Object (retrieved with Get-MigrationUser in the target tenant).
6. Next, the Migration service invokes New-MoveRequest, calling MRS.
7. MRS does a full validation by checking other attributes such as ExchangeGuid matching and that the source LegacyExchangeDN is present as an X500 address in the target. If this passes, the injection of the move request is successful, and you will see a Get-MoveRequest besides the previous Get-MigrationUser. This is where we also check if the mailbox being moved is under any type of hold, the number of auxiliary archives it has, and the Organization Relationship exists in the target tenant.
8. After the move has successfully completed, the mailbox in source tenant is converted to an MEU and the targetAddress on the source tenant’s Mail User Object is stamped with the remote routing address of the target tenant (the TargetDeliveryDomain you set at the beginning of the migration batch). This process leaves the source mailbox as an MEU to ensure coexistence and mail routing until the source tenant admin decides to remove it. Note that if the source mailbox is in an Exchange hybrid environment and you have an on-premises Mail User / Remote Mailbox for the corresponding source mailbox, the ExternalEmailAddress or RemoteRoutingAddress will still point to <SourceTenant>.mail.onmicrosoft.com. This is not changed by MRS because it can only make changes in the Exchange Online environments; it cannot modify any on-premises AD / Exchange objects. You must update on-premises objects after performing a cross-tenant mailbox migration (for example, by running Set-RemoteMailbox <Identity> -RemoteRoutingAddress<TargetTenant>.mail.onmicrosoft.com.
9. In the target tenant, after the mailbox migration is finished, the Mail User Object you created before migration as part of the prerequisite user matching between the two tenants will be mailbox enabled, as the user’s mailbox now resides in the target tenant.

We hope that this provides a good overview of the cross-tenant mailbox migration process and it’s moving parts. In Part 2 of this series, we cover troubleshooting.

Mirela Buruiana and Alberto Pascual Montoya