Google Workspace Tenant-to-Tenant Migration

A Workspace-to-Workspace migration looks deceptively simple. Both sides speak Gmail, both honour the same API, and there is even a free first-party tool. In practice the work is in the seams: which super-admin runs which step, when the domain leaves the source tenant, how labels survive a hop that may go via IMAP, and the M&A timing constraints that determine whether you can pre-stage at all. This guide covers the path most teams should take, with the trade-offs against Google's own Data Migration Service called out where they matter.

Google Data Migration Service vs third-party tools#

Before scoping anything, decide which tool is doing the work. There are three honest options:

1. Google Workspace Data Migration Service (DMS). Free, built into the admin console, IMAP-based. Good for mail-only migrations under a few hundred mailboxes where label flattening is acceptable. It does not migrate calendar, contacts, or Drive in a single workflow.
2. Google Workspace Migrate (the bigger first-party tool). Better for organisations already used to Google's tooling, and handles more data types. Setup is heavier than DMS.
3. Third-party API-based tools (including Mailbox Taxi). Use the Gmail API directly, preserve labels including nested structure, and tend to be faster because per-user concurrency is tuned to API quotas rather than to IMAP connection limits.

If label preservation matters at all, the IMAP-based path costs you. The trade-offs are covered more deeply in Google DMS vs third-party; read it before you commit to a tool for anything over 50 users.

Source-side prerequisites#

The migration starts on the source tenant. Get these settled before you touch anything else:

• A working super-admin account that is not bound to a security-key-only policy you cannot temporarily relax for service-account setup. (You can re-tighten after the project.)
• The Gmail API enabled on a Google Cloud project you control. The project itself can live in either tenant but practical experience says keep it on the destination side, so the source admin can revoke access cleanly post-migration.
• A service account with domain-wide delegation granted in the source Workspace admin console. Add the Gmail read scope, plus Calendar and Contacts read scopes if you will move those.
• A full export of users, aliases, groups, shared mailboxes, resource calendars, and the labels each user has created. Aliases are where M&A projects miss content; do not skip them.

If you have not done a Workspace migration before, the Google Workspace migration guide sets up these basics in more depth.

Destination-side prerequisites#

The destination tenant has its own list:

• Every destination user provisioned with their final UPN. If the destination uses a temporary alternate domain during transition, plan the UPN swap as a post-cutover step.
• Workspace licenses applied. Migrations into unlicensed mailboxes will fail with a permissions error that does not say "unlicensed".
• The source domain either verified on the destination as a secondary domain or scheduled for transfer after source decommission. Google enforces the constraint that a domain can only be primary on one tenant — exactly when that transfers happens matters.
• DNS access for MX, SPF, DKIM, and DMARC on cutover day. If DNS is hostage to a marketing agency, get the credentials a week early.

OAuth and identity during migration#

Both tenants use Google identity, which simplifies the auth model:

• Source-side reading is via the service account with domain-wide delegation, impersonating each user.
• Destination-side writing uses a second service account in the destination tenant, also with domain-wide delegation.
• Users do not see consent prompts. Their MFA setup is unchanged on either side.

For the user-perceptible part, expect each user to need to re-add Workspace on their mobile device after cutover. The web interface continues to work transparently if SSO is wired correctly on the destination.

How to run the migration#

1. Confirm super-admin access on both tenants

   On the source, log in as a super-admin and verify you can reach Admin > Security > API controls > Domain-wide delegation. On the destination, confirm super-admin access and that you can add domains. If either super-admin account is restricted by a security-key-only policy that blocks service-account creation, relax it temporarily for the project window.

2. Provision destination users and licenses

   Bulk-create destination users with their final UPNs, or with a temporary alternate-domain UPN if the source domain is still claimed. Apply licenses now, not later — license assignment can take 30 to 60 minutes to propagate to the mailbox layer. Build the email-address-mapping CSV at this point so it is locked before the bulk run.

3. Enable Gmail API and domain-wide delegation on source

   In Google Cloud Console, create a project, enable the Gmail API (and Calendar and People APIs if relevant), create a service account, and download the JSON key. In the source Workspace admin console, grant the service account client ID the read scopes you need. Test against one source mailbox before going further — if you cannot read one mailbox, you will not be able to read 500.

4. Verify the destination domain

   If the destination tenant is greenfield and the source domain is still primary on the source tenant, you cannot fully verify the destination domain until cutover. Use a temporary alternate domain (acme-new.com for acme.com) for the destination UPN during migration, then plan the rename at cutover. If the destination is an existing tenant with a different primary domain, add the source domain as a secondary now and the rename is administrative rather than blocking.

