Migrate large mailboxes from Google or other IMAP sources to Microsoft 365 Exchange
Introduction
This document provides comprehensive guidance for tenant administrators on migrating emails from Internet Mail Access Protocol (IMAP) sources, including Gmail, to Microsoft 365 Primary and Archive mailboxes concurrently. Known as Large Archive Onboarding (LAO), this solution empowers tenant admins to seamlessly migrate mailboxes exceeding 100 GB from IMAP sources by harnessing the auto-expanding archives feature within Microsoft 365.
Note
For migrating regular sized (<100G) mailboxes from IMAP sources, please use Exchange Admin Center (EAC) migration features. If your source is GMail, you can also use GMail migration features in M365 Admin Center (MAC).
Currently, LAO is available only through PowerShell cmdlets. Automated UI experience will be added later.
Important
Microsoft 365 offers a resultant cumulative mailbox size of up to 1.6 TB. This includes 100 GB of Primary Mailbox, and 1.5 TB of Archives (including 100 GB Main Archive). For more information, see archive-mailboxes and autoexpanding-archiving.
You require at least "Recipient Management" role to execute this. Read through the documentation, especially the linked documents to help kickstart migrations for large mailboxes.
Run the cmdlet to disable ELCProcessing before creating LAO migration batch. If it's not disabled, the folders might be moved by ELC during LAO, and the LAO migration might be blocked. Set-Mailbox <> -ELCProcessingDisabled:$true
What do you need to know before you begin?
Before creating the migration, you need to know:
- The list of users with large mailboxes (>100 GB) on the source side.
- If you have a large mailbox, the content (time, type) that you intend to migrate and to where (primary, main archive, auxiliary archives).
For each user, the content can be selected based on time range or folder. See the following examples.
Time-range-based mapping:
Table 1
Time range Target Mailbox After 2023/01/01 Primary From 2022/01/01 to 2023/01/01 Archive mailbox 1 From 2021/01/01 to 2022/01/01 Archive mailbox 2 Before 2021/01/01 Archive mailbox 3 Folder-based mapping:
Table 2
Folder Name Target Mailbox Inbox Primary SentItems Primary DeletedItems Archive mailbox 1 Important
Well-Known Folders: The folders that come under this categorization include but are not limited to Inbox, Deleted Items, Sent Items, and Drafts. Full list here.
Except Deleted Items, all these well-known folders and customer created labels/folders can be migrated to either primary or any archive mailboxes (both Main Archive and Auxiliary Archives). However, Deleted Items of a user can be migrated only to the Primary or Main Archive, and not Auxiliary Archive.
If a single source folder is larger than 100 GB, it can't fit in one Exchange mailbox, so the end user needs to separate it to several smaller folders.
Prepare XML file
To migrate large mailboxes automatically, you need to prepare an XML file that advises the system on the content-to-mailbox mapping.
Download a sample XML file here Download a copy of the large mailbox migration XML mapping file and take a quick look before you proceed.
Time-range-based mapping
In the XML file, you need to specify the time range in ContentFilter. Unlike Filterable properties for the -ContentFilter parameter, only Received property is supported, which means that the filtering is based on the "Received" parameters and not the "Sent" parameters in the mail item metadata. For example, filtering is executed on the Received TimeStamp (time when the mail landed in the user's mailbox) vs the Sent TimeStamp (time when the sender of the mail sent it to the user) of a mail, which the users received in their mailbox.
Four operators are supported:
- gt: greater than
- ge: greater than or equal to
- lt: less than
- le: less than or equal to
The value of EmailAddress should be the SMTP address of EXO user.
The value of Target can be the following four types:
- Primary
- MainArchive
- AuxArchive* (AuxArchive1, AuxArchive2, AuxArchive3)
- GUID-of-Existing-Mailbox
Following is the XML file for time range based mapping for the example shown in table 1.
<?xml version="1.0" encoding="utf-8" ?>
<Users>
<User EmailAddress="user1@contoso.onmicrosoft.com">
<Folder Name="/*">
<Mapping ContentFilter="Received -gt '2023/1/1'" Target="Primary" />
<Mapping ContentFilter="Received -gt '2022/1/1' -and Received -le '2023/1/1'" Target="MainArchive" />
<Mapping ContentFilter="Received -gt '2021/1/1' -and Received -le '2022/1/1'" Target="AuxArchive1" />
<Mapping ContentFilter="Received -le '2021/1/1'" Target="AuxArchive2" />
</Folder>
</User>
</Users>
You can use Get-MailboxLocation to get the mailbox 'GUID' of a user's primary mailbox and archive mailboxes if any, and put the mailbox 'GUID' in the Target property.
Important
If the time range in the XML file is changed during the migration process, there may be duplicated items. We recommend tenant admin have clear communication with end users before starting the migration.
Important
When you create time ranges, ensure that you use continuous time ranges. If it's not continuous, there will be missing items that the migration process can't detect.
Folder-based mapping
In the XML file, you need to specify the folder names in Name properties.
The value of EmailAddress should be the SMTP address of EXO user.
The value of Target can be the following four types:
- Primary
- MainArchive
- AuxArchive* (AuxArchive1, AuxArchive2, AuxArchive3)
- GUID-of-Existing-Mailbox
Following is an example of the XML file for folder based mapping for the example shown in Table 2.
<?xml version="1.0" encoding="utf-8" ?>
<Users>
<User EmailAddress="user1@contoso.onmicrosoft.com">
<Folder Name="#Inbox#/*">
<Mapping Target="Primary" />
</Folder>
<Folder Name="#SentItems#/*">
<Mapping Target="Primary" />
</Folder>
<Folder Name="#DeletedItems#/*">
<Mapping Target="MainArchive" />
</Folder>
</User>
</Users>
Create large mailbox migration using PowerShell
LAO migration steps are very similar to regular IMAP migration and GWS migration. Following are the links to learn more about the prerequisites and steps.
- What you need to know about migrating your IMAP mailboxes to Microsoft 365 or Office 365
- Perform a Google Workspace (formerly G Suite) migration to Microsoft 365 or Office 365
To create a large mailbox migration batch, you need to use New-MigrationBatch
with -XMLData
parameter.
Example:
New-MigrationBatch -SourceEndpoint MigEndpoint -Name LAO\_User1 -CSVData $([System.IO.File]::ReadAllBytes(".\user1.csv")) -XMLData $([System.IO.File]::ReadAllBytes(".\user1mapping.xml")) -TargetDeliveryDomain "contoso.onmicrosoft.com" -AutoStart
After the batch creation, you can check the status of the batch by using Get-MigrationBatch
or check the status of the user by using Get-MigrationUser
.
Example:
powershell Get-MigrationUser -EmailAddress \<email\>