Domain and email address mapping in CloudM Migrate

Updated August 18, 2026 16:19

When you migrate, addresses appear in far more places than the mailbox itself: calendar attendee lists, file sharing permissions, contact records, group memberships and delegate settings. This article explains how CloudM Migrate decides what to do with each of those addresses, and how to configure it so references survive the move.

CloudM Migrate checks the Domain replacement types settings first, before anything else. If domain replacement is switched off for an item type, addresses in that item type are left completely alone. Your CSV, your user list and your non-matched behaviour are never consulted. Email is off by default, so addresses inside migrated emails are not rewritten unless you deliberately turn it on.

How replacement works

Every address goes through the same sequence. The first rule that resolves the address wins, and processing stops there.

Flow chart of the six replacement steps. Step 1, the item type check, runs first and stops everything if that item type is off. Steps 2, 3 and 5 can each end processing. Steps 4 and 6 both run in the normal case.

Item type check. Is domain replacement switched on for the type of item this address came from? If not, the address is left as it is and nothing below runs. Documents and Drive addresses always pass this check.
Address replacements CSV. If the whole address appears in your CSV, it is replaced with the value you gave and processing stops.
Replace CSV addresses only. If this is on, CloudM Migrate applies any bare domain rows from Review domain names and then stops. Non-matched behaviour is not consulted.
Items to migrate. If Replace usernames is on, the name part of the address is swapped for the destination name from your user list. This only happens for addresses on one of your source domains.
Non-matched behaviour. If this is set to Retain original, processing stops and the address keeps its original form.
Domain swap. The domain part of the address is replaced using Review domain names.

Two points are easy to miss. Step 6 runs even when step 4 has already matched, which is how bob@oldco.com becomes robert@newco.com when your user list only says bob becomes robert. And step 4 deliberately skips addresses that are not on a source domain, so an external attendee or an outside collaborator on a shared file is never rewritten.

Which item types are included

Item type	Default	What it covers
Documents	Always on	File and folder sharing permissions, Drive ACLs. There is no setting for this and it cannot be turned off.
Appointments	On	Organiser and attendee addresses on calendar events.
Contacts	On	Addresses stored on contact records.
Users	On	Delegates, mail forwarding and send-as settings, group membership, Chat and Spaces membership, SharePoint and Microsoft 365 group permissions.
Tasks	On	Addresses on task items.
Email	Off	The To, CC and From addresses inside migrated messages.

Leaving Email off is the right choice for most migrations. Historical mail is a record of what was sent at the time, and rewriting the addresses inside it changes that record. The settings that matter for data integrity, permissions and calendar entries, are on by default.

The settings

Review domain names

Found under Configuration, General. This is your list of source domains and the destination domain each one maps to. The domains from your connection setup are filled in for you.

Review this list before you start. Anything you add here is also treated as a source domain, which affects whether an address is eligible for username replacement at step 4. If you have domain aliases or secondary domains on both platforms, add them.

Replace usernames

Found under Configuration, Advanced. On by default. Lets CloudM Migrate use the Items to migrate list as a mapping table, so a user who is changing address as part of the migration has references to them updated.

Leave this on unless you have a specific reason not to, and test if you turn it off. Switching it off does not disable everything else: your CSV still applies, and so does non-matched behaviour.

Address replacements (CSV)

Found under Configuration, Advanced. An explicit list of source values and what each one should become. This is the highest-priority rule and the only one that can express a mapping the tool could not work out on its own.

We strongly recommend using one for any migration involving permissions, shared content or more than one batch. See Building the address replacements CSV below.

Non-matched address replacement behaviour

Found under Configuration, Advanced. Controls what happens to an address that did not match your CSV and did not match your user list.

Option	Effect
Replace domains (default)	Swap the domain part using Review domain names, keep the name part.
Retain original	Leave the address completely unchanged.

Replace CSV addresses only

Found under Configuration, Advanced. Off by default. Restricts replacement to your CSV, plus bare domain values from Review domain names.

Use it for subset migrations, where you are moving some users out of a domain and the rest are staying put. In that situation a blanket domain swap would be wrong, because addresses belonging to users who are not moving must keep pointing at the original domain.

When this setting is on, non-matched behaviour is never consulted, and the Items to migrate list is not used. Anything you need remapped has to be in the CSV, including your domain mappings.

Choosing your approach

Approach	Use it when	What gets consulted
Defaults, no CSV	Simple whole-domain migration with no address changes and no shared content worth preserving.	Items to migrate, then Review domain names.
Defaults plus a CSV (recommended)	Almost every real migration. Anything with permissions, shared drives, groups or resources.	CSV first, then Items to migrate, then Review domain names.
Replace CSV addresses only	Subset migrations, where most of the source domain is staying behind.	CSV only, plus bare domain rows from Review domain names.

Building the address replacements CSV

File format

Two columns, source value first, replacement second. No header row.

# Users
jane.doe@oldco.com,jane.smith@newco.com
bob@oldco.com,robert@newco.com

# Groups and resources
finance@oldco.com,finance-team@newco.com
boardroom@oldco.com,boardroom@newco.com

# Domain mapping, required if you use Replace CSV addresses only
oldco.com,newco.com

The rules the parser enforces:

