How to Migrate Office 365 to Gmail

Microsoft 365 to Gmail looks straightforward — pull from outlook.office365.com, push to imap.gmail.com, done. In practice it lands you in the middle of Modern Authentication, Entra ID app registrations, shared mailbox licensing rules, and Exchange Online's silent throttling. The Microsoft side is more locked down than it used to be, and trying to drive an IMAP migration with Basic Auth on a current tenant will fail within minutes. Get the OAuth setup right up front and the migration becomes a long but predictable run.

What you need before you start#

The Microsoft 365 source side is where most of the preparation lives. Gmail's destination requirements are stable; M365's surface area is where mistakes hide.

On the Microsoft 365 source side you need:

• Global admin access to the source tenant, or at minimum Exchange admin plus Entra ID app admin.
• An Entra ID app registration with IMAP.AccessAsUser.All delegated permission (or IMAP.AccessAsApp application permission if you want client-credentials flow). Admin consent must be granted explicitly — the consent prompt won't appear during the migration itself.
• Confirmation that Modern Authentication is enabled on the tenant. Open Exchange admin center, Settings, Modern authentication, and confirm it's on. If it's off, turn it on at least 24 hours before migration — propagation isn't instant.
• The hostname outlook.office365.com on port 993 with TLS.
• A throttling policy check. Run Get-ThrottlingPolicy | Format-List Name,IMAPMaxConcurrency and note the per-mailbox cap. The default is 4–10 depending on tenant age.

On the Gmail (destination) side you need:

• Google Workspace accounts provisioned for every Microsoft 365 user. Decide upfront whether shared mailboxes become Google Groups, delegated accounts, or individual Workspace seats — they all have trade-offs.
• IMAP enabled in the Workspace Admin Console.
• A service account with domain-wide delegation, scoped to https://mail.google.com/. Per-mailbox app passwords are unmanageable above 20 users.
• MX records ready to flip to Google's mail servers.

On the planning side you need:

• A complete inventory of users, shared mailboxes, distribution lists, mail-enabled security groups, and aliases. The Microsoft side hides lots of objects that don't show up in a simple user list.
• A separate plan for calendars, contacts, and Teams. IMAP only moves mail.
• A decision on what happens to the M365 tenant post-migration — full decommission, partial keep for Teams or SharePoint, or coexistence for 90 days.

The migration in eight steps#

1. Audit the source tenant

   Run Get-Mailbox -ResultSize Unlimited | Select-Object DisplayName,PrimarySmtpAddress,RecipientTypeDetails and export to CSV. You want a definitive list of UserMailbox, SharedMailbox, RoomMailbox, and EquipmentMailbox accounts. Then Get-DistributionGroup and Get-UnifiedGroup for groups, Get-Mailbox | Where-Object {$_.LitigationHoldEnabled -eq $true} for hold accounts. Anything on litigation hold needs legal sign-off before you move it. Anything with an archive mailbox needs explicit inclusion in the migration scope.

2. Provision the Google Workspace destination

   Create Workspace users matching the Microsoft 365 primary SMTP addresses. Assign licenses, set up organizational units to mirror your M365 administrative units, and pre-create Google Groups to replace distribution lists. Give groups the same email addresses as the source distribution lists so that internal mail routing on day one doesn't break. The Google Workspace migration guide covers the broader Workspace prep in detail.

3. Register an Entra ID app for OAuth access

   In Entra ID, App registrations, New registration. Set a redirect URI matching what your migration tool expects. Under API permissions, add Office 365 Exchange Online, IMAP.AccessAsUser.All, then click Grant admin consent for <tenant>. Generate a client secret with at least 12 months of validity. Copy the tenant ID, client ID, and client secret into the migration tool. This single OAuth setup grants access to every mailbox in the tenant when authorised by an admin sign-in.

4. Handle shared mailboxes and licensing

   Shared mailboxes have no password by default and are unlicensed. Three options: (a) temporarily assign each shared mailbox a license, set a password via Set-Mailbox plus AAD password reset, migrate, then revert; (b) convert shared mailboxes to user mailboxes for the duration, then convert back; (c) use OAuth application permissions to access them without a user context. Option (c) is cleanest but requires IMAP.AccessAsApp consented at tenant level. The fix Modern Auth required guide covers the auth gotchas in detail.

5. Run a pilot batch with two test users

   Pick one heavy user (10+ GB, deep folder tree, lots of subfolders) and one light user (mostly inbox). Migrate just those two. Verify: folder tree comes across with hierarchy intact, Sent Items maps to [Gmail]/Sent Mail, Deleted Items maps to [Gmail]/Trash, Junk maps to [Gmail]/Spam, archive mailbox content (if licensed for archive) is included or excluded as you planned. Don't move on to bulk until this pilot has been live for at least 24 hours and the pilot users confirm everything is there.

6. Migrate calendars and contacts separately

   IMAP does not move calendar events, contacts, tasks, or notes. For each user, export an ICS file from Outlook (File, Open and Export, Export to a file) and import into Google Calendar via Settings, Import and export. Same for contacts: export VCF or CSV from Outlook and import into Google Contacts. For tenants with hundreds of users, scripts using Microsoft Graph to bulk-export calendars and contacts are essential — see the Office 365 migration guide for the broader playbook.

