Migrate email with the new data migration service

If there is an error during the CSV upload or the upload gets stuck, you can delete the current configuration and upload a new one.

1. Select the CSV file you want to remove.
2. Click Delete .
3. Click Yes to confirm that you want to delete the CSV file.
4. To upload a new list of source users, go to Step 2: Select users to migrate and follow the instructions for organizations with more than 10 users.

Adjust the following settings to choose which data to copy from Exchange Online.

1. For Data sources, check one or more of the following boxes to migrate data for all your selected users:
   • Email
   • Calendar events
   • Contacts
     Note: A new data migration duplicates any contacts you already migrated. Contact labels are not duplicated.
2. For Date range, select a date to start migrating data. All calendar events and email messages sent or received after this date are copied to Workspace. All contacts are copied regardless of creation date.
3. (Optional) To specify additional email messages and folders, check the following boxes:
   • Include deleted email—Migrate deleted email messages.
   • Include spam email—Migrate email messages in spam folders.
   • Exclude folders for all users in my organization—Exclude messages in specific folders. Enter the excluded folder names, separated by commas. For details, go to Exclude folders from migration.
4. (Optional) To migrate the Exchange Online users' calendars and events, including calendars for personal appointments, select Copy additional calendars. After a migration, these are in Other calendars in Google Calendar.
5. (Optional) For Calendar events for non-migrated users, manually add a list of additional users and resources in a CSV file. This list can include event invitees who aren't part of the migration. For example, you might be planning to migrate some users later. Or, the list could include event guests who are outside of your organization.
   1. Check the Upload a list of email addresses for non-migrated users box.
   2. Open a spreadsheet program.
   3. In the first column, add the header Source Email and add the user's original email address.
   4. In the second column, add the header Destination Email and add the new email address.

      Use a separate row for each user.

      Example:

      Source Email	Destination Email
      kim@example.com	kim@other-company.com
      alex@example.com	alex@other-company.com

   5. Save the spreadsheet as a CSV file.
   6. Click Upload CSV and follow the steps to upload the CSV file.
   7. (Optional) To choose what happens if the service finds additional users during the process, check the If the user's aren't in the list you uploaded, copy their addresses and box and opt to keep the same domain name or choose a different domain name from the list.

      This setting doesn't work for Exchange Online resource calendars. You must use a CSV file to map them to Google Calendar resources.

6. Click Save changes.

Exclude folders from migration

• Separately add each Exchange Online folder or subfolder name.
• If you exclude a folder, the migration doesn’t include its subfolders and any email messages in them.
• To exclude a subfolder, use the full path and separate the parent folder from the subfolder with a forward slash (/). For example:
  • If you want to exclude the subfolder Asia in the folder Travel, enter Travel/Asia.
  • If you also add Travel in the list, such as Travel, Travel/Asia, then all the subfolders are automatically excluded.
• To exclude a folder with a forward slash (/) in its name, replace each slash with an underscore (_). For example, to exclude Folder/with/slash, add it as Folder_with_slash.
• You can also exclude default Microsoft folders, such as Deleted Items, Inbox, or Junk email, and user-created folders.

Migrate additional calendars

When you migrate additional Outlook calendars, such as a calendar for personal appointments, they’re migrated as Other calendars in Google Calendar.

1. Sign in with a super administrator account to the Google Admin console.

   If you aren’t using a super administrator account, you can’t complete these steps.

2. Go to Menu  Data > Data import & export > Data Migration (New).
3. For IMAP, click Migrate.
4. For IMAP server address, enter the address of the IMAP server, for example, imap.example.com.

   For assistance with this information, go to the Connection information for common IMAP-based webmail providers table (later in this section).

5. Click Test connection.

   If the connection is successful, you get a Connected notification.

Connection information for common IMAP-based webmail providers

If your provider isn't listed here, check your provider's documentation for this information.

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.

The mapping file requires you to enter the user's password from their source account. However, some IMAP servers require the user to create an app password instead. For details on app passwords and whether they are required, consult your IMAP server documentation.

1. Create the mapping file

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

1. In a spreadsheet program, add the following headers:
   • Source ImapUser—The user's email address on the source account
   • Source ImapPassword—The user's password on the source account
   • Target GUser—The user's email address on the target account

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

2. Using valid email addresses, map the users and their passwords under the headers (both addresses are mandatory). Be aware of the following points:
   • You can't map a single source user to more than one target user.
   • Make sure the file contains no more than 100 source users and doesn't exceed 128 MB in size.

     The new data migration service currently supports a maximum of 100 users for IMAP migrations.

