Migrate Thunderbird to Gmail: MBOX Upload via IMAP

The first surprise when moving Thunderbird to Gmail is that the two systems disagree on what a folder is. Thunderbird thinks in folders backed by MBOX files on your disk. Gmail thinks in labels backed by a single conversation store on Google's servers. The migration is not a copy operation. It is a translation, where every Thunderbird folder becomes a Gmail label and every duplicate message between folders becomes a single Gmail message with multiple labels.

The folders-versus-labels gotcha#

Before you do anything else, accept that the destination will look different. A user who had Clients/Acme/2024 as a Thunderbird folder will see a Gmail label called Clients/Acme/2024, but searching in Gmail will reach that mail from the search bar, not from a nested folder tree on the left. If the user is moving because they want a labels-based workflow, that is fine. If they are moving against their will, brief them before cutover.

Gmail's IMAP server uses the IMAP LIST hierarchy delimiter of / to represent label nesting. Thunderbird typically uses . or / depending on the source server. Most uploaders normalise this automatically, but if you see flat labels with slashes in their name instead of nested labels, your tool used the wrong delimiter.

What lives where in Thunderbird#

Open Help > Troubleshooting Information and click Open Folder next to Profile Folder. Inside the profile:

• Mail/Local Folders/ contains MBOX files for everything stored locally
• Mail/<server>/ contains MBOX for POP accounts
• ImapMail/<server>/ contains cached MBOX for IMAP accounts

The cached IMAP store under ImapMail is what Thunderbird downloaded for offline use. If the original IMAP server still has the mail, you can ignore that directory and migrate IMAP-to-IMAP from the original server straight into Gmail. The MBOX path only matters when the source no longer exists or when content lives in Local Folders.

Gmail-side setup#

Gmail throws off enough quirks that getting the destination right is half the battle.

Turn IMAP on#

In Gmail go to Settings, See all settings, Forwarding and POP/IMAP. Make sure IMAP access is enabled. While you are there, set Folder Size Limits to "Do not limit the number of messages in an IMAP folder." Gmail otherwise truncates large folders at the IMAP layer and your migration appears successful while quietly missing mail.

Set Auto-Expunge to do not auto-expunge messages. This stops Gmail from immediately deleting messages that your migration tool flags as \Deleted.

For the deletion folder setting, choose "Move the message to the Trash." This means a \Deleted flag in your tool will not permanently destroy the message during a botched run.

OAuth or app password#

Gmail no longer accepts plain password IMAP login from new tools. You have two options.

OAuth2 is the right answer. Your migration tool registers as a Google client and the user grants IMAP access through the standard consent screen. Tokens are revocable and respect MFA. A desktop-first tool like Mailbox Taxi runs the OAuth flow locally so credentials never leave the machine.

App passwords are the fallback. Generate one at myaccount.google.com under Security, only available if 2-Step Verification is on. App passwords are 16-character strings with no spaces. They authenticate as the user but bypass MFA, so treat them with the same caution as a real password.

The full app password walkthrough covers the cases where OAuth2 is not an option.

Workspace tenants are different#

If "Gmail" actually means a Google Workspace tenant, an admin can use the Google Workspace Migration tool or the Data Migration Service in the admin console. Those are the cleanest path for tenant-wide migrations and they bypass per-user IMAP throttling entirely. The MBOX upload route described here is best for consumer Gmail or for a small number of Workspace mailboxes where central tools are overkill.

Source-side preparation#

Two things matter before you point anything at MBOX.

Compact every folder. Right-click each top-level account in Thunderbird, choose Compact Folders, and wait. Deleted messages still occupy space until you compact. A heavy mailbox can shrink by 40% after compaction, which directly cuts your migration time.

Snapshot the profile. Close Thunderbird. Copy the entire profile folder to a backup drive. Do not skip this. If anything during the upload damages the MBOX files, the snapshot is your only recovery option.

Running the migration#

1. Connect Gmail with OAuth2

   In your migration tool, add Gmail as the destination using OAuth2. The browser will prompt for consent. Approve the IMAP scope. Test the connection with a 5-message dry run before going further.

