Migrate Apple Mail to Gmail: Library Mail to IMAP Upload

Two storage models meet here and they do not get along. Apple Mail keeps each message as a separate .emlx file inside a folder hierarchy under ~/Library/Mail. Gmail keeps every message as part of a single conversation store and represents organisation through labels rather than folders. The migration is less a copy than a translation: every Apple Mail folder becomes a Gmail label, every duplicate message across folders becomes a single labeled message, and attachments that Apple Mail stored as separate files have to be stitched back into the message bytes before they upload.

Why the data layouts collide#

Apple Mail's .mbox is not the standard MBOX format. It is a macOS bundle — a directory tree that Finder displays as a single file. Inside, you find an Info.plist, a UUID-named subdirectory, a Messages/ folder full of .emlx files, and on modern macOS often an Attachments/ folder where Mail stores attachments outside the .emlx envelope.

An .emlx file is a standard RFC 822 MIME message wrapped with a four-digit length prefix at the start and an Apple-specific plist at the end. The middle is normal email. A tool that strips the prefix and trailing plist gets a perfectly valid MIME message.

Gmail wants standard MIME messages too, delivered via IMAP APPEND. The mismatch is structural: Apple Mail says "here is a directory of files," Gmail says "give me one APPEND per message." Bridging the two is what a migration tool does.

Folder-to-label translation#

