Matching mailboxes

For the migration to occur, each source mailbox needs to be paired with a target mailbox. The purpose of the matching process is to create associations between source and target mailboxes.

The matching process takes place in the Match mailboxes window and can be done automatically or manually.

This article covers the following aspects of the matching process:

Selecting source mailboxes to be matched

The Match mailboxes window is where you determine which source mailboxes will be matched to the target ones and based on what matching patterns.

There are two ways to open the Match mailboxes window:

  1. From the migration job wizard by clicking the Match mailboxes button in the Match mailboxes step.

    If you choose this option, all the mailboxes selected in the Source mailboxes step of the wizard will already be listed in the Match mailboxes window.

  2. From the Jobs tab by either:

    • clicking the Match button on the toolbar and selecting either Match all mailboxes or Match selected mailboxes from the drop-down menu, or
    • right-clicking anywhere in the mailboxes list and choosing Match target mailboxes option from the drop-down menu.

      If you do not want to match all listed mailboxes, select the ones that you want matched from the list before opening the Match mailboxes window.

The Match mailboxes window (Fig. 1.) is divided into three parts:

  1. top menu,
  2. the summary section, where you can monitor the matching process. Learn more
  3. mailboxes list.

Main parts of the Match mailboxes window.
Fig. 1. Main parts of the Match mailboxes window.

By default, mailboxes in the Match mailboxes window are listed alphabetically, based on the source email address. To arrange mailboxes by other criteria, click a corresponding column header. For example, to list mailboxes by the user’s last name, click the Last name column header.

Matching mailboxes automatically

We recommend matching as many mailboxes as possible automatically. Use the manual matching option only for those mailboxes that weren’t matched automatically despite several attempts or to match a primary mailbox with an archive mailbox (or vice versa).

To start the automatching process, click Automatch > Automatch all mailboxes or select the mailboxes that you want to match and click the Automatch > Automatch selected mailboxes button. This will open the Automatch window (Fig. 2.).

Migratory-Automatch window
Fig. 2. The default automatching settings.

You can now either:

Matching mailboxes using the default automatch pattern

By default, the program matches mailboxes based on the first and last name or the display name of the source and target users. If these two patterns are not sufficient to pair every mailbox, click the Change button to modify the default settings of the automatch mechanism or click the Browse button to upload a CSV file listing mailboxes that you want to pair. Learn more

If the automatch feature does not find a corresponding mailbox in the target environment, you can set the program to:

  • create a new user together with a mailbox in the target environment, or
  • create a mailbox for existing target user if the program finds a target user without a mailbox.

To enable this option, mark the Create target users/mailboxes if they don’t exist checkbox. If you want to change the default settings concerning the creation of users and mailboxes, click the Settings button.


Be aware that it is impossible to create target users/mailboxes, if your migration method uses a CSV file containing matched source and target mailboxes (e.g. migration from a hosted Exchange server).

The program will only create primary mailboxes. If you need to enable archive mailboxes (In-Place Archives) on your target server, you need to do that manually, as shown in this Knowledge Base article.

Learn more about creating users and mailboxes on the target server

When your configuration is ready, click the Automatch button to run the process. The result will be visible immediately after its completion (Fig. 3.).

Migratory-Automatch summary window
Fig. 3. Example summary after matching mailboxes automatically.

If some of the mailboxes were not matched in the first run, you can check the Automatching details column for more information (Fig. 4.).

Checking the automatching details of a mailbox.
Fig. 4. Checking the automatching details of a mailbox.

If there are many mailboxes left unmatched, change the matching settings and try again. Mailboxes that were matched in the first run will not be unmatched. However, if you make any changes in the mailbox settings after the initial run and you wish to apply these changes also to the mailboxes matched in the previous run, mark the Automatch again mailboxes that are already matched checkbox. When you start the migration jobs, the already matched mailboxes will be unpaired and rematched in accordance with the current settings.

If not all the mailboxes were matched after several runs, match the remaining mailboxes manually.

Modifying the automatch mechanism

To modify the automatch mechanism, click the Change button in the Automatch window (Fig. 3. above). This will open the Automatch pattern window (Fig. 5.) where you can:

Migratory automatch pattern window
Fig. 5. Automatching modification options.

Using patterns

A pattern is a set of conditions that need to be met when comparing a source and a target mailbox information. You can:


