Migrate Fastmail to Gmail: IMAP Walkthrough with App Passwords

Fastmail-to-Gmail is one of the cleaner migrations you can run. Both ends speak modern IMAP without weird detours, both support app passwords without forcing OAuth dances, and both have IMAP servers that behave well under load. The work that's left is mostly about getting the folder model right — Fastmail uses traditional folders, Gmail uses labels — and deciding what to leave behind. This walkthrough covers the full path from app-password generation to post-migration cleanup.

Why people move from Fastmail to Gmail#

Most of the time it comes down to one of three reasons. A user is joining a Google Workspace organisation and wants their personal archive accessible from the same address. A team is consolidating after an acquisition and the survivor runs on Workspace. Or someone's tired of paying for two separate mail services and wants to fold everything into the Gmail account they already have. None of those reasons matter to the migration itself — the mechanics are identical — but they shape what you do afterwards. A user joining a Workspace org needs send-as set up; a consolidating team needs unified contacts; a personal consolidator needs old Fastmail filters re-built as Gmail filters.

Before you start#

Four things to have ready:

• A Fastmail account at any paid tier. Fastmail's IMAP works the same on Standard, Professional, and Topicbox subscriptions.
• A Gmail or Google Workspace destination with IMAP enabled and 2-Step Verification turned on (so you can generate app passwords).
• A workstation you can leave running for the duration of the job. A laptop that sleeps will pause the migration.
• Disk headroom equal to about 5% of your mailbox size, for Mailbox Taxi's local index and resumability metadata.

Fastmail's app-password mechanism is fast — generation takes a few seconds. Gmail's is similar. Plan for the full migration including verification to take a half day for mailboxes under 5 GB and a full day for mailboxes 5–25 GB.

How the two systems differ#

Worth knowing before you start.

Folders vs labels#

Fastmail uses folders. A message lives in exactly one folder. Gmail uses labels. A message can have many labels (and conventionally lives in "All Mail" plus zero or more labels). When Fastmail folders migrate to Gmail, each folder becomes a Gmail label and each message gets exactly that one label. The mental model is unchanged from the user's perspective unless they go looking for the folder hierarchy in the Gmail UI, where it lives under "Labels" instead of in a folder tree.

Nested folders#

Fastmail supports nested folders. Gmail supports nested labels using slash separators. Mailbox Taxi translates Projects/2024/Client A on Fastmail into a single Gmail label Projects/2024/Client A which the Gmail UI shows as a three-level nested label. The structure preserves cleanly. Very deep hierarchies (5+ levels) can render awkwardly in the Gmail mobile app but the data is correct.

Aliases and masked email#

Fastmail's masked email and aliases route to your main mailbox. Migrated mail keeps the original To header (which shows the masked or alias address), so threading and search still work in Gmail. The masked-email feature itself doesn't translate — Gmail doesn't have an equivalent — so any masked addresses you actively use need to be either kept alive in Fastmail (with forwarding) or replaced with another masking service.

Sieve scripts#

Fastmail uses sieve for filtering. Gmail uses its own filter system. The two are not compatible and there's no automatic translation. If you have a complex sieve setup, list the rules before migrating and plan to recreate the important ones as Gmail filters.

Step-by-step migration#

