During mergers or divestitures, you might need the ability to move your users' Exchange Online mailboxes into a new tenant. Cross-tenant mailbox migration allows tenant administrators to use well-known interfaces like Exchange Online PowerShell and MRS to transition users to their new organization.

1. Users migrating must be present in the target tenant Exchange Online system as a MailUser

2. After the migration is complete, the source UserMailbox is converted to a MailUser, and the ExternalEmailAddress is stamped with the destination email address. This helps the converted MailUser in the source tenant for coexistence and mail routing. When business processes allow, the source tenant can remove the source MailUser or convert them to a mail contact.

3. When a mailbox is migrated, only user-visible content in the mailbox (email, contacts, calendar, tasks, and notes) is migrated to the target (destination tenant). Teams chat data is NOT migrated

4. Cross-Tenant migrations require a per user license (one-time fee) and can be assigned either on the source or target user object.

5. Cross Tenant User Data Migration license is available as an add-on to the following Microsoft 365 subscription plans: Microsoft 365 Business Basic, Standard, and Premium; Microsoft 365 F1/F3/E3/E5/; Office 365 F3/E1/E3/E5; Exchange Online; SharePoint Online; OneDrive for Business and EDU.

6. A mail-enabled security group in the source tenant is required. This group is used to scope the list of mailboxes that need to be migrated from source tenant to the target tenant preventing unintended users from being migrated.

• Navigate to the M365 Admin portal. Go to Marketplace, search for the add-on and purchase the number of licenses you need (equal to the number of users you want to migrate):

• Login to Microsoft Entra ID https://entra.microsoft.com/

• Select App registrations > New registration

• Give the application a name. Select "Accounts in any organizational directory (Any Microsoft Entra directory - Multi-tenant)". Then, under Redirect URI (optional), select Web, and then type https://office.com. Then, select Register

• Note the Application (client ID)

• Go to API permissions > Add Permission > select APIs my organization uses, search for Office 365 Exchange Online, and then select it.

• Select Application permissions. Under Select permissions, expand Mailbox and select Mailbox.Migration, and then select Add permissions at the bottom on the screen

• Select Grant admin consent for [your tenant]. In the Grant admin consent confirmation, select Yes.

• Create a Client Secret for you App and copy the value immediately as it would no longer be visible once you move away from this window:

• Formulate the URL in the below format to send to the source tenant administrator so that they can accept the application to enable mailbox migration.

https://login.microsoftonline.com/SOURCETENANTDOMAIN.ONMICROSOFT.com/adminconsent?client_id=[APPLICATION ID]&redirect_uri=https://office.com

• Client ID is the one we noted first. You can find it in the Application Overview page as "Application ID"

Example: https://login.microsoftonline.com/aaqwan.onmicrosoft.com/adminconsent?client_id=6d7424b6-3d4c-457b-xxxx-xxxxxxxxxb6e&redirect_uri=https://office.com

• Login to the source tenant and open the above formulated URL. It will ask you to accept the requested permissions. Click 'Accept':

• Now, we need to login to target tenant Exchange Online PowerShell. If you have not used or installed EXO PowerShell, please follow link:

• Copy the below script and populate the fields and paste it in EXO PowerShell. This will create the migration endpoint on the target tenant:

$AppId = "[Guid copied from the migrations app]"
$name = "[the name of your new migration endpoint]"
$remote = "<source>.onmicrosoft.com"
$secret = "[this is your secret password you saved in the previous steps]"
$dehydrated = Get-OrganizationConfig | select isdehydrated
if ($dehydrated.isdehydrated -eq $true) {Enable-OrganizationCustomization}
$Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $AppId, (ConvertTo-SecureString -String $secret -AsPlainText -Force)
New-MigrationEndpoint -RemoteServer outlook.office.com -RemoteTenant $remote -Credentials $Credential -ExchangeRemoteMove:$true -Name $name -ApplicationId $AppId

• Next, copy the below script in Notepad and populate the fields. Then paste and run in the same EXO PowerShell window (target). This will create the Organization Relationship on the target tenant. To find the Tenant ID, go to https://entra.microsoft.com/ > Overview.

$sourceTenantId = "[tenant ID of your trusted partner, where the source mailboxes are]"
$orgrelname = "[name of your new organization relationship]"
$orgrels = Get-OrganizationRelationship
$existingOrgRel = $orgrels | ?{$_.DomainNames -like $sourceTenantId}
If ($null -ne $existingOrgRel)
{
    Set-OrganizationRelationship $existingOrgRel.Name -Enabled:$true -MailboxMoveEnabled:$true -MailboxMoveCapability Inbound
}
If ($null -eq $existingOrgRel)
{
    New-OrganizationRelationship $orgrelname -Enabled:$true -MailboxMoveEnabled:$true -MailboxMoveCapability Inbound -DomainNames $sourceTenantId
}

• Connect to EXO PowerShell using the Source tenant credentials. Copy the below script and populate the fields and paste it in source EXO PowerShell. This will create a mail enabled security group and Organization Relationship in Exchange.

$targetTenantId = "[tenant ID of target tenant where the mailboxes are being moved to]"
$appId = "[application ID of the mailbox migration app you consented to]"
$scope = "[Provide a name for the mail enabled security group that will contain the list of users who are allowed to migrate]"
$orgrelname = "[name of your new organization relationship]"
$dehydrated = Get-OrganizationConfig | select isdehydrated
if ($dehydrated.isdehydrated -eq $true) {Enable-OrganizationCustomization}
if (!(New-DistributionGroup -Type Security -Name $scope)) { Write-Host "Group already exists." }
$orgrels=Get-OrganizationRelationship
$existingOrgRel = $orgrels | ?{$_.DomainNames -like $targetTenantId}
If ($null -ne $existingOrgRel)
{
    Set-OrganizationRelationship $existingOrgRel.Name -Enabled:$true -MailboxMoveEnabled:$true -MailboxMoveCapability RemoteOutbound -OAuthApplicationId $appId -MailboxMovePublishedScopes $scope
}
If ($null -eq $existingOrgRel)
{
    New-OrganizationRelationship $orgrelname -Enabled:$true -MailboxMoveEnabled:$true -MailboxMoveCapability RemoteOutbound -DomainNames $targetTenantId -OAuthApplicationId $appId -MailboxMovePublishedScopes $scope
}

You can ignore the error I received:

• Go to Exchange Admin Portal and add the mailboxes to be migrated as members to the group created in the above steps.