Microsoft Exchange Mailbox Tenant to Tenant Migration Guide
Introduction
The Apps4.Pro Migration Manager guide explains, step by step, how to move different Exchange mailboxes (user, shared, group and in-place archive) from one Microsoft 365 tenant to another Microsoft 365 tenant.
It covers all essential components of Office 365 Exchange Online Mailbox migration, including emails, folders, calendars, contacts, tasks, rules, and attachments, ensuring a seamless transfer without any data loss.
Apps4.Pro Migration Manager also supports migrating emails based on selected date ranges, allowing you to transfer only the emails within the specified timeframe.
Scope of Mailbox Migration
The migrated and non-migrated items are listed below for Office 365 Mailbox Migration.
Limitations
- Migrated calendars will appear as custom calendars instead of under Other Calendars.
- Hidden Mails / Folders: System-generated or hidden folders will not be migrated.
- Calendar Meeting Links: Meeting links will reference the Source Tenant and will not function in the Target Tenant. You will need to manually resend the events for them to work correctly in the Target.
Roles & Licenses for Mailbox Migration
- License: All the users scoped for migration should have valid Microsoft 365 / Office 365 License with “Exchange Online” app enabled in both Source and Target tenant.
- Role: Both the Source and Target connection configuration Accounts can be a normal user and need Admin consent for delegated permissions.
- Subscription: Source or Target tenant should have a Pay-As-You-Go (PAYG) Subscription to create Azure Storage Account.
Admin Consent for Delegated Permissions are required for Apps4.Pro to securely access and migrate data across Microsoft 365 workloads. These permissions facilitate authentication and authorization, ensuring a smooth migration while maintaining data integrity.
Architecture Diagram

Mailbox Inventory Report
Follow the below steps to export the Inventory Report of source tenant personal mailbox and shared mailbox storage size.
Step 1 : Open Windows PowerShell ISE as run as administrator
Step 2 : Download and open the attached script from PowerShell
Script File Link : GetPersonalMailboxStorage.ps1
Step 3 : Update the $mailboxStorageReportPath variable with the local “path to export the mailbox details” in the script.
Step 4 : Execute the script, and once it runs successfully, you will find the csv file saved in the location specified in the $mailboxStorageReportPath variable within the script.
Note:
Ensure the script is executed using an account that holds either the “Exchange Admin” role or the “Global Admin” role for proper permissions.
Sample Output file : PersonalAndSharedMailboxStorageReport.csv
Requirements for Mailbox Migration
Minimum System Requirements
Azure VM with following specifications
- 4 core CPU
- 16 GB RAM
- Windows 10 or above
- Region of VM must be same as Target tenant’s Data Center Location
- Docker latest version installed
Other Requirements
You would also need to prepare the items below to migrate Exchange Online content. The configuration of these items is explained in detail in the following part of the document.
- Create Azure Storage Account: Required to store Migration Data such as Task details, Migration Summary details and Error logs.
- Enable Archive Mailbox and Retention Policy [OPTIONAL]: Required only when Archive Mailboxes are part of your Migration Scope.
- Increase default mail attachment size: Execute PowerShell script to Increase default mail attachment size in Source and Target tenants.
Pre-Migration Setup for Mailbox Migration
1. Create Azure Storage Account and Get Connection String
Note:
The Azure Storage Account must be created with same region as Target tenant’s Data Center Location.
Follow the steps below to create Azure Storage Account
Step 1: Login to Azure Portal using the link below.
Recommended:
You can login either with Source or Target tenant. But make sure it has an active Azure Subscription.
Step 2: Search for “Storage Accounts” and click on it
Step 3: Click on “+ Create” button
Step 4: Fill in the required details as mentioned below, and click “Review + create”
Subscription – Valid subscription that the logged in account has access
Resource group – New dedicated resource group for Exchange migration
Storage Account name – Any unique name
Region – Select Target tenant region
Performance – Standard (Default)
Redundancy – Locally – Redundant Storage (LRS)
Step 5: Click on Create and wait for a few seconds for Deployment.
Step 6: From the left side menu, scroll up and expand “Security + Networking”. Click on “Access Keys”.
Copy the “Connection String” under “key1”. Copy and note this value in a notepad which is required to input in Apps4.Pro Migration Manager after installation.
2. Pre-requisite Setup for Archive Mailbox Migration
Note:
This Step is OPTIONAL. It is required only when Archive Mailbox is part of your Migration Scope.
Enable Archive Mailbox for the Target users
Follow the below steps for all the Scoped Target users for whom Archive Mailbox is part of the Migration scope.
- Go to “Exchange Admin center” in target tenant
- From the left side Menu, navigate to Recipients -> Mailboxes
- Click on specific User Mailbox
- Go to “Others” tab
- Click “Manage mailbox archive” option
- Enable “Mailbox archive status” option
- Click “Save”
Apply retention policy in Target Tenant
You need to apply the retention policy in Target Tenant same as in Source Tenant. Follow the below steps.
Set MRM Retention tags and policies
- Go to Microsoft Purview Compliance Portal using below link https://purview.microsoft.com
- From the left side menu, Click on “Solutions”
- Click on “Data Lifecycle Management”
- Under “Exchange (legacy)” section, Click “MRM Retention tags”.
- Verify if the listed Retention tags and its properties are same as Source Tenant. If not, you need to update it manually.
- Now, click “MRM Retention policies”.
- Verify if the listed Retention Policies and its tags are same as Source Tenant. If not, you need to edit and configure it manually.
Set Retention policy for Target User Mailboxes
Repeat the below steps for all the Target Users in Scope
- Go to Exchange admin center.
- Under “Recipients” section, click on “Mailboxes”.
- Click on specific mailbox, Go to “Mailbox” tab.
- Under “Retention policy”, click “Manage mailbox policies”.
- Set the “Retention policy” value same as Source Mailbox.
3. Increase default mail attachment size in Source and Target tenants
To increase mailbox attachment size for the required users in the Source and Target tenants, follow the below steps.
Step 1: Open Windows PowerShell ISE as ‘Run as administrator’
Step 2: Prepare a CSV containing the mailbox UPN List
Sample CSV Input File Format:

