How to migrate Teams message history between M365 tenants

Of the four M365 workloads, Teams is the hardest to migrate. Unlike email (which is just EML messages in a mailbox) or OneDrive (which is just files in a drive), Teams weaves together multiple Graph API resources: teams, channels, messages, members, tabs, apps, and channel files stored in SharePoint.

What actually gets migrated

• Team structure — team name, description, visibility (public/private), and settings.
• Channels — standard and private channels, including channel descriptions.
• Message history — all posts and replies in standard channels, including @mentions, emoji reactions, and attached images.
• Channel files — the SharePoint document library backing each channel.
• Member roster — owners and members are mapped to their destination UPNs.

The migration API sequence

Microsoft provides a Teams Migration API that allows creating teams and channels in migration mode, then importing messages with their original timestamps. The sequence is:

1. 1Create the team in migration mode using POST /teams with the creationMode: migration flag.
2. 2Create each channel in the team, also in migration mode.
3. 3POST messages to each channel using their original timestamps — this is what preserves history.
4. 4Complete migration mode on each channel, then on the team.
5. 5Add members and owners after completing migration mode — you cannot add members while in migration mode.

Throttle limits to plan around

The Teams migration API is significantly more throttled than standard Graph API calls. Practically, this means:

• Message import: roughly 1,000–2,000 messages per channel per minute before throttling kicks in.
• Channels with 100,000+ messages will take multiple hours regardless of worker count.
• Microsoft recommends not running more than 5 concurrent team migrations per tenant.
• Throttle responses (429) must be respected — the Retry-After header tells you exactly how long to wait.

Channel files

Each Teams channel has a backing SharePoint document library. These files need to be migrated separately as part of your SharePoint migration — they are not included in the Teams message migration. The channel file tab in Teams will resolve automatically once the SharePoint migration puts files at the correct URL.