7. Run bulk batches and cut MX records

   Migrate in batches of 20–30 mailboxes. Exchange Online's tenant-level throttling caps practical parallelism at around 10–15 concurrent IMAP sessions per source tenant. Push higher and sessions start queuing. Monitor the migration tool's progress, retry any rows that fail. Once all batches are in Synced state, update MX records to point to Google (aspmx.l.google.com plus the four alt servers). Wait for TTL to expire, then run a final delta sync.

8. Validate, set up coexistence forwarding, and decommission

   Send round-trip test messages to every migrated mailbox. Configure forwarding from Microsoft 365 to Gmail for the first 30 days so any stragglers (auto-replies, legacy systems still configured with the old address) deliver successfully. Drop M365 licenses to the cheapest Exchange Online Plan 1 tier rather than full Microsoft 365. After 30 days with no missed messages reported, suspend the source accounts but keep them for another 60 days. Only delete after 90 days total.

Provider-specific gotchas#

The Microsoft side has more sharp edges than the Google side, and they all stem from the same root: Microsoft has tightened authentication and quota controls over the last three years and the docs lag the actual behavior.

Modern Authentication is required. Period. Tenants created after October 2022 have Basic Auth blocked for Exchange Online out of the box, and Microsoft has been progressively disabling it for older tenants too. If your migration tool can't do OAuth, you cannot do this migration with that tool. Some tools claim OAuth support but require Basic Auth as a fallback — confirm before committing.

Shared mailbox licensing creates a hidden cost. A shared mailbox under 50 GB is free in M365. The moment you assign a license to access it for migration, you've crossed a billing threshold for the month. Plan to license-and-revert within the migration weekend, or use application-permission OAuth to avoid licensing entirely. Don't leave temporary licenses in place — Microsoft will keep billing.

Archive mailboxes are separate IMAP folders. If users have In-Place Archive enabled, the archive content lives in a separate Exchange mailbox and is exposed as a separate IMAP folder (Online Archive - <name>). Your migration tool needs to be told to include it. If not, you'll move primary mail and miss the entire archive — discovered three weeks later when a user looks for a 2022 invoice.

Throttling tightens during business hours. Microsoft applies more aggressive throttling on IMAP migrations between 8am and 6pm in the tenant's primary region. Schedule bulk migration runs for overnight or weekends to get the highest throughput. A 200-mailbox tenant that takes 18 hours on a Saturday will take 30+ hours if you start it on a Tuesday morning.

Litigation hold and retention policies don't transfer. Mail itself moves over IMAP, but the compliance metadata that puts mailboxes on hold doesn't. If you're moving away from Microsoft for cost reasons but legal still requires holds, you need to either keep the source tenant active (with Plan 2 licenses for affected users) or export the held content to a separate compliance archive before decommissioning.

Common errors#

The errors you will see, with the actual cause behind them:

• AUTHENTICATIONFAILED — Modern Auth not enabled on the source tenant, OAuth app permissions not consented, or the user's mailbox is disabled. Run Get-CASMailbox <user> | Format-List ImapEnabled,OAuth2ClientProfileEnabled to check.
• OAuth2 token expired — The Entra app's client secret expired, or the user signed out of all sessions, or a conditional access policy revoked the token. Refresh the secret in the app registration and re-authorize.
• Too many simultaneous connections — You're past Exchange Online's tenant throttle. Drop parallelism to 10 concurrent IMAP sessions, wait 15 minutes for the policy reset, resume.
• Modern Auth required — Your tool is trying Basic Auth and the tenant blocks it. There is no per-mailbox override; either switch to an OAuth-capable migration tool or temporarily enable Basic Auth via authentication policy (requires a tenant exception ticket with Microsoft Support). The fix Modern Auth required article walks through both options.
• Folder UTF-7 conversion error — A folder name contains characters IMAP's modified UTF-7 encoding can't handle. Rename the folder in Outlook web, wait five minutes, retry.
• MailboxNotFound — The destination Google Workspace user hasn't been provisioned, or the source mailbox was deleted before the batch started. Recreate or re-license.
• Message too large for destination — Gmail's incoming IMAP message limit is approximately 50 MB. Anything over that gets skipped. Note the message IDs from the report and retrieve them manually.

Communicating with your users#

Microsoft 365 users tend to be more attached to Outlook than they realize until they have to switch. The communications plan for an M365-to-Gmail move needs to be more thorough than the reverse direction.

Three weeks ahead, send a context message: why we're moving (cost, strategy, M&A — whatever the real answer is), what changes on day one (their inbox is in Gmail, their calendar is in Google Calendar, Teams becomes Meet), and what doesn't change (their email address, their data, their access to old mail). Leave nothing implicit. The biggest source of cutover-day support volume is users who didn't realize their address was staying the same.

Two weeks ahead, do a hands-on training session. Record it. Send the recording with timestamps for the sections that matter most: composing mail, finding folders-as-labels, calendar invitations, search. The Gmail interface is not Outlook, and pretending it is causes friction.

One week ahead, send a checklist for users to complete on their own: install Gmail mobile app, install Google Calendar, set their signature, set up filters they care about. Pre-empt the "where do I set my out-of-office" question with a screenshot.

Migration weekend, follow the standard "starting, halfway, complete" pattern. Include a "frequently asked" page link with answers to: where are my folders (they're labels), where is my calendar (it's in Google Calendar, here's the link to import from M365 if you haven't), what about my Teams chat history (it doesn't move, link to your retention plan).

After cutover, run a daily support standup for the first two weeks. Track which questions keep coming up, write answers, post them to your internal FAQ. The complete email migration guide has a reusable comms template you can adapt.