How to Migrate Gmail to Office 365

Moving mail from Gmail to Office 365 looks simple on the marketing slides and rarely is at 2am on cutover night. The destination expects IMAP credentials per mailbox, Google expects app passwords because two-step is on, and Microsoft's throttling quietly halves your throughput around mailbox forty. Add Gmail's label model on the source and an Outlook folder model on the destination, and you have four moving parts that all want to fight at the same time. This guide walks you through the migration the way the Exchange admin center expects it, with the gotchas called out before they bite.

What you need before you start#

A Gmail to Office 365 migration leans on credentials, DNS, and a clean CSV. Skipping any of these costs you a weekend.

On the Gmail (source) side you need:

• Super admin access to the Google Workspace tenant, or owner access to each consumer Gmail account in scope.
• IMAP enabled per mailbox under Settings, Forwarding and POP/IMAP. Workspace admins can enforce this via the Admin Console under Apps, Google Workspace, Gmail, End user access.
• Either an app password per mailbox (when 2-Step Verification is on, which it almost always is) or a service account with domain-wide delegation scoped to https://mail.google.com/. The service account route is the only sane choice above about 25 mailboxes.
• The source server hostname (imap.gmail.com) and port (993 over TLS).

On the Office 365 (destination) side you need:

• A licensed user with an Exchange Online mailbox for every account that will receive mail. No license means no mailbox, and the batch will fail with MailboxNotFound before it touches Gmail.
• The destination domain verified in Microsoft 365 admin center, with the DNS challenge in place.
• Exchange Online PowerShell access or a global admin who can sign into the Exchange admin center.
• A test mailbox you're willing to break. You will break it.

On the DNS and tooling side you need:

• TTLs on the source MX records lowered to 300 seconds at least 48 hours before cutover.
• A change window where mail can sit in the queue for 10–15 minutes during the MX swap.
• A CSV file you can edit without Excel mangling Unicode characters in display names.

The migration in eight steps#

1. Prepare the Office 365 destination tenant

   Verify the destination domain in Microsoft 365 admin center and assign Exchange Online Plan 1 or higher to every user in scope. Provisioning lag is real — newly licensed mailboxes sometimes take 15 minutes to appear in Exchange Online, and an IMAP batch that starts before that finishes will fail half its rows. Confirm with Get-Mailbox <user> in Exchange Online PowerShell before you do anything else.

