Migrate Fastmail to iCloud Mail: IMAP Walkthrough

iCloud Mail is what people move to when they've already committed to the Apple ecosystem and want their mail living next to their photos, notes, and calendars. The migration mechanics are straightforward — both Fastmail and iCloud speak standard IMAP, both use app passwords, no Bridge or OAuth dance needed — but iCloud has the slowest IMAP throughput of any major provider and the lowest concurrent-connection ceiling. Plan for the job to take longer than it would to any other destination and configure Mailbox Taxi accordingly.

Why iCloud is the slowest destination#

A Fastmail-to-Gmail migration runs at roughly 60–90 minutes per gigabyte. Fastmail-to-Office-365 runs at 60–120 minutes per gigabyte. Fastmail-to-iCloud routinely runs at 120–180 minutes per gigabyte, sometimes longer.

Two reasons. First, iCloud's IMAP server is notoriously conservative with APPEND throughput — somewhere around 1–2 messages per second per connection, where Gmail can usually sustain 2–3. Second, iCloud only tolerates 2–4 concurrent IMAP connections per account before it starts forcing disconnects. Mailbox Taxi defaults to higher parallelism on other providers; for iCloud you'll lower it to 2 and accept the wall-clock cost.

The throughput limit isn't a Mailbox Taxi issue or a Fastmail issue. It's an architectural choice on Apple's end — iCloud Mail isn't a workhorse archive service, it's a consumer mailbox for people who happen to use Apple devices. The throttling protects shared infrastructure.

Before you start#

Four prerequisites:

• A Fastmail account on any paid tier with an app password generated for IMAP.
• An Apple ID with 2FA enabled. Without 2FA, you cannot create app-specific passwords.
• An iCloud Mail account active on that Apple ID — check icloud.com/mail to confirm.
• Enough iCloud storage. 5 GB free, 50 GB / 200 GB / 2 TB / 6 TB / 12 TB on iCloud+ tiers. Pick a plan with at least 1.2x your Fastmail mailbox size, then add headroom for Photos and Drive.

The single biggest cause of failed Fastmail-to-iCloud migrations is running out of iCloud storage partway through because Photos was eating the quota.

Step-by-step migration#

1. Check iCloud storage quota

   Sign in at icloud.com, click your name in the top right, and open Account Settings → Storage. You'll see total available storage and what's currently using it. Subtract the current usage from the total — that's what's available for mail. Compare to your Fastmail mailbox size (Settings → Account → Storage in Fastmail).

   If you don't have enough headroom, upgrade your iCloud+ plan before going further. Plans bump up at 50 GB, 200 GB, 2 TB, 6 TB, and 12 TB. The 200 GB tier is the sweet spot for most users coming from a 10–50 GB Fastmail archive.

2. Enable 2FA and generate an iCloud app-specific password

   Go to appleid.apple.com and sign in. Open Sign-In and Security. If two-factor authentication is off, turn it on now — there's no path to app-specific passwords without it. Apple will walk you through verifying a trusted phone number.

   Once 2FA is on, scroll to App-Specific Passwords and click "Generate an app-specific password". Name it "Fastmail migration" and click Continue. Apple shows a 16-character password (formatted as xxxx-xxxx-xxxx-xxxx with hyphens). Copy it — including the hyphens. iCloud's IMAP server accepts the password with or without the hyphens, but copying it as Apple displays it avoids confusion.

   For more on app passwords across providers, the app password glossary entry covers the landscape.

3. Generate a Fastmail app password

   In Fastmail on the web, go to Settings → Privacy & Security → App passwords. Create a new app password named "iCloud migration", grant IMAP & POP access only, and copy the 16-character password Fastmail generates. Like Apple's, it's only shown once.

