Google Workspace Migration: A Complete Guide

A Google Workspace migration is deceptively simple on paper: pick a source, pick a destination, push the button. In practice, you're juggling label-to-folder semantics, OAuth scopes, service-account delegation, per-connection bandwidth caps, and the fact that Gmail's view of a message and Outlook's view of a message disagree about what a folder even is. This guide walks you through every decision for a google workspace migration — both into and out of Workspace — including the auth model that actually works at scale.

The four shapes of a Workspace migration#

Before any tooling conversation, decide which of these you're doing. The constraints are different.

Workspace into another Workspace tenant#

The most common case for M&A and consolidation work. Google's own Data Migration Service handles the basic mail-only path, but it stops at mail. Calendars, contacts, Drive, Chat — those are separate workflows. For a real cross-tenant move, you either run multiple parallel Google migration jobs (one per data type) or use a third-party tool that consolidates them.

Workspace into Microsoft 365#

A migration with two distinct halves: source-side authentication into Google and destination-side ingestion into Microsoft. The hard part is almost always the source — service account setup, scopes, and bandwidth — not the destination. The migrate Google Workspace to Office 365 guide covers the M365 destination specifics; this pillar covers the Workspace side.

Microsoft 365 (or other source) into Workspace#

The reverse direction. Google publishes a Data Migration Service that pulls mail from any IMAP-accessible source. For larger or richer migrations (calendars, contacts), you're back to a third-party tool. The destination throttling pattern matters here — Workspace ingestion is often the bottleneck, not the source.

Workspace into IMAP-only destinations#

Rare but real: moves into Fastmail, Zoho, ProtonMail Bridge, or a hosted IMAP service. These bypass Microsoft and Google's migration tooling entirely. The complete email migration guide covers the IMAP-only patterns in depth.

Data Migration Service vs third-party tools#

Google's Data Migration Service (DMS) is free, lives inside the Workspace admin console, and handles IMAP-source mail migration. It's the right tool for a narrow set of jobs and the wrong tool for everything else.

When DMS is the right call#

• Source is IMAP-accessible (Gmail, Outlook, IMAP host, on-prem Exchange with IMAP enabled).
• You only need mail. Not calendars, not contacts, not Drive.
• Mailbox count is under roughly 100.
• You can tolerate sequential per-user setup or scripted enrolment.
• No requirement for delta sync after the initial run.

When you need a third-party tool#

• Calendars and contacts must come across.
• More than 100 mailboxes with parallelism.
• Need delta syncs over multiple weekends.
• Migrating out of Workspace.
• Need detailed per-mailbox audit logs for compliance.
• Need to map Gmail labels to specific destination folders.

The Google data migration vs third-party comparison covers the trade-offs in depth, including the throughput and reliability differences.

Auth: app passwords vs service accounts#

This is the single most-confused part of Workspace migrations. Get it right and the rest is mechanical.

App passwords (the small-scale path)#

An app password is a 16-character credential generated per user in their own Google Account security settings. It lets a tool authenticate to that user's mailbox over IMAP without going through OAuth, and it bypasses 2-Step Verification at the IMAP layer.

App passwords work when:

• 2-Step Verification is enabled for the account (it's a prerequisite, not a workaround).
• The account's admin has not disabled "less secure app access" controls (terminology varies; in modern Workspace, app passwords are the supported replacement).
• You're moving a handful of mailboxes and per-user setup is acceptable.

App passwords don't scale to hundreds of users — generating one per account, then revoking them, is operationally painful. The Gmail app password fix walks through the specific error states you'll see when something goes wrong.

Service accounts with domain-wide delegation (the real-scale path)#

For anything past about 25 mailboxes, you want a service account. Conceptually:

1. An admin creates a Google Cloud project and a service account inside it.
2. The service account is granted domain-wide delegation in the Workspace admin console, with the OAuth scopes the migration tool requires (typically the Gmail API and Calendar API scopes).
3. The migration tool authenticates as the service account and uses its delegated authority to impersonate each user in the domain — without needing per-user credentials.

The mechanics of which exact scopes to grant depend on the specific tool. Don't over-grant — match the tool's documented requirements and nothing more. Domain-wide delegation is powerful enough that it should be revoked the day the migration completes.

Gmail label semantics — the silent gotcha#

Gmail does not have folders. It has labels. A single message can have many labels, including system labels like Inbox, Important, and Starred. When you migrate Gmail to a folder-based destination (Outlook, Exchange, IMAP), you have to decide what the mapping is.

The three common strategies:

1. One folder per label, message duplicated. Cleanest semantically, but storage cost balloons. A message with five labels becomes five copies.
2. One folder per label, message placed in primary label only. Smaller storage footprint, but loses the multi-label relationship. Most third-party tools default here.
3. Flat to Inbox, labels in headers. Move everything to Inbox and preserve original labels in a custom header. Works for archival but breaks user-facing organisation.

Decide before the pilot. Tell users which one they're getting. Users who lived inside Gmail labels for a decade will be disoriented if you don't communicate this.

System labels handle differently across tools:

• Inbox label → typically maps to the destination Inbox folder.
• Sent label → maps to Sent Items.
• Drafts label → usually skipped or mapped to Drafts.
• Spam/Trash labels → usually skipped.
• Important and Starred → tool-dependent; some preserve as flags, some drop entirely.

Throttling: the per-connection cap#

Google's documented IMAP throttling is conceptually simple but operationally finicky. The numbers you can plan around:

• Per-connection bandwidth soft limit of approximately 2 GB before Google rate-limits.
• Per-account concurrent IMAP connection limit of approximately 15.
• Per-domain API quota for the Gmail API, typically 1 billion quota units per day, with per-method costs varying.
• Per-user Gmail API rate limit of approximately 250 quota units per second.

In practice this means:

• One connection per mailbox is the safe default. Two is sometimes faster, three is usually slower.
• Parallel mailboxes within the same domain — typically 20–40 concurrent — give you the best aggregate throughput.
• Long-running connections that move more than 2 GB without disconnecting will get rate-limited mid-stream and look like a hang.

If a mailbox stalls mid-migration with no clear error, it's almost always a connection cap, not a tool bug. Disconnect, wait 60 seconds, reconnect, resume from the last completed item.

Discovery for a Workspace source#

Before you touch a tool, capture:

• User count by license type (Business Starter, Standard, Plus, Enterprise).
• Total mail data by user. Workspace admin reports give you this; the long tail matters.
• Calendar count and shared calendar count.
• Contact group ownership.
• Drive data, if it's in scope (often it isn't for an email migration, but stakeholders will ask).
• Active mobile devices via the Workspace admin console.
• Third-party Marketplace apps that hold OAuth grants — these don't migrate.
• Group memberships and group-based mail aliases.
• Routing rules and content compliance rules.

