Recipient Mapping ensures that user information is correctly mapped from the Source tenant to the Destination tenant during mailbox migrations, especially when usernames or domain names change. This article explains how Recipient Mapping works for migrations that use the Microsoft 365 (Graph API) mailbox endpoint.
What Gets Remapped?
| Content Area | Recipient Details Remapped |
|---|---|
| Email messages | Sender and From addresses, plus To, Cc, and Bcc recipients. |
| Calendar items | Organizer and attendee addresses. |
| Folder permissions: Mailbox and Calendar | The trustee, meaning the user, granted access to a shared or delegated folder. |
Why Recipient Mapping Matters?
Recipient Mapping matters because it keeps mail, calendar, and permission data usable after a migration:
- Reply addresses remain usable after migration, including after a Full (Delta) Migration, whether you keep the same domain name or change domains from Source to Destination.
- Calendar ownership and organizer display names appear correctly in the Destination tenant.
- Folder permissions point to the correct Destination user instead of an address that no longer exists.
Important
If you migrate from one Source domain to multiple Destination domains, create a separate project for each Destination domain when you use Recipient Mapping.
Default Mapping Behavior
If you do not add any Recipient Mapping entries, MigrationWiz handles each content area as follows:
- Email addresses and calendar attendees: addresses migrate exactly as they appear at the Source. If a Source address does not exist in the Destination tenant, the migrated item still shows the original Source address.
- Calendar organizers: if the organizer is the mailbox being migrated, MigrationWiz automatically uses that mailbox's Destination address, so you do not need a mapping entry. For any other organizer, MigrationWiz cannot identify the matching user at the Destination, so the item migrates under the Destination mailbox's own identity instead.
- Folder permissions: MigrationWiz first checks whether the grantee's address already exists in the Destination tenant as a primary SMTP address, UPN, or alias. If it does, the permission migrates to that user. If the address cannot be resolved by a mapping entry or by this check, MigrationWiz skips only that permission entry and logs a warning that names the address. The rest of that folder's permissions, and the rest of the migration, continue normally.
Add Recipient Mapping
Add Recipient Mapping under Advanced Options > Support Options in the project.
Important
The boxes with the recipient mapping statements are examples of full address and domain only formats.
Tenant to Tenant Migration (Same Domain Name)
When performing a Tenant to Tenant migration, your recipient mapping should follow this pattern:
RecipientMapping="@sourcetenant.onmicrosoft.com->@destinationdomain.com"
Migrating to a New Domain Name
For example, to migrate user1@sourcedomain.com to user1@destinationdomain.com:
RecipientMapping="@sourcetenant.onmicrosoft.com->@destinationdomain.com"
RecipientMapping="@sourcedomain.com->@destinationdomain.com"
User Prefix Changes
Use this mapping when a user address changes during a merger or when there is a naming conflict at the Destination.
For example, to change user1@sourcedomain.com to user1.new@destinationdomain.com:
RecipientMapping="user1@sourcedomain.com->user1.new@destinationdomain.com"
Order Matters:
Recipient Mapping entries apply from top to bottom in Advanced Options.
The domain only recipient mapping statement should be at the very bottom of your recipient mapping list.
See the example below, the last line is the domain only level recipient mapping needed to be at the bottom of the recipient mapping list.
RecipientMapping="user1@sourcedomain.com->user1.new@destinationdomain.com"
RecipientMapping="user2@sourcedomain.com->user2.new@destinationdomain.com"
RecipientMapping="user3@sourcedomain.com->user3.new@destinationdomain.com"
RecipientMapping="@sourcedomain.com->@destinationdomain.com"
If you have multiple projects for the same migration, such as batches, add the same mappings to every project.
To simplify large mapping lists, import a .txt file of Recipient Mappings using Bulk Load. For exact steps, see the Advanced Options & General Options article.
How Graph Applies Recipient Mapping?
Email and Calendar
Sender, From, To/Cc/Bcc, and calendar organizer and attendee addresses are rewritten according to the RecipientMapping entries.
Example
Whit this mapping in place:
RecipientMapping="@sourcedomain.com->@destinationdomain.com"
an email sent from user1@sourcedomain.com to user2@sourcedomain.com shows as sent from user1@destinationdomain.com to user2@destinationdomain.com after migration. A calendar event organized by user1@sourcedomain.com shows user1@destinationdomain.com as the organizer at the Destination.
Self Migration Fallback
If the mailbox owner you are migrating organized a calendar event, and you have not added a Recipient Mapping entry that covers their address, MigrationWiz still sets that mailbox's own Destination address as the organizer. You do not need a Recipient Mapping entry solely to preserve the organizer identity for the mailbox in the project itself. You still need Recipient Mapping to correctly identify any other organizer or attendee.
Example
When you migrate user1@sourcedomain.com to user1@destinationdomain.com, with no RecipientMapping entries added, a calendar event they organized still shows user1@destinationdomain.com as organizer at the Destination. A meeting organized by user2@sourcedomain.com, who is not part of this project and has no mapping entry, does not resolve to user2@destinationdomain.com. You need an explicit entry, or a domain level mapping that covers their address, for that to work.
RecipientMapping="user2@sourcedomain.com->user2@destinationdomain.com"
Folder Permissions
Folder permission grantees (the users in a shared or delegated folder is shared with) are remapped in the same way. If a grantee address has no explicit RecipientMapping entry, MigrationWiz checks whether that address already resolves to a valid recipient in the Destination tenant, for example because Source and Destination share the same domain, before treating it as unmapped.
Example
Folder permissions on a Source mailbox grant access to user3@sourcedomain.com. If you add the following mapping:
RecipientMapping="@sourcedomain.com->@destinationdomain.com"
that permission migrates to user3@destinationdomain.com. If you have not added a mapping but user3@sourcedomain.com already exists as a valid recipient in the Destination tenant, the permission still migrates correctly to that user.
If neither a mapping entry nor a match in the Destination tenant is found for a grantee, only that permission entry is skipped, and MigrationWiz logs a warning. The rest of that folder's permissions and the rest of the migration continue normally. A single unresolvable grantee does not fail the whole item.
Note
Default and Anonymous permission entries are predefined Exchange access levels, not real mailboxes. MigrationWiz always carries them over as is, and they do not need a mapping entry.
Address Used for Mapping
The Source and Destination address you enter for a mailbox in the project, to tell MigrationWiz which mailbox to connect to, is separate from the address used for Recipient Mapping matching on folder permissions and calendar organizers and attendees. That project level field can be a UPN, an alias, or the primary SMTP address, and does not need to match either.
For folder permission grantees and calendar organizers and attendees, MigrationWiz always compares the grantee's or organizer's primary SMTP address at the Source against the RecipientMapping entries, not the address format the permission was originally granted under. This is the same address type used for mail and calendar remapping in general, so one set of RecipientMapping rules, written using primary SMTP addresses and domains, covers mail, calendar, and folder permissions together.
When no explicit RecipientMapping entry exists, the automatic Destination lookup described above is not limited to an exact primary SMTP match at the Destination. It also matches if that same address string is the Destination account's UPN or any alias or proxy address. Once MigrationWiz finds a match, by any of those, it uses that account's actual primary SMTP address for the migrated permission.
Example
A folder permission on the Source grants access to admin@bittitanmigrationwiztest15.onmicrosoft.com, that user's primary SMTP address at the Source. No RecipientMapping entry covers this address. At the Destination, no account has that exact string as its primary SMTP address, but an account exists whose UPN is exactly admin@bittitanmigrationwiztest15.onmicrosoft.com. The permission still migrates correctly to that account, because the automatic lookup matches UPN as well as primary SMTP or alias. You do not need to add an explicit mapping entry for it.
The primary SMTP address is the property MigrationWiz uses on both sides of the matching process. MigrationWiz compares the Source primary SMTP address against the mapping rules, and writes the Destination primary SMTP address as the final result, whether that address came from an explicit mapping entry or from the automatic lookup. The automatic lookup can succeed through a UPN match or an alias match, not only through a primary SMTP match.
Folder Permissions Requirements
Folder permissions for Microsoft 365 (Graph API) migrations migrate through a separate Exchange Online management connection. For Recipient Mapping to work correctly on folder permissions, make sure the following are in place in the Destination tenant, in addition to the standard Microsoft 365 (Graph API) endpoint permissions:
- The application used for the migration, whether BitTitan's application or your own application when you use Bring Your Own Application, must have the Office 365 Exchange Online > Exchange.ManageAsApp application permission with admin consent granted.
- That same application must be assigned to the Exchange Administrator role, or an equivalent role, in the Destination tenant. This is separate from granting API permission consent and is easy to miss.
If these are not set up, mail and calendar Recipient Mapping still works normally, but folder permission migration and its Recipient Mapping fail for that project.
Use Cases
- Migrating Microsoft 365 to Microsoft 365 while keeping the same domain name.
- Migrating to a new domain name.
- User prefix changes during mergers or naming conflicts.
Notes and Exceptions
- Microsoft Graph does not support Delegate level calendar access. Where the Source grants Delegate level calendar access, MigrationWiz automatically downgrades it to Free/Busy access only at the Destination, and notes this downgrade in the migration report.
- Calendar folders are always handled by Calendar Permissions, never by Mailbox Folder Permissions. If you check Recipient Mapping results for a Calendar folder access grant, look at the Calendar Permissions item type, not Mailbox Folder Permissions.
- Tenant to Tenant Coexistence projects always include Automatic Replies and Mailbox Folder Permissions. You cannot turn off these two item types for that project type. This is part of the standard Coexistence workflow, not something Recipient Mapping affects. On the migration setup screen, you will see both options checked and unavailable to edit.
Migrations Using a High Volume of Recipient Mappings
If the project has 5,000 or more recipient mappings, add the following option to avoid a migration performance impact:
UseHashMapRecipientMapping=1