How-to · Exchange Online

Create, start, monitor and complete a migration batch

At the end you will have moved a group of mailboxes into Exchange Online with a migration batch, checked each user's progress and finalised (or cleaned up) the batch.

Updated 4 Nov 20267 steps7 official sources

Start here Back to the playbook

Before you start

What you need before step 1

Applies to: Exchange Online migration batches for remote move (hybrid), IMAP, staged, cutover and cross-tenant migrations, as documented by Microsoft

Admin roles you need

Exchange Administrator or Global Administrator in Microsoft 365
The Move Mailboxes role in Exchange Online, which Microsoft says is needed to run New-MigrationBatch and can be delegated to operators

Licences

A Microsoft 365 licence that includes Exchange Online for each migrated user

Install instructions

ExchangeOnlineManagement PowerShell module (for the PowerShell route)Install on your admin computer; see the Connect to Exchange Online PowerShell how-tohttps://learn.microsoft.com/powershell/exchange/exchange-online-powershell-v2Our step-by-step →Install steps

Also have ready

A migration endpoint for the source (see the Create a migration endpoint how-to). Cutover batches do not use a CSV.
For IMAP: target mailboxes already created in Microsoft 365

Step by step

7 steps

1
Build the CSV file
Where: Excel or any text editor on your admin computer
Row 1 holds the column names, separated by commas. Each later row is one user, with values in the same order. Leave an empty value (but keep the comma) to use the batch default. Required columns:
- Remote move onboarding (hybrid): EmailAddress. Optional: MailboxType. (BadItemLimit and LargeItemLimit are deprecated in Exchange Online; see the Data Consistency Score tip below.)
- IMAP: EmailAddress (the Microsoft 365 address), UserName (source sign-in), Password (source password). Up to 50,000 rows.
- Staged: EmailAddress; optional Password and ForceChangePassword. Up to 1,000 rows per batch.
Save as .csv.
```
EmailAddress,UserName,Password
terrya@contoso.com,terry.adams,P@ssw0rd1
annb@contoso.com,ann.beebe,P@ssw0rd2
```
You should see: A .csv file whose first line is exactly the header row for your migration type.
2
Create the batch in the Exchange admin center
Where: Exchange admin center > Migration > Add migration batch
Select Add migration batch. Type a name with no spaces or special characters and choose Migrate to Exchange Online. Select Next. Choose the migration type (for example IMAP migration), confirm the prerequisites page, then on Set a migration endpoint pick your endpoint. On Add user mailboxes select Import CSV file and upload your CSV. Set any filtering options, then on Schedule batch migration choose how to start and how to complete the batch. Select Save, then Done.
You should see: The batch appears on the Migration page. If you chose to start it automatically, its status shows Syncing.
3
Or create the batch in PowerShell
Where: PowerShell on your admin computer, connected with Connect-ExchangeOnline
The CSV must be read into bytes with [System.IO.File]::ReadAllBytes(). First line: hybrid remote move into contoso.mail.onmicrosoft.com. Second: IMAP, skipping two folders. Add -AutoStart to start at once and -NotificationEmails to get status reports. Use -CompleteAfter to sync now but hold completion until a set time (UTC unless you give an offset).
```
New-MigrationBatch -Name RemoteOnBoarding1 -SourceEndpoint Endpoint1 -TargetDeliveryDomain contoso.mail.onmicrosoft.com -CSVData ([System.IO.File]::ReadAllBytes("C:\Migration\RemoteOnBoarding1.csv")) -NotificationEmails admin@contoso.com
New-MigrationBatch -Name IMAPbatch1 -SourceEndpoint IMAP_SSL_Endpoint -CSVData ([System.IO.File]::ReadAllBytes("C:\Migration\IMAPmigration_1.csv")) -ExcludeFolders "Deleted Items","Junk Email" -AutoStart
```
You should see: PowerShell returns the batch with its Identity and Status.
4
Start the batch
Where: Same PowerShell session, or Exchange admin center > Migration > select the batch > Resume migration
If you did not use -AutoStart or an automatic start in the admin center, start the batch now.
```
Start-MigrationBatch -Identity RemoteOnBoarding1
```
You should see: The batch status changes to Syncing.
5
Monitor the batch and each user
Where: Same PowerShell session, or Exchange admin center > Migration > select the batch > View details
Check overall status, then per-user detail. -IncludeReport adds troubleshooting detail; the skipped items line shows what could not be copied.
```
Get-MigrationBatch -Identity RemoteOnBoarding1
Get-MigrationUser -BatchId RemoteOnBoarding1 | Get-MigrationUserStatistics
Get-MigrationUserStatistics -Identity terrya@contoso.com -IncludeReport | Format-List Status,Error,Report
Get-MigrationUserStatistics -Identity terrya@contoso.com | Format-List SkippedItemCount,SkippedItems
```
You should see: The batch reaches Synced (initial copy done) or Synced with errors (some users failed). Users then sync incrementally every 24 hours for most migration types.
6
Complete a remote move or Gmail batch
Where: Same PowerShell session, or Exchange admin center > Migration > select the batch > Complete migration batch
When the batch is Synced or SyncedWithErrors, complete it. This runs a final incremental sync, points Outlook profiles at the new mailbox and converts the source mailbox to a mail-enabled user. Do not rerun it within 8 hours; if it seems stuck, check for unapproved skipped items.
```
Complete-MigrationBatch -Identity RemoteOnBoarding1 -NotificationEmails admin@contoso.com
Set-MigrationUser -Identity terrya@contoso.com -ApproveSkippedItems
```
You should see: The batch status changes to Completed.
7
Finish an IMAP or cutover batch
Where: Your DNS host, then Exchange admin center > Migration
IMAP, cutover and staged batches have no completion step in Exchange Online, so Complete-MigrationBatch does not apply. Point your MX record at Microsoft 365, let the batch keep syncing (Microsoft suggests at least 72 hours for IMAP because sync runs once a day), then select the batch and choose Delete, or run Remove-MigrationBatch.
```
Remove-MigrationBatch -Identity IMAPbatch1
```
You should see: The batch is no longer listed on the Migration page and synchronisation stops.