The email migration checklist has a Workspace-specific section you can lift directly into a discovery document.

Discovery for a Workspace destination#

When you're migrating into Workspace, the discovery focus shifts to the source side and the destination license model:

• Confirm the destination Workspace edition supports the user count you're provisioning.
• Pre-create user accounts before you start the migration. DMS and most third-party tools will not create accounts on the fly.
• Confirm aliases and group addresses are set up before MX switch, or mail to those addresses will bounce post-cutover.
• Configure dual delivery during coexistence if you need it — this is set at the Workspace routing layer.

For the M365-to-Workspace direction specifically, the Microsoft 365 source guidance in the Office 365 migration guide covers the export side: app registration, Graph or EWS scopes, and modern auth requirements.

The cutover sequence#

Workspace migrations follow the same shape as any other email cutover, with a few Google-specific notes.

Two weeks before cutover#

• Final discovery sign-off.
• Pilot batch of 5–10 mailboxes representing the worst cases (largest mailbox, most labels, most calendar delegations).
• Comms to end users with screenshots of the new login flow.
• Drop MX TTL to 300 seconds 48 hours before cutover.

One week before cutover#

• All bulk mailboxes through their first full pass.
• Service account scopes verified and audit log clean.
• Calendar migration pass complete (if separate from mail).
• Shared mailbox and resource mailbox permissions exported.

Cutover weekend#

• Friday evening: final delta sync starts.
• Saturday morning: delta completes. Validate item counts on a 10% sample.
• Saturday midday: MX switch.
• Saturday afternoon: re-test inbound and outbound mail flow. Send tests from gmail.com, outlook.com, yahoo.com, and a personal domain.
• Sunday: monitor and re-run delta on any straggler mailboxes that received mail post-original-delta.

Post-cutover validation#

• Item count delta per label/folder within 2%.
• Total size delta per mailbox within 3% (Gmail's storage accounting includes things IMAP doesn't).
• Calendar free/busy resolves correctly across migrated and non-migrated users.
• Mobile devices reconnect or are re-enrolled.
• Shared calendar permissions intact.
• Group membership and aliases route correctly.

The tenant-to-tenant migration guide has the cross-tenant validation matrix in detail, including the Workspace-to-Workspace case.

Common Workspace migration errors#

The errors you'll actually see, and what they mean:

• AUTHENTICATIONFAILED — almost always an app password problem on the source side, or a missing scope on a service account.
• Too many simultaneous connections — per-account IMAP cap. Drop concurrent connections per mailbox.
• OAuth2 token expired — the tool's refresh token cycle doesn't match Google's token lifetime. Restart the affected batch.
• STARTTLS handshake failed — destination IMAP endpoint TLS version mismatch. Confirm the destination supports TLS 1.2+.
• Folder UTF-7 conversion error — IMAP folder names with non-ASCII characters on the destination side.
• Quota exceeded for quota metric 'Queries' — Gmail API quota burn. Slow down or request a quota increase.
• Message too large for destination — destination service message cap (typically 25 MB on Gmail, 150 MB on M365) smaller than source.

A migration that's "stuck" for more than 4 hours with no log progress almost certainly isn't progressing. Pause, check the last error, restart.

Workspace-to-Workspace specifics#

For the same-platform case, two things change:

1. Google's DMS doesn't support Workspace-to-Workspace mail migration in the way it supports IMAP-source-to-Workspace. You'll be using a third-party tool or the Gmail API directly.
2. You can use service accounts on both sides — one on the source, one on the destination — which makes the auth model symmetric and clean.

The migrate Google Workspace to Google Workspace guide covers the consolidation case in detail, including domain alias handling and the calendar invite resolution problem.

Gmail-to-Outlook specifics#

For a personal Gmail account or a small Workspace tenant moving to Outlook (either Microsoft 365 or Outlook.com), the constraints are tighter:

• Personal Gmail caps individual messages around 25 MB.
• Outlook desktop's PST behaviour after a migration depends on the Outlook profile version.
• Label-to-folder mapping defaults vary by tool.

See the migrate Gmail to Outlook walkthrough for the step-by-step, including the Outlook profile rebuild step that catches everyone the first time.

What good looks like at the 72-hour mark#

A Workspace migration is done when:

• Inbound mail flow is fully on the new platform.
• No more than 2% of users have reported a user-visible issue.
• Calendar free/busy resolves across the org.
• Mobile devices have reconnected without help-desk intervention.
• Service account credentials have been rotated or deleted.
• Domain-wide delegation has been revoked or restricted back to its pre-migration state.

The last two matter as much as the mail flow. A successful migration that leaves a service account with full Gmail read access for six months is not a successful migration.