The Ultimate Step-by-Step Guide to a Proven Zero-Downtime Email Migration from Google Workspace to Microsoft 365.

TL;DR / Hook

Email migrations between Google Workspace (GCP) and Microsoft 365 are common but full of small gotchas: authentication failures, throttling, label→folder mapping, DNS cutover mistakes, and unexpected costs or downtime. This post walks through the most frequent problems, real-world troubleshooting steps, commands and checks you can run, and a migration checklist to reduce risk.

Who this is for

IT admins, migration engineers, MSPs and SREs performing mailbox migrations between Google Workspace and Microsoft 365 (both directions). Assumes working knowledge of admin consoles, basic networking, DNS, and command line.

Migration scenarios covered

a. Google Workspace → Microsoft 365 (common “move to M365” scenario)

b. Microsoft 365 → Google Workspace (repatriation or multi-tenant reasons)

c. Hybrid / coexisting mail during staged cutover (MX split, coexistence)

 

1. Pre-migration planning checklist (do this first)

• • Inventory mailboxes (size, labels, aliases, delegates, shared mailboxes).

• • Pick migration method: Microsoft Data Migration Service (built-in), IMAP migration, third-party tools (BitTitan, Quest), or PST export/import.

• • Confirm admin access in both tenants (super admin / global admin roles, API access).

• • Check authentication model: OAuth vs basic auth. Modern tools prefer OAuth.

• • Plan MX cutover window and TTL reduction (set low TTL 24–48 hours before).

• • Backup/export critical mailboxes (PST or archived copy).

• • Communicate outage windows & fallback plans with stakeholders.

• • Test with 1–3 pilot mailboxes (small, medium, edge case like very large mailbox).

2. Common issues you’ll see (summary)

1. Authentication / permission failures (scoped OAuth, 2FA, blocked access)
2. IMAP connectivity / TLS handshake failures
3. Throttling / rate limits (source or target)
4. Label → folder / nested labels mapping issues
5. Large mailbox performance / timeouts / partial migrations
6. DNS / MX / Autodiscover / SPF / DKIM / DMARC misconfig after cutover
7. Calendar/contacts not migrated or duplicated
8. Missing permissions for shared mailboxes or delegated access
9. Message format issues (inline images, migration of attachments, truncated messages)

 

We’ll now walk through each with step-by-step diagnosis and fixes.

3. Troubleshooting — detailed steps (by issue)

---

A. Authentication & permission failures

Symptoms: email migration tool reports “authentication failed”, “invalid credentials”, or you see constant 401/403 errors.

Diagnosis

1. Confirm admin account used has required privileges on source and target (super admin / global admin).
2. Check whether the migration method uses OAuth2 (recommended) or legacy basic auth. Many providers are disabling basic auth.
3. For Google Workspace → M365: verify the Google Workspace admin has enabled API access (Admin console → Security → API controls), and that you created and granted the appropriate OAuth scopes if using service-account delegation.
4. For M365 → Google Workspace: ensure service account / OAuth client is allowed and the Gmail API is enabled.
5. Check conditional access / MFA policies in Microsoft Entra (Azure AD) that might block the migration account.
6. Inspect audit logs in both admin consoles for rejected auth attempts and reason codes.

Fixes

1. Use OAuth-based migration endpoints whenever possible (Data Migration in Microsoft 365 supports Google Workspace via OAuth).
2. If using delegated service account on Google side: create a service account, enable domain-wide delegation, and grant the following minimum scopes (example): https://mail.google.com/ and https://www.googleapis.com/auth/admin.directory.user.readonly (adjust per tool).
3. For Microsoft side, allow the migration account in conditional access (or exclude it during migration windows), or create a dedicated migration account with MFA disabled (or use app-passwords where supported) and re-enable MFA afterward.
4. Revoke stale tokens and re-authorize the migration tool.

Quick checks / commands

• • From a workstation, verify you can OAuth login to the admin UIs.

• • For Exchange Online: Connect-ExchangeOnline -UserPrincipalName admin@contoso.com (PowerShell) to validate creds & connectivity.

• • On Google: Admin console → Security → API controls → View Third-party app access.

---

B. IMAP connectivity / TLS handshake failures

Symptoms: “Cannot connect to imap.gmail.com:993”, TLS errors, “connection refused” or “certificate verification failed”.

Diagnosis

1. Network layer: is port 993 (IMAP SSL) outbound open from the migration host? Are proxies or firewalls interfering?
2. DNS resolution of imap.gmail.com or imap.gmail.com resolving to a blocked IP?
3. TLS: older clients may not support current TLS versions.
4. Check rate-limiting or temporary blocks from the source endpoint.

Fixes

1. Test connectivity from migration host:

1. 1. 1. • Linux: openssl s_client -connect imap.gmail.com:993 -crlf — confirm a valid certificate and successful handshake.
      • • Windows: Test-NetConnection -ComputerName imap.gmail.com -Port 993 (PowerShell).
      • • Or telnet imap.gmail.com 993 (shows whether TCP is reachable; TLS test still needs openssl).