2. Point the tool at the Thunderbird profile

   Add the source. For a desktop tool that reads MBOX directly, browse to the profile folder. For a tool that needs IMAP, point it at the original IMAP server with Thunderbird as a viewer.

3. Set up label mapping

   Map Inbox to Inbox, Sent to [Gmail]/Sent Mail, Drafts to [Gmail]/Drafts, Trash to [Gmail]/Trash, Junk to [Gmail]/Spam (or skip Junk). Local Folders content typically maps under a parent label like Archive/Thunderbird.

4. Cap parallelism low

   Set 2 to 3 parallel connections. Gmail will throttle you above that. Anyone telling you to "max it out" has not actually run this against a Workspace tenant.

5. Run a 200-message pilot

   Migrate one mid-sized folder first. Verify the label appears in Gmail, the messages are searchable, timestamps look right, and attachments open.

6. Run the full migration in daily waves

   Plan around the 2,500 MB/day soft cap. Move oldest folders first. Stop when Gmail starts returning rate-limit errors. Resume the next calendar day.

The throttle is the bottleneck#

Wall-clock IMAP throughput against Gmail can hit 50 to 100 MB per minute. That sounds great until you realise Gmail caps roughly 2,500 MB of IMAP upload per account per day. A 10 GB mailbox is therefore a 4 to 5 day job no matter how fast your line is.

Hit the cap and you get one of two error patterns. Either Gmail starts returning [OVERQUOTA] responses to APPEND, or your connection silently slows to crawl speeds for the rest of the day. Stop the tool when this starts. Pushing harder makes the throttle window longer.

If you have several Workspace mailboxes to migrate, run them in parallel across different accounts. The throttle is per-account, not per-tenant.

Common errors#

AUTHENTICATIONFAILED from Gmail. Your OAuth token expired or the app password is wrong. Regenerate.

Too many simultaneous connections — drop parallelism to 2.

Lookup failed on APPEND — usually a malformed folder name. Rename the source folder to ASCII as a workaround.

OAuth2 token expired — your tool should refresh automatically. If it does not, restart the run.

Message too large for destination — Gmail rejects messages over 25 MB on the API side and around 50 MB on IMAP for some accounts. Skip these and migrate them manually via web upload or Google Takeout in reverse.

Verification#

Once the upload finishes, do not declare victory until you have:

• Compared folder-to-label message counts. Gmail's All Mail count should equal Thunderbird's total minus duplicates across folders.
• Spot-checked ten messages per major folder. Check date, sender, body, attachments.
• Confirmed conversation threading. Gmail threads messages by In-Reply-To and References headers, and badly stripped headers break threading.
• Searched for known specific senders to confirm filter/label assignments.

Use Gmail's search operators: label:Archive/Thunderbird/2024 before:2024-12-31 will surface a specific slice of migrated mail. If counts are off, you probably hit the throttle and missed a chunk. The migration tool's resume function should pick it up on the next pass.

Things to set up afterwards#

Filters do not migrate. Recreate them in Gmail as filters with label assignments. Most Thunderbird filter rules map cleanly to Gmail's From, To, Subject, and Has the words conditions.

Address books export from Thunderbird as LDIF or CSV. Gmail Contacts imports CSV directly under contacts.google.com.

If you used Thunderbird's calendar (Lightning), export each calendar as ICS and import into Google Calendar.

Signatures and identities have to be set up by hand in Gmail's Settings > Accounts and Import.

When to take a different path#

The MBOX upload route is the right call for Thunderbird users with significant Local Folders content. If everything was already on an IMAP server, you save time by going IMAP-to-IMAP and ignoring Thunderbird entirely. Our migrate MBOX to Gmail post covers the same upload step for non-Thunderbird sources, and the MBOX format glossary entry explains the framing details that some uploaders get wrong.

If the destination is Microsoft 365 or Outlook.com instead of Gmail, see migrate Thunderbird to Outlook or migrate Thunderbird to Office 365. The MBOX extraction is identical; the upload target and auth differ.

The PST, MBOX, and EML migration guide covers cross-format conversions if you end up needing to hand a converted file to a downstream team rather than uploading directly.