Migrating emails from G Suite Legacy to a normal Gmail account with Got Your Back and Google Cloud Platform

Daniel Dantas (@dantasfiles)
10 min readMar 15, 2022

--

← Return to main migration guide

This post describes my experiences migrating emails from G Suite Legacy (x@y.com) to a normal Google account (x.y@gmail.com) using Got Your Back (GYB). Special thanks to the creator of the tool, Jay Lee.
This post was created using GYB version 1.61

Initial Browser Setup

This post assumes you have set up two Chrome profiles, one for x@y.com and one for x.y@gmail.com
The GYB program asks the user to perform authentication actions in browser windows using links it provides to you. Do not click those links directly in the terminal, or they may open in the wrong Chrome profile.
Instead, copy the links and pay close attention which of the two Chrome profiles (x@y.com or x.y@gmail.com) you should paste the links into.

Install GYB and create a GYB project for x.y@gmail.com

  1. Go to the Got Your Back website.
  2. On the Releases page, download and run the latest gyb-[latest-version]-windows-x86_64.msi installer

Once GYB installs, it opens a terminal and starts the project creation process. If it doesn’t start automatically or you quit out, open a terminal in the directory where you installed GYB and run the command:

gyb --action create-project --email x.y@gmail.com

3. Follow the instruction to visit the specified gyb-shortn.jaylee.us/[code] website (in your x.y@gmail.com Chrome profile), and allow GAM Project Creation to access your x.y@gmail.com Google Account

4. The browser window (for your x.y@gmail.com Chrome profile) will display the message The authentication flow has completed. You may close this browser window and return to GAM.
The authentication code should automatically be entered back into the GYB terminal at the Enter verification code or browser URL: prompt

5. If you’ve never used Google Cloud Platform before, follow the directions in the GYB terminal to accept the Terms of Service

6. After you’ve accepted the Terms of Service (or if you’ve accepted them in the past), the project will be created in the Google Cloud

7. The GYB terminal will instruct you to go to the console.cloud.google.com/apis/credentials/oauthclient?project=[your gyb project] website (in your x.y@gmail.com Chrome profile).
Before you can create an OAuth client ID, you must first configure the OAuth consent screen.
On the Create OAuth client ID screen, click Configure Consent Screen

8. On the OAuth consent screen, choose External

9. On the Edit app registration screen, set the App name to GYB, then enter x.y@gmail.com in the User support email and Developer contact information fields

10. On the Scopes screen, just click Save and Continue

11. On the Test users screen, enter all of the accounts you are planning to migrate from (e.g. x@y.com) and all of the accounts you are planning to migrate to (e.g. x.y@gmail.com), and click Save and Continue
So if you have 4 users in your custom domain, you should have 8 (4 G Suite Legacy + 4 normal Google) accounts listed as Test users.

12. You will see the Summary screen

13. Reopen the console.cloud.google.com/apis/credentials/oauthclient?project=[your gyb project] website (in your x.y@gmail.com Chrome profile) listed in the GYB terminal.
Now that you’ve configured the OAuth consent screen, you can create an OAuth client ID.
On the Create OAuth client ID screen, choose Desktop app as the Application type and GYB as the Name, and click Create

14. On the OAuth client created screen, copy Your Client ID and Your Client Secret
Note: You will need this Client ID later in the process as well

15. Enter Your Client ID and Your Client secret from the OAuth client created screen into the GYB terminal.
Remember to save the client ID for the next section.

Add GYB as a trusted app to your y.com domain

  1. Open Google Admin with your y.com administrator account logged in.
    (Depending on how you initially set up your custom domain, this may be one of your users, or a separate account from your normal users.)
  2. Click Security Access and data controlAPI controls.
  3. On the API controls screen, click Manage Third-Party App Access

4. On the App Access Control screen, click Add appOAuth App Name Or Client ID

5. On the Search an App screen, enter the Client ID of the GYB OAuth client that you recorded in the previous section and click Search. Mouse over the GYB app and click Select

6. On the Select OAuth client IDs screen, select the Client ID from before and click Select

7. On the Configure an app screen, Select Trusted and click Configure

If you don’t do the above steps, you’ll get an Authorization Error in the next section:

The preceding sections were one-time setup.
The following sections migrate the data and are what you need to repeat for each account to be migrated.

Connect GYB to your x@y.com account

  1. Open a terminal in the directory where you installed GYB and enter:
gyb --email x@y.com --action estimate

to connect GYB to your x@y.com account

2. Type 7 to continue

You may be able to get away with less permissions, but I haven’t tested anything but the defaults.

3. Follow the instruction to visit the specified gyb-shortn.jaylee.us/[code] website (in your x@y.com Chrome profile), re-sign into your x@y.com account, and allow GAM Project Creation to access your x@y.com Google Account

4. The browser window will display The authentication flow has completed. You may close this browser window and return to GAM.
The authentication code should automatically be entered back into the GYB terminal at the Enter verification code or browser URL: prompt

Once GYB has been linked to your x@y.com account, it will perform the estimate command and tell you how many messages you have in the x@y.com account

Set up email forwarding

If you don’t set up email forwarding from x@y.com to x.y@gmail.com before you backup the emails of x@y.com, you’ll lose any email that comes in to x@y.com after the backup. This is a temporary action — eventually, you’ll set up an external email host for x@y.com and connect x.y@gmail.com to it (which isn’t covered in this post).

  1. Go to GMail on your x@y.com account
  2. Click ⚙️→ See all settingsForwarding and POP/IMAP

3. Click Add a forwarding address

4. On the Add a forwarding address screen, enter x.y@gmail.com and click Next

5. On the Confirm forwarding address screen, click Proceed, then Ok on the next screen

6. Go to GMail on your x.y@gmail.com account and look for an email with a subject Forwarding Confirmation — Receive Mail from x@y.com
It will have a 9 digit confirmation code.

7. Go back to GMail on your x@y.com account, and enter the 9 digit confirmation code into the Verify x.y@gmail.com box and click Verify

8. Select Forward a copy of incoming mail to x.y@gmail.com and keep Mail’s copy in the Inbox

Your incoming email will now be forwarded from x@y.com to x.y@gmail.com.
Do the next section’s backup as soon as possible to avoid having to deal with many duplicate emails.

Backup the emails of x@y.com

Moving the emails from the backup file (that you are about to create) into your x.y@gmail.com account will take hours and hours in an upcoming step, so any time that you expend now (before you backup) on deleting old emails (e.g. long-expired promotional emails) will save you a lot of time later.

  1. Go to the directory where you installed GYB and type
gyb --email x@y.com

to start the backup. The backed-up emails will be placed into the GYB-GMail-Backup-x@y.com directory

Connect GYB to your x.y@gmail.com account

  1. Go to the directory where you installed GYB and type
gyb --email x.y@gmail.com --action estimate

to connect GYB to your x.y@gmail.com account

2. Type 7 to continue

You may be able to get away with less permissions, but I haven’t tested anything but the defaults.

3. Follow the instruction to visit the specified gyb-shortn.jaylee.us/[code] website (in your x.y@gmail.com Chrome profile), and re-sign into your x.y@gmail.com account.

4. On the Google hasn’t verified this app screen, click Continue

5. Check all the boxes and click Continue to allow GAM Project Creation to access your x.y@gmail.com Google Account.

Again, you may be able to get away with enabling less permissions here, but I haven’t tested it.

4. The browser window will display The authentication flow has completed. You may close this browser window and return to GAM.
The authentication code should automatically be entered back into the GYB terminal at the Enter verification code or browser URL: prompt

Once GYB has been linked to your x.y@gmail.com account, it will perform the estimate command and tell you how many messages you have in the x.y@gmail.com account. Since this is likely a relatively new account, there won’t be much in there.

Migrate the emails to x.y@y.com

  1. Go to the directory where you installed GYB and type
gyb --email x.y@gmail.com --action restore --local-folder GYB-GMail-Backup-x@y.com

to upload the emails in the GYB-GMail-Backup-x@y.com directory to your x.y@gmail.com account.

I found adding the --cleanup option to the above command was useful as it cleans broken emails. However, it’s more fragile than running GYB without the --cleanup option, so you may need to babysit the process more.
If --cleanup breaks on an email, restart the command without the cleanup option to bypass the problem. Let it run on its usual batch of 15 emails, then hit ctrl-c and restart the command with the --cleanup option for the remaining emails.
Or just don’t use --cleanup at all and accept that a few emails are going to remain broken.

Due to API limits, this process will likely take a very long time.

2. Move any emails in x.y@gmail.com that ended up in the Spam folder back into your Inbox
The easiest way I found to do this is to change the GMail settings to have 100 emails on page at a time, then select a hundred at a time and click Not Spam

I found that about 15% of my migrated emails ended up in the Spam folder

Migrate your remaining accounts

Follow the procedure above (connect the x@y.com and x.y@gmail.com account to GYB, download email from x@y.com, and upload email to x.y@gmail.com) for each of your accounts to be migrated. Note that you do not have to perform the one-time setup work (like OAuth setup and Managing 3rd Party Apps) again for your additional accounts.

If you receive an error, it’s probably because you forgot to include an account (either x@y.com or x.y@gmail.com) in your list of Test users

  1. Return to Google Cloud Console for the x.y@gmail.com account that you originally used to set up the GYB project
  2. Click APIs & Services OAuth consent screen
  3. Make sure your accounts are correctly listed in the Test users section and add them if necessary

(Optional) Remove the GYB project from the Google Cloud Platform

  1. Return to Google Cloud Console for the x.y@gmail.com account that you originally used to set up the GYB project
  2. Make sure the Got Your Back project is selected

3. In the top bar, click Project settings

4. On the Settings screen, Click 🗑️ Shut Down

5. On the Shut down project screen, copy-paste the project ID into the Project ID field, and click Shut Down

← Return to the main migration guide

--

--

Daniel Dantas (@dantasfiles)

I create guides to help me fully understand the issues that I’m encountering and fixing. Web: dantasfiles.com Email: daniel@dantasfiles.com