You can use several patterns at a time. All patterns are joined by the OR logical relationship. This means that a pair of source and target mailboxes will be matched if at least one of the patterns is applied.

Predefined patterns

The program contains three additional built-in patterns that should be sufficient for most environments. To access them, click Add in the Automatch pattern window (Fig. 5. above) and then choose Predefined pattern. In the Add a predefined pattern window (Fig. 6.), select one of three available patterns and click OK.

Migratory-Add a predefined pattern
Fig. 6. Selecting one of the predefined patterns.

To select more than one built-in pattern, open the Add a predefined pattern window again, select another pattern and click OK.

Custom patterns

If none of the built-in patterns meets your requirements, you can create a pattern of your own. To do so, click Add in the Automatch pattern window (Fig. 5. above) and choose Custom pattern. This will open the Add a custom pattern window (Fig. 7.). Use the top two drop-down menus to select which mailbox fields from the source server (left menu) will be paired to which fields on the target server (right menu). There are several fields to choose from. If you choose Email / Login or Display Name, additional drop-down menus will appear.

Migratory-Add a custom pattern
Fig. 7. Creating a custom pattern.


Let’s assume that you decided to match the source email address to the target email address. You want the program to pair all the source email addresses that follow the {FirstName}.{L} format to target addresses that follow the {F}.{LastName} format. For example, the source email address is [email protected] and you want to pair it with [email protected].

To achieve this result, choose Email / Login from the top Match this source mailbox field drop-down menu. Since the {FirstName}.{L} format is not readily available, in the Email / Login format menu choose Custom (Fig. 7. above).

The Custom Email / Login field format window (Fig. 8.) that opens, allows you to specify your own email address format by typing a string of text or adding placeholders.

Migratory-custom email format2
Fig. 8. Defining a custom source email address format.

Set the target mailbox field accordingly. Your final configuration should look like in the figure below (Fig. 9.).

Migratory-custom pattern example
Fig. 9. Final custom pattern configuration.

Using a CSV file

You can modify the automatch mechanism also by importing a properly formatted CSV file. To import the file, click the Browse button in the Automatch pattern window (Fig. 5. above) and navigate to the CSV file location.

The CSV file must include pairs of source and target mailboxes. Every entry should contain at least the source email and target email fields. Additionally, you can add the first and last name of each source mailbox user.

For example, let us assume you have the following user:
Display Name: Oneida Riddle
Source email address: [email protected]
Target email address: [email protected]
Mailbox Type: Primary

A valid CSV entry created in a text editor (e.g. Notepad) would be:

"[email protected]";"Oneida";"Riddle";"Primary";"[email protected]"


You can export a CSV file from your Office 365 or Exchange environment. Instructions are available in this KB article. Example of an exported CSV file is shown in Fig. 10. Keep in mind that the TARGET EMAIL ADDRESS column has been added manually to the CSV file after the export.

Office 365 Migration - example CSV file
Fig. 10. A CSV file exported from the Exchange admin center.

Further information on importing CSV files to the program is available here.

Matching mailboxes manually

We recommend using the manual matching option if only few source mailboxes were not matched to their target equivalents despite several attempts. To do so, select the row and in the Target user mailbox column right-click the Click to match target link to open a drop-down list with the matching options (Fig. 11.).

Manual matching options.
Fig. 11. Manual matching options.

The following options are available:

  • Create a new user – read more about creating target users in this section.

  • Choose an existing user from the list – this will open the list of all users that already exist in the target environment, even those without an active mailbox (Fig. 12.).

    Be aware that mailboxes belonging to users without a valid Office 365 license will not be active. The program can enable (activate) a mailbox if there are enough unassigned Office 365 licenses. Learn more

Migratory-Match target user window
Fig. 12. Selecting an existing target user.

  • Choose an existing archive mailbox from the list – this will open the list of all archive mailboxes that exist in the target environment.

  • Manually specify the existing mailbox address / Manually enter existing archive mailbox address – allows you to type in the target email address yourself (Fig. 13.). This option is available only for mailboxes (primary or archive) that already exist in the target environment. If you provide an email address of a mailbox that does not yet exist, the program won’t be able to migrate the source mailbox properly. Use this option only as a last resort, when the program cannot list target mailboxes. To check if the email address that you typed in is correct, click the Verify button.

    Migratory-manually specify
    Fig. 13. Entering the target email address.

  • Edit – this option is only available if you cleared the Use default settings box in the Create a new user window. It lets you manually change the details of the target user.
  • Unmatch – this will exclude the source mailbox from the migration process.

