Migrate Gmail to Fastmail: IMAP and Label Mapping Guide

Fastmail's appeal — clean UX, no ads, strong privacy posture, custom domain support starting from the entry plan — has been pulling Gmail users for years. The transfer itself is unusual because Gmail isn't a folder-based system; it's a label-and-conversation system that exposes labels as IMAP folders. Move it carelessly and you end up with duplicated messages, missing Sent, or an Archive folder containing ten copies of every conversation. This guide walks the working path with the label decisions that matter.

Understanding Gmail as a migration source#

Gmail stores each message exactly once. What you see as folders in IMAP — Inbox, Sent, Drafts, Trash, your custom labels — are views over the single canonical message. When a message has both an Inbox label and a "Receipts" label, IMAP shows it in both the INBOX folder and the Receipts folder. Same physical message, two folder appearances.

This has two important implications for migration:

1. If you fetch the message via INBOX and again via Receipts, you transfer the bytes twice unless your tool is deduplicating by Message-ID (Mailbox Taxi does this).
2. The destination — Fastmail in this case — does not have Gmail's label semantics. It has folders. A message in two Gmail labels lands in two Fastmail folders as two physical copies.

Two strategies follow from this:

Strategy A — Migrate labels: Map each Gmail label to a Fastmail folder. Multi-labelled messages duplicate into multiple folders. Fastmail's storage handles this fine; expect 10–20 percent more storage on Fastmail than the source Gmail reports, depending on how heavily you've used labels.

Strategy B — Migrate All Mail only: Map [Gmail]/All Mail to a single Fastmail folder (typically Archive). One canonical copy per message in Fastmail. No duplication. But you lose the label structure on the destination — labels exist only as metadata you'd need to recreate.

The right choice depends on how much you used labels. Heavy labellers want Strategy A; light labellers happy with one big archive want Strategy B.

Pre-flight checklist#

Before launching:

• Gmail account with IMAP on and 2-Step Verification enabled
• Google app password generated (16 characters, no spaces)
• Active Fastmail account
• Fastmail IMAP password (Fastmail uses app passwords too — never your main account password for IMAP)
• Decision on Strategy A vs Strategy B
• Storage check on Fastmail (the entry plan is 30GB; Standard is 50GB; Professional is 100GB)

Step 1: Confirm Gmail IMAP and 2SV#

1. Sign in to mail.google.com
2. Settings (gear), See all settings
3. Forwarding and POP/IMAP tab
4. Confirm IMAP access is enabled
5. Save

Then enable 2-Step Verification:

1. Open myaccount.google.com
2. Security, 2-Step Verification
3. Complete the enrolment flow

Step 2: Generate a Google app password#

1. From myaccount.google.com, Security
2. Click App passwords (only visible after 2SV is fully enrolled)
3. Generate a new app password labelled Mailbox Taxi
4. Copy the 16-character password (no spaces)

Background on how providers use app passwords across the board lives in our app-specific password reference.

Step 3: Generate a Fastmail app password#

Fastmail uses app passwords for all third-party IMAP access. Your main Fastmail account password won't work directly with external IMAP clients.

1. Sign in at fastmail.com
2. Settings, Privacy and Security
3. Integrations, then App Passwords
4. Click New app password
5. Name it Mailbox Taxi import
6. Choose access type: Mail (IMAP/SMTP/POP)
7. Copy the generated password

Fastmail's app passwords are scoped — an IMAP/SMTP-only password can't be used for CalDAV or other services. That's a deliberate Fastmail security design and worth knowing.

Step 4: Configure the source and destination#

Source (Gmail):

• Server: imap.gmail.com
• Port: 993, SSL on
• Username: full Gmail address
• Password: Google app password

Destination (Fastmail):

• Server: imap.fastmail.com
• Port: 993, SSL on
• Username: full Fastmail email address (typically @fastmail.com, @fastmail.fm, @messagingengine.com, or your custom domain)
• Password: Fastmail app password

Test each side independently in a desktop mail client before configuring Mailbox Taxi. For more on IMAP itself and the protocol's behaviour, see our IMAP protocol glossary.

Step 5: Label and folder strategy#

Decide between Strategy A (label-per-folder) and Strategy B (All Mail) before configuring.

Strategy A — Label per folder:

In the folder selection screen, deselect [Gmail]/All Mail. Select all your custom labels plus INBOX, [Gmail]/Sent Mail, [Gmail]/Drafts, [Gmail]/Trash, [Gmail]/Spam. Set mappings:

