How to Migrate iCloud Mail to Gmail

iCloud Mail is fine for casual use, but the moment someone needs server-side rules, label-based organisation, or shared inboxes they outgrow it. Gmail and Google Workspace cover those gaps, and the migration itself is mostly a straight IMAP copy. The hard parts are Apple's app-specific password requirement, the 5 GB iCloud free quota that quietly shapes what is even available to move, and the choice between personal Gmail's import wizard and Workspace's Data Migration Service. This guide walks the whole iCloud to Gmail path so you finish with mail in the right inbox and no surprises.

Prerequisites on both sides#

Both ends of this migration are quiet about their requirements until you hit them. Get these in place first.

iCloud source prerequisites#

• The Apple ID has two-factor authentication enabled. Without 2FA, the app-specific password option does not appear at appleid.apple.com.
• The iCloud Mail service is active on the Apple ID. Some Apple IDs have iCloud Mail switched off; sign in to iCloud.com first and confirm the Mail app loads.
• You know the canonical iCloud address. Accounts created years ago may use @me.com or @mac.com aliases that still work for sign-in but should not be used as the IMAP username.

Gmail or Workspace destination prerequisites#

• For personal Gmail, the destination Gmail account exists and you have the password. Gmail's Mail import wizard runs inside the destination account.
• For Google Workspace, you are a super admin in the destination domain and the Data Migration Service is enabled. Workspace also requires the destination users to exist before the DMS run.
• The destination has enough free space. Personal Gmail's 15 GB shared quota is almost always enough for an iCloud source.

Why iCloud to Gmail looks easier than it is#

On paper this is one IMAP source talking to one IMAP destination. In practice, four things tend to bite teams the first time they run it.

• App-specific passwords expire silently. Apple invalidates the password if the Apple ID password changes or if the user disables 2FA. A long-running migration may suddenly start failing with AUTHENTICATIONFAILED after a user does either thing on their iPhone.
• iCloud's 5 GB free quota is shared. Mail, photos, and device backups all share the same quota. Some iCloud mailboxes have effectively no historical mail because the user filled the quota with photos and iCloud quietly stopped delivering. You may find less to move than you expected.
• Aliases are not always migrated. iCloud lets users add up to three email aliases to a single mailbox. Mail to those aliases lives in the same store and moves with the rest, but the alias addresses themselves do not transfer to Gmail. Senders who use the alias need to be redirected separately.
• Read state and flags behave differently. Gmail labels are not folders. A message read in iCloud comes across as read in Gmail, but a flagged message in iCloud becomes a starred message in Gmail only when you select the right import option.

If you are also moving in the opposite direction for a different user, the Gmail to iCloud migration guide covers the same connection in reverse.

Step-by-step migration#

1. Audit the iCloud source

   Sign in to iCloud.com using the Apple ID and open Mail. Note the folders in the sidebar, including any nested folders and the system folders (Sent, Drafts, Junk, Trash, Archive). Open Settings on iCloud.com and check the storage breakdown — if Mail is using less than 100 MB, the user probably has most historical mail on a local Apple Mail client only, and you should check the Mac before assuming the server copy is complete.

2. Generate an app-specific password

   Browse to appleid.apple.com, sign in, choose Sign-In and Security, then App-Specific Passwords. Click Generate Password, label it something like mailbox-taxi-migration, and Apple returns a string in the format xxxx-xxxx-xxxx-xxxx. Use the password including the hyphens. Save it in a secure store; Apple will not show it again. The app password glossary entry covers why this exists and when it expires.

3. Choose the destination path

   For a single personal Gmail account, open Gmail, go to Settings, See all settings, Accounts and Import, and choose Import mail and contacts. This wizard accepts an IMAP source directly. For Google Workspace, sign in to admin.google.com, open Account, Data Migration, and set up a new migration. For one-off moves where you do not want to plug an Apple ID into Google's web UI, use a local tool like Mailbox Taxi. The technical mechanics in the complete email migration guide cover the trade-offs.

4. Configure the source connection

   Set the IMAP host to imap.mail.me.com, port 993, SSL required. The username is the full iCloud Mail address (user@icloud.com, not just user). The password is the 16-character app-specific password including the hyphens. If you see AUTHENTICATIONFAILED, verify that the address is the canonical one — @me.com aliases sometimes refuse to authenticate even when they receive mail correctly. The IMAP protocol glossary explains why the port and SSL settings matter.

5. Run a pilot account

   Move one iCloud mailbox into Gmail first. After the run completes, sign in to Gmail and confirm:

   • The number of messages in each label matches the source folder count.
   • Sent maps to Sent Mail and not a custom label called Sent.
   • Attachments open cleanly. Inline images render in the body, not as broken links.
   • Read and unread state matches the source.
   • Starred or flagged messages came across with the star intact.

   If anything is off, fix the configuration before scaling up. Re-running a single account is cheap; re-running 50 is not.

