Tenant Migration

How to Bulk Create Exchange Mail Users from CSV | Cross-Tenant Migration

Amos GikundaAmos Gikunda Oct 28, 2026 869 views

Question details

The user needs to bulk create multiple Exchange MailUser objects from a CSV file containing comprehensive migration attributes to prepare for a cross-tenant mailbox migration.

How to Bulk Create Exchange Mail Users from a CSV File
Product
Exchange Online
Device & OS
not provided
Scenario
Preparing directory objects for a cross-tenant mailbox migration using a CSV file with detailed user attributes like ExchangeGuid and LegacyExchangeDN.
Observed behavior
The New-MailUser cmdlet does not accept all necessary migration-related properties in a single command, blocking the complete provisioning of the user object.
Before you start

Ensure you have the Exchange Online PowerShell module installed, hold the necessary administrative privileges in the target tenant, and have your correctly formatted CSV file ready.

Solution 1Recommended

Create and Configure Mail Users using PowerShell Scripts

Use a two-step PowerShell script approach to first create the base user and then append the remaining advanced migration attributes.

Because the New-MailUser cmdlet only supports a subset of properties during initial creation, you must loop through your CSV file to create the base user. Immediately following this, you use Set-MailUser to apply advanced properties like ExchangeGuid, LegacyExchangeDN, and additional EmailAddresses.

1
Prepare your CSV file

Create a CSV file with headers matching your required attributes, such as Name, Alias, UserPrincipalName, PrimarySmtpAddress, ExternalEmailAddress, ExchangeGuid, and LegacyExchangeDN.

2
Connect to Exchange Online

Open PowerShell as an administrator and run the 'Connect-ExchangeOnline' command to authenticate with your target Microsoft 365 tenant.

3
Execute the New-MailUser loop

Import your CSV using the 'Import-Csv' cmdlet and pipe it to a Foreach-Object loop. Inside the loop, run 'New-MailUser' using the basic creation attributes supported by the cmdlet.

4
Apply advanced attributes with Set-MailUser

Immediately after the New-MailUser command within your loop, execute 'Set-MailUser' targeting the newly created user to apply the ExchangeGuid, LegacyExchangeDN, and any additional routing addresses.

Create and Configure Mail Users using PowerShell Scripts
Microsoft Documentation: Refer to Microsoft's official cross-tenant mailbox migration documentation for verified example scripts and specific attribute mappings.
Free Microsoft Office alternative

Manage Your Migration CSV Files with WPS Office

While tenant migrations require Exchange PowerShell execution, managing, editing, and formatting your complex migration CSV files is seamless with WPS Office. As a free and lightweight alternative to Microsoft Office, WPS Spreadsheet provides robust data management tools to prepare your migration batches without heavy subscription fees.

  1. 1. Visit the WPS Office Website: Go to the official WPS website to download the free office suite.
  2. 2. Install the Software: Run the installer and follow the on-screen prompts to set up WPS Office on your computer.
  3. 3. Prepare your CSV: Open your migration CSV file in WPS Spreadsheet to confidently edit your user attributes before running your PowerShell scripts.
Fully compatible with Microsoft Excel formats (.xlsx, .csv) for accurate PowerShell data preparation.Lightweight design ensures instant opening of large migration CSV files containing thousands of user rows.Familiar tabbed interface allows you to easily switch between user lists and PowerShell migration logs.Free to use with built-in tools for data validation, syntax checking, and duplicate removal.
microsoft office alternative - wps office

Frequently Asked Questions

Why doesn't New-MailUser accept the ExchangeGuid property?

The New-MailUser cmdlet is designed strictly for basic mail user provisioning. Advanced migration-specific attributes like ExchangeGuid and LegacyExchangeDN are considered post-creation configurations and must be systematically applied using Set-MailUser.

Can I use WPS Spreadsheet to create my migration CSV file?

Yes, WPS Spreadsheet fully supports creating, editing, and saving CSV (Comma Separated Values) files. You can organize your user attribute headers and export the file in the exact plain-text format required by Exchange Online PowerShell.

Where can I find example scripts for cross-tenant migration?

Microsoft provides detailed example scripts within their official cross-tenant mailbox migration documentation, typically found under the Frequently Asked Questions section. For highly customized scenarios, you can also consult the Microsoft PowerShell community.

What happens if I miss LegacyExchangeDN during the import?

If the LegacyExchangeDN is not migrated and added as an X500 proxy address, internal users replying to old email threads or using cached Outlook autocomplete entries may receive Non-Delivery Reports (NDRs) when emailing the migrated users.