This article will guide you through the steps for migrating mailboxes from Hosted and On-Premises Exchange servers (versions 2007 and later) to Microsoft 365 using Graph API.

We recommend reading through the complete guide before starting the migration to understand the process, timeline, and prerequisites. You will see notes called out throughout the guide; pay attention to these, as they may provide information to avoid migration failure.

MigrationWiz

MigrationWiz is a migration tool, not a syncing tool. If changes are made at the source after migration, they will not sync to the destination, nor will changes made at the destination sync to the source. We do not have “live” monitoring of changes (as with a sync agent) and we cannot handle scenarios such as conflict resolution without user interaction.

Prerequisites

It is important to highlight and meet the following prerequisites for a smooth migration project.

Go through the following steps to determine if this is property is appropriately set:

1. Go to the Microsoft 365 Admin Center of your destination tenant.
2. Select the Mail tab under Active Users for one of your users.
   

If a warning message similar to the one shown below appears when selecting this option, it indicates that the destination mailbox has not been provisioned. Consequently, MigrationWiz will be unable to establish a connection to the mailbox in Exchange Online.

To correctly set up the msExchMailboxGuid property to Null you can follow the steps on the Azure Identity considerations article.

Licensing

We recommend that you purchase User Migration Bundle licenses for this migration scenario. User Migration Bundle licenses allow the performance of multiple migrations with a single license. For questions on licensing, visit Which Migration License Do I Need?.

To use your license by following the next steps:

1. Review Considerations.
2. Purchase Licenses.
3. Create a Customer.
4. Apply Licenses.

Limitations

• Due to Microsoft limitations, using Delegate Permissions with Graph API is not supported at this time. Only Application Permissions can be used.
• Pinned/Flagged Emails are migrated but not Pinned/Flagged in the destination environment.
• The following Rule actions are unsupported by Graph API:
  • Server Reply
  • SMS Alert
  • Play Sound
  • Run Script
  • New Item Alert
  • Flag Message
  • Pin to Top
• Threading (email messages that belong to the same conversation) is not supported and will require Manual implementation. 
• Archive Mailbox as a destination is currently not supported. Support for this option is planned for a future release.

Migrated Items

Please click the bars below to check the migrated and non-migrated items. We are constantly working to create a better migration experience for you so these items may change over time.

Exchange Questions and Troubleshooting

Our Exchange Mailbox FAQ, Exchange Migration Setup and Planning, and Exchange Mailbox Migration Troubleshooting guides contain several common questions and concerns, along with more information, guidance, and steps to resolve issues such as throttling.

Prepare the Source Environment

You must complete the following steps to prepare your Source environment for the migration.

1. Create and configure permissions
2. Confirm access
3. Test mailbox access
4. Disable throttling limits

Detailed instructions can be found in the accordions below.

Preparing the Destination Environment

Modern Authentication Requirements

The steps listed in the Authentication Requirements using Graph API article apply to the destination tenants when using Microsoft 365 with the Microsoft Graph API. A Global Administrator account is required to consent to the BT app or create and consent to the BYO app, since the Entra app's permission types require global admin approval.

Set Up User Accounts

Set up user accounts on the destination Office 365 tenant and assign licenses. These can be created in several ways. (The following links are to external articles.)

• Manually, one at a time.
• By bulk import, via CSV file. 
• By PowerShell script. 

MigrationWiz Steps

Create a Mailbox Migration Project

1. Click Go To My Projects.
2. Click Create Project.
3. Select a Mailbox migration type. Mailbox projects are used to migrate the contents of the primary user mailbox from the previous environment to the new environment. Most mailbox migrations can migrate email, calendars, and contacts.
4. Click Next Step.
5. Enter a Project name and select a Customer.
6. Click Next Step.
7. Select a Source Endpoint from the Endpoint drop-down menu. If an Endpoint has not been created, follow the steps in the section below.
8. Click Save Project.

Endpoints

Endpoints are created through MigrationWiz. If you select an existing endpoint from the dropdown, it will only show ten endpoints. If you have more than ten, you may need to search it.

Consider that endpoint search is case and character-specific. For example, Cust0mer will not show up if the search is customer. We recommend keeping a list of endpoints you have created, along with any unique spellings or capitalization you may have used.

Create your Endpoints

Please review the following tabs to create your destination and source endpoints.