Matching public folders

Public folders can be matched by using the automatch mechanism. They are matched independently of user mailboxes, regardless of the selected matching pattern. However, for this to work, public folders must exist in the target environment. Instructions on how to create public folders are available in this article.

To match public folders manually, click the drop-down arrow (Drop-down arrow) in the Target user mailbox column, and then select Choose an existing user from the list, as shown in Fig. 14.

Matching public folders manually.
Fig. 14. Matching public folders manually.

Proceed to choose Public Folders from the list in the Match target user/mailbox window (Fig. 15.).

Selecting target public folders.
Fig. 15. Selecting target public folders.

To learn more about migrating public folders, read this article.

Matching shared mailboxes

Shared mailboxes are matched similarly to user mailboxes but in most cases they require creating a different matching pattern or manual matching. However, to be able to match mailboxes of this type, you must first create shared mailboxes in the target environment. This is demonstrated in this article.

To match a shared mailbox manually, click the drop-down arrow (Drop-down arrow) in the Target user mailbox column, and then select Choose an existing user from the list, as shown in Fig. 16.

Matching a shared mailbox manually.
Fig. 16. Matching a shared mailbox manually.

Proceed to choose the shared mailbox from the list in the Match target user/mailbox window (Fig. 17.).

Selecting target shared mailbox.
Fig. 17. Selecting target shared mailbox.

If the shared mailbox cannot be found on the user list, select Manually specify the mailbox address and enter the shared mailbox address (see Fig. 13.).

You can also use shared mailboxes as targets for migrating your public folders data. This e.g. gives users easier access to data collected in public folders from mobile devices. To learn more, read this article.

Creating target users and mailboxes

For the matching process to succeed, mailboxes must exist in the target environment. You can create them together with corresponding users directly in CodeTwo Office 365 Migration, as shown below.

Note that target public folders need to be created directly in Office 365. Instructions on how to create public folders are available here.


CodeTwo Office 365 Migration can only create target primary mailboxes. If you are migrating archive mailboxes (In-Place Archives), you need to enable them manually on your target server before performing mailbox matching. Find out how to enable an Exchange archive mailbox

Keep also in mind that the option to create target users/mailboxes is not available for the migration methods using a CSV file containing matched source and target mailboxes (e.g. migration from a hosted Exchange server). To successfully complete the matching process, create users/mailboxes in your target environment first (see this article to find your how to do this in bulk), include them in the CSV file, and import the file.

Tip: If you have already created new mailboxes in your target Office 365 tenant, it is possible to hide them from the GAL (e.g. to prevent your users from sending emails to them until the migration is finished). The mailboxes will be still visible in CodeTwo Office 365 Migration and the migration will proceed as usual.

To specify how the program should create target users and mailboxes, open the Create target users/mailboxes settings window (Fig. 18.):

  • by clicking Create user settings in the top menu of the Match mailboxes window, or
  • by clicking the Settings button in the Automatch window (see Fig. 2. above).

The Create target users/mailboxes settings window will also open if you choose the Create a new user option for the first time.

MigratorO365-Create target users
Fig. 18. The Create target users/mailboxes settings window
when migrating from Exchange Server or Office 365.

In the Create target users/mailboxes settings window, you can:

  • change the email address format or the display name format. If the default options suggested by the program do not meet your needs, click the Change button to open a separate window, similar to the one shown in Fig. 8. above. Depending on which Change button you choose, you can specify your SMTP address / user principal name or the display name format. You can type in a string of text or use a range of placeholders.


The primary SMTP email address may include any domain that is registered in your target Office 365 tenant.

  • set the password for your target users. All the newly created target users will receive the same password. The password needs to meet Office 365 requirements.
  • select which AD source attributes you want the program to copy to the target environment (not available when migrating from IMAP). Attributes are migrated when the job is running, not at the configuration stage.

Once you have configured all settings, click OK to save changes. These settings apply only to the current job and only if new users are created by the program (e.g. during the automatching process). 


