We recently started a fun project, doing some mailbox migration. For this project, in particular, we were merging four Exchange organizations together and the new Active Directory was to consist of brand new user accounts. In other words, we’re not moving the accounts themselves but just the mailbox.

The solution was a mixture of what docs.microsoft.com and many of the articles that I had read, so my thinking is that there’s a need for a really explicit article about this process. As always I use PowerShell wherever it’s applicable and we will specifically be looking at how we can migrate mailbox to a forest where the users already exist.

Prerequisite for cross-forest mailbox migration

There are a few things that need to be done before performing a cross-forest mailbox migration. Some are mandatory, others option or just nice to have done.

Run the latest patch of your Exchange server: Whenever I talk to customers about mailbox migration, I ask them to upgrade to the latest cumulative update. In some cases, it’s a necessity but either way, it should be done, just to make sure you don’t end up catching any bugs during the migration.

Have the right permissions: You can migrate mailboxes if you’re part of the Organization Management or the Recipient Management role group. Remember to practice the rule of least privilege.

Enable MRS Proxy endpoint: This is required for any cross-forest mailbox migration or remote move migrations between on-premises and Exchange Online. You could enable this either through EAC or with PowerShell.

If migrating mailboxes to existing users, they have to be mail enabled: So that the mailbox will match up, you have to run Enable-MailUser with the ExternalEmailAddress parameter.

The Exchange organizations should be connected: This one might be obvious, but it’s still worth mentioning. You need to be able to connect to EWS to migrate mailboxes.

Prepare for the mailbox migration

Preparing the mailbox is really a simple step. We utilize a script that comes with Exchange and then update the recipient. The script then copies some vital attributes from the source mailbox user to the target mail user. The following will be copied:

  • msExchMailboxGUID
  • msExchArchiveGUID
  • msExchArchiveName

Supposedly, the script should run the cmdlet Update-Recipient. This is to add the LegacyExchangeDN attribute to the user but this has not yet happened to me. Just in case it doesn’t happen, we will do this at the end of the script.

As you will see, we use the UseLocalObject and OverWriteLocalObject to merge the information of the mailbox to our existing user.

# Change directory to the script folder
CD "C:\Program Files\Microsoft\Exchange server\V15\Scripts"

# Add credentials, from both forests
## Remote = Source forest (Where the mailbox resides)
## Local  = Target forest (Where your new user is)

$RemoteCreds = Get-Credential
$LocalCreds = Get-Credential

# Create a splat with all our parameters and switches
$splat = @{
   identity = "[email protected]"
   RemoteForestDomainController = "dc1.old.domain.org"
   RemoteForestCredential = $RemoteCreds
   LocalForestDomainController = "dc1.new.domain.org"
   localForestCredential = $LocalCreds
   UseLocalObject = $True
   OverWriteLocalObject = $true
}

# Run the script, with our splat
.\Prepare-MoveRequest.ps1 @splat

# Make sure that the LegacyExchangeDN is added
Update-Recipient johnny@new.domain.org

PowerShell will let us know that the command is done running and that your mailbox is ready to be migrated.

If you’re migrating more than one mailbox you could either pipe several users or use a CSV. In either case, remember to remove the identity parameter in your splat.

If you’re curious about splatting, feel free to read this short introduction I’ve written.

Start the mailbox migration

We will start off by defining what Exchange-server we are migrating from, and what the new

$splat = @{
   Identity = "[email protected]"
   Remote = $True
   RemoteHostName = "exchange.old.domain.org"
   RemoteCredential = $RemoteCreds
   TargetDeliveryDomain = "new.domain.org"
}

New-MoveRequest @splat

You should now have created a new request that will migrate the users mailbox between forests, from one Exchange organization to another.