Create a control CSV file for user accounts

Google Workspace Migration for Microsoft Exchange

Before you migrate your data using Google Workspace Migration for Microsoft Exchange (GWMME), create a control comma-separated values (CSV) file to ensure your legacy data correctly maps to your new Google Workspace user accounts.

Note: GWMME uses 2 files: a control CSV file and a mapping CSV file. This article is about creating and using a control CSV file. For details about creating and using a mapping CSV file, go to Create a mapping CSV file.

How to create the control CSV file

  • Create the control CSV file in a spreadsheet program with one entry per line.
  • Headers are not required.
  • Make sure your CSV file is correctly formatted, or the migration won't run successfully.
  • We recommend you make a copy of the final file and save it in a text editor as a CSV file so you can review the syntax for consistency. Some spreadsheet editors add quotation marks to cells, which you need to delete before running the migration. Adding a space after the comma is optional.
  • If you plan to use multiple client machines, you need a separate CSV file for each client. Each CSV file must contain a unique set of users and calendar resources.
  • We recommend you don’t exceed 1,000 users and calendar resources in a single CSV file.
  • Verify whether you also need a mapping CSV file. For details, go to When do I also need a mapping CSV file?

Format of the control CSV file

Migrating email, contacts, and calendars for user accounts

The general structure of the control CSV file is sourceuser, targetuser. If the addresses in your Exchange source domain environment are different from the addresses in your Google Workspace target domain environment, you need 2 addresses per line in the CSV file—the source user address followed by the target user address.

Example: jsmith@solarmora.com, jensmith@solarmora.com

If the the sourceuser is identical to the targetuser, you can exclude the targetuser.

Example: djones@solarmora.com

GSMME control CSV file - email and contacts

Migrating calendar resources

If you're migrating calendar resources as well as users, you need to add the calendar resources to the same control CSV file. The format for adding calendar resources to the control CSV file is source-resource-email, googleworkspace-target-resource-email.

Example: board-room-1@solarmora.com, solarmora.com_37r2903631@resource.calendar.google.com

GSMME control CSV file - email, contacts, and calendar resources

To find the Google Workspace calendar resource email:

  1. Sign in to your Google Admin console.

    Sign in using your administrator account (does not end in @gmail.com).

  2. From the Admin console Home page, go to Appsand thenGoogle Workspace and thenCalendar.
  3. Click Resources.
  4. On the Resources page, click a calendar resource name (for example, NYC-14-12-Boardroom-15) to view its details.

    For more information on calendar resource naming conventions, go to Resource naming recommendations.

  5. Next to Resource email, copy the Google Workspace calendar resource email.

    For example, solarmora.com_37r2903631@resource.calendar.google.com.

Note: When you're migrating calendar resources, you will also need a mapping CSV file. For details, go to Create a mapping CSV file.

Variations on the control CSV file

Open all   |   Close all

Migrating from an Exchange server

If you're migrating from an Exchange server, we recommend you use the same usernames in Google Workspace as you do in your current mail server. You’ll have one name or SMTP address per line in the CSV file. You don't need to enter your users' passwords in the CSV file because authentication is through your Exchange server administrator account.

In the example, the sourceuser djones@solarmora.com is identical to the targetuser, so you can exclude it.

If the addresses in your Exchange source domain environment are different from the addresses in your Google Workspace target domain environment, you need 2 addresses per line in the CSV file—the source user address followed by the target user address.

In the example, the sourceuser jsmith@solarmora.com in Exchange is migrated to the targetuser jensmith@solarmora.com in Google Workspace.

GSMME control CSV file - email and contacts

Migrating from Google Workspace, Cyrus, Mirapoint, or Exchange IMAP servers

Some IMAP servers can migrate data using an administrator's username and password. You don't have to include the password for every user.

Google Workspace IMAP migrations

Note: These instructions apply if you're migrating data from Google Workspace, not personal Gmail accounts (for example, a @gmail.com account).

