Migrate Google Workspace to iCloud Mail: 2026 IMAP Guide

You're closing the business, the contract ended, or you simply want one less subscription. Whatever the trigger, you're moving Google Workspace mail to iCloud Mail with custom domain support, and you've discovered iCloud is far stricter than Workspace ever was. Apple throttles harder, demands app-specific passwords, and runs on a folder model that doesn't agree with Gmail's label semantics. The migration is straightforward but it does not forgive impatience. This guide walks the IMAP path that actually completes without losing mail.

When iCloud is and isn't the right destination#

iCloud Mail with custom domain is built for individuals and small households. It is the right destination when:

• You're winding down a sole-proprietor business and want to keep your domain mail forever without paying business rates.
• You already pay for iCloud+ for photos and family backup, and adding mail costs nothing extra.
• You don't need shared mailboxes, group accounts, admin console, audit logs, or eDiscovery.
• You can live with 5 alias limit per domain and 3 domains per account.

It's the wrong destination when:

• You have multiple people sharing inboxes (sales@, support@). iCloud has no shared mailbox concept.
• You need compliance retention, legal hold, or eDiscovery. iCloud Mail offers none of these.
• You have heavy custom mail rules with multi-condition logic. iCloud's filter rules are basic.
• You have more than ~50 GB of historical mail. iCloud throughput will make the migration painful.

For everything else, iCloud Mail is a perfectly reasonable destination. The price-for-feature trade is right for the small-and-personal use case.

What to prepare before you start#

This is where most iCloud migrations fail. Stop and gather all of this now.

• iCloud+ subscription. Free 5 GB tier is not enough for any real Workspace migration. Pick at least 200 GB iCloud+. Subscribe in System Settings → Apple ID → iCloud → Manage.
• Custom domain added to iCloud. Settings → Apple ID → iCloud → iCloud Mail → Custom Email Domain. Add your domain, choose "You and other people use this domain" or "Only you use this domain" based on whether you'll have multiple addresses on it. Add each email address you want active on the domain.
• DNS verification records placed. Apple will give you several DNS records to add: TXT for verification, MX records, SPF, and DKIM. Place them all in your domain registrar's DNS. Don't change MX yet — that's the cutover step.
• App-specific password for migration. appleid.apple.com → Sign-In and Security → App-Specific Passwords → Generate Password. Name it "Workspace migration". Copy the 16-character password with hyphens immediately; you cannot view it again.
• Workspace admin account with mail read access. For a self-migration of one user, just your own credentials with IMAP enabled. For multi-user organisational migration, a super-admin with delegated mailbox access to each user.
• App password on Workspace too if 2FA is on. myaccount.google.com → Security → App Passwords. Generate one specifically for the migration tool.
• Inventory of Gmail labels and their message counts. Use Gmail's Settings → Labels view or the Gmail API. This becomes your verification checklist.

Server settings#

Google Workspace IMAP (source):

• Server: imap.gmail.com
• Port: 993
• Encryption: SSL/TLS
• Username: full email address
• Password: account password or app password if 2FA is on

iCloud Mail IMAP (destination):

• Server: imap.mail.me.com
• Port: 993
• Encryption: SSL/TLS
• Username: full address with your custom domain (you@yourdomain.com)
• Password: the 16-character app-specific password

Some migration tools default to mail.me.com (no imap. prefix) which still works but is being phased out. Use imap.mail.me.com to avoid future breakage.

Label-to-folder mapping: the biggest planning problem#

Gmail's labels are not folders. A single message can have any number of labels. iCloud has folders, and a message is in exactly one folder. This mismatch is the single biggest source of mistakes in Workspace-to-iCloud migrations.

Three sane strategies:

1. One-folder-per-label with duplicates. Default behaviour of most IMAP tools. A message with 3 labels appears 3 times in iCloud, one in each folder. Search and threading still work; storage is inflated by ~15-30% for label-heavy users.
2. Inbox-only. Skip labels entirely; copy everything to iCloud Inbox. Loses organisation but cuts migration time and storage in half.
3. Primary-label-only. Choose one "primary" label per message (most recent applied, or alphabetically first). One copy per message; structure mostly preserved but you lose the multi-label richness. Best for technical users who can pre-process via Gmail API.

Pick strategy before you migrate, not during. Re-running is expensive.

Gmail concept	iCloud equivalent	Notes
Inbox label	Inbox folder	Direct map
Sent label	Sent Messages	Sent flag preserved
Drafts label	Drafts	Migrated but rarely useful
Trash	Trash	iCloud auto-purges after 30 days
Spam	Junk	iCloud re-classifies on its own filter
Custom labels	Custom folders	Each label becomes a folder
Nested labels (work/clients/acme)	Nested folders	Forward-slash delimiter both sides
Starred	Flagged	Direct flag map
Important	(lost)	Gmail's importance markers don't translate

The Important marker has no iCloud equivalent. Star/flag does map cleanly.

Step-by-step migration#

1. Verify iCloud Mail with custom domain is fully active

   Send a test mail from any outside address to you@yourdomain.com. It should arrive in iCloud Mail web at icloud.com/mail. If it doesn't, your DNS verification or MX records haven't propagated. Check at mxtoolbox.com. Do not start the migration until inbound mail flows correctly.