4. Configure the migration in Mailbox Taxi

   Source: Fastmail. Host imap.fastmail.com, port 993, SSL/TLS. Username: full Fastmail address. Password: Fastmail app password. Test.

   Destination: iCloud. Host imap.mail.me.com, port 993, SSL/TLS. Username: the part of your iCloud address before the @ — so for yourname@icloud.com, use yourname. (iCloud's IMAP server expects the local part, not the full address. This trips people up.) Password: the app-specific password from step 2. Test.

   In Mailbox Taxi's per-job settings, lower the concurrent-connection count to 2 for the destination. iCloud's connection ceiling is lower than other providers and forcing 4+ concurrent connections will trigger disconnects within a few minutes.

5. Map Fastmail folders to iCloud folders

   Mailbox Taxi proposes a folder map. iCloud's system folders (Inbox, Sent Messages, Drafts, Archive, Junk, Deleted Messages) map to the obvious Fastmail equivalents. Custom Fastmail folders become custom folders on iCloud at the root level.

   Things to consider:

   • Spam → Junk on iCloud. Usually exclude unless you have a reason to keep it.
   • Trash → Deleted Messages on iCloud. Almost always exclude.
   • Archive — iCloud has an Archive folder. Fastmail's Archive maps cleanly.
   • Deep nesting — iCloud handles nested folders but very deep hierarchies (10+ levels) sometimes display oddly in Apple Mail. Consider flattening anything past 5 levels.
   • Long folder names — iCloud is more conservative about folder name length than Fastmail. Names over 64 characters may get truncated.
6. Dry-run a single folder

   Pick a folder with 50–200 messages. Migrate only that one. Open icloud.com/mail and verify the messages arrived with correct subjects, dates, senders, attachments, and HTML rendering. Pay special attention to attachments — iCloud's web UI handles them slightly differently from Fastmail, and oversized attachments may have been rejected silently.

7. Run the full migration with reduced concurrency

   Kick off the full job with 2 concurrent connections to the destination. Expect 120–180 minutes per gigabyte. Leave the workstation awake and Mailbox Taxi running.

   Monitor for Too many simultaneous connections from iCloud. If you see them with concurrency already at 2, lower to 1 — slower but stable. iCloud occasionally drops connections silently rather than returning an error; Mailbox Taxi will reconnect and resume, but you'll see a slowdown when this happens.

8. Verify and reconfigure clients

   When the job finishes, Mailbox Taxi shows per-folder counts side by side. Confirm they match. Spot-check 20–30 random messages on icloud.com or in Apple Mail. Confirm subject, date, sender, attachments, and HTML render the way they did on Fastmail.

   Then reconfigure your mail clients. Apple Mail on macOS and iOS will pick up the iCloud mailbox automatically if iCloud Mail is enabled in System Settings. Add or remove the Fastmail account as needed.

   The IMAP protocol glossary covers the protocol terminology if any of the connection language is unfamiliar.

Gotchas specific to Fastmail → iCloud#

A few quirks that bite people on this exact pair.

iCloud's "Inbox" sometimes appears as "INBOX"#

iCloud's IMAP server reports the Inbox folder as INBOX (uppercase) by convention. Mailbox Taxi handles this transparently, but if you're inspecting the destination via a third-party IMAP client, don't be surprised to see INBOX rather than Inbox.

Mail rules don't translate#

iCloud Mail rules are configured in icloud.com/mail → Settings → Rules and are completely separate from Fastmail's sieve scripts. There's no automatic translation. Plan to manually recreate any business-critical rules in iCloud's rules UI after migrating.

Apple Mail caches aggressively#

After the migration, when you open Apple Mail on macOS or iOS, it'll start pulling the migrated mailbox down to the local cache. This can take hours for a large archive and saturates network bandwidth while it runs. Plan accordingly — don't kick off a Time Machine backup at the same time.

iCloud's quota error is delayed#

iCloud sometimes accepts APPEND requests and then later marks the message as failed when it processes server-side. This means a migration can run for a while seemingly cleanly before iCloud starts rejecting messages with quota errors. If your destination quota is tight, watch the iCloud storage indicator during the run and pause if it crosses 90%.

Send-as for custom domains#

If you sent from a custom domain on Fastmail, iCloud Mail doesn't support sending from arbitrary custom domains. iCloud+ supports a Custom Email Domain feature with up to five domains, but it requires DNS setup and only works for inbound. For outbound from a custom domain, you'll need a separate SMTP provider or you'll need to keep Fastmail alive for sending.

Real errors you'll see and what they mean#

• AUTHENTICATIONFAILED on source — Fastmail account password used instead of app password.
• AUTHENTICATIONFAILED on destination — Apple ID password used instead of the app-specific password, or 2FA not enabled on the Apple ID.
• Too many simultaneous connections from iCloud — lower concurrency to 1.
• Message too large for destination — iCloud's per-message limit is around 20 MB. Old messages with huge attachments may fail. Skip and handle manually.
• Quota exceeded — iCloud storage is full, often because Photos has been eating it. Free up storage or upgrade the plan.
• OAuth2 token expired — you ended up in an OAuth flow somehow; iCloud IMAP uses app-specific passwords, not OAuth. Re-check the destination config.
• STARTTLS handshake failed — host or port misconfigured. iCloud uses SSL/TLS on port 993, not STARTTLS.
• iCloud silently dropping connections — common at high concurrency. Lower to 1 connection.

Communicating the change#

iCloud migrations are usually personal moves rather than business cutovers, but they're worth thinking through:

• The cutover date and time.
• Whether to forward Fastmail to iCloud during the transition (recommended for at least 30 days).
• Mobile reconfiguration — add iCloud Mail in Settings → Mail on iOS and macOS.
• Third-party services where you've registered the Fastmail address — update them to the iCloud address.
• Calendars and contacts — export from Fastmail as ICS and vCard, import to iCloud.
• Aliases — anything you actively receive at on Fastmail needs forwarding configured.

If you're keeping a custom domain on Fastmail for sending, that's a longer-term setup. Plan it as a separate sub-project rather than rolling it into the migration window.

Post-migration checklist#

• Folder counts match for every folder you care about.
• 20+ random messages confirmed visually identical on both sides.
• Apple Mail on macOS and iOS configured for iCloud and (if needed) Fastmail in parallel.
• Forwarding from Fastmail to iCloud active during the transition.
• Mail rules recreated on iCloud.
• Contacts and calendars exported from Fastmail and imported to iCloud.
• Custom-domain sending plan documented if you have a custom domain.
• Fastmail account kept alive for at least 30 days as a fallback.