Before starting a Google Workspace IMAP migration, you need to authorize GWMME. For details, go to Authorize GWMME for your account.

Use the following syntax for the control CSV file: user1@googleworkspace-domain1.com, user1@googleworkspace-domain2.com.

IMAP CSV file

Or, you can use a CSV file that contains users' passwords. For details, go to Migrating from other IMAP servers. If you choose to include the passwords, you must give the source account access to less secure apps before you migrate data.

Cyrus or Mirapoint IMAP migrations

Enter the administrator username and password in step 1 of the GWMME tool. Use the following syntax for the control CSV file: user1@cyrus-domain.com, user1@googleworkspace-domain.com.

Cyrus IMAP CSV file

Ensure the Cyrus administrator account has all access control rights to each user's mailbox. For more information about migrating from Cyrus IMAP servers, go to "Step 1: Special instructions for Cyrus IMAP" in the GWMME Administration Guide.

Exchange IMAP migrations (not regular Exchange migrations)

Use the following syntax for the control CSV file: windowsdomain/exchangeadmin/user@exchange-domain.com#adminpassword, user@googleworkspace-domain.com.

Example: solarmora/admin/jensmith@solarmora.com#VjJ8zTsm, jensmith@solarmora.com

GSMME control CSV file - Exchange IMAP

In this example, the Windows Active Directory domain is solarmora, the administrator username is admin, and the administrator's password is VjJ8zTsm. The administrator is migrating email for the user jensmith@solarmora.com.

Exchange Online (Office 365) IMAP migrations (not regular Exchange migrations)

Use the following syntax for the control CSV file:
admin@exchange-domain.com/user@exchange-domain.com#adminpassword, user@googleworkspace-domain.com.

Example: admin@solarmora.com/jensmith@solarmora.com#VjJ8zTsm, jensmith@solarmora.com

GSMME control CSV file - Exchange Online IMAP

In this example, the Exchange Online administrator username is admin@solarmora.com, and the administrator's password is VjJ8zTsm. The administrator is migrating email for the user jensmith@solarmora.com.

Migrating from other IMAP servers

When you're using an IMAP server other than Google Workspace, Cyrus, Mirapoint, or Exchange, you must include the user's IMAP username, password, and Google Workspace username. The basic format is sourceuser-email#sourceuser-password, destinationuser-email.

Example: jensmith@solarmora.com#fKz47MCb, jensmith@solarmora.com

GSMME control CSV file - Other IMAP

Use the same username the user enters in their IMAP email client to check their email. Some IMAP servers only require a username, whereas other IMAP servers require the full email address (for example, "jensmith@solarmora.com" rather than just "jensmith"). When in doubt, use the full destination email address for the user.

Note: The domain you specify in step 1 of the GWMME tool must be the primary Google Workspace target domain environment you're migrating users to. If you're migrating mail to a Google Workspace account with secondary domains, the target domain you choose might differ from the domain in the email addresses you’re migrating.

Migrating from PST files

If you're migrating data using Personal Storage Table (PST) files, the basic format for the control CSV file is: user-folder-name, destinationuser.

Example: jen-smith-pst-archive, jensmith@solarmora.com

GSMME control CSV file - PST

For details, go to Migrate data from PST files.

When do I also need a mapping CSV file?

In the following situation, you need a mapping CSV file, in addition to a control CSV file, if:

  1. You're migrating calendar data; and
  2. Any addresses for your organization's users in your Exchange source domain environment are different from the addresses in your Google Workspace target domain environment.

    Example: jsmith@solarmora.com, jensmith@solarmora.com

    Note: When migrating calendar resources, source domain and target domain addresses are always different.

  3. When the differing domain addresses are attendees in calendar events in other people's calendars you're migrating. Use the mapping CSV file to list all user accounts and calendar resources—even if some of the users aren’t migrated at this time.

For details, go to Create a mapping CSV file.


Google, Google Workspace, and related marks and logos are trademarks of Google LLC. All other company and product names are trademarks of the companies with which they are associated.
Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue