Migrate Apple Mail to Office 365: Local Library to Exchange Online

Microsoft 365 has good import tooling for PST and good migration batches for IMAP-backed source servers. It has nothing built in for Apple Mail. The macOS Mail app stores everything as .emlx files inside .mbox package directories under ~/Library/Mail, and none of Microsoft's import endpoints recognise that format. To move a Mac user to Exchange Online, you either upload Apple Mail content over IMAP to the user's new mailbox, or you convert the local mailbox tree to PST and feed it to Microsoft 365's import service. Both routes are doable. Neither is automatic.

Picking the upload path#

Microsoft 365's admin centre exposes PST Network Upload, PST Drive Shipping, and IMAP migration batches. PST Network Upload takes PST files via AzCopy into Azure storage, then assigns them to mailboxes via a CSV mapping. IMAP migration batches read from a remote IMAP server. None of these read Apple Mail directly.

You have two practical paths.

Path A: Direct IMAP upload to Microsoft 365. A migration tool reads .emlx files from the Apple Mail packages and APPENDs each message to outlook.office365.com:993. Simple per user. Constrained by Exchange Online IMAP throttling at scale.

Path B: Convert Apple Mail to PST, then Network Upload. Convert each Apple Mail mailbox to a PST file using a converter, upload PSTs to Azure storage via AzCopy, then map PSTs to mailboxes in the M365 admin centre. Faster for large mailboxes and for many mailboxes, but adds disk and a conversion step.

Pick A when you have under about 5 GB per mailbox and fewer than ten Mac users. Pick B at scale or when individual mailboxes exceed 5 GB.

The rest of this post covers Path A. For Path B, pair this guide's source-side preparation with the Office 365 migration guide for Network Upload steps.

Inventorying the Mac source#

You need to know what you are moving before you move it.

Find ~/Library/Mail#

Library is hidden in Finder. Hold Option, click Go in the menu bar, choose Library. Open Mail. Look for the highest-numbered V folder — V10 on Sequoia and Sonoma and Ventura, V9 on Monterey, V8 on Big Sur, V7 on Catalina, lower on older macOS.

Inside the V folder you find:

• MailData/ — local config, not for migration
• Per-account directories like IMAP-user@host or EWS-user@host
• Mailboxes/ — On My Mac local content not backed by any server

Each .mbox is a package (bundle) — a directory disguised as a file. Inside, a UUID-named subdirectory contains Messages/ (the .emlx files), an Info.plist, and on modern macOS often an Attachments/ subdirectory where Mail stores attachments separately from the .emlx envelope.

Inventory before staging#

For each Mac user, list the .mbox packages, their sizes, and which account they belong to. Total per user tells you whether Path A or Path B is right. Per-account totals tell you how to set up parallelism across mailboxes.

Pay attention to On My Mac content under Mailboxes/. That is local-only mail. The user's IMAP or Exchange account does not have a server copy. Migrate it carefully — losing it is permanent.

Microsoft 365 destination setup#

Exchange Online IMAP is the destination protocol for Path A. Setting it up correctly is half the migration.

Confirm IMAP is enabled#

In the Exchange admin centre, find the target user under Recipients > Mailboxes. Open the mailbox and check Manage email apps. IMAP should be enabled. If your tenant baseline disabled it, switch it on for the migration period.

Sort out authentication#

Microsoft has progressively disabled basic authentication for Exchange Online IMAP. Most tenants today require OAuth2.

OAuth2 path: register an Azure AD application with the IMAP.AccessAsUser.All delegated permission. Configure your migration tool with the client ID, tenant ID, and (where required) a client secret. The user grants consent on first use. Tokens refresh automatically.

App password path: works only for users with MFA on and where the tenant allows app passwords (many do not). Generate at account.microsoft.com under Security info > Add sign-in method > App password. The result is a 16-character string.

For fleet migrations, you can use a service account with delegated mailbox access plus impersonation rights, but Microsoft is phasing this out. Stick with OAuth2.

The app password walkthrough covers Microsoft-specific edge cases when MFA blocks your tool.

Check conditional access#

In the Microsoft Entra admin centre, Protection > Conditional Access. Look for policies that:

• Require compliant devices and apply to all cloud apps
• Block legacy authentication
• Require app-enforced restrictions on Office 365

Any of these can reject your migration tool. Either exempt the migration user explicitly, exempt the registered Azure AD app, or run the migration from a network range the policies allow.

Source-side preparation#

Same Mac, same prep regardless of destination.

Quit Mail.app properly#

Cmd+Q in Mail.app. Then check Activity Monitor for any process containing "Mail" — Mail Web Content, MailQuickLook, etc. Force-quit anything that remains. Apple Mail rewrites cache files while running, and any tool reading the package at the same time can corrupt the source.

