Migrate MBOX to Gmail: IMAP Append Process Explained

MBOX archives show up from Thunderbird users, Apple Mail exports, old Unix mailservers, and Google Takeout downloads. Gmail does not accept MBOX directly through the web or the Workspace admin console. The only practical route is uploading the contents over IMAP, either through a desktop migration client that reads MBOX natively or by loading the MBOX into Thunderbird and copying messages into a connected Gmail account. Both approaches share the same Gmail-side constraints: IMAP throttling, label conventions, and a few quirks around date preservation.

Where MBOX files come from#

The MBOX format is older than most active mail clients. You'll meet it in roughly these flavours:

• Thunderbird — Each folder is a single MBOX file with no extension. The file lives under the profile directory at <profile>/Mail/<account>/ on Windows or ~/Library/Thunderbird/Profiles/<profile>/Mail/<account>/ on macOS. Subfolders are separate MBOX files in nested directories.
• Apple Mail — Folders are directories with the .mbox extension, containing a metadata folder and an mbox file inside. Slightly different layout but readable by most MBOX tools.
• Google Takeout — A single MBOX file per Gmail account export. All labels collapsed into one file with X-Gmail-Labels headers preserving the original label information.
• Old Unix mailservers — Per-user single MBOX files in /var/spool/mail/ or /var/mail/. Strict mbox-O format with From line separators.
• Eudora, Pine, Mutt — Anything from the pre-IMAP era likely uses mbox.

The variations matter because tools that handle Thunderbird MBOX cleanly sometimes choke on the X-Gmail-Labels-style Takeout files, and vice versa.

Prerequisites#

Locate and identify the MBOX files#

Find the source files. For Thunderbird, navigate to the profile directory and look in Mail/<account>/. Each folder corresponds to one MBOX file (Inbox, Sent, Drafts, plus any custom folders). Subfolders sit in a .sbd directory matching the parent name.

For Apple Mail, the export is a .mbox directory; inside, the actual data is in a file called mbox (no extension).

For Google Takeout, you get one large .mbox file per account. The X-Gmail-Labels header on each message tracks original label membership.

Copy everything to a working folder on local SSD before starting. MBOX is line-sensitive and network-share read inconsistencies can corrupt the stream.

Verify integrity#

Open each MBOX file in a hex editor or simple viewer. Look for:

• The file starts with a From line (capital F, no colon, followed by a sender address and date).
• Each subsequent From line at the start of a new line marks a new message boundary.
• The file ends cleanly without truncation mid-message.

A common corruption is a copy that stops mid-message because the source disk was full or the copy was interrupted. The file will look mostly correct but the last few messages are unreadable.

For Thunderbird sources, also check that messages are not in the trash-pending state. Thunderbird marks deleted messages with an X-Mozilla-Status header but leaves them in the MBOX until you compact the folder. Compact folders in Thunderbird first, then export, to avoid uploading deleted messages.

Convert if needed#

Most modern tools read MBOX natively. The exception is Apple Mail's .mbox directory format, which some tools want as a flat file. Extract the inner mbox file from the .mbox directory and use that as the source.

For Outlook-as-intermediary workflows (rare, but used for compatibility with PST-only tools), convert MBOX to PST first using a converter, then import the PST. That's not the path we cover here because IMAP upload skips the intermediate.

Prepare Gmail#

Enable IMAP in Gmail settings: See all settings > Forwarding and POP/IMAP > IMAP Access > Enable IMAP. Save.

For Workspace tenants, the admin must also enable IMAP under Apps > Google Workspace > Gmail > End User Access.

Generate an app password if the account uses 2-Step Verification: Manage your Google Account > Security > App passwords. For Workspace tenants where admins block app passwords, use a migration client that supports Workspace OAuth.

Check quota headroom. A 10 GB MBOX landing in a Workspace account already at 95 percent quota will fail partway through with Message too large for destination or a hard quota error. Expand quota before starting.

Migrate the messages#

1. Stage the MBOX files

   Copy all source files into one working folder. For Thunderbird sources, preserve the directory structure including .sbd subdirectories so nested folders survive the upload. Note the total size and message count if your reader can produce one.

2. Choose the upload method

   Two practical options:

   • Thunderbird-mediated upload — Add the Gmail account to Thunderbird as IMAP. Drag the MBOX folders into the Gmail account's folder tree. Thunderbird uses IMAP APPEND under the hood. Slow but no third-party tools needed.
   • Dedicated migration client — A desktop tool that reads MBOX and writes to Gmail over IMAP with proper throttling and resume support. Faster and produces logs.

   For one-off small migrations under 2 GB, Thunderbird is fine. For anything bigger or batch jobs across multiple source files, a dedicated client is the practical choice.

