Create a control CSV file for user accounts

G Suite Migration for Microsoft Exchange

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

Note: GSMME 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 G Suite 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, gsuite-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 G Suite 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 G Suite 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

Migrating from an Exchange server

If you're migrating from an Exchange server, we recommend you use the same usernames in G Suite 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 G Suite 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 G Suite.

GSMME control CSV file - email and contacts

Migrating from G Suite, 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.

G Suite IMAP migrations

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

Before starting a G Suite IMAP migration, you need to authorize GSMME. For details, go to Authorize GSMME for your account.

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

GSMME control CSV file - G Suite IMAP

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 GSMME tool. Use the following syntax for the control CSV file: user1@cyrus-domain.com, user1@gsuite-domain.com.

GSMME control CSV file - Cyrus IMAP

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 GSMME 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@gsuite-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 (Microsoft 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@gsuite-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 G Suite, Cyrus, Mirapoint, or Exchange, you must include the user's IMAP username, password, and G Suite 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 GSMME tool must be the primary G Suite target domain environment you're migrating users to. If you're migrating mail to a G Suite 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: PST-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 G Suite 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