5. Run a pilot batch

   Pick a normal user, a heavy mailbox (>20 GB), a shared mailbox, a user with deeply nested labels, and one resource calendar. Migrate them, then verify total item counts, folder structure, calendar attendee retention, and a spot-check of attachments. Open the destination in Gmail web and on at least one mobile client. Watch for label flattening — if you are seeing it where you did not expect, the tool is using IMAP under the hood.

6. Migrate calendars and contacts separately

   Calendar migration is its own job. Preserve recurrence rules, attendee lists, and resource bookings. Be honest with users that free/busy lookups across tenants will be wrong during the coexistence window — shorten that window rather than trying to fix it. Contacts are a third pass and usually fast.

7. Schedule the bulk batches

   Run 50 to 100 users per batch. Stagger batch starts by 30 minutes so you do not hit the Gmail API per-project quota in one wave. Run during off-hours in the source time zone. Monitor the migration tool's progress and the Gmail API metrics in Google Cloud Console — sustained 429 responses mean you need to back off concurrency.

8. Cut over MX and finalise

   On cutover day, run a final delta sync. Swap MX to the destination tenant's Google MX records. Remove the source domain from the source tenant per Google's flow, then claim it as primary on the destination. Re-run a small delta a few hours later to catch in-flight messages. Validate Sent integrity, calendar events, and that mobile clients re-provision cleanly.

Label preservation specifics#

Gmail labels are the heart of why Workspace-to-Workspace migrations are worth doing properly:

• API-based tools call users.messages.list per label and re-tag on the destination via users.messages.modify. Nested labels survive intact.
• IMAP-based tools (including Google's free DMS for mail) see labels as folders and may not reproduce the hierarchy faithfully. You will see "label/sub-label" appear as a flat label name.
• System labels (INBOX, SENT, STARRED, IMPORTANT, SPAM, TRASH) are remapped to their destination equivalents.
• The All Mail virtual label is skipped to avoid double-storing every message.

M&A scenarios#

Most Workspace-to-Workspace migrations come from an acquisition. The shape is usually:

• Day 0: deal closes, source tenant identified, destination tenant chosen.
• Week 1–2: discovery, sizing, license planning, communications drafted.
• Week 3: source-side API access granted, pilot batch runs.
• Week 4–6: bulk migration in batches.
• Week 7: cutover window, MX swap, source domain transfer.
• Week 8+: source tenant decommission, with a 30-day grace period for late mail.

The variables that move that timeline are domain count (one is easy, twelve is not), Drive content (out of scope here, but the project plan needs it), and whether SSO is changing. The M&A email migration playbook goes into the legal and HR sequencing that ties this to a deal close. For the broader tenant-to-tenant pattern across providers, the tenant-to-tenant migration guide is the right anchor.

Errors you will see#

• AUTHENTICATIONFAILED — service-account delegation not propagated, or the scope is missing. Wait 10 minutes after granting delegation before retrying.
• OAuth2 token expired — token refresh failed. Usually transient; persistent failures mean the service account was disabled.
• userRateLimitExceeded — per-user Gmail API quota hit. Reduce per-user concurrency to 1.
• Folder UTF-7 conversion error — only on IMAP-based paths; rename the source label.
• Message too large — Gmail rejects messages over 35 MB on the receiving side. These need to be flagged and handled out of band.

What to tell users#

Three notes work better than one long one:

1. Two weeks before: "We are moving email. Here is the new tenant name, here is the cutover date, expect a mobile reconfig."
2. 72 hours before: "Cutover is Thursday at 8pm. Mail will be quiet for up to two hours during MX propagation. Here is the help-desk contact."
3. Cutover day: "MX has swapped. If you cannot send mail in the next hour, here is what to do. Mobile reconfig steps attached."

If the migration is M&A-related, coordinate with HR and legal communications. The migration email cannot leak the deal before HR has spoken to users.

After cutover#

Keep the source tenant alive for at least 30 days. Use this window for:

• Late mail that bounced during MX propagation.
• Calendar reconciliation if users notice events that did not transfer cleanly.
• License cleanup, in that order: revoke source licenses last.

For the broader context the complete email migration guide is the pillar; if you are moving from Workspace to Microsoft instead of Workspace to Workspace, the Workspace to Office 365 path is the closer fit.