How to Migrate Gmail to iCloud

Moving a Gmail mailbox to iCloud sounds like a simple IMAP-to-IMAP copy until you hit Apple's app-specific password rule, run into Gmail's label model, and notice that iCloud only gives you 5GB by default. This guide walks you through a Gmail-to-iCloud migration the way an IT admin would actually run one: prerequisites first, then a controlled IMAP transfer with the right folder mapping, then verification. You will finish with a clean iCloud mailbox that mirrors what the user had in Gmail, minus the duplication.

Why a Gmail-to-iCloud move is different from other IMAP migrations#

iCloud Mail is IMAP underneath, but Apple wraps it in two constraints that catch first-time migrators. First, normal Apple ID passwords no longer authenticate against imap.mail.me.com. You must generate an app-specific password from appleid.apple.com or migration tools will see an AUTHENTICATIONFAILED response on the very first LOGIN. Second, the standard iCloud mailbox ships with a 5GB quota shared across mail, Drive, and backups. If the Gmail source is 12GB, you have a sizing decision to make before you copy a single message.

On the Gmail side, the unusual element is labels. Gmail does not store messages in folders. A message tagged Clients/Acme and Invoices shows up in two label views plus All Mail, but it is one underlying message. iCloud, like most IMAP servers, expects real folders with one copy per folder. A naive migration that copies every label folder plus All Mail will land three copies of the same message in iCloud and burn through the 5GB quota fast.

Prerequisites and pre-flight checks#

Before you start any migration run, work through this list. Half the support tickets on this pair come from skipping one of these.

On the iCloud side#

• A working iCloud Apple ID with Mail enabled. Sign in to iCloud.com and open Mail once to confirm.
• Two-factor authentication on the Apple ID. iCloud requires it before you can generate app-specific passwords.
• Enough storage. Check Settings → Apple ID → iCloud and confirm the destination has enough free space for the Gmail source plus 15 to 20 percent headroom. Upgrade to iCloud+ first if not.
• An app-specific password generated at appleid.apple.com under Sign-In and Security → App-Specific Passwords. The string looks like abcd-efgh-ijkl-mnop. Copy it immediately because Apple never displays it again.

On the Gmail side#

• IMAP enabled in Gmail settings under See all settings → Forwarding and POP/IMAP.
• Either OAuth-based access through your migration tool (preferred) or an app password generated at myaccount.google.com under Security → 2-Step Verification → App passwords.
• A clean inventory of labels. Export the label list and decide which ones become folders, which get merged, and which are skipped.
• Disabled auto-forwarding rules if you do not want messages bouncing back to iCloud during the cutover window.

For broader context on app-specific passwords and how they differ between providers, see what an app password actually is. If you hit Google-side credential problems during the run, jump to fix Gmail app password before retrying.

The migration procedure#

The procedure below assumes you are using a desktop IMAP migration tool such as Mailbox Taxi that can connect to both providers and copy mailbox-to-mailbox. The same logical steps apply if you script it yourself with imapsync, but you lose some of the safety rails.

1. Confirm iCloud Mail is provisioned

   Open iCloud.com in a browser, sign in with the destination Apple ID, and click Mail. If you see a setup prompt asking you to choose an @icloud.com address, finish it. Mail will not accept IMAP connections until that step is complete, and the symptom looks like a generic authentication failure later.

2. Generate an Apple app-specific password

   At appleid.apple.com, sign in and go to Sign-In and Security → App-Specific Passwords. Generate one and label it Mailbox Taxi migration or similar so you can revoke it later. Apple shows the password once in the form abcd-efgh-ijkl-mnop. Save it to your password manager immediately. You will use this string, not the real Apple ID password, in the IMAP password field.

3. Audit and prepare the Gmail source

   In Gmail, open Settings → See all settings → Forwarding and POP/IMAP and make sure IMAP is enabled. Then export the label list. Decide whether you are migrating All Mail (which is everything Gmail has ever stored) or only specific labelled folders. For most users, copying labelled folders and skipping All Mail and Spam is the right call — it avoids duplicates and keeps the destination size predictable.

4. Generate Gmail credentials

   If your tool supports Google OAuth, use it. OAuth scopes are scoped per-app and easy to revoke. If you are stuck with classic IMAP auth, generate an app password at myaccount.google.com → Security → App passwords. Two-Step Verification must already be on. Save the 16-character string. If Google rejects the password later, see the dedicated troubleshooting steps for fixing a Gmail app password.

5. Map labels to iCloud folders

   This is the step most teams skip and most teams regret. Open the label list and decide:

   • Flat labels like Receipts become folders called Receipts.
   • Nested labels like Clients/Acme either become Clients/Acme (if your tool preserves nesting) or Clients - Acme (if you flatten).
   • System labels (Important, Starred, Categories) usually get skipped because iCloud has no equivalent.
   • All Mail gets skipped if you are also copying labelled folders, otherwise you double-store every message.