1. Generate a Fastmail app password

   Sign in to Fastmail on the web and open Settings → Privacy & Security → Integrations → App passwords (the exact path moves around occasionally — search for "app password" in settings if you can't find it). Create a new app password. Give it a descriptive name like "Mailbox Taxi migration". Choose "IMAP & POP" as the access type rather than "All" — least-privilege is good practice and you don't need SMTP for a migration. Fastmail will display a 16-character password once. Copy it immediately; you can't retrieve it later.

   For more context on what app passwords are and how they fit into the auth landscape, the app password glossary entry covers the full picture.

2. Enable IMAP and generate a Gmail app password

   In Gmail, click the gear icon → See all settings → Forwarding and POP/IMAP. Confirm IMAP access is enabled. If it isn't, enable it and save.

   Then open myaccount.google.com/apppasswords. If you see "App passwords aren't available for your account", 2-Step Verification isn't enabled on this Google account — enable it at myaccount.google.com/security first, then come back. Generate an app password. Pick "Mail" for the app and "Other" for the device, name it "Mailbox Taxi import", and copy the 16-character password Google shows.

3. Add the Fastmail source in Mailbox Taxi

   Create a new migration job. Source: Fastmail. Host imap.fastmail.com, port 993, SSL/TLS. Username: your full Fastmail address (e.g. you@fastmail.com or you@yourcustomdomain.com if you use a custom domain on Fastmail). Password: the Fastmail app password from step 1. Click Test connection. You should see "Connected" within a second or two.

   If the connection fails with AUTHENTICATIONFAILED, you've almost certainly pasted your regular Fastmail password instead of the app password. Re-copy from the Fastmail settings page.

4. Add the Gmail destination in Mailbox Taxi

   Destination: Gmail. Host imap.gmail.com, port 993, SSL/TLS. Username: your full Gmail address. Password: the Gmail app password from step 2. Test connection.

   Common failure: pasting your Google account password instead of the app password. Re-generate the app password if you're not sure.

5. Map Fastmail folders to Gmail labels

   Mailbox Taxi scans both sides and proposes a folder map. Fastmail's system folders (Inbox, Sent, Drafts, Archive, Spam, Trash) map to Gmail's system labels. Custom Fastmail folders become Gmail labels with the same names. Nested folders translate to nested labels using slash separators.

   Review the map carefully. Things to adjust:

   • Spam and Trash — exclude unless you have an explicit reason to keep them.
   • Notes — if you used Fastmail's Notes folder, it'll come across, but Gmail won't render notes nicely. Consider migrating to Google Keep instead.
   • Archive — Fastmail's Archive becomes a Gmail label called Archive, separate from Gmail's built-in archive concept. Some users prefer to map it to "All Mail" instead (which preserves the archived state in Gmail's UI). Either works.
6. Run a dry-run on one small folder

   Pick a folder with 50–200 messages. Run only that. Watch progress, then open Gmail and confirm the messages arrived with the right subjects, dates, senders, attachments, and HTML rendering. If anything's off — character encoding, missing inline images, wrong dates — fix it now before the full run.

7. Run the full migration and verify

   Kick off the full job. Mailbox Taxi will run 4–6 concurrent IMAP connections, which is roughly what Gmail tolerates per account. Expect 60–90 minutes per gigabyte. Fastmail's IMAP rarely throttles; Gmail is almost always the limit. If you see Too many simultaneous connections errors from Gmail, lower concurrency to 3.

   Once finished, compare folder counts on both sides — Mailbox Taxi shows them side by side in its verification view. Spot-check 30–50 random messages: open the original in Fastmail and the copy in Gmail, confirm subject, date, From/To/Cc, attachments, and inline images all match.

   For more on the IMAP terminology Mailbox Taxi uses under the hood — UIDs, APPEND, EXAMINE, and so on — the IMAP protocol glossary is the reference.

Gotchas specific to Fastmail → Gmail#

A few quirks that come up reliably on this pair.

Gmail re-classifies threads#

Gmail's threading is more aggressive than Fastmail's. Messages that were separate conversations in Fastmail may get grouped into one Gmail thread because Gmail uses subject line plus participants, while Fastmail relies on the In-Reply-To and References headers. The data is fine; the visual grouping is just different. Users sometimes file this as a "missing emails" bug; it's not.

Fastmail's Drafts use a slightly different format#

Migrated drafts will land in Gmail's Drafts folder but may not be editable as drafts — Gmail sometimes treats them as received messages because of how the headers are laid out. Test on the dry-run. If drafts come across as non-editable received messages, accept that limitation rather than trying to force a roundtrip.

Send-as for custom domains#

If you sent from a custom domain on Fastmail, that custom domain isn't automatically wired up in Gmail. Add it in Gmail Settings → Accounts → Send mail as → Add another email address. You'll need access to the domain's DNS to verify (or to receive a verification email at the custom address).

Fastmail aliases#

Mail received via Fastmail aliases migrates fine — the To header preserves the alias. But the alias itself only exists in Fastmail. To keep receiving at the alias post-migration, either set up forwarding from Fastmail to Gmail (and pay Fastmail to keep the alias alive), or set up the alias as a custom address on Gmail's side using a separate mail-forwarding service.

Real errors you'll see and what they mean#

• AUTHENTICATIONFAILED on source — Fastmail account password used instead of app password. Re-copy.
• AUTHENTICATIONFAILED on destination — Gmail account password used instead of app password, or 2-Step Verification isn't enabled. Fix one or both.
• Too many simultaneous connections from Gmail — other clients (mobile, desktop) are using the same Gmail account. Disconnect them for the duration, or lower Mailbox Taxi's concurrency.
• STARTTLS handshake failed — host or port misconfigured. Fastmail and Gmail both use SSL/TLS on port 993, not STARTTLS.
• Folder UTF-7 conversion error — a Fastmail folder name contains non-ASCII characters that Gmail won't accept. Rename it on Fastmail before migrating.
• Message too large for destination — Gmail's per-message size limit is around 25 MB for received messages. Old messages with huge attachments may fail to APPEND. Skip these and handle manually.

Communicating the change#

Even on a personal migration, give yourself a checklist:

• The cutover date and time, in your local timezone.
• The forwarding plan from Fastmail to Gmail for transition mail.
• Mobile devices to reconfigure with the new account.
• Any third-party services (newsletters, billing accounts) where your contact email is the Fastmail address — those need updating separately.
• The retention plan for the Fastmail account itself. Keep it alive for at least 30 days as a safety net.

If you're an MSP doing this for a client, all of the above goes into the project plan with named owners and dates.

Post-migration checklist#

• Folder counts match for every label you care about.
• 30+ random messages confirmed visually identical on both sides.
• Send-as addresses for custom domains added in Gmail.
• Fastmail filters reviewed and any business-critical ones recreated as Gmail filters.
• Forwarding set up from Fastmail to Gmail during the transition window.
• Mobile apps reconfigured.
• Fastmail account kept alive for at least 30 days as a fallback.