How to Migrate Google Workspace to Office 365

Moving an entire Google Workspace tenant to Office 365 is rarely just "mail". You are reconciling two identity models, two folder paradigms, two throttling regimes, and a Drive estate that needs its own plan. This guide walks through the path that keeps mail intact: a Workspace service account with domain-wide delegation on the source side, a tenant-level migration endpoint in the Microsoft Exchange Admin Center on the destination side, and disciplined batches in between. Read it once end to end before you license a single seat.

Before you touch the Exchange Admin Center#

You will not have a calm migration if any of the following are unsettled:

• Destination domain ownership is verified in Microsoft 365 and the domain is not still primary for an active Workspace tenant routing decision.
• You have a list of every user, every alias, every shared mailbox, every Google group, and every resource calendar. Aliases are where these projects bleed time.
• Source MFA posture is mapped. Service-account delegation bypasses user MFA, but if anyone has security keys enforced you still want to know before cutover.
• You have a written calendar and contacts plan. The Microsoft Workspace migration endpoint handles mail. Calendar and contacts are separate jobs and a separate set of failure modes.
• Drive is scoped out or has its own project plan. Trying to bundle Drive into a mailbox migration is how deadlines slip by a week.

If your environment also includes a hybrid Exchange relic or a partial Outlook deployment on the destination side, read the broader tenant-to-tenant migration playbook before you continue. There are scenarios where you stage the migration through an intermediate tenant, and you do not want to discover that mid-batch.

For a deeper look at Workspace specifics before you cut over, the Google Workspace migration guide covers source-side license retention and the order in which to disable POP, IMAP, and forwarding rules.

Authentication: pick one model and stick to it#

You have three realistic ways to authenticate against Google Workspace as a source:

1. Service account with domain-wide delegation (preferred). You create a service account in Google Cloud, enable the Gmail API, then in the Workspace Admin console grant the service account's client ID the Gmail scopes it needs. The migration tool then impersonates each user without per-user OAuth consent. This is the model the Microsoft EAC endpoint expects.
2. Per-user OAuth. You walk every user through a consent screen. Fine for a 5-seat agency, miserable for 800 users.
3. App passwords with IMAP. Still works but Google has been steadily restricting this path. Treat it as a fallback if delegation is blocked by policy, not as a default.

The first option is what the Microsoft Workspace migration endpoint accepts as a JSON key file. It is also what Mailbox Taxi uses when you point it at a Workspace tenant. Once delegation is granted, the same credential works for every user in the tenant, which is what lets you script bulk batches.

Folder mapping: labels are not folders#

Gmail labels are tags. Outlook folders are containers. The translation is mechanical but it is where users notice migration "weirdness":

• A message with three labels in Gmail (Inbox, Clients/Acme, Invoices) maps to one message stored in Inbox and copies that appear in Clients/Acme and Invoices unless your tool deduplicates against the destination Message-ID. Without dedup you can multiply mailbox size by 1.5 to 2x.
• Nested labels using / translate to nested folders. Verify the depth limit on the destination — extremely deep label trees occasionally trip Outlook UI quirks.
• The Inbox, Sent, Drafts, Spam, Trash, and All Mail system labels are remapped to their Outlook equivalents. All Mail is intentionally skipped to avoid 2x storage cost.
• Starred items either become a flag on the destination message or are mapped to a Starred folder. Tell users which behaviour to expect before they ask.

If your users live in Gmail's conversation view, prepare them for Outlook's flatter threading. This is a training issue, not a migration issue, but it lands on the help desk the day after cutover.

How to run the migration#

1. Confirm tenant and domain readiness

   In the Microsoft 365 admin center, add and verify the domain you will use. Provision and license target mailboxes ahead of time — you cannot migrate into a mailbox that does not exist. Lower the public MX TTL to 300 seconds 24 to 48 hours before planned cutover. Confirm Azure AD Connect is either not in scope (greenfield tenant) or fully aware of the users you are adding.

2. Create the Workspace service account

   In Google Cloud Console, create a project, enable the Gmail API (and Calendar, People APIs if you will migrate those in the same pass), create a service account, and download the JSON key. In the Workspace admin console under Security > API controls > Domain-wide delegation, add the service account's client ID with the Gmail read scope (https://www.googleapis.com/auth/gmail.readonly). Test the credential against one mailbox using a quick script or your migration tool's "test connection" function before going further.

3. Build the migration endpoint

   In the Exchange Admin Center, go to Migration > Endpoints and create a new Google Workspace endpoint. Upload the JSON key, provide a test user UPN, and confirm the endpoint validates. If you are using Mailbox Taxi or another desktop tool, point it at the same credential and verify it enumerates users correctly.

