Microsoft 365 Tenant-to-Tenant Migration Architecture: Cross-Tenant Mailbox, OneDrive, Teams and Domain Move

Overview

Mergers, acquisitions and divestitures regularly require moving users from one Microsoft 365 tenant to another. A tenant-to-tenant migration touches several workloads, each with its own tool, licensing and limits:

Microsoft's planning guidance frames the choice as either Migration Orchestrator (multi-workload batches) or the individual cross-tenant tools when you need control over each workload's timeline. This guide covers the individual tools in detail, because the orchestrator builds on the same prerequisites.

The examples use contoso.com / contoso.onmicrosoft.com for the source tenant and fabrikam.com / fabrikam.onmicrosoft.com for the target tenant.

Phase 1: Planning and Identity Mapping

Start by agreeing the end state with both organizations:

• Who moves: build a mapping file of source UPN, target UPN, source primary SMTP, target primary SMTP, mailbox size, archive status, OneDrive size and hold status. Mailboxes and OneDrives on any kind of hold are blocked from migration, so legal and compliance teams need to decide early how holds are handled.
• Naming: decide whether users take the target organization's domain (user@fabrikam.com) or whether the source domain (contoso.com) moves to the target tenant. The second option is common in divestitures and drives the cutover design in Phase 6.
• Tenant IDs: each side needs the other's tenant ID (a GUID, not a domain name) for the organization relationship.
• Batching: Microsoft recommends no more than 2,000 mailboxes per batch and submitting batches about two weeks before the cut-over date, since synchronization has no user impact. Move delegates and the mailboxes they access in the same batch, because cross-tenant mailbox and calendar permissions are not supported.
• Coexistence: plan mail routing (source mail users forward to the target), free/busy sharing between tenants, and Teams federation for the period when users are split across tenants.

Users in the target tenant can be created by script, by Microsoft Entra Connect if an on-premises Active Directory feeds the target, or with Microsoft Entra cross-tenant synchronization. Whatever creates them, the Exchange attributes described in Phase 3 still have to be stamped before mailboxes move. Microsoft also documents a Cross-Tenant Identity Mapping feature (in preview at the time of writing) that automates part of this.

Phase 2: Licensing