Snapshot ~/Library/Mail#

Copy the entire Mail directory to an external drive. This is your rollback path. Skipping the snapshot turns a recoverable mistake into a lost mailbox.

Identify attachments handling#

Modern Apple Mail stores some attachments inside the Attachments/ subdirectory of the .mbox package, separately from the .emlx envelope. Confirm your migration tool reattaches those during upload. A pilot with messages known to have large attachments tells you whether the tool handles this correctly.

Running the migration#

1. Snapshot and inventory

   Mail.app quit, ~/Library/Mail copied, package sizes listed. Decide which mailboxes go in which wave.

2. Connect Microsoft 365 with OAuth2

   Point the migration tool at outlook.office365.com:993 with TLS. Configure with the Azure AD app credentials. Test connectivity with a single throwaway message before bulk runs.

3. Map Apple Mail folders to Exchange folders

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

4. Pilot one full mailbox

   Migrate one user fully. Verify message counts, dates, read flags, attachments, threading. Confirm Outlook on the web shows the migrated mail correctly.

5. Bulk run overnight

   Cap at 2–3 IMAP connections per mailbox, 5–10 mailboxes concurrent. Schedule the start for 18:00 local. Monitor for throttling. Resume any failed mailboxes the next morning.

6. Verify and cut over

   Per-folder count comparison, ten-message spot checks per mailbox, search verification, then Outlook desktop reconfiguration on each Mac.

Throughput, throttling, and limits#

Exchange Online IMAP runs at about 80–120 MB per minute per connection in healthy conditions. The practical ceiling shows up as Too many simultaneous connections, Server unavailable, or long stalls when you push past the tenant rate limit.

Plan around:

• 2–3 IMAP connections per mailbox
• 5–10 mailboxes concurrent across the tenant
• About 90 minutes per 5 GB of mailbox content
• 5–15 minute throttle recovery after hitting the rate limit

If the bulk run hits a throttle wall, stop, wait an hour, lower parallelism, resume. Pushing harder extends the throttle window for the entire tenant.

Errors you should expect#

AUTHENTICATIONFAILED — token expired or basic auth disabled. Reauthorise via OAuth2.

Too many simultaneous connections — drop parallelism, wait, retry.

Message too large for destination — Exchange Online accepts 150 MB by default but tenants can lower. Raise MaxSendSize and MaxReceiveSize if you have admin rights, or skip affected messages.

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

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

STARTTLS handshake failed — usually a corporate proxy intercepting TLS. Whitelist outlook.office365.com or run from an unproxied network.

Apple Mail specifics#

A few macOS-specific things that catch people out:

Separately stored attachments. Confirm your tool reattaches them. Test with a known message that has a 20MB+ attachment.

S/MIME encrypted messages. Bytes upload fine but only decrypt where the matching cert is installed. Plan how the user reads encrypted mail post-cutover — usually by copying the S/MIME cert from the Mac keychain to the new device or to Microsoft 365.

Exchange-account mailboxes. Apple Mail can connect to Exchange via EWS. Those .mbox packages contain the same .emlx files. Calendars and contacts from Exchange live elsewhere on macOS and need separate migration paths.

Smart Mailboxes. Saved searches, not real mailboxes. Skip during folder mapping. Rebuild as Outlook Search Folders afterwards.

Mail Activity log. Mail.app keeps a log under MailData. It does not migrate. If a user troubleshoots a missing message after cutover, point them at the snapshot, not the live source.

Verification#

A done Apple Mail to Office 365 migration looks like:

• Per-folder count comparison between Apple Mail and the destination mailbox in Outlook on the web. Counts should match within a small margin.
• Spot-check ten messages per major folder: date, sender, body, attachments, threading.
• Outlook search for known senders returns the migrated mail.
• Attachments open correctly, including ones Apple Mail stored separately.
• On My Mac content reached the destination under the expected parent folder.
• The user's chosen Outlook client is configured and they can read the migrated mail before cutover is declared done.

Keep the ~/Library/Mail snapshot for at least 30 days. Missing-message reports surface weeks after cutover and the snapshot is your only reliable way to answer them.

Related routes#

If the destination is Outlook.com (consumer) instead of Microsoft 365 (business), see migrate Apple Mail to Outlook. The auth model is simpler and the throughput limits are different.

If the destination is Gmail or Google Workspace, migrate Apple Mail to Gmail covers label-mapping and Gmail's daily upload cap.

For the PST route (Path B), pair this guide with migrate MBOX to Office 365 for the upload step and with the Office 365 migration guide for Network Upload mechanics.

The MBOX format glossary entry explains the standard MBOX layout and how Apple Mail's package format differs.