Migrate Apple Mail to Outlook: Mailbox Packages to IMAP Upload

Apple Mail uses a storage format that confuses every migration tool not specifically built for it. The mailboxes appear in Finder as .mbox files, which sounds like the standard Unix MBOX format. Open the package and you find a directory tree of individual .emlx message files, an Info.plist, and an index file. Outlook understands none of it. To move an Apple Mail user to Outlook you either re-export each mailbox as a real MBOX file via Mail.app itself, or you use a migration tool that reads the Apple Mail package structure directly and uploads each message to Outlook over IMAP.

The Apple Mail storage layout#

Apple Mail stores everything under ~/Library/Mail. The Library folder is hidden by default in Finder. The fastest way in is to hold Option, click Go in the Finder menu bar, and choose Library.

Inside ~/Library/Mail you find a versioned subfolder. macOS Sequoia uses V10, Sonoma uses V10, Ventura uses V10, Monterey uses V9, Big Sur uses V8, Catalina uses V7, and older macOS uses lower numbers. The current Mail app reads only the highest-numbered folder.

Inside the V folder:

• MailData/ contains rules, signatures, account state, and SQLite databases
• Each IMAP account has its own directory named like IMAP-user@host
• Each Exchange account has its own directory named like EWS-user@host
• Mailboxes/ holds local "On My Mac" mailboxes that never touched any server

Inside each account directory you find .mbox packages. A package called Receipts.mbox is actually a directory containing:

• Info.plist — metadata about the mailbox
• A UUID-named subdirectory containing the actual messages
• Messages/ inside the UUID — a flat directory of .emlx files, one per message
• Attachments/ — attachment payloads when present as separate files
• .OfflineCache/ — server-side state Mail caches locally

An .emlx file is an RFC 822 message with a leading length byte count and a trailing plist of Apple-specific flags. Most tools that read it ignore the length prefix and trailing plist and process the middle as a standard MIME message.

The On My Mac problem#

Anything stored under Mailboxes/ in the V folder is local-only. It never existed on an IMAP server. If you migrate Apple Mail by reconfiguring the IMAP account, On My Mac content is lost. The full-package upload path is the only way to be sure.

Outlook destination setup#

Outlook has two flavours and the difference matters.

Outlook.com is the consumer service. IMAP host is imap-mail.outlook.com, port 993, SSL. SMTP is smtp-mail.outlook.com:587 STARTTLS. Authentication is OAuth2 or app password when MFA is on.

Microsoft 365 is the business service. IMAP host is outlook.office365.com, port 993, SSL. Authentication is OAuth2 with IMAP.AccessAsUser.All scope, or app password where allowed.

If the user logs in at outlook.com and sees the consumer interface, it is Outlook.com. If they see "Outlook on the web" with corporate branding, it is Microsoft 365 — read migrate Apple Mail to Office 365 instead.

For Outlook.com, the rest of this post applies directly. Enable IMAP in Outlook.com settings, generate an app password if you cannot use OAuth2, and set the mailbox size limit allowance if your tenant has one.

Choosing how to read the source#

You have three options for getting Apple Mail content into a form a migration tool can use.

Option 1: Read the .mbox packages directly. A tool that understands the Apple Mail bundle structure parses .emlx files from Messages/ and uploads each to IMAP. No export step. Mailbox Taxi takes this approach because it is reversible and incremental.

Option 2: Use Mail.app's Export Mailbox. Select a mailbox in Mail.app, choose Mailbox > Export Mailbox, pick an output folder. Mail.app writes a standard MBOX file per mailbox. You then upload those MBOX files to Outlook via a generic MBOX-to-IMAP tool. The export step takes time and writes a second copy to disk, but the output is portable.

Option 3: Reconfigure the IMAP account and use server-side migration. If the user's Apple Mail account was already IMAP-backed and the original server is still live, point a migration tool at the original IMAP server, not at Apple Mail at all. You lose On My Mac content but skip the package parsing entirely.

Option 1 is the most efficient for one user. Option 3 is the most efficient for many users when there is no local-only content.

Running the migration#

1. Quit Mail and snapshot the data folder

   Cmd+Q Mail.app. In Terminal or Finder, copy ~/Library/Mail to an external drive. This is your rollback path. Skipping this step is how migrations destroy mailboxes.

