Notes:

PowerShell integration requires a ShareGate Migrate Pro or Enterprise subscription. It is not available on the Essentials plan.

At the end of January 2026, Microsoft began deprecating the IDCRL cookie, meaning that only Browser and Modern authentication methods with the parameters -Browser and -ModernAuth will work in most Microsoft 365 tenants. To learn more, see Important change to "Other user" authentication for Microsoft 365.

Use PowerShell to copy multiple Microsoft 365 mailboxes from a mapping file. This approach lets you process mailboxes in batches and export a report after each batch, making your larger mailbox migrations more manageable.

How-to

For your mailbox migration, you will need a mapping file and a PowerShell script that reads from that file to copy mailboxes in batches.

Set up your mapping file

Your mapping file is a CSV that pairs each source mailbox with its destination. Set it up before running the migration to review and adjust the pairings.

With PowerShell

Run the following script to automatically generate your mapping file. ShareGate Migrate matches source and destination mailboxes by display name.

$source = Connect-MicrosoftOnline
$destination = Connect-MicrosoftOnline

Export-MailboxMappings -SourceConnection $source -DestinationConnection $destination -Path "C:\MyMappings\"

Update "C:\MyMappings\" to the folder on your drive where you want to save the mapping file. See Export-MailboxMappings for available parameters.

Mailboxes with no match at the destination are left blank in the CSV. Review the file and fill in any missing pairings before proceeding.

From ShareGate Migrate

Follow the steps in Copy mailboxes - Mappings to set up your operation and reach the mapping screen.
Click the Export mappings icon.
Save the CSV file and note its path.

Once you have your mapping file, open it and confirm the pairings. You can edit the CSV to add, remove, or adjust any source-to-destination matches before running the migration.

Create your script

Copy and paste the following script into the PowerShell application of your choice. Update the -Path values in $mappings and $csv to point to the mapping file you saved in the previous section.

$sourceConnection = Connect-MicrosoftOnline
$destinationConnection = Connect-MicrosoftOnline

$options = New-MailboxCopyOptions -IncludeEmails
$mappings = Import-MailboxMappings -SourceConnection $sourceConnection -DestinationConnection $destinationConnection -Path "C:\MyMappings\SharegateMailboxesMapping.csv"

$csv = Import-Csv -Path "C:\MyMappings\SharegateMailboxesMapping.csv"

# Ensure $csv is treated as an array, even with a single mailbox
$csv = @($csv)

# Initialize the starting index and the batch size
$index = 0
$batchSize = 16

while ($index -lt $csv.Count) {
    # Select the current batch
    $guids = $csv | Select-Object -Skip $index -First $batchSize -ExpandProperty "Source user id"

    # Fetch the mailboxes
    $mailboxes = Get-Mailbox -Id $guids -Connection $sourceConnection -AllowMultiple

    # Copy the mailboxes
    $result = Copy-Mailbox -SourceConnection $sourceConnection -DestinationConnection $destinationConnection -CopyOptions $options -MappingSettings $mappings -Mailboxes $mailboxes

    # Export the report
    Export-Report -SessionId $result.SessionId

    # Increment index for next batch
    $index += $batchSize
}

Adjust the script to work in your environment. Here are a few guidelines:

$sourceConnection and $destinationConnection: Connect to your source and destination Microsoft 365 tenants. See Connect-MicrosoftOnline for authentication options.
$options: Sets the content to include in the copy. Replace -IncludeEmails with the options for your migration. See New-MailboxCopyOptions for available parameters.
$mappings and $csv: Both must point to the same mapping file. Update -Path and Import-Csv -Path to match the file you saved in the previous section.
$batchSize: The number of mailboxes to process per batch. Start with 16 and adjust based on how your environment performs.
$guids: Extracts the source user IDs for the current batch from the CSV.
$mailboxes: Fetches the mailbox objects for the current batch. The -AllowMultiple parameter is required when passing more than one ID. See Get-Mailbox for details.
$result: Holds the result of the copy operation, including the session ID used by Export-Report.
Export-Report: Exports the migration report for each batch after it completes. See Export-Report.

Run your script once it's properly adjusted and tested.

Considerations

Modern authentication with -ModernAuth is the most secure authentication method for Microsoft 365 and can be used with Username and Password variables as long as multi-factor authentication (MFA) is not enforced. See Connect-MicrosoftOnline to learn about different authentication options, or to switch to Browser authentication if needed.
Migration reports are generated per batch. The script exports each batch's report automatically with Export-Report.
You can schedule your migration using PowerShell to run it off-hours and optimize performance.
To perform an incremental migration, re-run the script after the initial copy to sync only items that have been added or changed since the last run.
Batch size: The right batch size depends on your mailbox sizes and network conditions. Start with 16 and adjust based on performance. Smaller batches are easier to monitor and troubleshoot if something fails.
Script errors and testing: Test your script on a small subset of mailboxes before running it on your full environment. Testing helps identify potential issues before they affect a large number of users.

Copy multiple mailboxes with PowerShell