• Cross-Tenant User Data Migration is a per-user, one-time add-on required for cross-tenant mailbox and OneDrive migration (and for the orchestrator's Teams workloads). It can be assigned on either the source or the target user. Microsoft does not offer exceptions: moves fail without it, with an error such as CrossTenantMigrationWithoutLicensePermanentException.
• Exchange Online licenses are required for users in both tenants.
• Cross-Tenant Shared Data Migration is a separate license for SharePoint site moves, sold per 100 GB of data moved, and at the time of writing available only to Enterprise Agreement customers through the Microsoft account team.
• For Teams chat and meeting migration through the orchestrator, users need Teams licenses in both tenants.

Phase 3: Native Cross-Tenant Mailbox Migration

Configure the target tenant first. Different administrators can perform each tenant's steps; nobody needs credentials for both tenants.

3.1 Target tenant: app registration and consent

In the target tenant's Microsoft Entra admin center:

1. Create an app registration with Accounts in any organizational directory (multitenant) and the web redirect URI https://office.com.
2. Under API permissions, add Office 365 Exchange Online > Application permissions > Mailbox.Migration. The default User.Read permission is not needed.
3. Create a client secret and store it securely; it is shown only once.
4. Grant admin consent in the target tenant.
5. Send the source administrator a consent URL in this format:

https://login.microsoftonline.com/contoso.onmicrosoft.com/adminconsent?client_id=<application-id>&redirect_uri=https://office.com

3.2 Target tenant: migration endpoint and organization relationship

After the source administrator has consented, create the endpoint and an organization relationship that allows inbound moves:

# Target tenant - Exchange Online PowerShell
$AppId  = "<application-id>"
$secret = "<client-secret>"
$Credential = New-Object System.Management.Automation.PSCredential -ArgumentList $AppId, (ConvertTo-SecureString -String $secret -AsPlainText -Force)
 
New-MigrationEndpoint -Name "T2T-Contoso" -RemoteServer outlook.office.com `
    -RemoteTenant "contoso.onmicrosoft.com" -Credentials $Credential `
    -ExchangeRemoteMove:$true -ApplicationId $AppId
 
New-OrganizationRelationship -Name "Contoso-Moves" -Enabled:$true `
    -MailboxMoveEnabled:$true -MailboxMoveCapability Inbound `
    -DomainNames "<source-tenant-id>"

If the tenant is dehydrated, run Enable-OrganizationCustomization first. If an organization relationship with the partner already exists, update it with Set-OrganizationRelationship instead of creating a second one. Endpoint creation fails with an authentication error if the source has not consented yet.

3.3 Source tenant: consent, scoping group and organization relationship

The source administrator opens the consent URL, accepts the application, and then scopes which mailboxes may leave the tenant using a mail-enabled security group. Only members of this group can be moved, which protects against accidental migration of the wrong users. For more than 10,000 users, Microsoft recommends several groups; nested groups work but are not recommended.

# Source tenant - Exchange Online PowerShell
New-DistributionGroup -Type Security -Name "T2T-Fabrikam-Movers"
 
New-OrganizationRelationship -Name "Fabrikam-Moves" -Enabled:$true `
    -MailboxMoveEnabled:$true -MailboxMoveCapability RemoteOutbound `
    -DomainNames "<target-tenant-id>" `
    -OAuthApplicationId "<application-id>" `
    -MailboxMovePublishedScopes "T2T-Fabrikam-Movers"

Changing MailboxMoveCapability requires the Organization Management role; running the moves themselves only requires the Move Mailboxes role.

3.4 Prepare target mail users

Every mailbox that moves needs a matching MailUser in the target tenant with these attributes:

Export the values from the source tenant:

# Source tenant
Get-DistributionGroupMember "T2T-Fabrikam-Movers" -ResultSize Unlimited | ForEach-Object {
    Get-Mailbox -Identity $_.PrimarySmtpAddress |
        Select-Object PrimarySmtpAddress, Alias, DisplayName, ExchangeGuid, ArchiveGuid, LegacyExchangeDN, EmailAddresses
} | Export-Clixml "C:\T2T\source-mailboxes.xml"

Then stamp them on the target mail users (created beforehand with New-MailUser, Entra Connect or another provisioning method):

# Target tenant
$mailboxes = Import-Clixml "C:\T2T\source-mailboxes.xml"
foreach ($m in $mailboxes) {
    $target = "$($m.Alias)@fabrikam.onmicrosoft.com"
    $x500 = @("x500:$($m.LegacyExchangeDN)") + ($m.EmailAddresses | Where-Object { $_ -like "x500:*" })
 
    Set-MailUser -Identity $target -ExchangeGuid $m.ExchangeGuid -EmailAddresses @{add = $x500}
    if ($m.ArchiveGuid -and $m.ArchiveGuid -ne [guid]::Empty) {
        Set-MailUser -Identity $target -ArchiveGuid $m.ArchiveGuid
    }
}

Watch for these pitfalls:

• Do not license the target user for Exchange Online before ExchangeGuid is stamped. A license applied first provisions a new, empty mailbox, and the move cannot proceed. The safest pattern is to assign the license after the move completes, within the 30-day grace period.
• If a target user previously had a mailbox, clear it with Set-User <identity> -PermanentlyClearPreviousMailboxInfo (irreversible) before stamping the source ExchangeGuid.
• All SMTP proxy addresses on the target mail user must belong to domains the target tenant owns. A source-domain address such as contoso.com blocks the conversion to a mailbox.
• The X500 addresses keep replies to old messages and Outlook autocomplete entries working; without them, users see 5.1.1 non-delivery reports.

3.5 Validate and create batches

Test the endpoint against a prepared mail user, and consider running Microsoft's cross-tenant mailbox migration validation script (linked from the documentation) against the whole population:

# Target tenant
Test-MigrationServerAvailability -Endpoint "T2T-Contoso" -TestMailbox "lara.newton@fabrikam.com"
 
New-MigrationBatch -Name "T2T-Wave1" -SourceEndpoint "T2T-Contoso" `
    -CSVData ([System.IO.File]::ReadAllBytes("C:\T2T\wave1.csv")) `
    -TargetDeliveryDomain "fabrikam.onmicrosoft.com" -AutoStart
 
# Later, on the cutover date
Complete-MigrationBatch -Identity "T2T-Wave1"
 
# Cross-tenant moves only
Get-MoveRequest -Flags "CrossTenant"

The CSV contains an EmailAddress column with the target tenant addresses of the mail users. After a move completes, the source mailbox becomes a MailUser whose ExternalEmailAddress points to the target, which keeps mail routing working for anyone still sending to the old address. The source mailbox itself is removed and is no longer discoverable in the source tenant, so take any copies needed for eDiscovery beforehand.

3.6 What moves and what does not

• Moves: email, contacts, calendar, tasks, notes, the Recoverable Items folders, archives (including auto-expanding archives with up to 12 auxiliary archives), voicemails, and mailbox permissions where both principal and delegate move together. Shared mailboxes move too.
• Does not move: Send on Behalf (GrantSendOnBehalfTo) must be restamped; mailbox signatures; Outbox items; Teams chat folder content (it stays searchable by the source administrator); sensitivity labels (recreate in the target); Microsoft 365 Groups.
• Teams meetings move as calendar items, but their join links still point at the source tenant, so they must be recreated (or migrated with the orchestrator's Teams meetings workload).

Phase 4: Cross-Tenant OneDrive Migration

OneDrive moves use SharePoint Online PowerShell (install the latest SharePoint Online Management Shell). Key constraints:

• Users must exist and be licensed in the target, but must not have a OneDrive yet. Restrict OneDrive creation in the target for these users, because an existing site makes the move fail and cannot be overwritten.
• Each OneDrive can hold at most 5 TB or 1 million items, and full paths must stay within 400 characters.
• OneDrives with a hold policy are blocked; source OneDrives must be read/write; the source must not use Microsoft Purview Customer Key.
• The move is one-time: there are no incremental passes. The OneDrive is read-only for a few minutes, and a redirect is left at the old URL.
• Up to 4,000 OneDrive (and SharePoint) moves can be queued at a time.

# Both tenants: get each tenant's cross-tenant host URL
Get-SPOCrossTenantHostUrl
 
# Source tenant: trust the target
Set-SPOCrossTenantRelationship -Scenario MnA -PartnerRole Target -PartnerCrossTenantHostUrl "https://fabrikam-my.sharepoint.com/"
# Target tenant: trust the source
Set-SPOCrossTenantRelationship -Scenario MnA -PartnerRole Source -PartnerCrossTenantHostUrl "https://contoso-my.sharepoint.com/"
 
# Both tenants: verify (expect GoodToProceed)
Verify-SPOCrossTenantRelationship -Scenario MnA -PartnerRole Target -PartnerCrossTenantHostUrl "https://fabrikam-my.sharepoint.com/"
 
# Target tenant: upload the identity map (users and groups, no header row)
Add-SPOTenantIdentityMap -IdentityMapPath "C:\T2T\identitymap.csv"
 
# Source tenant: check compatibility (Compatible or Warning means proceed)
Get-SPOCrossTenantCompatibilityStatus -PartnerCrossTenantHostUrl "https://fabrikam-my.sharepoint.com/"
 
# Source tenant: start or schedule a move (Microsoft documents the preferred dates as UTC)
Start-SPOCrossTenantUserContentMove -SourceUserPrincipalName "lara@contoso.onmicrosoft.com" `
    -TargetUserPrincipalName "lara@fabrikam.onmicrosoft.com" `
    -TargetCrossTenantHostUrl "https://fabrikam-my.sharepoint.com/" `
    -PreferredMoveBeginDate (Get-Date "2026-11-14 22:00")
 
# Either tenant: monitor
Get-SPOCrossTenantUserContentMoveState -PartnerCrossTenantHostUrl "https://fabrikam-my.sharepoint.com/" -SourceUserPrincipalName "lara@contoso.onmicrosoft.com"

After a trust is requested, Microsoft documents a seven-day waiting period (reported as DormantByPartner while it runs), so set the relationship up at least a week before the first move. The identity map has six columns per row: User, source tenant ID, source UPN, target UPN, target email, user type for users; Group, source tenant ID, source group object ID, target group object ID, group name, group type for groups. Re-uploading the map replaces it entirely, so always upload the complete list. Users and groups in the map keep their permissions on migrated content.

Phase 5: SharePoint Sites and Teams

SharePoint sites

Cross-tenant SharePoint site migration uses the same trust, identity map and compatibility checks as OneDrive. Moves are started from the source with Start-SPOCrossTenantSiteContentMove for regular sites and Start-SPOCrossTenantGroupContentMove for group-connected sites. The same 5 TB / 1 million item / 400 character limits apply, the target site must not exist beforehand, and the move is one-time with a redirect left behind. Workflows, SharePoint apps, Power Apps and Power Automate flows must be recreated, and sites containing sensitivity labels with user-defined permissions cannot be moved until those labels are removed.

Teams

Be clear with stakeholders about what is and is not native:

• Teams chats and meetings for individual users can be moved with Migration Orchestrator, which runs Exchange, OneDrive, Teams chats and Teams meetings in one batch and handles the ordering. The meetings workload requires the chats and mailbox workloads in the same batch. Chats are recreated in the target; the original messages stay in the source (possibly edited, with participant lists changed), and duplicate threads can appear. The orchestrator has additional prerequisites such as Teams migration apps in both tenants and Teams licenses on both sides.
• Teams, channels and channel conversations are not migrated by any native tool. Moving a Teams-connected SharePoint site moves only its files. The usual approach is to recreate the team structure in the target, move the files with cross-tenant SharePoint migration, and either archive channel history in the source or use a third-party migration product if channel messages must be preserved.
• Apps, tabs, connectors and Planner plans need to be rebuilt.

Phase 6: Domain Move and Cutover Sequencing

A domain can be verified in only one tenant at a time, and target mail users cannot hold addresses in a domain the source tenant still owns. This dictates the sequence when a vanity domain moves:

1. Weeks before: migrate mailboxes and OneDrives using target-owned addresses (for example @fabrikam.onmicrosoft.com or a temporary target domain). Source mail users forward mail to the target. Lower the TTL on the domain's MX, SPF and autodiscover records.
2. Cutover start: stop inbound mail to the source for the domain (or accept that it queues at the sender while MX is changing).
3. Remove the domain from every object in the source tenant: user UPNs, mailbox and mail user addresses, groups, Microsoft 365 Groups, contacts, and app registrations. For synchronized objects, make the change in on-premises Active Directory and let Entra Connect sync it.
4. Remove the domain from the source tenant, then add and verify it in the target tenant. Verification can fail for a while after removal; allow time for this in the plan.
5. Stamp the domain on target users (UPN and primary SMTP), update MX, SPF, DKIM, DMARC and autodiscover to the target tenant's values.

Find what still references the domain before trying to remove it:

# Source tenant - Microsoft Graph PowerShell
Connect-MgGraph -Scopes "Domain.Read.All", "Directory.Read.All"
Get-MgDomainNameReference -DomainId "contoso.com" -All |
    Select-Object Id, @{n="Type"; e={$_.AdditionalProperties.'@odata.type'}}
 
# Source tenant - Exchange Online PowerShell: recipients still using the domain
Get-Recipient -ResultSize Unlimited |
    Where-Object { $_.EmailAddresses -like "*@contoso.com" } |
    Select-Object DisplayName, RecipientTypeDetails, PrimarySmtpAddress

Change UPNs with Update-MgUser (cloud users) and email addresses with the Exchange cmdlets for each recipient type, for example Set-MailUser -Identity <id> -EmailAddresses @{remove = "smtp:alias@contoso.com"}. Microsoft Graph treats proxyAddresses as read-only, so address cleanup has to be done in Exchange Online. When nothing references the domain, Remove-MgDomain -DomainId "contoso.com" succeeds. The Microsoft 365 admin center's domain removal can also rename references automatically, which is practical for smaller tenants.

Phase 7: User Impact

• Outlook: users sign in with a new identity and the mailbox no longer carries the old primary address, so Outlook profiles must be rebuilt with the new UPN and primary SMTP address, and the OST and offline address book download again. This is the largest bandwidth and helpdesk event of the migration.
• OneDrive sync client: users sign in with the new identity and files resync. Shared links redirect to the new location for people who are in the identity map.
• Teams: users sign in to the target tenant; team memberships in the target come from the recreated teams. After the mailbox moves, Teams in the source tenant loses access to that mailbox (no calendar, profile picture updates or joining public teams there).
• Authentication: MFA methods, passkeys and Windows Hello registrations do not move. Users register again in the target tenant, so plan a Temporary Access Pass or supported onboarding flow.
• Devices: devices joined to or registered with the source tenant's Entra ID and enrolled in its Intune must be re-joined and re-enrolled in the target. Autopilot reset or a fresh deployment is often simpler than in-place re-joins.
• Mobile: remove and re-add accounts in Outlook mobile and Teams mobile.

Cutover Weekend Runbook

References

• Plan a Microsoft 365 tenant-to-tenant migration
• Cross-tenant mailbox migration
• Cross-tenant OneDrive migration overview
• Cross-tenant OneDrive migration Step 2: establish trust
• Cross-tenant OneDrive migration Step 5: identity mapping
• Cross-tenant OneDrive migration Step 6: start the migration
• Cross-tenant OneDrive migration Step 7: post-migration steps
• Cross-tenant SharePoint site migration overview
• Migration orchestrator overview
• Migration orchestrator planning and prerequisites