Microsoft 365 Tenant-to-Tenant Migration in 2026: The Native Migration Orchestrator Changes the Game

TL;DR

• The migration orchestrator entered worldwide public preview in December 2025 and is still in preview as of August 2026. Plan around a preview, not a GA product.
• It moves four workloads, not three: Exchange mailboxes, OneDrive, Teams chats, and Teams meetings.
• It moves content, not identities. You create and map the target users yourself before anything moves.
• There is no admin portal. Batches are created and driven entirely through Microsoft Graph PowerShell, capped at 100 users per batch.
• Mailboxes on any type of hold are blocked from migrating. Inventory your holds before you inventory anything else.

Four corrections to the earlier version of this article

Four claims in the original don't survive a check against Microsoft's documentation. Correcting them in the open beats quietly editing them away.

Correction 1: SharePoint sites do not require a third-party tool. Microsoft ships cross-tenant SharePoint site migration as a separate native feature driven from SharePoint Online PowerShell. It sits outside the orchestrator and is licensed differently — probably why the two get conflated.

Correction 2: the orchestrator covers four workloads. Teams meetings are a distinct workload alongside Exchange, OneDrive, and Teams chats — and a batch fails to initiate if you select meetings without also selecting chats and mailboxes.

Correction 3: "no third-party tool required" is not the same as "free." A paid Cross-Tenant User Data Migration add-on licence is mandatory per migrating user. Microsoft states that migrations fail without it and that no exceptions are granted.

Correction 4: the orchestrator is not an identity move. Microsoft's overview is unambiguous — "This migration moves content, not identities." Every target user must already exist, correctly shaped, before a batch validates.

What the orchestrator actually does

Microsoft put a real orchestration layer behind mail, files, and Teams conversations. That changes the shape of a migration plan; it does not remove the plan.

The service groups users into a batch, validates every prerequisite, syncs quietly until the cutover date you set, then flips workloads in dependency order: Exchange first, then OneDrive, Teams chats, and Teams meetings in parallel. Submit batches two weeks before the completeAfterDateTime — nothing is user-visible during sync.

Two constraints reshape wave planning immediately. The batch ceiling is 100 users, and validation results expire after seven days — validate too early and you revalidate before you can migrate. A shared queue limit of 4,000 also applies across OneDrive and SharePoint moves.

flowchart LR
    subgraph Orch["Migration orchestrator (preview) - Graph PowerShell"]
      A[Exchange mailboxes]
      B[OneDrive]
      C[Teams chats]
      D[Teams meetings]
    end
    subgraph SPO["Cross-tenant SharePoint migration - SPO PowerShell, EA only"]
      E[Team + communication sites]
      F[Group-connected sites]
    end
    subgraph Gap["No native path"]
      G[Teams channels + channel messages]
      H[Power Automate / Power Apps]
      I[Public folders]
    end
    Orch --> T[(Target tenant)]
    SPO --> T
    Gap --> M[Rebuild or third-party tooling]

Teams channels are the honest gap. The SharePoint feature migrates a Teams-connected site's content only — Microsoft states it "doesn't include migration of Teams content, channels or associated structure." Channel conversations have no native cross-tenant path at all.

Two licences, and they are not interchangeable

This is where migration budgets go wrong. Two separate SKUs, sold on different units, to different customer types.

Size the SharePoint side before you commit to a date. Sum StorageUsageCurrent across in-scope sites and add headroom — Microsoft allows roughly 20 percent growth against the licensed volume.

# Size the SharePoint estate for Cross-Tenant Shared Data Migration licensing
Get-SPOSite -Limit All |
    Select-Object Url, StorageUsageCurrent |
    Sort-Object StorageUsageCurrent -Descending |
    Export-Csv .\spo-sizing.csv -NoTypeInformation

Identity mapping is the real prerequisite

Cross-Tenant Identity Mapping (CTIM) decides whether your migration validates. It stamps the source mailbox's ExchangeGuid, ArchiveGuid, and LegacyExchangeDN (as an x500: proxy address) onto the target MailUser — the attributes without which the move refuses to proceed.

The ordering trap is licensing. Run CTIM before assigning workload licences in the target tenant, so target users become MailUsers rather than provisioned mailboxes. A target user who already has a mailbox or OneDrive site fails migration, and there is no overwrite. Disable OneDrive creation for target users the moment you create them.

# Target tenant: install and authorize CTIM, then map the wave
Install-Module CrossTenantIdentityMapping -AllowPrerelease
Import-Module CrossTenantIdentityMapping
Connect-MgGraph                       # Global Administrator, one-time consent
Add-CtimServicePrincipal

