Migrate email with the new data migration service

The new data migration service is currently in public beta and is subject to the "Pre-general availability offerings terms" section of the Google Workspace Service-Specific Terms.

If you're migrating from a Google Workspace account, you can migrate your users' email data to Google Workspace using the new data migration service.

Except where indicated, perform the following steps in the Google Admin console of your target Google Workspace account (the account you're migrating to).

Run a migration

You must be signed in as a super administrator for this task.

Expand section  |  Collapse all & go to top

Step 1: Request authorization

1. Sign in to your Google Admin console.

   Sign in using an account with super administrator privileges (does not end in @gmail.com).

2. In the Admin console, go to Menu  AccountData migration.
3. At the top, click Go to Data Migration (New).
4. Click Source email address and enter the email address of a super administrator on the source account (the account where you are migrating from).

   Important: Only the admin you specify in this field can authorize the process.

5. Click Request authorization.

   An authorization request is sent in an email to the super admin specified in step 4. The request expires in 24 hours. If the request expires and you want to resend it, click Resend request. You must wait 24 hours after you send a request before you can resend it.

Next steps

To proceed, the super admin of the source account must open the authorization link in the email, sign into their Admin console and click Authorize. The authorization process also generates a client ID and grants domain-wide delegation for Data Migration (New) in the source account. For more information, go to Control API access with domain-wide delegation.

If you click Verify authorization in the Admin console of the target account, the status changes to Connected.

Step 2: Create & upload a migration map

You use a migration map to connect users on the source account to users on the target account. The new data migration service uses the migration map to transfer email data from the source user to the target user.

1. Create the mapping file

Tip: Click Download sample CSV to get an example comma-separated values (CSV) file that you can use.

In a spreadsheet program:

• Add the first header, Source GUser (for users' email addresses on the source account), then the second header, Target GUser (for users' email addresses on the target account).

  You can download a list of users from your Google Admin console. For details, go to Download a list of users.

• Using valid email addresses, map the users under the headers (both addresses are mandatory).

  You can't map a single source user to more than one target user.

• Make sure the file doesn't have more than 100 source users.

  The new data migration service supports only up to 100 users at this time.

• Save the spreadsheet as a CSV file.

Example:

Source GUser	Target GUser
[e-mail]	[e-mail]
[e-mail]	[e-mail]

In this example, the source domain is example.com. The target domain is solarmora.com.

2. Upload the file

1. In the Admin console of your target account, click Upload migration map CSV.
2. Go to and select your CSV mapping fileclick Open.
3. Click Tasks to confirm that the mapping file has successfully uploaded.
4. If you get an error message, correct your CSV file. Then, repeat steps 1–2 to upload your mapping file.

Step 3: Select the migration settings

1. Click Start date and enter the date that you want messages migrated from.

   The new data migration service migrates messages from the selected date to the date that you start the migration.

2. (Optional) To migrate email messages that have been deleted by users, check the Migrate deleted emails box.
3. (Optional) To migrate email messages with the Spam label, check the Migrate spam emails box.
4. (Optional) If you don't want to migrate messages that have specific labels, check the Exclude specific labels from migration box, and enter the label names, separated by commas.

   For details, go to How to exclude labels from migration (later on this page).

5. Click Save.

How to exclude labels from migration

• Specify each label or sublabel separately.
• When you add a sublabel, use the full path and separate the parent label from the sublabel with a forward slash (/).

  Example: You want to exclude the label Travel and its child label, Asia. To do so, you enter Travel,Travel/Asia.

• If you add All Mail, the new data migration service doesn’t migrate any email messages.

Step 4: Start & view the progress of the migration

You must be signed in as a super administrator for this task.

1. Click Start migration.

   This action also grants domain-wide delegation and creates a client ID for Data Migration (New) in the target account. For more information, go to Control API access with domain-wide delegation.

2. The status changes to In progress and the following information is updated in real time:

   • Discovered tasks–Total number of items (messages, labels, and other tasks) that were migrated, skipped, or failed
   • Warning–Number of items that were migrated, but failed to complete as expected
   • Failed–Number of items that failed to migrate, due to an error
   • Skipped–Number of items that were skipped
   • Successful–Number of items that were migrated successfully
   • Users processed–Number of users whose migration has completed
   • Emails discovered–Number of email messages that were migrated, skipped, or failed
   • Emails migrated–Number of email messages that were migrated
   • Emails skipped–Number of email messages that were skipped
3. To download the reports in CSV format, in your Google Admin console, click Download migration report or Download user report. You can download the reports at any point, once the migration has started.
4. If the Tasks list doesn't open automatically with the downloaded report, click Tasks .
5. For Your Tasks, click the link to open the file.

For information about the reports including details on warnings and errors, go to Understand the new data migration service reports.

Run a delta migration

During a delta migration, the new data migration service migrates newly-added email messages to your target account. It also identifies changes to previously-migrated email messages, such as the message's read status or new labels, and updates the message on the target account.

A delta migration skips over objects that have already been successfully migrated and haven't been updated on the source account. These items are marked as skipped.

To start a delta migration, in the target account, click Run delta migration.

Exit a completed migration

Important: Once you exit a migration, you can no longer access its configuration data or reports.

Information about a completed migration is displayed in the Admin console until you exit the migration. When you exit, the system deletes the client ID and removes Data Migration (New) as a client in the domain-wide delegation setting.

To exit a completed migration, click Exit migration.

Related topic

Check events for the new data migration service