Microsoft 365 Mail Migration Guide
This guide is aimed at experienced system administrators who are capable of connecting to remote systems and using a variety of administration tools.
Overview
This Microsoft 365 Mail Migration UserGuide shows you how to migrate your mailboxes between Microsoft 365 tenants or to Google Workspace.
Cloudiway uses Exchange Web Services API (EWS) to migrate emails, contacts, and calendars. It uses PowerShell for mailbox permissions, shared mailboxes, rooms, and resources. All network operations are performed over TLS 1.2.
Looking for our Microsoft 365 Migration Solution?
Discover all features, pricing, and use cases for Microsoft 365 cross-tenant migration.
View Solution PagePrerequisites
To perform the Microsoft 365 Mail Migration, you need to configure an Entra ID Application with the appropriate permissions.
Entra ID Application
Cloudiway uses an Entra ID Application with Application Permissions to access Microsoft 365 mailboxes. This authentication method requires:
App Registration
Create an application in Microsoft Entra ID
API Permission
Microsoft 365 Exchange Online → full_access_as_app (Application)
Admin Consent
Granted by a Global Administrator
Certificate Authentication
OAuth 2.0 client credentials flow with certificate
What is Migrated
The following items are migrated during a Microsoft 365 mail migration:
Limitations
The following items are NOT migrated:
- Email signatures
- Out of office messages
- Attachments to calendar events
- Public folders (not supported)
- Task steps and "add to my day"
- Conversation History (Skype history)
- External sharing links
Migration Process
The Microsoft 365 to Microsoft 365 mail migration is a five-step process:
Step 1: Create Connectors
For Cloudiway to migrate your mailboxes, it needs to be able to communicate with both your source and target Microsoft 365 tenants. To do this, Cloudiway uses connectors.
You will need to set up a connector for each source tenant you wish to migrate and each target tenant that mail should be migrated to.
Navigate to Connectors
Click on Connectors > New in the Cloudiway platform.
Select Connector Type
Select Connector Type: Microsoft 365 and set a Connector Name with Mail selected.
Choose Authentication Type
This setting is not used for mail migration. Leave it as default.
Automatic Configuration
The platform automatically retrieves the Tenant Name, the Default Domain Name, and automatically creates an Entra ID application.
Step 2: Configure Global Settings
After setting up source and target connectors, you're ready to configure your global settings.
Convert Email Address
The Convert Email Address option is switched on by default (and is best left on). When activated, this option rewrites email addresses found in:
- Email headers
- Calendar items
- Mailbox permissions
It replaces source email addresses with their corresponding target email addresses in the mapping table.
Save Your Settings
Click on the Save button at the bottom of the screen to update your global settings.
Step 3: Fill User List
The User List contains all mailboxes to be migrated. There are three ways to populate it:
Option 1: Discovery (Get List)
Click on User List > Get List to automatically discover all mailboxes from the source Microsoft 365 tenant.
Then specify the following parameters:
Target Recipient Type
Select Mail as the Target Recipient Type.
Matching Rule
Choose how source emails should be mapped to target emails:
- Mail Exact Match: source email = target email ([email protected] → [email protected])
- Keep Email Prefix Same as Source: only the domain changes ([email protected] → [email protected])
- FirstName.LastName: (e.g., [email protected])
- F.LastName: (e.g., [email protected])
- FLastName: (e.g., [email protected])
- LastNameF: (e.g., [email protected])
Target Domain
Specify the target domain for the migrated users.
Option 2: Import User List
Click on User List > Import to upload a CSV file containing the users to migrate.
Prepare your CSV file
Create a CSV file with the source and target email addresses. For more details on the syntax of the CSV file, read our guide: How to Fill the Users/Groups CSV File
Click on Browse
Click on the BROWSE button to open the file selector.
Select your CSV file
Locate your CSV file on your computer and select it.
Select Connectors
Select the appropriate connectors in the Source and Target fields.
CSV File Format
Option 3: Create Manual Entry
Click on User List > Create to manually add individual users. Enter the source email address and the target email address for each user.
Step 4: Verify Mapping Table
Cloudiway automatically populates this mapping table when source mailboxes are discovered by Get List functionality. However, make sure that the mapping table was populated correctly and that you are not missing any email addresses.
If you make an error in your mapping table, you will have to erase everything and restart the migration with new licenses.
It's important that all users exist in the mapping table before migration begins.
Step 5: Run Migration
Now that you have performed all the pre-migration steps within your tenants and within Cloudiway, you're ready to migrate.
- Verify that the target email address is correct for each user
- Ensure the target account already exists in the target tenant
- Ensure the target account has a valid Microsoft 365 license assigned
Important: Cloudiway does not provision user accounts. All target mailboxes must be created and licensed before starting the migration.
For Individual Users
- Under the Users tab, select all the users you want to submit
- Click on MIGRATION
- Click the Start button
For User Batches
- Under the Batches tab, select the user batch you want to submit
- Click on MIGRATION
- Click the Start button
Migrate Shared Mailboxes
Shared mailboxes can be migrated along with user mailboxes. The platform handles shared mailbox permissions automatically.
Migrate Rooms and Equipment
Room and equipment mailboxes are migrated with their calendar data and booking settings.
Delta Pass
Cloudiway is an incremental migration platform that supports delta passes. For more details, read our complete guide: Delta Pass Mail Migration.
Every time you restart the migration of a mailbox:
- Only items that haven't already been copied to the target will be migrated
- Items that have been modified in the source will be updated in the target
- The platform does not duplicate items, just updates them
How to Start a Delta Pass
To start a delta pass, simply restart the migration and the platform takes care of everything.
Delta Pass Limitations
Cloudiway is a migration platform, not a synchronisation platform. For this reason, we limit the number of delta passes:
- You can submit as many migration passes as you want for 3 months
- Until consuming the amount of GBs allowed by the assigned licenses
- Usually, you only need one pass before the cutover and another after the cutover
Change Propagation
When migrating from Exchange or Microsoft 365, changes after migration are propagated including:
- Mail deletion
- Moving mail from one folder to another
- Mail marked as read
- Deletions from Google are propagated
When migrating from other sources, these changes are not propagated (the respective APIs do not propose a way to detect the changes between two passes).
X500 Aliases Migration
X500 aliases ensure email continuity after migration. The platform can automatically migrate X500 addresses.
Archive Migration
In-Place archives can be migrated separately or along with primary mailboxes. You can also migrate emails to the target archive based on age.
Frequently Asked Questions
How many mailboxes can I migrate concurrently?
A Microsoft 365 account can access up to 100 mailboxes concurrently. Therefore, by default, Cloudiway allows you to migrate 100 concurrent users per connector. To speed up your migration, you can create additional connectors with different migration accounts.
What happens if I make an error in the mapping table?
Any error in the mapping table will cause corruptions and incomplete migrations (loss of metadata, loss of permissions). If you make an error, you cannot simply rerun the migration as the delta pass will only propagate changes. You will need to erase everything and restart the migration with new licenses.
Are email signatures migrated?
No, email signatures are not migrated. All other user settings are retained including folder structure, read/unread status, calendar entries, flags, reminders, notes, contacts, and rules.
Does Cloudiway support delta passes?
Yes, Cloudiway is an incremental migration platform that supports delta passes. Every time you restart the migration, only items that haven't been copied will be migrated, and modified items will be updated. You can submit migration passes for 3 months within your license quota.
Are archives migrated by default?
In-Place archives at the source are treated differently to standard mail and are not migrated by default. You can buy a mail archive quota package to perform an archive migration. Cloudiway supports migration to Microsoft 365 archives to prevent downloading the entire mailbox to Outlook OST files.
Get a free migration quote in minutes — entirely self-service.