# Source admin initiates, target admin accepts, target admin maps and writes
New-CtimCopyRequest    -SecurityGroupGuid <sourceScopeGroupGuid> -TargetTenantGuid <targetTenantGuid>
Accept-CtimCopyRequest -RequestID <requestId> -SourceTenantGUID <sourceTenantGuid>
New-CtimMapRequest     -SourceTenantGuid <sourceTenantGuid>      # matches on PrimarySmtpAddress
New-CtimWriteRequest   -SourceTenantGuid <sourceTenantGuid>      # stamps ExchangeGuid / x500

Scope comes from a mail-enabled security group in the source tenant, referenced by MailboxMovePublishedScopes on the organization relationship. No user may sit in two scopes.

Where cross-tenant sync fits — and where it does not

The original article was right about this, and Microsoft's FAQ now says it in one sentence: cross-tenant synchronization "isn't a migration tool because the source tenant is required for synchronized users to authenticate."

Sync earns its place in coexistence. During a phased migration you have people on both sides for weeks, and cross-tenant access settings plus B2B automatic redemption keep them working without consent prompts. Enable automatic redemption inbound in the target and outbound in the source — the prompt is suppressed only when both are set.

The pre-migration inventory that predicts the pain

Six data points explain most tenant-move overruns. Collect them before you commit to a wave plan.

Holds. Mailboxes on any type of hold are blocked outright, and OneDrive accounts under a hold policy are blocked too. This is the item that most often drags legal onto the critical path, so pair it with a clear-eyed read of your retention estate — our guide to what native Microsoft 365 backup and retention covers is the companion inventory.

Mailbox size and quota. Mailboxes at or near quota fail mid-move. Enabling archives helps — up to 12 auxiliary archives are supported — but if an auto-expanding archive expands during the move, the migration fails and the user must be resubmitted.

Delegates and shared mailboxes. Shared mailboxes migrate and store permissions are preserved, but cross-tenant mailbox and calendar permissions are not supported. Principals and delegates must move in the same batch or the relationship breaks. GrantSendOnBehalfTo lives in the directory and does not move at all — restamp it in the target.

Path length. The 400-character limit covers source path plus target site or user URL combined. Long target names silently sink OneDrive and SharePoint moves.

Sensitivity labels. Labels don't export, and sites holding labels with user-defined permissions cannot migrate until those labels are removed.

Automation. Power Automate flows and Power Apps must be recreated and reconnected in the target. So must SharePoint workflows, apps, and any web part pointing at another site.

# Source tenant: the inventory that decides your wave plan
Get-Mailbox -ResultSize Unlimited |
  Select-Object PrimarySmtpAddress, RecipientTypeDetails, LitigationHoldEnabled,
                InPlaceHolds, ArchiveGuid, ArchiveStatus |
  Export-Csv .\mailbox-inventory.csv -NoTypeInformation

# Delegate graph — principals and delegates must share a batch
Get-Mailbox -ResultSize Unlimited | ForEach-Object {
  Get-MailboxPermission $_.Identity |
    Where-Object { $_.User -notlike 'NT AUTHORITY\*' -and -not $_.IsInherited }
} | Export-Csv .\delegate-map.csv -NoTypeInformation

Configuring the tenants

Mailbox moves need an organization relationship on both sides plus a migration endpoint on the target, exactly as standalone cross-tenant mailbox migration always required.

# Target tenant — accept inbound moves, then create the endpoint
New-OrganizationRelationship -Name "FromSource" -Enabled:$true -MailboxMoveEnabled:$true `
  -MailboxMoveCapability Inbound -DomainNames $sourceTenantId

New-MigrationEndpoint -Name "T2T" -ExchangeRemoteMove:$true -RemoteServer outlook.office.com `
  -RemoteTenant $sourceTenantDomain -Credentials $cred -ApplicationId $appId

# Source tenant — publish the scope group and authorize the outbound move
New-OrganizationRelationship -Name "ToTarget" -Enabled:$true -MailboxMoveEnabled:$true `
  -MailboxMoveCapability RemoteOutbound -DomainNames $targetTenantId `
  -OAuthApplicationId $appId -MailboxMovePublishedScopes $scopeGroup

The orchestrator adds its own applications on top: Grant-CTMSAppPermissions and Set-CalendarRBACRoles on the target, Grant-OneDriveAppPermissions and Grant-CTTMAppPermissions on both, and Grant-MMSAppPermissions -TenantType "source" / "target". Teams chat migration also needs Set-CsTenantFederationConfiguration -AllowFederatedUsers $True on both tenants.

Running a wave

Everything runs from the target tenant as a Microsoft 365 Migration Administrator — a purpose-built role that should be your default instead of Global Administrator. Source tenants cannot run migration commands.

Connect-MgGraph -Scopes 'CrossTenantContentMigration.ReadWrite.All'

