Share via

Use PowerShell to move mailboxes

You can use PowerShell to move mailboxes, in addition to the Exchange Admin Center (EAC).

Move on-premises mailboxes to an Exchange Online organization

To move an on-premises mailbox to Exchange Online using PowerShell, perform the following steps:

  1. Connect to Exchange Online PowerShell: Start PowerShell as administrator and Connect to Exchange Online PowerShell by running the following command:

    PS C:\> Connect-ExchangeOnline

  2. Find migration endpoint name: Get the name of the migration endpoint you will use by using the Get-MigrationEndpoint cmdlet.

    Get-MigrationEndpoint | Format-List Identity

    The following output appears:

    PS C:\> Get-MigrationEndpoint | Format-List Identity

Identity     : Hybrid Migration Endpoint - EWS (Default Web Site)

  3. Copy the Identity value as you need it in the next part.

  4. Move one or multiple mailboxes to Exchange Online using PowerShell

    • Create a CSV file named Users.csv and place it in the directory C:\migration.

    • Open the CSV file, name the header column EmailAddress, and fill in all the mailboxes that you like to move to Exchange Online.

      Screenshot that shows the CSV on which the details of mailboxes to move are entered.

    • Create and start a migration batch by running the following:

      $OnboardingBatch = New-MigrationBatch -Name YourBatchName -SourceEndpoint "Identity of the Migration Endpoint you want to use" -TargetDeliveryDomain yourOffice365DomainPrefix.mail.onmicrosoft.com -CSVData ([System.IO.File]::ReadAllBytes("C:\temp\CSVForMigrationBatch.csv"))
Start-MigrationBatch -Identity $OnboardingBatch.Identity.Name

  5. Move primary mailbox only to Exchange Online using PowerShell

    There's a scenario wherein the archive mailbox location is in Exchange Online and the primary mailbox location is in Exchange on-premises. On this scenario once the migration batch is created, you will see the user in the batch fail with an error saying you must specify the PrimaryOnly parameter, so we run this instead:

    $OnboardingBatch = New-MigrationBatch -Name YourBatchName -SourceEndpoint "Identity of the Migration Endpoint you want to use" -TargetDeliveryDomain yourOffice365DomainPrefix.mail.onmicrosoft.com -CSVData ([System.IO.File]::ReadAllBytes("C:\temp\CSVForMigrationBatch.csv")) -PrimaryOnly
Start-MigrationBatch -Identity $OnboardingBatch.Identity.Name

  6. Move only archive mailbox to Exchange Online using PowerShell

    $OnboardingBatch = New-MigrationBatch -Name YourBatchName -SourceEndpoint "Identity of the Migration Endpoint you want to use" -TargetDeliveryDomain yourOffice365DomainPrefix.mail.onmicrosoft.com -CSVData ([System.IO.File]::ReadAllBytes("C:\temp\CSVForMigrationBatch.csv")) -ArchiveOnly
Start-MigrationBatch -Identity $OnboardingBatch.Identity.Name

  7. Get mailbox move status

    • Get the status of the mailbox move request by using the Get-MoveRequest cmdlet.

      Get-MoveRequest -Identity "Maisha.Lee@contoso.com" | Get-MoveRequestStatistics

    • Run the following command to get all the mailbox move requests:

      Get-MoveRequest | Get-MoveRequestStatistics

      The output shows the mailbox move status as Completed status, as shown in the following screenshot:

      Screenshot that shows the command that enables the user to get the mailbox move status.

      If that isn't the case and you can't complete the mailbox move request, you can suspend and resume the move request.

Move Exchange Online mailboxes to an on-premises organization

To move an Exchange Online mailbox to the on-premises organization using PowerShell, perform the following steps:

  1. Connect to Exchange Online PowerShell: Start PowerShell as administrator and Connect to Exchange Online PowerShell by running the following command:

    PS C:\> Connect-ExchangeOnline

    Note

    You aren't pulling the Exchange Online mailbox to on-premises. In fact, you are pushing the Exchange Online mailbox to on-premises. That's why you need to connect to Exchange Online and run the commands from Exchange Online PowerShell.

  2. Find migration endpoint name: Get the name of the migration endpoint you will use by using the Get-MigrationEndpoint cmdlet.

    Get-MigrationEndpoint | Format-List Identity

    The following output appears:

    PS C:\> Get-MigrationEndpoint | Format-List Identity

Identity     : Hybrid Migration Endpoint - EWS (Default Web Site)

  3. Copy the Identity value as you need it in the next part.

  4. Move one or multiple mailboxes from Exchange Online to Exchange on-premises using PowerShell

    • Create a CSV file named Users.csv and place it in the directory C:\migration.

    • Open the CSV file, name the header column EmailAddress, and fill in all the mailboxes that you like to move to Exchange Online.

      Screenshot that shows the CSV on which the details of mailboxes to move are entered.

    • Create and start a migration batch by running the following:

      $OffboardingBatch = New-MigrationBatch -Name YourBatchName -TargetEndpoint "Identity of the Migration Endpoint you want to use" -TargetDeliveryDomain YourDomain.com -TargetDatabases @(YourDB1,YourDB2,YourDB3) -CSVData ([System.IO.File]::ReadAllBytes("C:\temp\CSVForMigrationBatch.csv"))
Start-MigrationBatch -Identity $OffboardingBatch.Identity

  5. Move primary mailbox only from Exchange Online to Exchange on-premises using PowerShell

    There's a scenario wherein the archive mailbox location is in Exchange Online and the primary mailbox location is in Exchange on-premises. On this scenario once the migration batch is created, you will see the user in the batch fail with an error saying you must specify the PrimaryOnly parameter, so we run this instead:

      $OffboardingBatch = New-MigrationBatch -Name YourBatchName -TargetEndpoint "Identity of the Migration Endpoint you want to use" -TargetDeliveryDomain YourDomain.com -TargetDatabases @(YourDB1,YourDB2,YourDB3) -CSVData ([System.IO.File]::ReadAllBytes("C:\temp\CSVForMigrationBatch.csv")) -PrimaryOnly
  Start-MigrationBatch -Identity $OffboardingBatch.Identity

  6. Get mailbox move status

    • Get the status of the mailbox move request by using the Get-MoveRequest cmdlet.

      PS C:\> Get-MoveRequest -Identity "Jordy.Twin@contoso.com" | Get-MoveRequestStatistics | ft DisplayName,StatusDetail,TotalMailboxSize,TotalArchiveSize,PercentComplete

DisplayName StatusDetail TotalMailboxSize             TotalArchiveSize PercentComplete
----------- ------------ ----------------             ---------------- ---------------
Jordy Twin  Completed    231.6 MB (242,877,775 bytes) 0 B (0 bytes)                100

      The mailbox move completes. If that isn't the case and you can't complete the mailbox move request, you can suspend and resume the move request.

To implement the next step of removing the completed migrated batches, see Remove completed migration batches.