3. Map MBOX files to Gmail labels

   Each MBOX file should become a Gmail label. The naming convention matters:

   • An MBOX named Inbox becomes the Gmail INBOX label, which is the actual inbox.
   • An MBOX named Sent becomes the Gmail Sent label.
   • An MBOX named Clients/Acme becomes a nested label Clients/Acme.

   Most tools handle this automatically. Confirm the mapping before starting. Watch out for tools that prefix everything with Imported/; that's safe but produces a longer label path users will need to expand.

4. Configure throttling

   Gmail throttles IMAP append at:

   • About 750 MB per hour per account.
   • About 2,500 messages per day before rate limiting kicks in.
   • A practical concurrency cap of 2 to 3 simultaneous appends.

   Tools with built-in pacing handle this automatically. If your tool lets you set raw concurrency, keep it at 2. Anything higher triggers Too many simultaneous connections and rolls back recent appends.

5. Run the upload

   Start during a low-traffic window for the user (overnight is common). Expect:

   • 80 to 120 messages per minute on a healthy residential link.
   • A 5 GB MBOX with around 25,000 messages: 4 to 6 hours.
   • A 10 GB MBOX with around 50,000 messages: 8 to 12 hours.

   Leave the workstation awake. Disable sleep, disable Windows Update auto-reboot, and keep the network connection stable. Resumable tools can recover from a dropped connection, but many run a slow re-scan to figure out what's already uploaded.

6. Verify after the run

   Open Gmail and check each label against the source MBOX. Compare counts, not just spot-check. Most tools produce a per-file log; read it. Re-run any file that came up short or threw recoverable errors.

What changes during the upload#

Date handling#

Gmail's IMAP APPEND command accepts an optional internal date argument. Tools that pass the original message Date header here keep messages in original chronological order. Tools that omit it let Gmail timestamp messages with the upload time, which makes the inbox view nonsensical (a 2015 message appears at the top of the list because it was just uploaded).

Verify your tool handles this correctly by checking a few old messages after upload. They should appear in their original 2015 (or whenever) position, not at the top.

Label-from-folder mapping#

Gmail's IMAP layer interprets folder names with slashes as nested labels. An MBOX file or IMAP folder named Projects/2024/Q3 lands as a nested label. This usually does what you want but can produce awkward labels when source folder names contained slashes for some other reason.

Sent items handling#

The Sent folder needs care. Gmail automatically applies the Sent label to outgoing messages it sends, but for IMAP-appended messages, the label is set based on the source folder name. Append to [Gmail]/Sent Mail directly to land messages in the Sent view; some tools handle this, some create a separate Sent label that's not the same thing.

Read state and flags#

Read/unread state survives. Stars do not have a direct MBOX equivalent and are lost unless the source was Google Takeout (the X-Gmail-Labels header preserves Starred markings, and good tools restore them).

Common failure modes#

AUTHENTICATIONFAILED#

The Gmail credential is wrong, IMAP is disabled, or the app password was revoked. Check IMAP is on, regenerate the app password, confirm the username is the full email address.

Too many simultaneous connections#

Concurrency too high. Drop to 2 or 3. If using Thunderbird, set mail.server.default.max_cached_connections to 3 in advanced config.

Message too large for destination#

Gmail caps individual messages at 25 MB for IMAP append. Larger messages are skipped. Log lists them; extract attachments and re-deliver separately if needed.

Folder UTF-7 conversion error#

A folder name contains characters that fail IMAP's modified UTF-7 encoding. Usually emoji or unusual punctuation. Rename in the source before uploading.

Maximum messages per day reached#

Hit Gmail's daily append cap. Pause for 24 hours, resume. The cap resets daily on a rolling window.

When to use a dedicated client#

Thunderbird-mediated upload is fine for one-off small jobs. For anything else, dedicated migration clients win on:

• Per-file logs with skipped-message details.
• Resume from last successful message.
• Throttle handling that adapts to Gmail's actual response (slows down when it sees rate-limit responses).
• Concurrent uploads across multiple source MBOX files.
• Date-preservation through proper IMAP APPEND arguments.

For format background, see the MBOX format glossary entry and the broader PST, MBOX, and EML migration guide. If your source is specifically Thunderbird, the Thunderbird to Gmail walkthrough covers the Thunderbird-as-bridge approach in more detail. If your destination is Microsoft instead of Google, see MBOX to Office 365 and MBOX to Outlook.