Fixing a Corrupted Thunderbird popstate.dat File

The problem

When Thunderbird crashes, the popstate.dat file can become corrupted, empty, or go missing entirely. This file tracks which emails have already been downloaded from the POP3 server.

Without this file, Thunderbird loses track of what it has already downloaded and attempts to retrieve everything again — potentially thousands of messages, wasting bandwidth and time.

This issue is documented as Thunderbird bug #263142.

The solution

The key to solving this is retrieving the UIDL (Unique Identifier Listing) for emails currently stored on the server. Each email has a unique identifier that Thunderbird uses to track download state.

I created a PHP script called rebuild_thunderbird_popstate that connects to your POP3 server, retrieves the UIDL list, and generates a new popstate.dat file.

Usage

php rebuild_popstate.php [options] server [port]

# Example: Rebuild for Gmail
php rebuild_popstate.php -s pop.gmail.com 995

# Example: Standard POP3 server
php rebuild_popstate.php mail.example.com 110

Options

• -c — Use CRLF line endings (for Windows servers)
• -d — Debug mode
• -f file — Output filename (default: popstate.dat)
• -i n — Ignore the last n messages
• -s — Use secure POP3 (SSL/TLS)
• -v — Verbose output

How it works

1. Connects to your POP3 server (with optional SSL/TLS)
2. Authenticates with your credentials
3. Retrieves the UIDL list for all messages on the server
4. Generates a properly formatted popstate.dat file

Installation

# Clone from GitHub
git clone https://github.com/Magentron/rebuild_thunderbird_popstate

# Run the script
cd rebuild_thunderbird_popstate
php rebuild_popstate.php -s your-mail-server.com 995

After running the script

1. Close Thunderbird completely
2. Locate your Thunderbird profile folder
3. Find the Mail/[account] directory
4. Replace the corrupted popstate.dat with the generated file
5. Restart Thunderbird

Check out the project on GitHub.