2. Set up Outlook authentication

   For Outlook.com with MFA, generate an app password at account.microsoft.com under Security > Advanced security options. For OAuth2, your migration tool runs the consent flow against Microsoft's identity service.

3. Point the tool at ~/Library/Mail

   A package-aware tool reads the V folder directly. A tool that needs standard MBOX gets a working directory of files exported from Mail.app via Mailbox > Export Mailbox.

4. Map mailboxes to Outlook folders

   Inbox to Inbox, Sent to Sent Items, Drafts to Drafts, Trash to Deleted Items, Junk to Junk Email. On My Mac local mailboxes go under a parent folder like Archive/Apple Mail. Per-account mailboxes typically go under a parent named after the account.

5. Pilot one mailbox

   Migrate the smallest non-empty mailbox first. Verify in Outlook on the web that messages appear, dates are right, attachments open, and read flags are preserved. Fix any issues before scaling up.

6. Run the full migration

   Cap at 2–3 IMAP connections to Outlook.com. Outlook.com throttles aggressively at higher counts. Plan around 50–80 MB per minute realistic throughput.

Throughput and limits#

Outlook.com is the tighter of the two destinations. Plan for:

• 2 to 3 concurrent IMAP connections per account
• 50 to 80 MB per minute realistic throughput
• Per-message limit around 150 MB
• A mailbox quota of 15 GB on the free tier, 50 GB or more with Microsoft 365 subscriptions

A 5 GB Apple Mail user typically lands in 90 to 120 minutes. A 20 GB user is an overnight job. Anything above 25 GB needs a tenant on Microsoft 365 rather than Outlook.com.

Errors you should expect#

AUTHENTICATIONFAILED — MFA on, password rejected. Generate an app password or switch to OAuth2.

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

Message too large for destination — message exceeds 150 MB. Skip or migrate manually.

Folder UTF-7 conversion error — non-ASCII folder name encoding mismatch. Rename source folder to ASCII.

OAuth2 token expired — tool should auto-refresh. If not, restart with fresh consent.

Things that bite specifically on macOS#

A few Apple Mail quirks that catch people out.

Attachments stored separately. Modern Apple Mail can store attachments outside the .emlx file in the Attachments/ subdirectory. A migration tool that reads only the .emlx without reattaching from Attachments/ will deliver a message with broken attachment references. Verify attachments specifically during the pilot.

Smart Mailboxes. Smart Mailboxes are saved searches, not real mailboxes. They do not contain messages of their own. Skip them during folder mapping — their content is already in the underlying real mailboxes.

Encrypted messages. Apple Mail can encrypt with S/MIME certificates installed in Keychain. The encrypted bytes upload to Outlook fine, but they only decrypt on a client with the matching S/MIME certificate. Confirm the certificate is on the user's new device before declaring the migration complete.

Exchange-account mailboxes. Mail.app stores Exchange (EWS) accounts under directories named EWS-*. The .mbox packages inside contain the same .emlx files as IMAP accounts. The bigger issue is calendar and contacts data — those live in a separate Mac framework (CalendarStore, AddressBook) and do not migrate via mail tools.

Verification#

A done migration looks like this:

• Per-mailbox message counts match between Apple Mail and Outlook within a small margin
• Spot-check ten messages per mailbox: date, sender, body, attachments, threading
• Search in Outlook for known senders to confirm message reachability
• Confirm Junk and Trash were either migrated or intentionally skipped per the plan
• Confirm On My Mac content lives somewhere reachable in Outlook
• Reconfigure the user's mail client (Outlook for Mac or the new Outlook for Mac) and confirm the user can read their migrated mail before letting them go

Set a 30-day window before deleting the snapshot of ~/Library/Mail. Users find missing messages weeks after cutover, and the snapshot is your only reliable answer.

Adjacent paths#

If the destination is Gmail or Google Workspace, see migrate Apple Mail to Gmail. Label mapping is the main difference.

If the destination is Microsoft 365 specifically (business tenant, not Outlook.com), see migrate Apple Mail to Office 365. The auth model differs and conditional access becomes relevant.

If you have already exported Apple Mail's content as standard MBOX files, migrate MBOX to Outlook covers the upload step generically.

The MBOX format glossary entry explains why the standard format differs from Apple Mail's package format, which is worth understanding if your pilot shows odd behaviour. The PST, MBOX, and EML migration guide covers cross-format conversion in more depth if you need to hand a converted file to a downstream team.