2. Confirm both IMAP endpoints connect

   Add the source Workspace account and the destination iCloud account to a throwaway IMAP client like Thunderbird. Watch them sync at least one folder each. If either fails to connect, your migration tool will fail too. The fix is always credentials — re-generate the app password.

3. Decide and apply your label strategy

   Choose duplicate-per-label, inbox-only, or primary-label-only. If primary-label-only, run a Gmail API script first to remove all-but-one label from every message. This is irreversible on the source side, so back up first or operate on a copy.

4. Run a pilot of one small label

   Pick a small label with 100–300 messages, ideally a project archive you no longer use. Migrate just that label to iCloud. Validate: folder appears in iCloud Mail web, counts match, attachments open, dates preserve. If any of these fail on 100 messages, they will fail on 50,000.

5. Run the full migration single-threaded

   Set your tool to one connection per account, 100-message batches. iCloud throttles per account, not per connection, so adding parallelism doesn't help. A 50 GB Workspace mailbox typically takes 2–3 full days of wall-clock runtime. Plan accordingly and don't expect overnight completion.

6. Reconcile counts and re-run gaps

   Compare folder-by-folder counts between Workspace and iCloud. Small discrepancies (1–3 messages) are usually drafts being edited or messages being sent during the migration. Anything larger needs a re-run of the affected folder.

7. Cutover MX records

   Once counts reconcile, update DNS MX records to point at iCloud's MX (mx01.mail.icloud.com and mx02.mail.icloud.com with priorities 10 and 20). Keep Workspace running for at least 30 days post-cutover as a safety net via forwarding.

Errors you'll see in production#

Real errors and what they mean:

• AUTHENTICATIONFAILED Invalid credentials on iCloud — almost always means you used your Apple ID password instead of the app-specific password. Regenerate the app password and retry.
• Too many simultaneous connections on iCloud — you exceeded 4 concurrent IMAP sessions per account. Drop to 1.
• Message too large for destination — iCloud caps incoming IMAP messages at 20 MB. Workspace caps outbound at 25 MB. Messages above 20 MB will fail. Either re-create them with attachments removed or accept the loss and log failed message IDs.
• OAuth2 token expired on Workspace — your Google session expired. If your tool uses OAuth, refresh; if app password, this shouldn't happen — re-check.
• STARTTLS handshake failed on iCloud — your migration tool is using port 143 with STARTTLS instead of port 993 SSL/TLS. Apple deprecated 143; use 993.
• Folder UTF-7 conversion error — non-ASCII label names. Rename source labels to ASCII or accept mangled folder names in iCloud.

What does not move#

Set expectations up front:

• Google Calendar events. Export as ICS from calendar.google.com, import into iCloud Calendar via Calendar.app.
• Google Contacts. Export as vCard from contacts.google.com, import into iCloud Contacts.
• Google Drive files. Completely separate. Either keep them in Drive permanently, or use a Drive-to-iCloud-Drive sync tool.
• Gmail filters. iCloud's filter syntax is much simpler. Rebuild the top 10 manually; let the rest go.
• Mailbox delegation. Workspace's "give Alice read access to my mail" doesn't exist in iCloud at all.
• Google Groups membership. No iCloud equivalent. The address dies on cutover.
• Aliases beyond five per domain. iCloud caps at 5 aliases per domain. Heavy alias users (devs with one address per service) will need to consolidate.

A desktop tool versus the alternatives#

You have three real options for this migration:

1. iCloud's "Add Another Account" import. Apple Mail can connect to Gmail and copy messages, but the throughput is even worse than direct IMAP, and the folder-to-label mapping is poor. Useless for anything beyond a couple of thousand messages.
2. A cloud SaaS migration service. Works, but you hand both credentials to a third party. Overkill for a single personal-style migration.
3. A desktop IMAP migration tool like Mailbox Taxi. Runs locally, both providers see direct IMAP from your IP, no mail leaves your network in transit. You pay once, run it as many times as you need, pause and resume around iCloud's throttling.

For broader context on the destination side, the Workspace to Apple ecosystem migration is the closest sibling guide (Outlook to iCloud Mail covers similar territory from the Microsoft side). The reverse direction is covered in iCloud to Gmail migration. For a tenant-to-tenant move rather than to personal iCloud, see Workspace to Microsoft 365. The Apple app-specific password reference is essential reading before the migration starts. And the Google Workspace migration guide covers planning that applies regardless of destination.

Post-cutover checklist#

In the first 48 hours after MX cutover:

• Send test mail from an external account to you@yourdomain.com. Confirm arrival in iCloud Mail.
• Check Workspace's mail flow report to confirm no mail is still landing there. If it is, your DNS propagation isn't complete — wait another 6–12 hours.
• Update reply-to in iCloud Mail settings to your custom domain address (not the default @icloud.com).
• Update password recovery email on critical accounts (bank, government, work) to the new iCloud address.
• Verify Junk folder daily for the first week — iCloud's first-time spam classifier is aggressive.
• After 60–90 days of confirming nothing breaks, decide whether to keep Workspace running as a safety net or fully cancel.

The fragile dependency here is the iCloud app-specific password. If Apple invalidates it (Apple ID password change, suspicious activity flag, password aged out), the migration halts. Store it in a password manager and revoke it explicitly the moment the migration ends.