6. Run remaining migrations

   For Workspace DMS, point the migration at the source CSV (one row per user with the iCloud username and app-specific password) and let DMS process them in parallel. For local tools, batch the accounts in groups of 10 or so to keep an eye on each run. iCloud does not publish formal throttle limits, but expect approximately 300 to 500 MB per hour per connection in real-world conditions. Let incremental syncs run until the day of cutover so newly arrived mail does not need a manual sweep.

7. Switch where new mail arrives

   The migration itself does not redirect new mail. To stop the iCloud inbox from receiving anything new, log into iCloud.com, open Mail Preferences, and set up forwarding to the Gmail address. Tick the box to delete forwarded mail from iCloud so storage does not fill up. In Gmail, add the iCloud address under Settings, Accounts and Import, Send mail as so users can still reply from the iCloud identity if needed. Tell the user to update their address in any high-priority services manually.

8. Decommission the iCloud connection

   Once you are confident the move is complete, revoke the app-specific password at appleid.apple.com. Remove the iCloud account from Apple Mail and Outlook on the user's devices, or leave it configured if they want a local archive. Archive the migration logs to evidence storage — they are your only record of skipped messages or quota failures. If you plan to close the Apple ID, wait at least 30 days after the forwarding switch so any straggler senders have time to be redirected.

iCloud-specific gotchas#

These are the issues that come up repeatedly. None of them is a deal-breaker if you plan for it.

The 5 GB free quota story#

iCloud's free tier is shared across mail, photos, and device backups. Many users with full iCloud Photo Libraries have no quota left for mail, and iCloud Mail silently bounces new messages with a non-delivery report. By the time you arrive, the source mailbox may have nothing newer than the last day the quota had headroom. Check the bounce history with the user before assuming the migration captured everything.

The @me.com and @mac.com alias trap#

Apple keeps legacy aliases working forever. A user whose mailbox is technically dan.okafor@icloud.com may receive most of their mail at dan.okafor@me.com. The IMAP server treats both as the same store, but only the canonical @icloud.com form authenticates reliably as a username. Always use the @icloud.com form in the migration config.

Apple Mail's local-only folders#

If the user has been running Apple Mail with On My Mac mailboxes, those folders never touched iCloud and the IMAP migration cannot see them. Walk the user through dragging those mailboxes back into the iCloud account before the move, or export them to mbox and import to Gmail separately.

Family Sharing accounts#

When the Apple ID is part of a Family Sharing group, the iCloud Mail quota may behave differently than the storage indicator suggests. Confirm that the user's own quota is not exhausted because of another family member's photo library.

Errors you will actually see#

• AUTHENTICATIONFAILED — usually the app-specific password is wrong or the source address is the wrong alias. Regenerate the password and try the canonical @icloud.com form.
• OAuth2 token expired — only relevant on the Gmail destination if you authenticated via OAuth. Re-authorise the destination connection in Gmail's Accounts and Import settings.
• Folder UTF-7 conversion error — a folder name uses characters that the legacy IMAP folder encoding does not handle. Rename the folder in iCloud and rerun the affected segment.
• Message too large for destination — Gmail accepts up to 25 MB per attachment by default. iCloud allows up to 20 MB outbound but can store larger inbound messages, so occasional skips are possible. Log them and decide case by case.
• Too many simultaneous connections — iCloud throttled the connection. Reduce the parallel connection count and let the tool retry.

Communication plan for the end user#

Users do not care about IMAP. They care about whether their mail is in the right place tomorrow.

• Tell them the cutover date and what to do with new mail in the meantime. If you set up forwarding from iCloud to Gmail, they can keep using the iCloud address until the world catches up.
• Walk them through removing the iCloud account from their phone's Mail app and adding the Gmail account in its place, or installing the Gmail app if they prefer.
• Remind them that calendar entries and contacts stored in iCloud do not move with mail. Those need a separate export and import, and you should set expectations clearly.
• Send a short follow-up two days after cutover asking whether anything looks off. Most issues that get reported in week two could have been caught with one targeted email.

When to use Mailbox Taxi instead#

Gmail's import wizard and the Workspace Data Migration Service work well for clean, one-direction moves. They struggle when the source is a personal Apple ID with quirky aliases, when you need to migrate into a destination you do not fully control, or when the user is the IT person and does not want to plug their Apple credentials into a web-based migration tool. Mailbox Taxi runs locally, keeps credentials on the device, and handles the iCloud IMAP source through a familiar wizard. The iCloud to Office 365 path is a useful reference when the destination is Microsoft instead of Google.