1. If proxies block TLS inspection, bypass for migration host or add exception for imap.gmail.com.
2. Ensure the migration tool is using SSL/TLS and correct port.
3. Retry after a short interval if Google temporarily blocks connections due to suspicious traffic.

---

C. Throttling and rate limits

Symptoms: Migration stalls or shows repeated transient errors, “429” responses, or very slow throughput.

Diagnosis

• • Check the migration tool logs for HTTP 429/503 errors.

• • Check source provider’s admin console for throttling alerts.

• • Identify if many parallel threads are used (too many simultaneous mailbox connections).

Fixes

• • Reduce concurrency (threads/parallel migrations) — use small batches.

• • Schedule migrations off-peak when source/target services are less busy.

• • For Microsoft 365: use migration batches and limit concurrent migration users. Tools like BitTitan have auto-throttle settings.

• • Consider staged migration: small batches, then larger.

• • If necessary request quota / rate increases with provider support (rarely granted but possible for large enterprise migrations).

---

D. Label → Folder mapping & missing messages

Symptoms: Many messages seem not to appear in Outlook/Exchange; some emails only visible in Gmail label view.

Cause: Gmail uses labels (an email can have multiple labels). IMAP and Exchange use folders. A message with multiple labels may map to multiple folders or be skipped depending on tool mapping.

Diagnosis

• • Compare message counts: in Gmail web UI check total messages under “All Mail” vs. in migrated mailbox in Outlook.

• • Check migration logs for skipped items or conversion errors.

Fixes

• • Use a migration tool that understands Gmail labels and maps them to folders correctly (Microsoft Data Migration Service handles this for Google Workspace if used correctly).

• • If using IMAP migration, ensure mapping settings treat Gmail “All Mail” as primary source, and avoid double-migrating identical messages (deduplication).

• • Post-migration: run an item count reconciliation script (PowerShell) comparing counts and flag high-value mailboxes for manual inspection.

Workaround for duplicates: instruct end users to compact folders / remove duplicates using mailbox tools, or use dedupe utilities.

---

E. Large mailbox timeouts / partial migrations

Symptoms: Big mailboxes never finish or time out mid-migration; attachments > certain size fail.

Diagnosis

• • Check migration logs for “timeout” entries or partial completion statuses.

• • Confirm migration tool timeouts and maximum message size settings.

Fixes

• • Break large mailboxes into smaller chunks where possible (archive older mail to PST and migrate separately).

• • Increase migration tool timeout thresholds or use a tool that supports chunked transfer / resume.

• • For very large attachments, consider migrating attachments to SharePoint/OneDrive and link from mail, or migrate mail body only then attachments separately.

• • Ensure sufficient bandwidth and that no intermediate NAT/proxy is killing long connections.

---

F. DNS / MX / Autodiscover / SPF / DKIM / DMARC issues after cutover

Symptoms: Mail being rejected, SPF failures, Autodiscover not pointing to new tenant, some inbound still arriving at old system.

Diagnosis

1. • Confirm MX record change and check propagation (nslookup -type=MX domain.com or online DNS checker).

• • Check SPF record includes new provider IP ranges or services.

• • Verify DKIM keys have been added to DNS for the new provider.

• • Test Autodiscover behavior for Exchange/Outlook (Test E-mail AutoConfiguration in Outlook, or Test-OutlookWebServices via PowerShell).

Fixes

• • Before cutover: lower MX TTL to short window (e.g., 300–3600 seconds) 24–48 hours prior. After cutover, keep old MX for a short period to catch stragglers.

• • Update SPF TXT to include include:spf.protection.outlook.com (for M365) or Google’s include for Google Workspace. Update to reflect both during coexistence.

• • Publish DKIM for the target tenant and enable it in the admin console.

• • Publish / update DMARC policy if used. Start with p=none if uncertain and monitor.

• • For Outlook Autodiscover: update SCP records and verify Autodiscover DNS CNAMEs are correct.

---

G. Calendar & Contacts migration issues

Symptoms: Missing meetings, duplicate events, or missing attendees; contacts lacking fields.

Diagnosis

• • Check whether the migration tool migrated calendar/contacts or only mail.

• • Compare counts on both sides and inspect sample missing event metadata for differences (recurrence rules, organizer info).

Fixes

• • Use tools that explicitly support calendar & contacts migration (Microsoft/Google migration utilities or third-party tools).

• • For recurring meetings with external organizers, sometimes re-invite may be required if organizer identity changed; communicate this to users.

• • Manual export/import using ICS or vCard for specific problem mailboxes as a last resort.

---

H. Shared mailboxes & delegated access not migrated

Symptoms: Shared mailboxes not present or permissions broken.

Diagnosis

• • Verify whether shared mailboxes were included in migration scope — some tools ignore resource/shared mailboxes by default.

• • Check source mailbox permissions and whether delegation is via group or direct permissions.

Fixes

• • Explicitly include shared/resource mailboxes in migration batch; for Google, resource calendars are special objects that may need separate handling.

• • After migration, reapply permissions (automate with PowerShell for Exchange Online):
    
    • • Example: Add-MailboxPermission -Identity "SharedMailbox" -User "user@contoso.com" -AccessRights FullAccess

