Migrate messages to Gmail as client-side encrypted email

To use the migration utility to transfer your messages, export your encrypted messages from Gmail using Google Takeout or Google Workspace Vault. Use the tooling provided by your non-S/MIME encryption vendor to decrypt the mail messages to plaintext.

The Gmail CSE Migration Utility operates over the plaintext messages. When exporting the messages via Google Vault, make sure that your export uses the mbox file format. The PST files generated by Vault contain insufficient information to allow message reinsertion back into Gmail.

For each imported message, the Gmail CSE Migration Utility will add an S/MIME-encrypted copy of the message in addition to the original message. Each user account with Gmail must have sufficient free space to allow for message copies to be inserted.

• Windows 10/11 x86_64
• Linux x86_64
• macOS 12+ x86_64 or M

The Gmail CSE Migration Utility operates over the plaintext messages. Make sure your messages are in one of the following file formats:

• PST
• Mbox

The Gmail CSE Migration Utility does not currently support the MSG file format. For details on the supported formats, refer to the file format documentation.

Before you can use the migration utility to migrate your messages, set up the Gmail API and Gmail CSE for your users. For details, see Gmail only: Upload encryption keys for client-side encryption.

Migration will re-use the Google service account API credential that you used during Gmail CSE setup.

1. Download the Gmail CSE migrator utility to your device.
   • Windows x86_64
   • Linux x86_64
   • macOS universal x86_64 & M

Extract the gmail-cse-migrate utility from the downloaded bundle.

To use the migration utility, enter the following command in a terminal or command prompt. Replace the placeholders with your flags and filenames.

Windows

> gmail-cse-migrate.exe [Optional flags] -api-credential=<filename> -input=<filename>

For example, to migrate email messages from a file named input.pst into Gmail CSE, enter the following command:

> gmail-cse-migrate.exe -api-credential=my-api-credential.json -input=input.pst

Linux, macOS

$ ./gmail-cse-migrate [Optional flags] -api-credential=<filename> -input=<filename>

For example, to migrate email messages from a file named input.pst into Gmail CSE, enter the following command:

$ ./gmail-cse-migrate -api-credential=my-api-credential.json -input=input.pst

Notes:

• Provide following required flags when you run the command:
  -api-credential=<filename> and -input=<filename>
• For detailed information about the functions of the required flags, enter gmail-migrate.exe -help.
• The migration utility can operate on both single input files and directories.
• For an input directory, the migration utility recursively traverses the directory to search for files with the extensions .pst and .mbox.
• You can specify multiple input files and directories in a single execution.

Your Google service account must be granted use of OAuth scope https://www.googleapis.com/auth/gmail.modify when performing the migration.

We strongly recommend performing a dry run of the migration process before adding messages to the Gmail storage. This helps you identify and correct any potential issues that could cause the migration to fail. For example, if you do not have any configured CSE keypairs, some messages may fail to encrypt during the migration. A dry run will help you identify this issue before it causes the migration to fail.

To perform a dry run, use the -dryrun flag. For example, if your Google service account private key is located at c:\my_svc_acct.json2, enter the following command:

gmail-migrate.exe -input user1.pst -input user2.pst -api-credential c:\my_svc_acct.json -dryrun

This example performs a dry run of the migration process on the two input files user1.pst and user2.pst. The dry run verifies the following:

• The messages from the files can be parsed.
• The messages can be encrypted in preparation for migration.

After the dry run, enter the following command to complete the migration.

gmail-migrate.exe -input user1.pst -input user2.pst -api-credential c:\my_svc_acct.json

Note: Your Google service account must be granted the OAuth scope https://www.googleapis.com/auth/gmail.readonly when operating in dry-run mode.

When a message migration is successful, an S/MIME-encrypted copy of the message is inserted into the message owner’s Gmail account alongside the original message encrypted in the non-S/MIME format. The migration utility does not delete the original message.

When inspection of the user account shows that the S/MIME copies are usable by Gmail CSE, then the account owner or the enterprise admin can delete the original messages that were encrypted in the non-S/MIME format. To help you find these messages, the Gmail CSE migration utility will add a custom user label named “Gmail CSE Migration Source Messages” to each original message.

Be careful when deleting messages using the Gmail UI. The default interface aggregates messages into threads or conversations, and deletion of a single message will delete the entire conversation, including unencrypted messages and the inserted CSE message copies. Users should first disable conversation view via the Gmail settings pane so that deletion applies to individual messages rather than threads.

1. To identify the cause of the failure, do the following:
   • Review the log file for error messages.
   • Ensure that the migrator has the necessary permissions to access the PST files and the Gmail account.
   • Verify that the API credentials are valid.
   • Confirm that the PST files are not corrupt or damaged.
2. Make the necessary changes to address the cause of the unsuccessful migration.
3. Re-run the migration command.

Note: The migration utility skips messages that were successfully migrated in the previous attempt.

Migrator flags can be specified using one or two leading hyphens, not slashes. For example, on Windows, you can specify the flag for displaying help information with either of the following:

-help

--help

For flags that accept a string argument, you can specify them with either an equals sign or a space to define the argument. For example, the following flags are equivalent:

-input=filename.pst

-input filename.pst

Help flags

Flag	Description
-version	Prints the version string. If you contact support, provide the version you’re having issues with.
-help	Prints a usage screen of all flags.
-logfile	Specifies the output file where execution logs will be written. If the special text TIMESTAMP is present in the filename, it will be replaced with the execution start time.

Migration flags

Flag	Description
input <directory_or_file>	Required. Specifies the input directory or mail file.
-api-credential <file>	Required. Specifies a JSON file containing the private key to a Google service account delegated domain-wide access.
-dryrun	Optional. Specified to verify that the migrator can process the mail message files and prepare the messages for migration.