This comprehensive guide walks you through the process of migrating email data between Google Workspace (formerly G Suite) environments using the Gmail API and BitTitan's MigrationWiz solution. MigrationWiz is an industry-leading cloud migration tool that provides a secure and efficient way to migrate your data. The guide covers prerequisites, setup steps, and important considerations for a successful migration.
Overview
The Gmail API migration method using MigrationWiz provides a secure and efficient way to transfer email data between Google Workspace environments. This approach requires proper configuration of both source and destination Google Workspace environments and appropriate API permissions.
Prerequisites
- Admin access to both source and destination Google Workspace environments
- Google Cloud Platform subscription
- Google Super Administrator account
- Service account setup capability on both Google Workspace tenants
- All migrating accounts must be in Active status
Licensing Requirements
We recommend that you purchase User Migration Bundle licenses for this migration scenario. User Migration Bundle licenses allow the performance of multiple migrations with a single license. For questions on licensing, visit MigrationWiz Licenses.
1. Purchase Licenses
- Sign in to your BitTitan account
- In the top navigation bar, click Purchase
- Click the Select button and choose User Migration Bundle licenses
- Enter the number of licenses you want to purchase. Click Buy Now
- Enter a Billing address if applicable
- Click Next
- Review the Order Summary and enter a payment method
- Click Place Your Order
2. Create a Customer
Create Customer on MSPComplete by performing these steps:
- Click the Add button in the top navigation bar
- Click the Add Customer button on the All Customers page
- Select the appropriate workgroup in the left navigation pane and click All Customers
- Click Add Customer
- Enter the new customer's information in the Add Customer form
- Primary Email Domain and Company Name are required
- Other fields are optional
- Click Save
3. Apply Licenses
Perform these steps on MSPComplete:
- Select the correct workgroup on the top of the left navigation pane
Important: This is the workgroup which the customer and migration projects were created under. Your account must be part of the workgroup if the project was not created under your account.
- Click Customers on the left navigation pane
- Click the customer that employs the user to whom you want to use the User Migration Bundle license
- Click the Users tab at the top of the page
- Apply the license to the users by checking the box to the left of their emails
- Click the Apply User Migration Bundle License button at the top of the page
- Click Confirm if at least one unassigned User Migration Bundle license is available for each selected user
License Considerations
Licenses are released once payment has been received:
- Licenses are available immediately upon payment if you purchase via credit card
- If you purchase via wire transfer (100+ licenses), the licenses will be available once payment is received and accepted
- We do not accept purchase orders because of processing overhead
In both cases, you will be notified by email that payment has been accepted and licenses are available in your account upon notification.
For more information on licensing, including coupon redemption and other licensing types, see our Licensing FAQ.
Preparing the Source Environment
Create a Google Project
- Go to the Google Cloud Platform (GCP) Console and sign in as a super administrator
- For new users:
- Agree to the Terms of Service and click Create Project
- For existing users:
- Click the down arrow next to your most recent project name
- Click New Project
- Enter a project name and click Create
- Note: If you cannot create a project, check the Google Admin Center under Apps Additional Google Services Google Cloud Platform to ensure project creation is enabled
Enable Required APIs
- From the Google Cloud Platform Console, navigate to Menu APIs & Services Library
- Enable each of these APIs:
- Google Drive API
- Google Calendar API
- Gmail API
- Contacts API
- People API
- Admin SDK
- Important: Verify that Gmail, Calendar, and Contacts services are enabled within the Google tenant
Create Service Account
- Navigate to Menu API & Services Credentials CREATE CREDENTIALS Service account
- Click Create Service Account and enter a name
- Assign the Owner role to the new Service Account
- Click Continue, then Done
- Generate and download JSON key:
- Click on the service account
- Select ADD KEY Create new key
- Select JSON format
- Click Create and save the file
- Note: The JSON file must contain "type", "private key", and "client email" fields
Configure Service Account Permissions
- Find your Unique ID (Client ID):
- Navigate to Menu API & Services Credentials
- Locate your service account
- Copy the Unique ID number
- Set up API Scopes:
- Go to admin.google.com
- Navigate to Security Access and data control API controls Manage Domain Wide Delegation
- Click Add new
- Paste your Client ID
- Add the following scopes:
https://mail.google.com/, https://www.google.com/m8/feeds, https://www.googleapis.com/auth/contacts.readonly, https://www.googleapis.com/auth/calendar, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/drive, https://sites.google.com/feeds/, https://www.googleapis.com/auth/gmail.settings.sharing, https://www.googleapis.com/auth/gmail.settings.basic, https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/contacts.other.readonly
- Click Authorize
Preparing the Destination Environment
Create Users in Google Workspace
Follow Google's standard user creation process to set up all destination accounts.
Configure Service Account
You can either:
- Use the same service account as the source (recommended), or
- Create a new service account following the same steps as the source setup
If using the same service account, you only need to configure the destination scopes:
- Go to admin.google.com
- Navigate to Security API Controls Manage Domain Wide Delegation
- Add the Client ID and configure the same scopes as listed in the source setup
Creating the Migration Project
- From MigrationWiz dashboard, click Go To My Projects
- Click Create Project
- Select Mailbox migration type
- Enter project name and select Customer
- Configure endpoints:
- Select G Suite (Gmail API) for both source and destination
- Upload the appropriate JSON key file(s)
- Provide administrator email addresses
Add User Accounts
Add accounts using either:
- Quick Add: One account at a time
- Bulk Add: Multiple accounts via CSV file
Running the Migration
- Verify Credentials:
- Select items to validate
- Run Verify Credentials
- Pre-Stage Pass:
- Select users
- Run Pre-Stage Migration
- Set date range (90 days recommended)
- MX Record Cutover:
- Update DNS settings to point to destination
- Full (Delta) Pass:
- Select users
- Choose items to migrate (Mail/Contacts/Calendar)
- Run Full Migration
- Error Handling:
- Review error logs
- Run Retry Errors as needed
Limitations
- Contact Groups migrate to top-level contacts folder, with folders created but contacts not sorted
- Calendar Owners (users with "Make changes and manage sharing" permissions) migrate by default
- Google Hangouts links in calendar meetings are added to meeting description text
- Calendar colors may not map exactly due to platform differences
Migrated Items
Always Migrated:
- Inbox contents and structure
- Folders/Labels
- Email (including muted emails)
- Contacts
- Calendars and calendar permissions
- Calendar notifications
- Google Categories (Social, Promotions, Updates, Forums)
- Mailbox rules
- Automatic replies (Out-of-Office messages)
- Signatures
Non-Migrated Items
- Calendar Reminders
- Google Spaces and Chats
- Appointments
- Chat message attachments
- Google Groups for Business
- Calendar Attachments
- Tasks
- Email attachments that are links to Google Drive
Troubleshooting Tips
- Verify all required APIs are enabled in Google Cloud Console
- Ensure service account has proper permissions and scopes
- Check that all user accounts are in Active status
- Monitor API quotas and adjust as needed
Was this helpful?
If you've followed this guide, we'd love to hear about your experience. Please leave a comment below to share whether this guide helped you achieve your goal. If you found an alternative approach that worked, we encourage you to share that as well. Your feedback helps us improve our documentation and assists others in the community.
Need Further Assistance?
If you need additional support or would like personalized guidance, we're here to help. Check out our dedicated support plans at IT Solver Support Plans for expert assistance tailored to your needs.
References
This guide was adapted from: BitTitan's G Suite Gmail API to G Suite Gmail API Migration Guide
Comments
0 comments
Please sign in to leave a comment.