You need to configure the users/mailboxes settings before you begin matching source and target mailboxes. If you open the Create target users/mailboxes settings window and make additional changes after you have matched the mailboxes (either automatically or manually), these changes will not be applied. You need to match these mailboxes again. 

Target users can also be created in the Create new user window (Fig. 19.) that becomes available under the Create a new user link when the Office 365 password has been set. The window opens with the default data already in place. To manually enter the details of the target user, clear the Use default settings checkbox. To change the default settings, click the Default settings button. This will open the Create target users/mailbox settings window described above.

MigratorO365-Create a target user
Fig. 19. Creating a new user in the target environment.

Note that all the users created manually with custom settings will be marked by Migratory-custom-user-icon  icon on the mailbox list.


If during the migration the program recognizes that a mailbox with identical configuration already exists in the target environment, that mailbox will not be overwritten. Instead, the program will migrate to the existing target mailbox without making any changes to its AD attributes, password, mailbox database, UPN and SMTP address.

Viewing summary information

The upper part of the matching window (Fig. 20.) displays:

  1. the results of the matching process,
  2. a list of actions that will be taken by the program when you start the migration job, and
  3. the number of Office 365 licenses that exist in your target environment.

The summary of the mailbox matching process.
Fig. 20. The summary of the mailbox matching process.

To export this information from the program, you can generate an HTML report.

Mailboxes matching summary

This card of the Match mailboxes window lets you check how many mailboxes were matched, how they were matched (automatically or manually) and how many remain unmatched.

Actions summary

The Match mailboxes window will contain a summary of all actions to be taken by CodeTwo Office 365 Migration when the job starts:

  • Create new user with mailbox and migrate – the program will create a new user in the target environment along with a new mailbox and will also automatically assign an Office 365 license to the newly created user. Target users and mailboxes will be created based on the settings provided in the Create target users/mailboxes settings window or the CSV file
  • Enable mailbox for existing user and migrate – if the program detects that a target user together with the associated mailbox already exists in the target environment, but that mailbox is not active, the program will enable such a mailbox by assigning an Office 365 license to the user. Enabling a mailbox will not result in any changes to the user’s settings: the user's password and other details will remain unchanged.
  • Migrate to existing mailbox – after successfully matching source and target mailboxes (automatically or manually), the program will simply migrate data between them. This will happen if a mailbox already exists in the target environment and is active (which means that the user has a valid Office 365 license). The program will not make any changes to the user or the corresponding mailbox. Migration of that user’s data will start immediately.
  • Don't migrate – the program will ignore any source mailboxes included in the job that were not matched with mailboxes existing on the target server.

To see what action will be performed for a particular mailbox, have a look at the Action column (Fig. 21.).

Fig. 21. Checking what action will be performed
for a mailbox when the migration starts.

Office 365 licenses

The program automatically detects the total number of licenses in your target Office 365 tenant and whether a given target user already has a valid Office 365 license assigned.

You won’t be able to migrate user’s data if a source user or a target user does not have an Office 365 license. If there are any unassigned Office 365 licenses in your target tenant, CodeTwo Office 365 Migration will automatically assign those licenses to users that do not yet have them when you start the migration job. The licenses will be assigned one by one to users on the list.

If there are multiple Office 365 plans in your tenant, such as Office 365 Enterprise E5, Office 365 Business Premium, etc. (plans may be named differently in your country), CodeTwo Office 365 Migration will assign Office 365 plans at random. To change the Office 365 plan that will be assigned to a user, go to the row that corresponds to that user. Click the drop-down arrow (Drop-down arrow) in the Assign Office 365 license column to open the drop-down list where you can change the plan.

Releasing Office 365 licenses

If some Office 365 licenses are assigned to target users who no longer need them, you can release them in the Admin center of your Office 365 tenant. To update the Office 365 licensing information displayed by CodeTwo Office 365 Migration, click the Refresh license info button located in the top menu of the Match Mailboxes window.

HTML Report

The HTML Report button lets you generate an HTML file that contains comprehensive information on the matching process and can be easily shared with others. Learn more

Saving the configuration

To save your current configuration, remember to click the Save button before closing the window. You will be prompted to do so by the program if you try to close the Match mailboxes window without saving your work.

The program will inform you of any changes in the matching process by displaying (modified) in the title bar.

In this article

Was this information useful?