2. Enable IMAP and issue credentials in Gmail

   For Workspace, open the Admin Console and confirm IMAP access is enforced for the OU containing your migrating users. For consumer Gmail, each user has to do it themselves under Settings. Then either generate an app password per account (you'll need 2-Step Verification on first), or set up a service account with domain-wide delegation. The service account approach lets you authenticate as any user in the Workspace tenant without per-mailbox passwords.

3. Build the migration CSV file

   Microsoft expects a CSV with three columns: EmailAddress, UserName, Password. EmailAddress is the destination Office 365 address. UserName is the source Gmail address. Password is the app password — not the Google account password. Save as CSV UTF-8 from a plain text editor; Excel happily corrupts non-ASCII display names and you will only notice when a French-speaking exec emails you about it.

4. Create the IMAP migration endpoint in EAC

   In the Exchange admin center, open Migration, Endpoints, Add a migration endpoint, and choose IMAP. Set the server to imap.gmail.com, port 993, authentication Basic, and encryption SSL. Set Maximum concurrent migrations to 10. Push it higher and Gmail starts returning Too many simultaneous connections and the batch crawls. Microsoft's practical ceiling on a single endpoint is about 10 active sessions per source server.

5. Start a migration batch

   Under Migration, Batches, Add a migration batch, upload the CSV, select your new endpoint, and choose Manual complete the migration batch. Manual completion gives you the final-cutover knob — without it, the batch will try to finalise itself the moment it finishes initial sync, and you lose control of timing. Start the batch in a low-impact window: Friday evening for SMB, Saturday morning for follow-the-sun teams.

6. Monitor throttling and retry failures

   Check the batch status hourly for the first 12 hours. Expect a small number of mailboxes to show Synced with errors — usually a handful of corrupt messages Gmail's IMAP layer can't expose cleanly. Re-run rows that hit AUTHENTICATIONFAILED after refreshing the app password. Don't try to fix everything at once; finish the bulk sync first, then chase the tail.

7. Cut MX records and complete the batch

   Once the batch reaches Synced, update your domain's MX records to point at Microsoft (<domain>.mail.protection.outlook.com). Wait for the TTL to expire. Then in EAC, click Complete this migration batch to run the final delta sync. Most mailboxes pick up a few hundred messages in this delta; large active accounts can pick up several thousand.

8. Validate and decommission Gmail

   Send and receive a test message from each migrated mailbox. Spot-check Sent Items, Drafts, and at least three deeply nested labels-turned-folders per pilot user. Run a folder count comparison: Gmail's IMAP list versus the new Outlook folder tree. Only after stakeholders sign off should you suspend the Gmail accounts. Keep them suspended, not deleted, for 30 days as a safety net.

Provider-specific gotchas#

Gmail and Office 365 each have quirks the documentation glosses over. The ones that bite in production:

Labels expand into folders, and they multiply. Gmail's IMAP layer exposes every label as a folder. A message with three labels appears in three folders after migration, taking three times the space. Run a label audit on the source first. Anything that's a process tag rather than a real archive folder — to-read, follow-up, 2023-budget — should be removed before the migration runs.

All Mail and Important confuse the batch. The [Gmail]/All Mail folder contains every message in the account. If you don't exclude it, Microsoft's tool will dutifully copy the same message twice — once from its label folder, once from All Mail — and your destination mailbox doubles in size. Exclude [Gmail]/All Mail, [Gmail]/Important, and [Gmail]/Starred in the batch settings.

App passwords expire silently. Google occasionally invalidates app passwords during the migration window — usually after a security event on the account, sometimes for no obvious reason. The batch row goes red with AUTHENTICATIONFAILED and stays that way. Reissue the app password and re-run that row only.

Microsoft throttling halves around mailbox 40. Microsoft applies tenant-level throttling to IMAP migration that's invisible until you hit it. Above roughly 40 active mailbox migrations the per-mailbox throughput drops by half. Batch in groups of 30–40 if you can; don't try to push 200 mailboxes through a single batch overnight.

Modern Authentication is not in play here. IMAP migration uses Basic Authentication against Gmail. That's fine for Gmail — Google still supports it for app passwords and service accounts. But if you've inherited a Microsoft 365 tenant that has Basic Auth disabled across the board, the migration endpoint still works because the Basic Auth lives on the Gmail side. Don't let a panicked compliance officer disable the endpoint to "fix" this.

Common errors#

Real errors you will see in the batch status pane, and what to do about them:

• AUTHENTICATIONFAILED — App password is wrong, expired, or 2-Step Verification was disabled and re-enabled on the source. Reissue the app password and re-run that row. For service-account setups, check the domain-wide delegation scopes in the Workspace Admin Console.
• Too many simultaneous connections — You've exceeded Gmail's per-server connection ceiling. Drop Maximum concurrent migrations on the endpoint from 10 to 5, wait an hour, and resume. Gmail's quota resets cleanly; you don't need to do anything else. Our guide on fixing Gmail app password issues covers the credential side in detail.
• Folder UTF-7 conversion error — A Gmail label contains a character Microsoft's IMAP migration can't translate. Usually emoji or right-to-left text. Rename the label on the source side, wait five minutes for the IMAP cache to refresh, re-run the row.
• Message too large for destination — Exchange Online's hard limit is 150 MB per message. Anything above that gets skipped. Note the message IDs in the report, retrieve them from Gmail manually, and let the user know they're not coming across. There's no workaround — Microsoft does not negotiate on this limit.
• The remote server returned an error: (552) Mailbox size limit exceeded — Destination mailbox hit its quota. Either bump the user's license tier or split the migration: pull recent mail first, then a second pass for archive. The Office 365 throttling guide covers the broader Microsoft-side limits.
• OAuth2 token expired — Only shows up if you're using a service account. The OAuth token your delegation script issued has lapsed. Regenerate it; the batch will pick up from where it stopped.

Communicating with your users#

Migration day is when your users will email you the most, and almost all of it is avoidable with the right comms two weeks before.

Send a heads-up two weeks ahead with one specific outcome people care about: their Gmail inbox will still work, but they should expect a 10–15 minute mail gap on the cutover weekend. Tell them exactly what their new login looks like (user@domain.com is fine; firstname.lastname@onmicrosoft.com will cause a panic). Tell them about Outlook for desktop, web, and mobile, and link to a one-page setup guide.

One week ahead, send a reminder with the cutover date and time, and a single sentence about labels-becoming-folders. Most users have never heard of either and will assume the migration broke their mail when they see the new folder tree.

Twenty-four hours ahead, send the cutover window with a clear "do not delete anything from Gmail until you hear from us" line. Users who panic-delete during the delta sync cause the worst data loss incidents.

On cutover day, send a "we've started" message, a "we're 50% done" message, and a "you're live" message with the URL for Outlook on the web and instructions for reconnecting their mobile clients. The complete email migration guide has a full comms template you can adapt.

After cutover, leave Gmail suspended for at least 30 days. Tell users that if they spot something missing, you can pull it from the source — but only for a month. Set an explicit deadline and stick to it.