Converters

The Apple Mail Envelope Index and when to rebuild it

It is the fix everybody reaches for and the one that fails most, because half these symptoms come from somewhere else.

Divya Krishnan 5 September 2026 7 min read

The Envelope Index is a database of everything about your mail except the mail. Headers, dates, flags, which mailbox holds what. When search returns nothing or Mail beachballs on a folder it has opened a thousand times, that database is the usual suspect. Rebuilding it does not touch a single message.

It is also the fix everybody reaches for and the one that fails most, because half these symptoms come from somewhere else entirely.

What the index actually is

Apple Mail keeps two separate things. The messages, stored as files on disk. And a SQLite database describing them.

The database lives in the MailData folder inside the Mail store, alongside two companion files ending in -shm and -wal that SQLite uses while writing. Together they hold every sender, subject, date, read state, flag and mailbox membership on the Mac.

Almost everything you see in Mail comes from that database rather than from the messages. The list of a mailbox, the sort order, the unread counts, the search results, the smart mailbox contents. Mail only reads an actual message file when you click one.

That separation is why a rebuild is safe. Delete the index and the messages are untouched, because they were never in it. Mail reads them again and writes a fresh database.

The folder sits under a version number that changes with macOS releases, which is why a path copied from an older guide points at nothing.

Match the symptom before you touch anything

This is the step everybody skips. It is why the same fix gets applied four times to a problem it cannot solve.

Symptom	Likely cause	Does a rebuild help
Unread counts wrong or stuck	Index out of step with the messages	Yes
Mailbox list slow to open, beachballs	Index bloated or damaged	Yes
Messages show blank or headers only	Index rows without their message files	Yes
Smart mailboxes empty or wrong	They are queries against the index	Yes
Search finds nothing, anywhere	Spotlight more than Mail	Sometimes
Search fails in one account only	A sync problem on that account	No
Messages missing from the server too	Not a local problem at all	No
Mail will not launch	Could be either. Try the index first	Worth trying

The fifth row is the one that costs people evenings. Mail search leans on Spotlight, so a Spotlight index that has stopped working takes Mail search down with it. No amount of rebuilding the Envelope Index changes that. Spotlight has a repair of its own.

Back up before you do it

Rebuilding is safe in the normal case and the normal case is not everybody.

Anything in an On My Mac mailbox exists only on this Mac. If the rebuild goes wrong there is no server to fetch it back from, which is the entire difference between an inconvenience and a loss.

So before anything else, check whether you have On My Mac mailboxes with content in them. If you do, get a copy off the machine first. Everything held on an IMAP or Exchange server can be re downloaded and needs no such care.

The rebuild

Quit Mail completely. Not the window, the application. A running Mail holds the database open and writes to it.
Open the MailData folder inside the Mail store, under the version folder for your macOS release.
Move every file beginning with Envelope Index to the desktop. That is the file itself plus the -shm and -wal companions. Move rather than delete, so you can put them back if anything looks wrong.
Open Mail and leave it alone. It builds a new database from the messages. On a large mailbox this takes a long time and looks like a hang.
Check search once it has settled, then delete the files from the desktop.

The fourth step is where people go wrong. A quarter of a million messages takes a while. The progress reporting is poor. Quitting halfway leaves a half built database that behaves worse than the one you replaced.

Rebuild Mailbox is a different thing

Mail has a Mailbox menu with a Rebuild command in it. The two get confused constantly.

Rebuild in that menu works on one mailbox. On an IMAP account it discards the local copy of that mailbox and downloads it again from the server. It is the right tool for one folder showing the wrong contents. It does nothing for an index problem spanning the whole application.

Deleting the Envelope Index works on everything at once and pulls from what is already on disk rather than from the server. Different scope, different source, different job.

What a rebuild will not fix

Worth knowing in advance, because a rebuild takes long enough that finding out afterwards is expensive.

Messages that are genuinely gone. The rebuild reads what is on disk. Nothing on disk means nothing in the new index.

Spotlight. A separate index maintained by macOS, with its own failure modes and its own repair.

An account that is not syncing. If the server connection is stalling, a local database rebuild leaves the stall exactly where it was.

A disk with no room. The rebuild writes a whole new database. On a nearly full disk it fails partway. The symptom afterwards looks like a corrupt index, which invites you to do the same thing again.

Why it goes wrong in the first place

Three causes cover most of it.

A macOS upgrade that moves the store to a new version folder has to convert the database on the way. A conversion that half completes leaves exactly these symptoms.

A force quit or a power loss while Mail was writing leaves the -wal file describing changes that never landed.

And size alone. A database tracking hundreds of thousands of messages across a decade degrades without anything dramatic happening to it.

None of those is preventable in any useful sense. The index is a cache of your mail rather than your mail, which is the reassuring part of the whole subject.

Common questions

What is the Envelope Index in Apple Mail?

A SQLite database holding the details of every message on the Mac, including senders, subjects, dates, flags and which mailbox each one is in. It sits in the MailData folder inside the Mail store. The messages themselves are separate files, which is why deleting the index does not delete mail.

Is it safe to delete the Envelope Index?

In the normal case yes, because Mail rebuilds it from the message files. The exception is On My Mac mailboxes, which exist nowhere else. If you have those with content in them, copy them off the Mac before starting.

Why is Apple Mail search not working even after a rebuild?

Because Mail search leans on Spotlight. A Spotlight index that has stopped working takes Mail search with it. Rebuilding the Envelope Index cannot fix that. Search failing in one account only points at a sync problem on that account instead.

How long does an Apple Mail rebuild take?

Minutes on a small mailbox and hours on a large one. Progress reporting is poor, so it frequently looks like a hang. Quitting partway leaves a half built database that behaves worse than the one you replaced.

What is the difference between Rebuild Mailbox and deleting the Envelope Index?

Rebuild Mailbox works on one mailbox and, on an IMAP account, re downloads it from the server. Deleting the index rebuilds everything at once from the files already on disk. Different scope and a different source.

Why does my Envelope Index keep breaking?

A macOS upgrade converting the database to a new version folder. A force quit or power loss while Mail was writing. Sheer size after years of accumulation. None of them is preventable, which is why it helps that the index is a cache rather than the mail itself.

Sources

Every file name and stated behaviour above traces back to one of these pages. Last verified on 5 September 2026.