New-MgBetaCrossTenantMigrationJob -DisplayName "wave-01-finance" `
  -CompleteAfterDateTime 2026-09-12T22:00:00Z -ResourceType Users `
  -Resources @('<targetUserObjectId1>','<targetUserObjectId2>') `
  -SourceTenantId <sourceTenantGuid> `
  -ExchangeSettings @{ SourceEndpoint = 'T2T'; TargetDeliveryDomain = 'target.onmicrosoft.com' }

Test-MgBetaCrossTenantMigrationJob -CrossTenantMigrationJobId "wave-01-finance"
Get-MgBetaCrossTenantMigrationJobUser -CrossTenantMigrationJobId "wave-01-finance" |
  ConvertTo-Json -Depth 100          # per-user errors when status is ValidateFailed
Move-MgBetaCrossTenantMigrationJob -CrossTenantMigrationJobId "wave-01-finance"

Cancellation is possible only before completeAfterDateTime passes — Stop-MgBetaCrossTenantMigrationJob for the batch, Stop-MgBetaCrossTenantMigrationJobUser for one person. After that date the migration completes whether you want it to or not.

If a mailbox looks stuck more than 24 hours past cutover, check the Data Consistency Score. Investigate can be approved; Poor goes to Microsoft Support, not to -ApproveSkippedItems.

Get-MigrationUser -Identity user@target.com | Select-Object BatchId, Status, DataConsistencyScore
Set-MigrationUser -Identity user@target.com -ApproveSkippedItems   # only when grade is "Investigate"

What breaks — tell users before it happens

Every item below is documented behaviour, not bad luck. Put them in the comms, not the post-mortem.

• Teams chat history is approximate. Reactions, self-chats, unsent scheduled messages, code snippets, app messages including Polls, deleted messages, and attachments that aren't .jpg/.jpeg/.png do not migrate. Microsoft grades a chat migration completed if 80% of messages and 90% of threads land — a partial move is the designed outcome.
• Duplicate and temporary chats appear. When two people in a 1:1 chat migrate at different times, an interim thread is created and never deleted.
• Meetings older than 60 days keep dead join links. Only meetings whose last occurrence falls inside 60 days get updated URLs. Modified recurring occurrences, room-organized meetings, town halls, webinars, and anything marked Confidential do not migrate. All RSVPs reset.
• OneDrive links redirect, but only until the source dies. Redirects survive until the source tenant is deprovisioned — a deadline, not a permanent state. There is no delta pass: the move is one-and-done.
• Licence timing is a failure mode. Users need Teams and Exchange Online licences in both tenants for chat and meeting migration, and no target mailbox or OneDrive before the move.
• Sign-in and MFA start over. New tenant means new accounts: users re-register MFA, re-enrol devices, rebuild Outlook profiles, and re-sync OneDrive. Mailbox signatures are not migrated.

A phased sequence that survives contact with reality

1. Inventory and licence. Holds, quotas, delegate graph, site sizes, labels. Buy both add-ons; confirm EA eligibility.
2. Establish trust. Organization relationships, migration endpoint, orchestrator apps, SharePoint and OneDrive trust, Teams federation.
3. Create and map identities. Target users as MailUsers, CTIM copy → map → write, verify ExchangeGuid and x500 on every object. Only then apply licences.
4. Pilot one wave of ~50 IT users. Validate, migrate, and read the Teams chat percentages rather than the status word.
5. Migrate in waves by dependency, not org chart. Delegates with principals, SharePoint sites alongside the people who own them.
6. Cut over. Confirm ValidatePassed inside seven days, set completeAfterDateTime two weeks out, freeze delegate changes, communicate the MFA re-registration window, and keep source forwarding and objects intact until the programme ends.
7. Rebuild what doesn't move. Channels, flows, workflows, labels, retention, and Conditional Access — configured in the target before data lands, per our Entra tenant hardening checklist.

If yours is a divestiture rather than a merger, the sequencing inverts — see tenant carve-out vs. consolidation.

The bottom line

The orchestrator is a genuine advance: four workloads, one dependency-aware batch, real validation, a cutover you control. It is also a preview with a 100-user batch cap, no portal, a mandatory paid licence, and a hard stop at anything shared.

Plan for the gaps rather than around them. Inventory holds first, map identities before you license, keep principals and delegates together, and warn users about the Teams history they will lose. The tooling improved enormously; the discipline did not change at all.

Further reading

• Migration orchestrator overview (Microsoft Learn)
• Cross-tenant identity mapping (Microsoft Learn)
• Running a migration with the migration orchestrator (Microsoft Learn)
• Public Preview: Cross-tenant Orchestrated User Data Migration (Microsoft Community Hub)
• What is cross-tenant synchronization in Microsoft Entra ID? (Microsoft Learn)

Image credit: Joël van der Loo via Wikimedia Commons (CC BY-SA 4.0).