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, or
    • right-clicking anywhere in the mailboxes list and choosing Match target mailboxes option from the drop-down menu.

      However, you first need to select source mailboxes that you want to match from the main program window. You can select mailboxes one by one or use Ctrl+A to include all the source mailboxes listed by the program.

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.

MigratorO365-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.

To start the automatching process, select mailboxes that you want to match and click the Automatch 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.

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.).

Migratory-Automatching det
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 Automach 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 and you want to pair it with

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 user.

For example, let us assume you have the following user:
Name: Oneida Riddle
Old email address: oneida.riddle@a.example
New email address: o.riddle@b.example

A valid CSV entry would be:



You can export a CSV file from your Office 365 or Exchange environment. Instructions are available in this KB article.

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. 10.).

Migrator O365-manual matching
Fig. 10. 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. 11.).

    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. 11. Selecting an existing target user.

  • Manually specify the existing mailbox address – allows you to type in the target email address yourself (Fig. 12.). This option is available only for mailboxes 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. 12. 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.

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 either directly in your Office 365 tenant or allow CodeTwo Office 365 Migration to do it for you.

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

Office 365 Germany

The option to create target users and mailboxes from within the program is not available for Office 365 Germany. We advise administrators migrating to Office 365 Germany to create target users and mailboxes directly in their Office 365 tenant. Instructions how to create users in Office 365 are available on a dedicated Office 365 support page (available in German).

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

  • by clicking Create user settings in the top menu of the Match mailboxes window, or
  • by clicking the Settings button in the Automatch window.

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. 13. 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.


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.

Target users can also be created in the Create new user window (Fig. 14.) 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. 14. 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.

Viewing summary information

The upper part of the matching window (Fig. 15.) 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.

MigratorO365-Summary section
Fig. 15. 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. 16.).

Fig. 16. 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 downward facing 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 HMTL 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.

Was this information useful?