Fixing a corrupted Thunderbird popstate.dat file

TL;DR

Use the rebuild_thunderbird_popstate PHP script to regenerate your popstate.dat file by retrieving the UIDL list from your mail server.

Gebruik het rebuild_thunderbird_popstate PHP-script om je popstate.dat-bestand opnieuw te genereren door de UIDL-lijst van je mailserver op te halen.

Usa el script PHP rebuild_thunderbird_popstate para regenerar tu archivo popstate.dat recuperando la lista UIDL de tu servidor de correo.

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

Connects to your POP3 server (with optional SSL/TLS)
Authenticates with your credentials
Retrieves the UIDL list for all messages on the server
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

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

Check out the project on GitHub.

Het probleem

Wanneer Thunderbird crasht, kan het popstate.dat-bestand corrupt raken, leeg worden of volledig verdwijnen. Dit bestand houdt bij welke e-mails al zijn gedownload van de POP3-server.

Zonder dit bestand verliest Thunderbird het overzicht van wat er al is gedownload en probeert het alles opnieuw op te halen — mogelijk duizenden berichten, waardoor bandbreedte en tijd wordt verspild.

Dit probleem is gedocumenteerd als Thunderbird bug #263142.

De oplossing

De sleutel tot het oplossen hiervan is het ophalen van de UIDL (Unique Identifier Listing) voor e-mails die momenteel op de server zijn opgeslagen. Elke e-mail heeft een unieke identifier die Thunderbird gebruikt om de downloadstatus bij te houden.

Ik heb een PHP-script gemaakt genaamd rebuild_thunderbird_popstate dat verbinding maakt met je POP3-server, de UIDL-lijst ophaalt en een nieuw popstate.dat-bestand genereert.

Gebruik

php rebuild_popstate.php [opties] server [poort]

# Voorbeeld: Opnieuw opbouwen voor Gmail
php rebuild_popstate.php -s pop.gmail.com 995

# Voorbeeld: Standaard POP3-server
php rebuild_popstate.php mail.example.com 110

Opties

-c — Gebruik CRLF regeleinden (voor Windows-servers)
-d — Debug-modus
-f file — Uitvoerbestandsnaam (standaard: popstate.dat)
-i n — Negeer de laatste n berichten
-s — Gebruik veilige POP3 (SSL/TLS)
-v — Uitgebreide uitvoer

Hoe het werkt

Maakt verbinding met je POP3-server (met optionele SSL/TLS)
Authenticeert met je inloggegevens
Haalt de UIDL-lijst op voor alle berichten op de server
Genereert een correct geformatteerd popstate.dat-bestand

Installatie

# Kloon van GitHub
git clone https://github.com/Magentron/rebuild_thunderbird_popstate

# Voer het script uit
cd rebuild_thunderbird_popstate
php rebuild_popstate.php -s your-mail-server.com 995

Na het uitvoeren van het script

Sluit Thunderbird volledig af
Zoek je Thunderbird-profielmap
Vind de Mail/[account] map
Vervang het corrupte popstate.dat met het gegenereerde bestand
Herstart Thunderbird

Bekijk het project op GitHub.

El problema

Cuando Thunderbird se bloquea, el archivo popstate.dat puede corromperse, quedar vacío o desaparecer por completo. Este archivo rastrea qué correos electrónicos ya se han descargado del servidor POP3.

Sin este archivo, Thunderbird pierde el control de lo que ya ha descargado e intenta recuperar todo nuevamente — potencialmente miles de mensajes, desperdiciando ancho de banda y tiempo.

Este problema está documentado como error de Thunderbird #263142.

La solución

La clave para resolver esto es recuperar el UIDL (Listado de Identificadores Únicos) de los correos electrónicos almacenados actualmente en el servidor. Cada correo tiene un identificador único que Thunderbird usa para rastrear el estado de descarga.

Creé un script PHP llamado rebuild_thunderbird_popstate que se conecta a tu servidor POP3, recupera la lista UIDL y genera un nuevo archivo popstate.dat.

Uso

php rebuild_popstate.php [opciones] servidor [puerto]

# Ejemplo: Reconstruir para Gmail
php rebuild_popstate.php -s pop.gmail.com 995

# Ejemplo: Servidor POP3 estándar
php rebuild_popstate.php mail.example.com 110

Opciones

-c — Usar finales de línea CRLF (para servidores Windows)
-d — Modo de depuración
-f file — Nombre del archivo de salida (predeterminado: popstate.dat)
-i n — Ignorar los últimos n mensajes
-s — Usar POP3 seguro (SSL/TLS)
-v — Salida detallada

Cómo funciona

Se conecta a tu servidor POP3 (con SSL/TLS opcional)
Se autentica con tus credenciales
Recupera la lista UIDL de todos los mensajes en el servidor
Genera un archivo popstate.dat correctamente formateado

Instalación

# Clonar desde GitHub
git clone https://github.com/Magentron/rebuild_thunderbird_popstate

# Ejecutar el script
cd rebuild_thunderbird_popstate
php rebuild_popstate.php -s your-mail-server.com 995

Después de ejecutar el script

Cierra Thunderbird completamente
Localiza tu carpeta de perfil de Thunderbird
Encuentra el directorio Mail/[cuenta]
Reemplaza el popstate.dat corrupto con el archivo generado
Reinicia Thunderbird

Consulta el proyecto en GitHub.