Share via

Migrate large mailboxes from Google or other IMAP sources to Microsoft 365 Exchange

  • Article

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

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 kick start migrations for large mailboxes.

What do you need to know before you begin?

Before creating the migration, you need to know:

  1. The list of users with large mailboxes (>100 GB) on the source side.
  2. 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.

  1. 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

  2. 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.

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.

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\>