Add Accounts (Items)

Add the accounts that will be migrated, also referred to as items, to a project using one of the following options:

Advanced Options

Advanced Options allow you to choose your notifications, filtering, maintenance, licensing, performance, and some configuration options.

Support Options are advanced configurations that make use of PowerShell or code blocks to provide extra options or resources for your migration.

Support Tab

Consider that each Support Option includes the "=" character and is to be entered under the Support tab in the section named Support Options.

Add additional blank fields for new Support Options by clicking on the "+" button. In case you want to delete a field click the trash can icon.

• InitializationTimeout=8 This increases the initialization timeout window to eight hours. This value is in hours, up to a maximum of 100 hours. Values above 100 are in milliseconds. For example:​
  • InitializationTimeout=2 will increase the timeout to 2 hours.
  • InitializationTimeout=8 will increase the timeout to 8 hours.
  • InitializationTimeout=14400000 will increase the timeout to 4 hours.
  • InitializationTimeout=21600000 will increase the timeout to 6 hours.

Performance Tab

Set Maximum concurrent migrations. To be very safe, we recommend initially setting this to 5. This means that when all mailboxes are selected and the migration begins, only the first five (5) mailboxes in the list will be migrated (using parallel processing), and then when the first of the five (5) completes, the next in the list will begin migrating, and so on down the list, through to completion of all mailboxes. If the Source server has enough server resources, set this parameter based on the bandwidth guideline of three (3) mailboxes per 1Mbps of bandwidth. Therefore, for example, if there is a 10Mbps connection, we recommend that the maximum concurrent migrations parameter be set to 30.

Bulk Load

To upload a large list of Advanced Support options, see the Bulk Load - Advanced Options when Migrating Mailbox projects using Graph API for additional guidance.

Run Migration

The following sections will guide you through setting up and launching your migration. Each header is one step, with its component steps below. Follow these steps in order, and read the notes for important information about dependencies or best practices.

Run Verify Credentials

1. Open the Project containing items you wish to validate.
2. Select the items you wish to validate.
3. Click the Start button in your dashboard.
4. Select Verify Credentials from the drop-down list.
5. Once complete, the results of the verification will be shown in the Status section.

Notify Users

Send out the final notification that the migration is beginning. Include when the migration will start, the expected duration, any usage instructions during migration, and any expected steps or notifications for the post-migration timeline.

If using DeploymentPro, refer to the sample email for some sample text and screenshots that can be included in this email.

Pre-Stage Pass

1. Select the users.
2. Click the Start button from the top, and select Pre-Stage Migration.
3. Under the Migration Scheduling section, from the drop-down list, select 90 days ago.
4. Click Start Migration. 

MX Record Cutover

Change over MX records on the DNS provider's portal. Also, include the AutoDiscover (CName) setting. There are several options for this, based on the size of your project.

Small to Medium Projects

Manually set forwards during a migration on a per-user basis, from the admin portal. Forwards are useful if you are migrating users in batches, and switching some users over to the new Destination before others. Forwards allow for mail coexistence, but not for calendar-free/busy coexistence.

We recommend not saving a copy locally, because when you migrate the mailbox to the destination, you will end up with duplicates.

Large Projects  

If you are migrating in batches and coexistence is required, you will not be cutting over the MX records until your final batch of users has been migrated, and you must perform two extra steps:

Forwards for Coexistence

If you are not cutting over an entire domain/organization at once by changing the MX records, you can perform a phased migration and set up coexistence by setting up forwards on the mailboxes you wish to migrate.

This can be done via one of the following methods.

By PowerShell

Here is how to do this via PowerShell:

Forward the email to the internal recipient and DON'T save a local copy.

PowerShell command syntax:

Set-Mailbox -Identity <Identity> -ForwardingAddress <Office 365 User Email Address> -DeliverToMailboxAndForward $False

• Example: Set-Mailbox -Identity John -ForwardingAddress Suzan@o365info.com -DeliverToMailboxAndForward $False
• Because you set DeliverToMailboxAndForward to false, a copy of the email will NOT be kept in the on-premises mailbox. When setting up forwards, make sure that you do NOT save a local copy before the forward. If you do save a local copy, then when you perform Delta passes, MigrationWiz will migrate the items that it previously hasn’t migrated (and watermarked). This will cause duplicates at your Destination.
• The email address specified on the 'ForwardingAddress' parameter should exist as a Mail Contact.