No header row. A header line is read as a mapping like any other.
Exactly two comma-separated values per line. Anything else stops the migration with an error naming the line number. Values cannot contain commas.
Lines beginning with # are ignored, so you can comment and group the file.
Duplicate source values stop the migration. If the same address appears twice, the batch fails to start with an error naming the entry and the line. This matters most when several people contribute to one file.
Values are treated as lower case. You cannot use the CSV to give a destination address a particular capitalisation.
Blank values are rejected. Both columns must have content.

What to include

Anything that can be referenced by another item. Not just the people you are migrating.

Users. Everyone being migrated, plus anyone still referenced in permissions or invitations.
Groups. Google Groups, Microsoft 365 Groups including Teams, Microsoft security groups and distribution lists. Security groups and distribution lists cannot be migrated, but include them anyway so permissions referencing them resolve.
Box and Dropbox groups. These have no email address, so map them by group name. A plain name in the first column is valid input, not a workaround.
Resources. Meeting rooms, equipment and anything else with an address that appears on a calendar invitation.
Domains, if you are using Replace CSV addresses only.

Using one master CSV across batches

If your migration is split into batches, build a single master CSV and apply it to every batch. A user in batch three is still named in a calendar invitation and a file permission belonging to batch one, and only the master file lets batch one resolve them.

Nothing in the product checks that every batch has the same CSV, or that a batch has one at all. This is a process you have to hold. What the product does catch is a duplicate entry inside a single file, and that stops the batch rather than warning you.

Worked examples

Take a migration configured with the defaults, plus:

Review domain names: oldco.com maps to newco.com
Address replacements CSV: contains jane.doe@oldco.com,jane.smith@newco.com
Items to migrate: includes a user bob whose destination name is robert

Here is what happens to addresses found on a calendar invitation, which is an item type that has domain replacement on by default.

Address on the invitation	Result	Which step resolved it
`jane.doe@oldco.com`	`jane.smith@newco.com`	Step 2, matched in the CSV
`bob@oldco.com`	`robert@newco.com`	Step 4 gave the name, step 6 gave the domain
`someone@oldco.com`	`someone@newco.com`	Step 6, no earlier match
`partner@external.com`	`partner@external.com`	Not a source domain, so nothing applies
`oldco.com` (a domain-wide permission)	`newco.com`	Step 6, matched as a bare domain

Now take just someone@oldco.com, and change one setting at a time.

Setting changed	Result
Nothing (defaults)	`someone@newco.com`
Non-matched behaviour set to Retain original	`someone@oldco.com`
Replace CSV addresses only switched on	`someone@oldco.com`
Replace usernames switched off	`someone@newco.com`
Domain replacement for Appointments switched off	`someone@oldco.com`

Why Replace CSV addresses only behaves differently

Under normal operation, Review domain names is compared against the domain part of an address. Under Replace CSV addresses only, the same list is compared against the whole address instead. That single difference is why a value that would normally be rewritten is left alone.

The same address compared two ways. With Replace CSV addresses only on, the whole address is compared against the domain list and does not match. With it off, only the domain part is compared and it does match.

Bare domain values still match, because a bare domain is the whole string. This is what keeps domain-wide sharing scopes working. But someone@oldco.com does not, which is why you have to list every address you care about in the CSV when you use this setting.

Mapping global and domain permissions

Shared files can carry permissions that are not addressed to a person, such as a file shared with everyone at a domain, or with anyone holding the link. You can redirect these using the same Address replacements CSV.

This applies to Google Drive source migrations only. It has no effect on any other source platform.

Source value	Matches
`domain`	Shared with everyone at the domain.
`domainWithLink`	Anyone at the domain who has the link.
`anyone`	Shared publicly.
`anyoneWithLink`	Anyone with the link.

Put the scope value in the first column and the target in the second. You can add :user, :group or :domain to the target to state what it is, but this is optional and the target is treated as a group if you leave it out.

domain,my-user@newco.com:user
anyoneWithLink,my-group@newco.com:group

Platform notes

Google Workspace

Google migrations often need very little configuration, because the source domain from your connection setup is registered automatically and the item types that matter are on by default. This is the same mechanism described above, not a separate one, so everything in this article still applies.

Two things are specific to a Google source. Test domain suffixes such as .test-google-a.com are stripped before any replacement runs, if that option is enabled on the connection. And the Google export domain counts as a source domain for the step 4 eligibility check without you adding it to Review domain names.

If you switch on Replace CSV addresses only for a Google migration, add a domain row to your CSV. Without it, domain-wide sharing and all-staff calendar invitations stay pointed at the original domain.

Microsoft 365

Microsoft migrations usually need more explicit mapping. Check that Review domain names covers every source domain and alias, and provide an Address replacements CSV. Permissions and group references are more varied on Microsoft, and the tool cannot infer every one of them.

A related setting: Modify Sent Address

If your destination is Google Workspace, there is a separate setting called Modify Sent Address in the destination platform settings. It is on by default.

When a message carries the Sent label, this rewrites the From header to the destination account address so the Gmail interface shows the sender correctly. It is not part of domain replacement and it is not controlled by the Email item type setting. If you have left Email off and are wondering why the From address on sent mail has changed anyway, this is why.

Related to: