For the purposes of this guide, we are using ‘itadon’ as the Google Workspace admin account for the example domain, and the source and target email accounts ‘itadon’ and ‘info’, respectively. This process was documented on Windows.
This guide was derived from GYB’s official documentation on their wiki.
(https://github.com/GAM-team/got-your-back/wiki)
The steps in this guide were established in mid-2023, but we feel the steps outlined below still have value if you are new to the GCP (Google Cloud Platform) or the GYB (Got Your Back) open source tool. Leave us comments to help us keep this guide up to date
Installing GYB Locally and Associating GYB with Google Workspace Via Google Cloud Console:
1. Go to the GYB GitHub page: https://github.com/GAM-team/got-your-back
If on Windows, download the most recent MSI and install it. The default installation directory is ‘C:\GYB\”. Keep it this way.
2. During installation, a Windows CLI will appear asking you to input an email address. This is the Google Workspace admin email address that will be used to provision GYB in the domain. In this case, I entered ‘user@domain.tld’.
The CLI will present a unique, shortened URL, and it will open a new browser tab to establish a relationship between GYB and the Google account.
Click ‘Allow’.
The browser page will tell you the authentication flow has completed.
Close this tab.
The CLI will proceed to enable the necessary APIs.
3. Copy the link specified in the CLI.
Note: we recommend you conduct the next steps using a single private/incognito window (or another browser). As of the time of this writing, if you are logged in with multiple accounts and the account used during this process is not set as the Google default, selecting “SWITCH ACCOUNT” does not appear to work.
Open a new private/incognito browser window The link will take you to a page to create an OAuth ID. Select ‘Web application’ and name it “GYB Service Account” like so:
Click ‘CREATE’.
4. From the GYB wiki documentation:
The instructions will ask you to supply Client ID and Client Secret without telling you how to find them though, so here’s how:
Once you’ve completed that flow, you will find yourself at the ‘APIs & Services’ Dashboard. Select ‘Credentials’, and ‘+ CREATE CREDENTIAL’. Now you can follow the instructions from GYB’s prompt.
As of the time of this writing, the above appears not to apply, and I am presented with a popup with the vital information required to complete GYB setup.
Use the copy buttons to copy the ‘Client ID’, paste it in the CLI, and press ENTER. Do the same for the ‘Client secret’ when prompted.
5. The CLI will ask “Are you a G Suite admin backing up user mail? [y or n]”. Type “y” and press ENTER.
It will then prompt you to input “… the email address of a regular G Suite user…” This can be any user with standard permissions, but we will use ‘user@domain.tld’ in this example.
The CLI wizard will check that appropriate service account scopes have been established. This will fail.
Copy the unique, shortened URL and paste it into a new tab in the same browser window as the private/incognito window you launched earlier.
As the CLI wizard states, the link takes you to a pre-populated client ID authorization screen like so:
Click ‘AUTHORIZE’.
6. Wait at least five minutes before returning to the CLI and typing ‘y’, ENTER, and entering an account with standard permissions to retry the service account scope check.
If it fails after a few minutes, wait another minute or two and try again. It will eventually succeed like so:
Press any key to continue. The CLI will close and the MSI installation wizard will show that the installation is complete:
7. In your current private/incognito browser session, go to ‘https://console.cloud.google.com/’. Navigate to ‘APIs & Services’, click on ‘Credentials’, click the ‘ADD URI’ button and add a value of ‘http://127.0.0.1:8080/’. Your input should look like this:
Click: “SAVE”
Copying Desired Emails from Source Mailbox to Local Drive:
8. If you haven’t already done so, you should go to the source inbox and label all of the emails you want to restore to the target inbox. You will need this label to isolate the relevant emails and prevent backing up the entire inbox. In this case, I have labeled all the desired emails “Info”.
9. Now we need to run a command to capture the desired emails.
We want GYB to capture all emails with the label ‘Info’ from the source inbox and place them (along with other files containing meta information) into ‘C:\GYB\emails’.
Open CMD, change your directory to ‘c:\gyb’, and enter the following command:
gyb –email it user@domain.tld –search “label:Info” –local-folder “c:\gyb\emails“
You will then be presented with a menu to select the appropriate actions. By default, the selections will be as follows:
Since we do not require any group operations, we will deselect options 5 and 6 by typing in both numbers one at a time and pressing ENTER each time.
We will then select option 0 by typing “0” and pressing ENTER to give GYB the minimum permissions required to accomplish this task. Your menu should now look like this:
Press ‘7’ and ENTER to continue.
9b. If this is the first time running a GYB operation from this instance, the CLI will attempt to launch a new tab in your non-private/incognito window. Close this tab, go back to the CLI, copy the new shortened URL provided, and paste it into a new tab in your current private/incognito browser session.
You will be presented with the following screen:
Click on the relevant account. Click the ‘Allow’ button on the following screen:
The browser page will tell you the authentication flow has completed. Close this tab.
The command will now execute, and our desired emails will be saved to ‘C:\GYB\emails’.
Success looks like this:
Copying Desired Emails from Local Drive to Target Mailbox:
10. Finally, we need to run a command to copy the captured emails from your local drive to the target account’s inbox, in this case ‘info@(your_domain).com’. We are specifying that our command be run with domain-wide delegation via our admin account. We will also label these emails so the mailbox’s owner can easily identify them; “Recovered 2Mar23”.
Run the following command:
gyb –email user@domain.tld –service-account –action restore –local-folder “c:\gyb\emails” –label-restored “Recovered 2Mar23”
The pending operations look like this:
Success looks like this:
11. If you don’t intend to keep the GYB instance alive for future transfers, when finished, carefully remove all traces of GYB in APIs, keys, OAuth instances, etc.
If you need assistance with setting up email transfers in Google Workspace or managing similar configurations, ITAdOn is here to help. Our team can simplify the process and handle all the technical steps for you, ensuring a smooth and secure transfer. Reach out to ITAdOn for expert support with your email and IT needs.