• • Document delegation and reapply.

---

I. Message formatting / attachments problems

Symptoms: Inline images broken, attachments missing or corrupted.

Diagnosis

• • Check migration logs for conversion warnings.

• • Identify whether transport conversions (MIME to MAPI) caused issues.

Fixes

• • Use email migration tools that preserve MIME structure or perform careful conversion testing.

• • For problematic messages, export the raw message (EML/MBOX) from source and import into target where possible.

---

4. Migration monitoring & verification (what to run during and after)

• • Email Migration batch status (Exchange Online): Get-MigrationBatch & Get-MigrationUser -BatchId <batch>

• • Message tracing: use message trace in M365 Security & Compliance center for delivery issues.

• • Connectivity tests: Test-NetConnection (PowerShell) for ports; openssl s_client for TLS.

• • DNS checks: nslookup -type=MX domain.com, dig (Linux) and external checkers.

• • End user validation: create a validation checklist for pilot users: send/receive, calendar invites, search across mail, mobile sync.

• • Audit logs: confirm no unexpected administrative changes.

---

5. Post-migration hardening & cleanup

• • Remove or retire old MX records after a safe window.

• • Decommission legacy mail servers only after verifying mail flow and archiving.

• • Reapply security controls (MFA, conditional access, baseline policies) on migration accounts.

• • Configure retention, labeling and archiving in the new tenant.

• • Educate users: new login flows, mobile reconfiguration, and where to find archived mail if archived separately.

---

6. Quick reference commands & checks

Exchange Online PowerShell

# Connect
Connect-ExchangeOnline -UserPrincipalName admin@contoso.com

# Get migration batch status
Get-MigrationBatch | Format-Table Identity,Status,TotalCount,CompletedCount -AutoSize

# Get users in a migration
Get-MigrationUser -BatchId "GoogleToM365Batch1" | ft EmailAddress,Status

# Reapply full access permission (example for shared mailbox)
Add-MailboxPermission -Identity "shared@contoso.com" -User "user@contoso.com" -AccessRights FullAccess

Connectivity tests (Windows PowerShell)

# Test TCP connectivity
Test-NetConnection -ComputerName imap.gmail.com -Port 993

# DNS MX lookup
Resolve-DnsName -Name contoso.com -Type MX

OpenSSL TLS test (Linux/macOS)

openssl s_client -connect imap.gmail.com:993 -crlf

---

7. Real-world troubleshooting playbook (step-by-step for a failing migration)

1. • Reproduce with a pilot: choose a mailbox that fails and create a small controlled test.

• • Read logs: email migration tool logs, Exchange/Microsoft diagnostic logs, Google Admin audit logs. Capture error codes.

• • Validate connectivity: telnet/openssl/Test-NetConnection to the source IMAP/API endpoint.

• • Validate auth: open a browser and log in as the migration account to both admin consoles; check for second-factor or conditional access blocks.

• • Reduce scope: try migrating a single folder or a subset of messages to isolate problematic messages.

• • Check for throttling: reduce concurrency and retry.

• • Check message size & special items: search for very large messages or malformed messages in source mailbox. Migrate without attachments to test.

• • If problem persists, escalate: open ticket with the source or target provider (include logs, sample message IDs, timestamps). Provide a sample message exported as EML/MBOX for deeper troubleshooting.

• • Apply workaround: if tool cannot migrate some content, export to PST/EML and import manually; document any data loss or limitations for stakeholders.

---

8. Email migration runbook

1. • T−48h: Lower MX TTL to 300–3600s. Notify users.

• • T−24h: Run discovery & inventory, create mapping CSV for migration tool, grant API permissions.

• • T−12h: Run pilot (3 mailboxes), test send/receive, calendar.

• • Cutover window: Start migration batches, monitor logs, reduce concurrency if errors.

• • Post cutover (0–72h): Monitor message trace, reconfigure mobile devices, update DNS TTL back to normal.

• • 2 weeks after: Decommission old servers once no mail is observed and stakeholders sign off.

---

9. Email Migration checklist

• • Inventory complete (mailbox sizes, delegates, shared mailboxes)

• • API & OAuth permissions configured on source and target

• • Pilot migration completed and validated (3 users)

• • MX TTL lowered and documented

• • Backup/export taken for critical mailboxes

• • Migration batches created and scheduled

• • Monitoring dashboards configured (migration, message trace, DNS)

• • Post-migration authentication & security policies reapplied

• • Communication plan executed with end users (instructions to reconfigure Outlook / mobile)

10. Recommendations

• • Always perform a pilot and monitor logs carefully — most surprises surface in pilot.

• • Use vendor migration tools where possible (Microsoft has built-in tools for Google Workspace target), or trusted third-party vendors for complex environments.

• • Treat calendar and shared resource migration as first-class items — they often break workflows if mishandled.

• • Keep a rollback plan and retain the old mail path for a short window to catch stragglers.

• • Automate repetitive post-migration tasks (permissions, licenses, reassignments) with PowerShell or scripts.