3. Save the spreadsheet as a CSV file.

Example:

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 CSV.
2. Go to and select your CSV mapping fileclick Open.
3. Click Tasks to confirm that the mapping file has successfully been uploaded.

   Note: If the CSV file doesn't load successfully, go to the next section, (Optional) 3. Delete a CSV file.

(Optional) 3. Delete a CSV file

If there is an error during the CSV upload or the upload gets stuck, you can delete the current configuration and upload a new one.

1. Select the CSV file you want to remove.
2. Click Delete .
3. Click Yes to confirm that you want to delete the CSV file.
4. To start a new upload, return to the previous section, 2. Upload the file.

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, 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 folders from migration box, and enter the label names, separated by commas.

   For details, go to How to exclude folders from migration (in the next section).

5. Click Save.

How to exclude folders from migration

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

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

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
   • Emails failed–Number of email messages that failed to migrate
3. To export and interpret the reports, go to Understand the new data migration service reports.

To move data that has been added to the source account since the primary migration, run a delta migration. For details, go to Run a delta migration.

1. Sign in with a super administrator account to the Google Admin console.

   If you aren’t using a super administrator account, you can’t complete these steps.

2. Go to Menu  Data > Data import & export > Data Migration (New).
3. For Google Workspace emails, click Migrate.
4. Click Source super admin 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 5. 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 in to 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.

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 a 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).
• 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. You can download a list of users from your Google Admin console. For details, go to Download a list of users.

• Make sure the file contains no more than 1,000 source users and doesn't exceed 128 MB in size.

  The new data migration service currently supports a maximum of 1,000 users for migrations to Google Workspace.

• Save the spreadsheet as a CSV file.

Example:

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 been uploaded.

   Note: If the CSV file doesn't load successfully, go to the next section, (Optional) 3. Delete a CSV file.

(Optional) 3. Delete a CSV file

If there is an error during the CSV upload or the upload gets stuck, you can delete the current configuration and upload a new one.

1. Select the CSV file you want to remove.
2. Click Delete .
3. Click Yes to confirm that you want to delete the CSV file.
4. To start a new upload, return to the previous section, 2. Upload the file.

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 (in the next section).

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.

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 export and interpret the reports, go to Understand the new data migration service reports.

To move data that has been added to the source account since the primary migration, start a delta migration. For details, go to Run a delta migration.

• Complete the requirements in About migrating email with the new data migration service.
• If a user is enrolled in the Advanced Protection Program, they must turn off the program before their migration is set up and while the migration is in progress. For details, refer users to How do I turn off Advanced Protection?

You must be signed in as a super administrator for this task. Resellers can't migrate data for their customer accounts.

1. Sign in with a super administrator account to the Google Admin console.

   If you aren’t using a super administrator account, you can’t complete these steps.

2. Go to Menu  Data > Data import & export > Data Migration (New).
3. For Gmail, click Migrate.
4. For Source email address, enter the address of the user’s Gmail account and click Request authorization.

   The owner of the Gmail account receives an email with a request to connect their account. To proceed, they must authorize the request. If you're the owner of the account, you can authorize the request directly from the Admin console.

5. A Pending authorization message appears as the new data migration service automatically checks if the connection request has been authorized. If this message disappears and your request still hasn't been authorized, click Verify connection to continue checking for authorization. 
   One of the following messages is displayed:

   • Pending authorization—Wait for the account owner to authorize the request, then continue the migration process.
   • Connected—The account owner authorized your request.
   • Authorization denied—The account owner rejected your request to connect to their account. You must cancel your current request before sending a new request to connect to the same account or a different one.
   • Request expired—If the account owner doesn't authorize your request to connect to their account within 24 hours, the request expires. Click Refresh request to resend the authorization request.

1. For Target account, enter the email address of the Google Workspace account you want to migrate data to.

   The user of this account must have a Google Workspace license and have the Gmail service turned on. For details, go to About migrating email with the new data migration service.

2. Click Save.

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.

   • If you don't select a start date, by default all messages sent or received for your organization will be migrated starting from Jan. 1, 2000.

2. (Optional) To migrate email messages that have been deleted, 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 a comma.

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

5. Click Save.

How to exclude labels from migration

• Specify each label or sub-label separately.
• When you add a sub-label, use the full path and separate the parent label from the sub-label 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.

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
   • 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
   • Emails failed–Number of email messages that didn't migrate
3. To export and interpret the report, go to Understand email migration reports.

To move data that has been added to the source account since the primary migration, start a delta migration. For details, go to Run a delta migration.