Through Exchange Management Console

The first step is to create the forwarding objects in your local Active Directory. These forwarding objects will be hidden from the address book and will be used purely to forward mail for mailboxes that are migrated. Note that these objects are created but not used until you set the forwarding, so these steps

The next step is to set up forwarding for mailboxes before migration. Before submitting a mailbox for migration, set the forward by performing the following:

1. Launch the Exchange Management Console from the Start Menu.
2. Expand the Recipient Configuration note from the navigation tree.
3. Click the Mailbox node from the navigation tree.
4. Right-click on the mailbox to set the forward for and click Properties.
5. Click the Mailbox Flow Settings tab.
6. Select Delivery Options and click Properties. Do not select the option "Deliver message to both forwarding address and mailbox". This is important to ensure that Delta passes do not cause duplicates. If you do save a local copy, then when you perform Delta passes, MigrationWiz will migrate the items that it previously hasn't migrated (and watermarked). This will cause duplicates on your Destination.
7. Click the checkbox Forward to, then click Browse.
8. Select the name of the user that contains the prefix (External Forward) in the display name. This is the forwarding object created previously. 
9. Click OK.
10. Click OK.

Setting up Mail Routing on Microsoft 365

For the setup, use PowerShell, because it is faster and easier to set up than working through the Microsoft 365 admin portal. If you need information about how to do this through the Microsoft 365 admin portal, contact Microsoft Support.

1. Connect to Exchange Online PowerShell.
2. Create the Distribution List (DL):
   New-DistributionGroup -Name "BtNotMigratedUsers"
3. Add All Users to this DL.
4. Create the Connector:
   $result = New-OutboundConnector -Name "CBRConnector" -ConnectorType OnPremises -SmartHosts "<fill smart host to source environment>" -UseMXRecord $false -IsTransportRuleScoped $true
   • -SmartHosts entry needs to be set to the URL or IP Address of the Source environment server.
   • On Exchange 2010, this will be the address of the Transport server.
   • On Exchange 2013 and 2016, this will be the address of the Mailbox server, not the Transport server.
   • If the Source environment is Hosted, you would need to obtain this address from the Hosted Provider.
   • If the Source environment is G Suite, you would need to change the -SmartHosts entry to be the following: -SmartHosts “aspmx.l.google.com”
5. Create Rule:
   $result = New-TransportRule -Name "PilotInABoxRule" -SentToMemberOf "BtNotMigratedUsers" -RouteMessageOutboundConnector "CBRConnector"

When a user is fully migrated, remove the user from the DL, and they will receive their email in their own Microsoft 365 mailbox.

• There must be a mail-enabled contact on-premises for each user that has been migrated.

Run Full Pass Migration

1. Select the users – you may either select individual users or select all users in a project by clicking the checkbox to the left of Source Email.
2. Click the Start button from the top.
3. Select Full Migration. If you want to delay your migration, then select the checkbox marked "Automatically start the migration at", and enter the date and time to have the migration start. To start a migration immediately, you do not need to select the scheduling option.
4. Click Start Migration. 

Run Retry Errors

Each error logged represents an item that was not migrated. MigrationWiz contains a mode in which you can resubmit the migration to retry failed items. This mode of operation is always free of charge. You may only submit mailboxes in this mode only if they satisfy all of the following conditions:

1. The last migration was completed successfully.
2. The mailbox contains at least one error.

If your mailbox does not satisfy these conditions, you will receive a warning when submitting the migration in this mode and your request will not be fulfilled.

To submit one or more mailboxes in retry mode, perform the following steps:

1. Click the Go To My Projects button.
2. Select the project that contains the mailboxes that you want to retry.
3. Select the mailboxes that have migration errors.
4. Click the Start button.
5. Select Retry Errors from the menu.
6. Click the Retry Errors button.

When errors are repaired, they will disappear from the error log. Some errors may not disappear if the Source item was not reprocessed (due to filters, for example), has been deleted or moved, or if the item failed again.

Final Steps

Users must create new Outlook profiles, set up their signatures again, and reattach any PST files attached to their previous profile.

Click the bar chart icon in the MigrationWiz dashboard to receive an email containing all the project migration statistics. 

Related Topics

• Authentication Options using Graph API
• Exchange Online Advanced Options using Graph API