• Gmail INBOX → Fastmail Inbox
• Gmail [Gmail]/Sent Mail → Fastmail Sent
• Gmail [Gmail]/Drafts → Fastmail Drafts
• Gmail [Gmail]/Trash → Fastmail Trash
• Gmail [Gmail]/Spam → Fastmail Spam (or Junk)
• Each user label → Fastmail folder with the same name

Multi-labelled messages will land in multiple Fastmail folders. That's intentional.

Strategy B — All Mail only:

Deselect everything except [Gmail]/All Mail. Map:

• Gmail [Gmail]/All Mail → Fastmail Archive (or a new folder you create called Gmail Archive)

This gives you one folder containing every Gmail message. No duplication. No label structure preserved.

Step 6: Pilot#

Pick a single label or folder of 200 to 500 messages. [Gmail]/Sent Mail is usually ideal — historic, doesn't churn, exercises most metadata fields.

Verify:

• Final count matches between Gmail label and Fastmail folder
• Sort order in Fastmail matches Gmail
• Read/unread flags preserved
• Three random messages open with attachments via Fastmail web UI
• Fastmail's conversation grouping kicks in (you'll see threads form automatically)

Step 7: Run the full transfer#

Concurrency for this pair:

• Gmail source: 2 connections (Gmail throttles IMAP at higher counts — Too many simultaneous connections appears around 15 total, but at 2 to 3 you stay well clear)
• Fastmail destination: 4 connections (Fastmail's IMAP server handles parallel writes well)

Throughput: 1 to 2.5GB per hour. Gmail is the throttling factor more often than Fastmail.

• 5GB mailbox: 2 to 5 hours
• 15GB mailbox: 6 to 15 hours, overnight typical
• 50GB mailbox: multi-session over two or three days

Gmail's OAuth2 token expired error sometimes appears even when you're using app passwords — Google's internal throttling sometimes returns this misleading message. Mailbox Taxi recognises it and backs off automatically.

Step 8: Verify#

When complete:

1. Folder counts side by side. Strategy A: each Fastmail folder should match its Gmail label count. Strategy B: Fastmail Archive should match [Gmail]/All Mail count.
2. Open Fastmail web UI, confirm conversation threading looks right
3. Spot-check by date — open messages from across years and confirm content
4. Test sending and receiving on Fastmail

If counts are off, run a delta sync — Mailbox Taxi re-attempts only the messages whose Message-ID isn't on the destination.

Step 9: Cut over#

If you're keeping the @gmail.com address but reading mail at Fastmail:

1. In Gmail, Settings, Forwarding and POP/IMAP
2. Add forwarding address: your Fastmail address
3. Verify the address (Gmail sends a confirmation code)
4. Forward all incoming mail to Fastmail
5. Keep a copy in Gmail's inbox or archive (recommended for the first 30 days)

If you're cutting over a custom domain you've used with Gmail:

1. Add the domain to Fastmail (Settings, Domains)
2. Verify domain ownership via the DNS TXT record Fastmail provides
3. Update MX records to point at Fastmail's mail servers
4. Set SPF, DKIM, and DMARC per Fastmail's instructions

Common failures#

AUTHENTICATIONFAILED on Gmail: not using an app password despite 2SV being on. Generate one.

AUTHENTICATIONFAILED on Fastmail: not using an app password (Fastmail never accepts the main account password for IMAP). Generate one.

OAuth2 token expired on Gmail: misleading Google error for general throttle. Drop source concurrency to 1, wait 5 minutes, resume.

Too many simultaneous connections on Gmail: source concurrency too high. Drop to 2.

Message too large for destination on Fastmail: rare. Fastmail allows up to 70MB per message, more generous than most. If you see this, the message exceeds Fastmail's destination policy — Mailbox Taxi logs it.

Folder UTF-7 conversion error: a Gmail label has special characters Fastmail's IMAP server can't handle. Rename the Gmail label or remap to a sanitised destination name.

After the migration#

• Update services with your new address if you're changing addresses
• Run an auto-reply on Gmail for 30 to 60 days
• Don't shut down Gmail immediately — keep forwarding for 90 days
• Revoke both app passwords from each provider's security settings
• Export Gmail contacts to CSV from contacts.google.com before final shutdown

If Fastmail isn't the right destination after all, Gmail to Outlook and Gmail to ProtonMail cover those alternative routes. To go the other direction later, see Fastmail to Gmail.