Apple Mail folders include both server-backed mailboxes (under per-account directories) and local "On My Mac" mailboxes (under the V folder's Mailboxes/ directory). All of them become Gmail labels in the destination. Nested folders become labels with slash separators: Clients/Acme/2024 in Apple Mail becomes a Gmail label of Clients/Acme/2024.

If a message exists in two Apple Mail folders (which can happen with manual copies in Apple Mail), Gmail will deduplicate by Message-ID and assign both labels to the single resulting Gmail message. This is the desired behaviour — you do not want duplicates.

Locate the Apple Mail data#

Library is hidden in Finder by default. Hold Option, click Go in the menu bar, choose Library. Inside, open Mail. You will see one or more V-numbered folders (V7 through V10 depending on macOS version). Use the highest-numbered V folder — that is the one the current Mail app reads from.

Per account, you find a directory named after the protocol and address (IMAP-user@host, EWS-user@host, etc.). Per local store, you find Mailboxes/. Inside each, .mbox packages hold the actual content.

Skip these things during migration:

• MailData/ — local config, signatures, rules. Not migratable as mail.
• Envelope Index — SQLite index Mail rebuilds on demand.
• .OfflineCache — server-side caches.

Migrate these things:

• .mbox packages under per-account directories (real mail)
• .mbox packages under Mailboxes/ (On My Mac local content)

Gmail destination setup#

Gmail's IMAP front-end is generous in some ways and stingy in others.

Turn IMAP on#

Settings > See all settings > Forwarding and POP/IMAP. Switch IMAP access on. Set Folder Size Limits to "Do not limit the number of messages in an IMAP folder." Without this, Gmail truncates large folders at the IMAP layer and your migration completes silently incomplete.

Set Auto-Expunge to "Do not auto-expunge messages." This prevents accidental permanent deletes during a botched run.

For the deletion folder, choose "Move the message to the Trash."

Authenticate#

Gmail no longer accepts plain password IMAP login. Two real options:

OAuth2 is correct. Your migration tool registers as a Google client, the user grants IMAP scope, you get a refresh token. Tokens are revocable and respect MFA.

App passwords are the fallback. Generate at myaccount.google.com under Security, requires 2-Step Verification on. App passwords are 16 characters with no spaces and bypass MFA, so treat them carefully.

The full app password walkthrough covers Google-specific edge cases.

Workspace tenants#

If the destination is Google Workspace and you are migrating many users, an admin can use the Workspace Data Migration Service from the admin console. That bypasses per-user IMAP throttling but requires an IMAP source server, which Apple Mail is not. For one or two users, direct IMAP upload is simpler. For dozens, you may want to stage Apple Mail content to an intermediary IMAP server first.

Running the upload#

1. Snapshot Apple Mail

   With Mail.app quit, copy ~/Library/Mail to a backup drive. This is non-negotiable for any Apple Mail migration. Skipping it is how people lose mail.

2. Connect Gmail with OAuth2

   Add Gmail as destination in your migration tool. The browser launches a consent flow. Approve the IMAP scope. Test with a 5-message dry run before going further.

3. Point at the V folder

   A package-aware tool reads .mbox packages directly. Mailbox Taxi runs locally on the Mac and can parse .emlx files in place without an export step.

4. Map mailboxes to labels

   Inbox to Inbox, Sent to [Gmail]/Sent Mail, Drafts to [Gmail]/Drafts, Trash to [Gmail]/Trash, Junk to [Gmail]/Spam (or skip Junk). On My Mac content goes under a parent label like Archive/Apple Mail.

5. Cap parallelism

   Two to three concurrent IMAP connections. More than that and Gmail throttles.

6. Run a 200-message pilot

   Migrate one mid-sized mailbox first. Verify in Gmail that the label appears, messages are searchable, timestamps are right, attachments open, and special characters render.

7. Run in daily waves

   Plan around the 2,500 MB/day soft cap. Stop when Gmail returns rate-limit errors. Resume the next calendar day. Verify per-wave.

Daily caps shape the schedule#

Wall-clock IMAP throughput against Gmail tops out around 60–100 MB per minute. Gmail caps roughly 2,500 MB of IMAP upload per account per day. A 10 GB Apple Mail user is therefore a 4 to 5 day job, not the 90 minutes the raw upload time would suggest.

Hit the cap and Gmail starts returning [OVERQUOTA] errors to APPEND, or your connection silently slows to crawl speeds for the rest of the day. Stop the tool when this happens — pushing harder extends the throttle window.

If you have multiple users to migrate, run them in parallel across different accounts. The cap is per-account.

Errors to recognise#

AUTHENTICATIONFAILED — OAuth token expired or app password wrong. Reauthorise.

Too many simultaneous connections — drop to 2 connections, wait, retry.

Lookup failed on APPEND — malformed folder name. Rename source to ASCII.

OAuth2 token expired — tool should refresh. If not, restart.

Message too large for destination — Gmail rejects messages over 25 MB on the API and around 50 MB on IMAP for some accounts. Skip these.

Apple Mail specifics to watch#

A few details that bite specifically on the Apple Mail side.

Attachments stored separately. Modern Apple Mail can store attachments outside the .emlx file in an Attachments/ subdirectory inside the .mbox package. A migration tool that reads only .emlx misses these. Verify attachments during the pilot and confirm your tool handles them.

Smart Mailboxes. Smart Mailboxes are saved searches, not real mailboxes. They contain no messages of their own. Skip them. Rebuild as Gmail filters or search bookmarks afterwards.

S/MIME encrypted messages. Encrypted bytes upload fine but only decrypt where the matching S/MIME certificate is installed. Most users have their cert in Keychain on the source machine but not in Gmail's web view. Plan how the user will read encrypted mail after cutover.

Exchange-account content. Mail.app stores Exchange (EWS) account mail under EWS-* directories with the same .emlx layout. Calendars and contacts from Exchange live elsewhere on macOS and do not come across via mail tools.

Verification#

Done means:

• Per-mailbox message counts match between Apple Mail and Gmail label totals, allowing a small margin for deduplication
• Spot-check ten messages per major label: date, sender, body, attachments, threading
• Search in Gmail for a known recent sender to confirm reachability through search
• Confirm threading: Gmail threads on In-Reply-To and References, which IMAP APPEND preserves
• Confirm On My Mac content reached the destination under the expected parent label
• Cut over the user's mail client (web Gmail, native Gmail, or whatever they prefer) and confirm everything works before celebrating

Keep the ~/Library/Mail snapshot for at least 30 days post-cutover. Missing-message reports come in weeks after the migration finishes and the snapshot is the only reliable source.

Related paths#

If the destination is Outlook.com or Microsoft 365, see migrate Apple Mail to Outlook and migrate Apple Mail to Office 365. The source-side work is identical; the destination auth and folder mapping differ.

If you have already exported Apple Mail content as standard MBOX files via Mail.app's Export Mailbox feature, migrate MBOX to Gmail covers the upload step in isolation.

The MBOX format glossary entry explains the differences between standard MBOX and Apple Mail's package format that some uploaders mis-parse. The PST, MBOX, and EML migration guide covers cross-format conversion in more depth.