From experience

Expert tips

Sync early, complete in a short window

Create and start batches days ahead so the bulk copy happens in business hours with no user impact. After the initial sync, Microsoft keeps most migration types in incremental sync every 24 hours, so the final delta is small. Use -CompleteAfter (UTC unless you add an offset) or manual completion to finalise in your agreed window. Do not pre-stage too far ahead: Microsoft stops Synced batches with no admin activity after 60 days.

BadItemLimit no longer protects you; the Data Consistency Score does

The old -BadItemLimit and -LargeItemLimit (default 0, so any bad item failed the move) are deprecated in Exchange Online. Microsoft now grades each move: Perfect and Good need no action, Investigate needs you to approve skipped items before remote move and Google Workspace batches can complete, and Poor needs Microsoft Support. Review SkippedItems in Get-MigrationUserStatistics, then approve with Set-MigrationUser -ApproveSkippedItems or Set-MigrationBatch -ApproveSkippedItems. IMAP, cutover and staged moves need no approval.

Retry failed users without rebuilding the batch

Read the cause first with Get-MigrationUserStatistics -Identity user@contoso.com -IncludeReport. After fixing it, select Resume migration (or run Start-MigrationBatch) on the batch; Microsoft says it then attempts the mailboxes that failed.

Pilot two or three mailboxes first

Run a small batch with your own and a volunteer's mailbox before the first real wave. It proves the endpoint, licences, CSV format and completion behaviour (Outlook profile switch, mail-enabled user conversion) end to end. Then size real waves so completion fits your window.

IMAP: leave the batch running after the MX change

IMAP batches have no completion step. Change MX, then keep the batch syncing for at least 72 hours (Microsoft's suggestion, because sync runs once a day) to catch mail that landed on the old server. The IMAP CSV holds user passwords in clear text: store it securely and delete it when the batch is removed.

Check it worked

How to confirm it worked

In the Exchange admin center go to Migration, select the batch and check its status is Completed (or Synced for IMAP) with zero in the Failed column.
Run Get-MigrationUser -BatchId RemoteOnBoarding1 | Get-MigrationUserStatistics and check every user shows a completed or synced status.
Sign in to Outlook on the web as a migrated user and confirm folders and recent mail are present.

Undo

How to reverse it

Rollback:

Before completion you can stop a batch (Stop migration in the admin center or Stop-MigrationBatch) and remove it. After a remote move batch completes, the mailbox lives in Exchange Online and the source is converted to a mail user; reversing it means a new offboarding move back to Exchange Server, not an undo. Deleting an IMAP batch stops sync but leaves copied mail in place.

Troubleshooting

Errors you might see

Synced with errors

Cause: The initial sync finished but some mailboxes failed.

Fix: Run Get-MigrationUserStatistics -Identity user@contoso.com -IncludeReport | Format-List Status,Error,Report for each failed user and fix the cause. For IMAP, check the EmailAddress column holds the correct Microsoft 365 address.

Batch appears stuck after Complete-MigrationBatch

Cause: The batch was already signalled for completion (Microsoft says repeats within 8 hours may not be processed), or skipped items are waiting for approval.

Fix: Wait, and approve skipped items with Set-MigrationUser -ApproveSkippedItems.

Complete-MigrationBatch -SyncAndComplete returns an error

Cause: SyncAndComplete needs zero failed, corrupted or stopped items.

Fix: Fix or approve the failed items, or complete without -SyncAndComplete.

Batch stopped on its own

Cause: Microsoft stops Synced batches with no admin activity for 60 days.

Fix: Resume the batch, then complete it. Stopped or Failed batches are removed after 90 days and Completed batches after 60 days.

FAQ

Questions

How many users can one CSV hold?

Microsoft documents up to 50,000 rows (10 MB) for IMAP and up to 1,000 rows per staged migration batch.

How often does a batch sync after the first copy?

For most migration types, Microsoft says source and target synchronise every 24 hours during incremental sync.

What does -AutoComplete do?

It finalises each mailbox as soon as its initial sync finishes. It only works for local moves and remote move migrations.

Can I see progress in the admin center?

Yes. Select the batch on the Migration page and choose View details for the migration users status report.

Sources

Official sources

Vendors change menus and requirements. Confirm on the source before you rely on a detail. Last checked 4 Nov 2026.

Microsoft Learn: New-MigrationBatch Microsoft Learn: CSV files for mailbox migration Microsoft Learn: Manage migration batches Microsoft Learn: Get-MigrationUserStatistics Microsoft Learn: Complete-MigrationBatch Microsoft Learn: Migrate other types of IMAP mailboxes Microsoft Learn: Cross-tenant mailbox migration

Microsoft 365

Google Workspace

Email and domains

Files and collaboration

Servers and cloud

Databases

Websites and ecommerce

Business apps

Identity and security

End of support

Create, start, monitor and complete a migration batch

What you need before step 1

Admin roles you need

Licences

Install instructions

Also have ready

7 steps

Build the CSV file

Create the batch in the Exchange admin center

Or create the batch in PowerShell

Start the batch

Monitor the batch and each user

Complete a remote move or Gmail batch

Finish an IMAP or cutover batch