6. Run a small pilot batch

   Pick one user or one labelled folder with a few hundred messages and run it end-to-end. Open the result in iCloud.com Mail and the Apple Mail client. Verify: sent items appear in Sent, attachments open, dates look right (not the migration date), Unicode subjects are not mangled, and folder names are not encoded as IMAP UTF-7 strings like &AKM-. A clean pilot saves you a 6-hour rerun.

7. Run the full migration

   Kick off the full run with 2 to 4 IMAP threads per mailbox. iCloud will accept more, but it starts throttling silently above that. Monitor the log for AUTHENTICATIONFAILED, Too many simultaneous connections, and any Message too large for destination warnings. Gmail will happily send messages larger than iCloud's per-message ceiling, and those messages need to be skipped or re-uploaded as attachments manually.

8. Verify and cut over

   Compare per-folder message counts on both sides. Expect small variance for Drafts and for messages Gmail tagged with multiple labels — those should consolidate, not duplicate. Update the user's mail client to point at imap.mail.me.com (port 993, SSL) for IMAP and smtp.mail.me.com (port 587, STARTTLS) for SMTP. Tell users when to make the switch and disable any Gmail auto-forwarding rules.

Gotchas specific to this pair#

A few things will trip you up on a Gmail-to-iCloud run that would not show up on, say, Gmail-to-Outlook.

Nested labels do not always survive cleanly. Apple's IMAP server accepts folder hierarchies, but the maximum depth and the separator behaviour differ from Gmail's. If you have labels nested 4 or 5 deep, flatten them in advance. Pick a naming convention you can sort by, like Clients - Acme - 2024.

Gmail's special folders confuse iCloud clients. Folders like [Gmail]/Sent Mail, [Gmail]/Drafts, and [Gmail]/All Mail should be mapped to iCloud's Sent Messages, Drafts, and (usually) skipped. If you copy them as-is, Apple Mail shows ghost folders that look broken to the user.

Attachment limits differ. Gmail accepts attachments up to 25MB inline; iCloud's per-message limit on IMAP appends sits a little lower in practice. Messages near the ceiling can hit Message too large for destination. You can rerun those manually through Mail Drop later, but flag them so they do not silently disappear.

Time zones in headers. Gmail stores timestamps in UTC and the client converts on display. iCloud trusts the Date: header. Most of the time this is fine. Occasionally a message lands a day off; usually it is messages that were originally received through a forwarder.

Errors you will see and what they mean#

A short field guide to the errors that come up on this exact pair. Knowing the message saves you twenty minutes of guessing.

• AUTHENTICATIONFAILED on the iCloud side, despite you being sure the password is right. You are almost certainly using the real Apple ID password instead of the app-specific one. Regenerate at appleid.apple.com and try again.
• AUTHENTICATIONFAILED on the Gmail side after months of working. The app password has been revoked, often because the user changed their main Google password. Generate a fresh one.
• Too many simultaneous connections from imap.mail.me.com. You have more than 4 IMAP threads against one iCloud mailbox. Drop the concurrency.
• Mailbox full or quota-related append failures partway through. The destination iCloud quota is exhausted. Upgrade iCloud+ before resuming.
• Folder UTF-7 conversion error on Gmail labels with non-ASCII characters. Rename the label on the Gmail side, or have your tool transliterate before copying.
• OAuth2 token expired mid-run on the Gmail side. The token refresh failed. Re-authenticate and resume; messages already copied should be skipped on retry.

For a fuller reference on the IMAP terminology that comes up in these logs, see the IMAP protocol glossary.

Communicating the cutover to users#

End-user communication is where this migration succeeds or fails politically. The technical part is easy compared to telling 50 people to point Apple Mail at imap.mail.me.com on Tuesday at 6pm. A workable pattern:

A week before, send a short note explaining that mail is moving to iCloud, that they need to add the new account in Mail (or whatever client they use), and that the old Gmail address will keep working as a forwarder for 30 days. Include a one-screen setup guide with the exact IMAP and SMTP settings. The day of cutover, send a second note with a 15-minute heads-up and a contact for problems. The day after, send a "we are done, here is how to remove the old Gmail account" note.

Plan the cutover for a low-traffic window. For most teams that means after 5pm on a weekday or a Saturday morning. iCloud's IMAP server is generally fast, but the user experience of seeing 8,000 messages re-sync into Apple Mail takes a few minutes per user.

For broader strategy on planning multi-user migrations and DNS cutovers, the complete email migration guide covers the project management side. If you are running this in reverse — moving an iCloud mailbox back into Gmail — that procedure lives at migrate iCloud to Gmail. If your destination ends up being Microsoft 365 instead of iCloud, the closest reference is migrate Gmail to Outlook.