Google Workspace to Google Workspace: the complete playbook

This is the end-to-end guide for moving one Google Workspace into another with MigrateX — a domain consolidation after an acquisition, a rebrand onto a new primary domain, splitting a division out, or changing reseller. It covers what to prepare, what happens at each step, what moves and what doesn't, how the domain changes hands, and what to do the morning after.

1 · Plan the move

Workspace moves are usually about domains. Decide these three things first.

The rule is the same as on every route: copy in waves, cut over once. Drive copies inside Google and is quick; Gmail is the long pole, so start the biggest mailboxes first.

A realistic timeline (150 people)

2 · Prepare both Workspaces

In the target Workspace

• Create the accounts with the same username where possible (aisha.rahman@) so auto-match pairs them. A person can only land on an account that exists.
• Assign Workspace licenses that include Gmail and Drive; Gmail must be turned on for the organisational unit.
• If the domain moves, the target needs a verified fallback domain (its primary domain) that accounts hold until cutover. Google does not allow the same domain in two Workspaces at once.
• A super administrator to authorise domain-wide delegation.
• A Google Cloud organization for each domain (a super administrator has signed in at console.cloud.google.com at least once); without it delegation fails with unauthorized_client.

In the source Workspace

• A super administrator for delegation and for the directory calls.
• Make sure the Admin SDK, Gmail, People, Calendar, Drive and Chat APIs are not restricted for the OU (Admin console → Security → API controls → App access control).
• Decide what stays behind: suspended users, service accounts, archived shared drives.

In MigrateX

• Create the project with the route Google Workspace → Google Workspace and tick the scope: Gmail, Groups & aliases, Drive, Shared drives & Chat.
• Licenses: one per person; Groups, shared drives, Chat spaces and every pass are free. See Licenses and billing.

3 · Connect both Workspaces

1. Connect the sourceOverview → Connect source tenant. MigrateX shows the client ID and the exact scopes. In the source Admin console: Security → Access and data control → API controls → Manage domain-wide delegation → Add new. Paste both. Enter a super administrator address in MigrateX and press Verify.
2. Connect the targetThe same in the target Admin console. Use its own super administrator address.
3. Check the scope listEach tenant node lists every scope as verified or missing. A missing one is almost always a typo in that scope — edit the delegation entry, don't add a second.

Full detail: Connect a Google Workspace tenant.

4 · Assess

Assessment → Run assessment. It reads users, Gmail and Drive sizes, Groups, shared drives and Chat spaces from both Workspaces, pairs people up and scores readiness. Typical findings on this route:

5 · Match users

Auto-match pairs by username, then by alias, then by unique display name. Fix the rest by typing a target address or importing a two-column CSV; exclude suspended users and service accounts. Detail: Matching users.

6 · Pilot

Pick five to ten people on purpose — the two largest Gmail accounts, someone who shares a lot in Drive, one Group with a collaborative inbox — and press Migrate selected. When they are in sync, sign in as one in the target and check:

• Labels, including nested ones; read/unread, stars and importance on a few old messages; the original dates.
• A recurring event: recurrence and reminders intact, nobody re-invited.
• Contacts and contact labels.
• Drive: a shared file shows the same people with the same roles; a Google Doc opens as a Doc.

7 · Gmail

Doesn't move: Spam and Trash (on purpose), messages over Gmail's size limit (listed by name), delegation settings, third-party add-ons.

8 · Calendar & Contacts

• Calendars: every calendar the person owns, with events, recurrence, exceptions, reminders and free/busy. Events are imported, not re-created, so attendees are not re-invited. Calendars shared by others are re-shared once the owner is migrated.
• Contacts: People contacts and contact labels. "Other contacts" (auto-collected) are not moved.
• Resources (rooms, equipment): recreated in the target where the API allows; listed otherwise.

9 · Drive

Drive to Drive is the fast part: MigrateX copies inside Google — share the file with the target account, copy it, unshare — so the file never leaves Google and Google-native formats stay native. Dates are kept; the current version moves; sharing is re-granted to the matched people with the same role. Sharing links and external people are listed as notes; shortcuts are recreated where their targets moved.

Doesn't move: version history; files owned by people who are excluded (they stay with the owner — transfer ownership first if you need them); comments' authorship becomes the copying account.

10 · Groups & aliases

On Groups & aliases, press Read again, wait for the members to be matched, then Migrate selected.

11 · Shared drives

On Shared drives & Chat, each shared drive is recreated in the target with the same name; managers, content managers, contributors, commenters and viewers are mapped to target accounts; content copies inside Google. Restrictions (download, sharing outside the domain) are re-applied.

12 · Chat spaces

A space is created in the target in import mode, its history imported with the original authors and timestamps, then files referenced from Drive. The space is staged: nobody can use it yet; delta passes keep it current. When you press Make selected spaces available, it leaves import mode and gets its members. Google accepts no more history after that, so complete spaces on cutover evening, after the final delta.

Not covered by the import API and listed instead: direct messages and group DMs, reactions, apps and webhooks, Meet recordings.

13 · Waves & delta passes

• Migrate in waves by team. People keep working in the source throughout.
• Run delta pass nightly: Gmail history and Drive changes make it exact and quick. Passes are free.
• Google's per-user and per-project quotas are honoured across every worker; when Google says slow down, everything pauses and resumes.
• Failures are retried up to five times; anything still failing shows its newest reason under "Items that need a look".

14 · Verify

Migration → Verify everyone lists every label, calendar, contact group and Drive again and checks each item against the target. Missing items are shown by name; Copy missing items queues them. Verify after the full wave and again after the final delta.

15 · Cutover evening

The wizard on Cutover walks these steps in order. Google releases and verifies domains quickly; the long part is DNS.

1. Freeze changesAsk people to stop creating new content in the source for the evening.
2. Forward mail from the sourceEach migrated account forwards to its target twin.
3. Final delta passThe last hours of mail, files and history.
4. VerifyCopy anything missing.
5. Complete staged Chat spacesThey leave import mode and get their members.
6. Remove the domain from the sourceMigrateX first moves every source user and Group to the source's fallback domain so nobody loses an address, then removes acme.com from the source Workspace.
7. Add and verify the domain in the targetAdd the TXT record MigrateX shows (Site Verification); press Check.
8. Claim the addressesPrimary addresses and every alias on acme.com are applied to the target accounts and Groups.
9. Point DNS at the targetGoogle's MX records, SPF (include:_spf.google.com), DKIM from the target Admin console. The wizard checks MX for you.
10. Send the notice, sign offThe drafted notice tells people what changed; the report goes in the change record.

16 · The day after

• Gmail on the web just works with the new account. Phones and mail clients: remove and re-add the account.
• Drive for desktop: sign out, sign in with the target account, re-sync.
• External people who had links or shares need new ones — the notes list them.
• Meet, Sites, Keep, Forms are outside the migration APIs; recreate what you need.
• Keep the source Workspace, and forwarding, for a month. Run a delta and verify if anyone reports something missing.

17 · Limits and known gaps

Checklist