Step 3: Download and open the attached script from PowerShell
Script to increase attachment size limit: IncreaseDefaultAttachmentSize-Exchange.ps1
Note:
In this script, the size is set to the maximum size of 150 MB.
Step 4: Replace the $csvPath value with the CSV file path prepared in Step 2.
Step 5: Run
the script using user with the “Global Admin” or “Exchange Admin” role
Note:
By default, Exchange Online mailboxes have a 36 MB attachment size limit. However, users may have increased this limit to upload larger attachments. You must increase the attachment size limit to the maximum limit.
- On Target mailboxes, to upload attachments exceeding the default size.
- On Source mailboxes, to successfully read attachments exceeding the default size.
4. Sign-in & Setup Process
Contact us at presales@apps4.pro for the tool link and open it in a web browser.
Pre-requisite Configuration
- Install the latest Docker build on the VM.
- Extract the downloaded zip file inside the VM.
- Run Start-mm app.ps1 inside the extracted using PowerShell.
- Choose Exchange workload.
- Select the azure application creation option. (This creates a multi-tenant azure application used for the migration. Permission will be added once the consents are provided)
- Choose Table Storage.
- Once the process is completed you can proceed with the sign-in.
Initial Sign-in Configuration
Login using any of the below options:
- Option 1: Users with existing account can sign-in with their email account and enter the code received in the mail.
- Option 2: First-time users can create a new account by clicking “No account? Create one” link and enter the code received in the mail.
- Option 3: First-time users can also create a new account by clicking “Sign in with Microsoft Work or School Account” link and enter the code received in the mail.
Required Permissions:
| Permission | Justification |
| Sign in and read user profile | Allows you to sign in to the app with your organizational account and let the app read your profile. It also allows the app to read basic company information. |
| Maintain access to data you have given it access to | Allows the app to see and update the data you gave it access to, even when you are not currently using the app. This does not give the app any additional permissions. |
5. Create Organization
- Give a name for your organization.
- Click ‘Create Organization’.
- You can also Invite users to perform the migration.
- Invitees will receive the email where they can access the portal and perform the migration.
6. Source & Target Connection Setup
1. Source Connection
- Navigate to the Tenants tab, then click ‘Add Tenant’ to configure source.
- Sign-in using the Source Service Account.
2. Admin Consent for Source Service Account
- Click on the added Tenant.
- Grant consent for the permissions listed.
- Core.Basic
- Exchange.Basic
Option 1: Grant Consent using the Consent URL (If the Service Account is a normal user with minimum privileges)
- Click on option ‘Copy Consent URL’ to copy the admin consent URL to your clipboard.
- Share the copied URL with the Global Administrator of the Source Tenant, and request them to follow the steps below:
- Open the consent URL in a web browser.
- Sign in using a Global Administrator Account.
- Select the checkbox “Consent on behalf of your organization.” and Accept.
Option 2: Grant Consent from the tool (If the Service Account is a Global Administrator)
If the Service Account is a Global Administrator, you can directly grant consent from the tool by following these steps:
- Click the “Grant Consent” button.
- Sign in using the Global Administrator Account.
- Review the requested permissions.
- Click Accept to grant the required delegated permissions.
3. Login with Service Account
Once the consent in granted, Login once with the Service Account.
4. Target Connection
- Click ‘Add Tenant’ to configure target.
- Sign-in using the Target Service Account.
5. Admin Consent for Target Service Account
- Click on the added Tenant.
- Grant consent for the permissions listed.
- Core.Basic
- Exchange.High
6. Login with Service Account
Once the consent in granted, Login once with the Service Account to get the token ID.
7. Create Project
- Navigate to Projects tab
- Click Create Project
- Enter a Project Name and description
- Choose the Source and Target Tenants
- Select Workloads >> Exchange
- Grant Consent if not granted earlier during account setup
- Review the details and click ‘Finish‘
8. Discover & Map Users
To facilitate the migration of mail collaborators and permissions from the source tenant to the target tenant, it is necessary to map users and Office365 groups accordingly.
Discover Users
Follow the below steps to discover the Source Tenant-level Users.
- Click on the created Project.
- Click Exchange panel.
- Move to the Users tab.
- Use any of the Discover options to list all source users.
- Discover From Selected: Select an user from the listed tenant-level users.
- Discover From CSV: Discover users added in the CSV(Source ID/UPN).
- Discover All: Discover all the users.
Auto-Map Users
Post discovery, auto-map the users with the target users using any of the below options.
Map by
- Display Name
- User Principal Name
(OR)
- Map from CSV
Export Users
In the Users tab, click
>> Export All to export all the discovered and matched users in an excel format.
Sample Tenant-level Users Export Report

