Notes
- Although present in the UI, BYO App using Client Certificate is currently unavailable. We are working on a resolution for this issue at this time.
- GoDaddy-Hosted Office 365 is currently not supported with the Graph Endpoints at this time.
- Due to Graph API limitations at this time, Archived Mailboxes migrations are not fully supported using the Graph API. If your migration involves Archived Mailboxes, you should use EWS (IMAP Migrations) to perform your migration project until the Graph limitations are resolved by Microsoft and we are able to extend support for this scenario using the Graph API.
This is the complete onboarding task flow for migrating mailboxes from IMAP systems to Microsoft 365 using the Graph API.
This guide includes a folder mapping under the MigrationWiz Steps section, which will ensure that folders are mapped to the root label on the Destination mailboxes, rather than under the inbox/label name.
Important
If your source is POP, refer to the IMAP and POP Migration FAQs for alternate steps to set up your POP endpoint.
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.
MigrationWiz supports the capability to share migration projects across a Workgroup. When the Project Sharing feature is turned on, all Agents besides those who are Inactive can view all migrations projects.
First migration?
We’ve created a guide on scoping, planning, and managing the migration process for your use. If this is your first migration, we recommend reading this guide carefully.
Prerequisites
There are many different versions of IMAP mail systems available. For this reason, we recommend running a trial migration on one or more mailboxes before the actual full migration project. Once the trial migration completes, check on the folder structure at the Destination to ensure that the directory structure is as desired.
To run a trial migration, follow these steps:
- Sign in to your MigrationWiz account.
- Click on your migration project. If you haven't created a project, create a project (following the steps laid out in the Create a Mailbox Migration Project below) and add a user to that project.
- Select the user for whom you wish to perform the trial migration.
- Click on Start.
- From the drop-down list, click on Trial Migration .
- Click on Start Trial Migration.
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:
- Review Considerations.
- Purchase Licenses.
- Create a Customer.
- Apply Licenses.
Licenses are released once payment has been received:
- Licenses are available immediately upon payment if you purchase via credit card.
- If you purchase via wire transfer (100+ licenses), the licenses will be available once payment is received and accepted.
- We do not accept purchase orders because of processing overhead.
In both cases, you will be notified by email that payment has been accepted and licenses are available in your account upon notification.
For more information on licensing, including coupon redemption and other licensing types, see our Which License Do I Need? guide.
Purchase licenses by following the steps below:
- Sign in to your BitTitan account.
- In the top navigation bar, click Purchase.
- Click the Select button and choose User Migration Bundle licenses.
- Enter the number of licenses you want to purchase. Click Buy Now.
- Enter a Billing address if applicable.
- Click Next.
- Review the Order Summary and enter a payment method.
- Click Place Your Order.
Create Customer on MSPComplete by performing these steps:
- Click the Add button in the top navigation bar
- Click the Add Customer button on the All Customers page
- Select the appropriate workgroup in the left navigation pane and click All Customers.
- Click Add Customer.
- Enter the new customer’s information in the Add Customer form. Primary Email Domain and Company Name are required. The rest are optional.
- Click Save.
- Repeat steps 1 through 4 for each customer you want to add.
Perform these steps on MSPComplete:
-
Select the correct workgroup on the top of the left navigation
pane.
Important
This is the workgroup which the customer and migration projects were created under. Your account must be part of the workgroup if the project was not created under your account. - Click Customers on the left navigation pane.
- Click the customer that employs the user to whom you want to use the User Migration Bundle license.
- Click the Users tab at the top of the page.
- Apply the license to the users by checking the box to the left of their emails.
-
Click the Apply User Migration Bundle License
button
at the top of the page.
Tip
We recommend adding users to the Customer page with the vanity domain. Then apply the User Migration Bundle Licenses, before editing to show the .onmicrosoft domain, if the .onmicrosoft domain will be used for the migration. -
Click Confirm if at least one unassigned
User
Migration Bundle license is available for each selected user.
Important
If there are no User Migration Bundle licenses currently available to be assigned and your role in the workgroup is Manager or higher, the form that appears provides all the necessary information and will walk you through the steps of purchasing User Migration Bundle licenses.
Limitations
- Due to API limitations, IMAP migrations will only migrate mail items and we can only migrate mail items that are stored on the IMAP server. Verify that a copy of the mail remains on the server.
- If there is no mail on the IMAP server and it's stored in a local PST, use the PST migration process.
- If the data is stored in a local Outlook OST file (Outlook 2013 and Outlook 2016), export the mailbox to a PST and use the PST migration process.
- Only mail folders are migrated with this scenario. Contacts and Calendar items will need to be exported/imported manually.
- 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.
- Threading (email messages that belong to the same conversation) is not supported and will require Manual implementation.
- Delegate-level calendar access isn't supported by Microsoft Graph. It's automatically downgraded to Free/Busy-only.
- Archive Mailbox as a destination is currently not supported. Support for this option is planned for a future release.
Prepare the Source Environment
Please perform the following steps before starting a migration:
- Test connectivity to the IMAP server through our connectivity test tool. Fill in the form and click the Test button.
- Export the user list to a CSV file.
Besides, consider the following information:
- Administrator accounts with at least read rights can export a user list.
- If you do not have an administrator account, you will need to ask your IMAP host to provide you with a complete user list, in CSV file format.
- This CSV file will be used to bulk-add users into your MigrationWiz mailbox project.
Prepare the Destination Environment
Modern Authentication Requirements
The KBs listed in the Exchange Online Authentication options using Graph API section will help you configure the destination tenant 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.)
MigrationWiz Steps
Create a Mailbox Migration project
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.
- Click the Go to My Projects button.
- Click the Create Project button.
-
Select the Mailbox Project.
Important
For mailbox migrations, use the migration service credentials to access mailboxes. In most migration scenarios, this account must have full access rights to the Source mailboxes.
- Click Next Step.
- Enter a Project name and select a Customer.
- Click Next Step.
- Select endpoints or follow the steps below to create new endpoints.
- Click Save Project.
Endpoints
Service Account Password
Before migrating, ensure that the service account password in the source does not contain any commas. If it does, update the password before starting the migration process.
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.
Create your source endpoint by following the next steps:
- Click Endpoints.
- Click Add Endpoint.
- Select IMAP.
- The server name should follow the format: imap.example.com
- Enter server port. As a general rule, the server port will be either 143 or 993 (if using SSL).
- If you are using SSL, add a checkmark next to Use SSL.
Create your destination endpoint by following the next steps:
- Click New.
- Name the endpoint.
- Select Microsoft 365 Graph API for the endpoint type and Click Add.
- In the Permissions section, Application Permissions are selected by default (Delegated Permissions are not supported at this time).
- Complete the Migration Service Account and the Tenant ID.
- Click Save Project.
- Next, click Save and Go to Summary.
Add Users
Add the user accounts that will be migrated to the project. MigrationWiz allows you to bulk import mailboxes into the system.
Use the Bulk Add option, and import from the CSV file that you prepared under the Prepare the Source section of this guide.
Important
Administrator credentials are not supported for this type of IMAP endpoint
- Request credentials from each user.
- Reset mailboxes to use the same password (this will lock users out).
- Have MigrationWiz automatically request credentials from end users. Click here to learn more.
To request credentials from users:
Enter the Source Email addresses in the Source Email column, and checkmark the I don't know the login name and password for the Source mailbox box (highlighted in blue with the below example). Users will then be requested to provide their credentials during the migration process.
For the destination users, you only need to enter the destination email address of each user as administrator credentials are used (supplied in the destination endpoint setup) for the import to the Exchange Online mailboxes.
Bulk Add
To import one or more mailboxes once you have gathered the necessary credentials:
- Sign in to your MigrationWiz account.
- Select the Project for which you want to perform the bulk import.
- Click on Add.
- Click on Bulk Add.
- Follow the instructions on the page.
Advanced Options
Support Tab
-
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.
- FolderMapping="^INBOX/->" This will map folders to the root label on the Destination mailboxes, rather than under the inbox/label name.
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 Verify Credentials
- Open the Project containing items you wish to validate.
- Select the items you wish to validate.
- Click on the Start button in your dashboard.
- Select Verify Credentials from the drop-down list.
Once complete, the results of the verification will be shown in the Status section.
Notify Users
Notify users that a migration is occurring. Send an email to all users telling them the time and date of the migration.
Run Migration
Pre-Stage pass
- Select the users you wish to migrate.
- Click the Start button from the top.
- Select Pre-Stage Migration.
- Under the Migration Scheduling section, from the drop-down list, select 90 days ago.
- Click Start Migration.
MX Record Cutover
Change over MX records on the DNS provider's portal.
Also, include the AutoDiscover (CName) setting.
- Select the users.
- Click the Start button from the top.
- Select Full Migration.
- Click Start Migration.
Run Retry Errors
Look through the user list and click any red "failed migration" errors. Review the information and act accordingly.
If problems persist, contact Support.
Unexpected Extra Arguments
If errors are listed in the MigrationWiz dashboard with the following error message: "Unexpected extra arguments to Examine Context: FolderNameWithQuote", then follow the steps below to add the support option flag AllowQuoteInFolder=1 at the item level, and run retry errors.
Steps
- Click the Edit Item icon to the right of the item that you wish to edit.
- Under the Support section, enter the support option:
AllowQuoteInFolder=1 - Click Save Item.
- Select the line item in your MigrationWiz dashboard.
- Click Start.
- Retry Errors.
Outlook Configuration
Users must create new Outlook profiles, set up their signatures again, and reattach any PST files that were attached to their previous profile.
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.