4. Map source addresses to destination mailboxes

   Export a CSV with EmailAddress,UserName rows where EmailAddress is the Workspace address and UserName is the destination UPN. Include any aliases as separate rows mapped to the same target mailbox if the tool supports it, otherwise plan a separate pass. Validate every row resolves to a licensed destination mailbox.

5. Run a pilot batch

   Pick 3 to 5 users: a normal mailbox, a heavy mailbox (>20 GB), a shared mailbox, and a user with deeply nested labels. Run the migration, then verify folder counts, total item counts, Sent items dating, and a sample of attachments. Open the destination in Outlook on Windows and Mac and on mobile — render quirks usually surface in one client and not another.

6. Migrate calendars and contacts

   Calendar and contacts are separate jobs. Use a calendar-aware tool to copy events, including recurrence and attendee lists. Free/busy lookups will be wrong during coexistence — accept that and shorten the coexistence window. If users have personal contact groups, they will arrive as flat distribution lists unless your tool preserves group membership explicitly.

7. Schedule bulk batches

   Group users in batches of 50 to 100. Stagger start times by 30 minutes to avoid hitting Google's per-tenant API quota in a single thundering-herd. Run the bulk during off-hours in the source time zone, because Google's API quota replenishes are softer when load is otherwise low. Monitor the destination for any Too many simultaneous connections responses from Exchange Online and back off if you see them.

8. Cut over MX and validate

   On cutover day, run a final delta sync, then swap MX to Microsoft 365's *.mail.protection.outlook.com record. Disable Workspace mail routing for users (leave the tenant alive for at least 30 days). Re-run a small delta a few hours after MX swap to catch in-flight messages. Validate Autodiscover, modern auth in Outlook desktop, and mobile profile re-provisioning.

Throttling: both sides will push back#

Google enforces per-user and per-tenant Gmail API quotas. Microsoft enforces EWS and Graph throttling on the destination plus mailbox-level throttling policies. The realistic picture:

• Google will return 429 responses if a single user is hit too fast. Mailbox Taxi paces per-user concurrency to stay under typical limits; if you script your own, keep per-user concurrency to 1 or 2 connections.
• Microsoft will throttle ingestion via EWS if you push too aggressively at the tenant level. Symptoms include slow batch progress and occasional Connection was aborted messages in tool logs.
• The combined practical ceiling is roughly 0.5 to 2 GB per hour per mailbox depending on average message size. Many small messages migrate slower per-GB than fewer large messages because of per-item overhead.

Common errors and what they actually mean#

You will see some of these in tool logs. Recognise them and you save an hour of forum reading.

• AUTHENTICATIONFAILED — service-account key is wrong, the scope is missing, or domain-wide delegation has not propagated. Wait 10 minutes after granting delegation before retrying.
• Too many simultaneous connections — Exchange Online destination throttling. Drop concurrent workers per mailbox to 2 or fewer.
• OAuth2 token expired — token refresh failed mid-batch. Most tools recover automatically; if it persists, the service account may be disabled or the project's API quota exhausted.
• Message too large for destination — a message exceeds Exchange Online's 150 MB attachment ceiling. These need to be skipped or extracted manually; flag them in the migration report.
• Folder UTF-7 conversion error — a Gmail label uses characters that fall outside the IMAP UTF-7 path encoding. Rename the source label or rely on a tool that handles UTF-8 IMAP extensions.

What to tell users#

Send three communications: one when the project is announced, one 72 hours before cutover, one on cutover day. Cover:

• The cutover date and time, in their local time zone.
• That contacts and calendar will be present but may show a "Updated from migration" tag for a few days.
• Mobile profile re-provisioning steps (delete old Workspace profile, add new Exchange profile).
• A direct help-desk path for anything that does not match expectations.

The 72-hour notice has the highest open rate. Put your cutover-day support contact in that one.

After cutover#

Keep the Workspace tenant alive for 30 days minimum. Reasons:

• You will need it to chase late-arriving mail that bounced during MX propagation.
• Calendar events on the source side may have lingering reminders or attendee responses that get raised once or twice.
• License revocation in Workspace is the last step, not the first.

For the broader pattern that applies to other Microsoft-bound migrations, read the Office 365 migration guide. If you are also moving Gmail-only personal accounts associated with the same domain, see Gmail to Office 365. And if your tenant is Workspace to Workspace rather than a Microsoft move, the Workspace tenant-to-tenant playbook is the closer match.

For the larger context that ties every provider pair together, the complete email migration guide is the pillar.