9. Discover & Map Groups
To facilitate the migration of mail collaborators and permissions from the source tenant to the target tenant, it is necessary to map Office365 groups accordingly.
Discover Groups
Follow the below steps to discover the Source Tenant-level Groups.
- Move to the Groups tab.
- Use any of the Discover options to list all source groups.
- Discover From Selected: Select a group from the listed tenant-level groups.
- Discover From CSV: Discover users added in the CSV(Source ID/Source Mail).
- Discover All: Discover all the groups.
Auto-Map Groups
Post discovery, auto-map the source groups with the target groups using any of the below options.
Map by
- Group Name
- Mail Nick Name
(OR)
- Map from CSV
Export Groups
In the Groups tab, click
>> Export All to export all the discovered and matched groups in an excel format.
Sample Tenant-level Groups Export Report

10. Discover Mailboxes
Upon completion of user and group discovery, discover all the latest user mailboxes at the Tenant-level.
- Proceed to Mailbox tab.
- Option 1: Discover all matched User Mailboxes
- Select “Discover” drop-down >> Discover All User Mailboxes: Use this option to retrieve all the matched user mailboxes available in the source tenant.
- Option 2: Discover only selected User Mailboxes.
- Discover Selected User Mailboxes: Select this option to discover only the selected user mails.
Discovering Mailboxes pulls the basic details of the Mail, such as Mail name, Mail, Target Account, Mail type – User/Group/Archive.
11. Collect Metrics
Use “Collect Metrics” option to pull additional Mailbox details, including:
- Number of
- Mails
- Calendars
- Contacts
- Tasks
- Rules
- Storage Availability
- Issues
- Source/Target License – Did not find licenses for current user
- File Size exceededUnsupported File
- Unsupported Rule
You can choose to Collect Metrics of all the listed mailboxes or a specific subset, by selecting from the listed mailboxes.
Note:
We recommend running a small pilot migration before moving all Tenant-level mailboxes, to validate your setup and measure throughput.
Once all the above preparatory steps are done, you are ready to create a Migration Task.
Start Mailbox Migration
- Navigate to Mailbox tab.
- Select all Mailboxes Or few of the Mailboxes and click ‘Migrate‘.
- Enter a Workflow Name.
- Click Start Migration.
- The system will now generate a Workflow and start migration.
- From Workflow tab, you can monitor the progress of the workflow.
How to view Migration Task Status
To view the Migration Task Status of Mailbox Migration, follow the below steps:
- Navigate to Summary tab.
- Verify the Migration status of the mailbox.
- Check whether the Migration status is Completed / In Progress / Completed with error.
How to perform Incremental Migration?
The Rerun function enables incremental migration for newly added items in the Source User’s Mailbox after the initial migration.
Steps to Perform Incremental Migration:
- Navigate to the Mailbox tab.
- Select the mailboxes with Completed status that you want to rerun.
- Click Migrate.
- Enter a Workflow Name.
- Verify that the Migrated(Rerun) checkbox is automatically selected. If it is not selected, manually enable it.
- Click ‘Start Migration’ to initiate the rerun process.
- From Summary tab, review migration status of the rerun workflow.
If the columns “FolderErrorCount” & “ItemErrorCount” has a non-zero number of errors, review the errors with the support team before proceeding with the Incremental Migration.
How to Retry a Mailbox Migration?
The Retry function helps resolve errors when a mailbox migration is failed or completed with an error.
Steps to Retry a Task:
- Navigate to Mailbox tab.
- Identify mailboxes with CompletedWithError status.
- Select the Mailbox(s) you want to retry.
- Click ‘Migrate’.
- Enter a Workflow Name.
- Verify that the Failed(retry) checkbox is automatically selected. If it is not selected, manually enable it.
- Click ‘Start Migration’ to initiate the retry process.
- From Summary tab, review migration status of the retried workflow.
Troubleshoot
How to Identify and Export Migration Errors?
To identify the cause of migration errors and retry the failed mailbox migration, follow these steps:
- Navigate to the Summary tab.
- Identify the mailbox with CompletedWithError status.
- Click the dropdown icon next to the affected user’s name to expand the details.
- Click the Export Error option to download the error details.
- Review the exported error report and identify the cause of the migration failure.
- After addressing the issue, navigate to the Mailbox tab.
- Select the mailbox with CompletedWithError status.
- Click Migrate and follow the retry migration steps to restart the migration.
Reports
How to Export the Migration Summary Report?
To export the Migration Summary Report, follow these steps:
- Navigate to the Summary tab.
- Click the three-dot (⋮) menu on the page.
- Select Export All to export the complete migration summary.
Conclusion
In summary, using Apps4.Pro Migration Manager for Exchange Online Mailbox migration ensures a smooth and effective transfer of mailbox data, including emails, folders, calendars, contacts, rules, and tasks. By following the outlined steps, you can confidently migrate Exchange mailbox content between Office 365 tenants. For further assistance or inquiries, refer to our FAQ or contact our support team at support@jijitechnologies.com.



Migrate
Manage







