Limpiador local de Gmail sin enviar correspondencia a servidores de terceros

En algún momento, cada uno de nosotros abre su correo electrónico y ve decenas de miles de mensajes sin leer. Descuentos de tiendas donde compramos algo hace cinco años, resúmenes de servicios, notificaciones de rastreadores de tareas. La limpieza manual en la propia interfaz de Gmail se convierte en una pesadilla porque el cliente web de Google maneja con reluctancia selecciones de más de 50-100 mensajes a la vez.

La mayoría de las utilidades comerciales de limpieza de correo electrónico funcionan bajo un modelo de suscripción. Solicitan acceso completo a la cuenta y envían tus correos a sus propios servidores para su análisis. El autor del proyecto gmail-cleaner adoptó un enfoque diferente: desarrolló una herramienta local ligera con una interfaz web que funciona exclusivamente en tu máquina a través de la API oficial de Gmail.

¿Por qué ejecutar la limpieza localmente?

La idea principal del proyecto es la privacidad completa. Sin backends de terceros, sin bases de datos externas y sin planes de pago. Toda la pila se ejecuta localmente y tus datos no van a ningún otro lugar.

La aplicación resuelve cuatro problemas comunes:

• Encuentra boletines y te ayuda a darte de baja de ellos con un clic.
• Agrupa correos por remitente, mostrando quién satura más tu bandeja de entrada.
• Elimina o archiva masivamente conversaciones de remitentes seleccionados.
• Marca miles de correos como leídos en un par de segundos.

Todos los correos eliminados van a la papelera estándar de Gmail. Si eliminas accidentalmente algo que necesitabas, tienes 30 días para recuperar los datos a través de la interfaz web estándar de Google.

Para acelerar el proceso, la utilidad utiliza solicitudes por lotes de la API de Gmail, empaquetando hasta 100 operaciones en una sola llamada. Por eso limpiar varios miles de correos toma un tiempo mínimo.

¿Qué hay dentro y cómo funciona?

En su interior hay Python 3.9+ y un servidor web que sirve una interfaz limpia al estilo de Gmail.

Desde una perspectiva de seguridad, creas tu propia aplicación en Google Cloud Console. Esto significa que los tokens OAuth te pertenecen solo a ti y los permisos se solicitan solo para lo estrictamente necesario: acceso de lectura y modificación para mover mensajes a la papelera y cambiar el estado de lectura.

Los archivos credentials.json y token.json se almacenan localmente. En el build de Docker, se proporciona un volumen separado ./data para este propósito, así que no necesitarás reautorizar después de reiniciar el contenedor.

Cómo desplegar el proyecto

La forma más sencilla de ejecutar el proyecto es a través de Docker. Para los entusiastas de los entornos virtuales, también hay una opción usando el gestor de paquetes uv.

Primero, necesitas ir a Google Cloud Console, crear un proyecto, habilitar la API de Gmail y generar un Client ID de OAuth (tipo Web application para Docker o Desktop app para ejecución directa con Python). Asegúrate de añadir tu correo a la lista de usuarios de prueba en la pantalla de consentimiento de OAuth.

Guarda el archivo descargado como credentials.json en la raíz del proyecto.

Ejecución a través de Docker

Clona el repositorio:

git clone https://github.com/Gururagavendra/gmail-cleaner.git
cd gmail-cleaner

Coloca el archivo credentials.json junto a él e inicia el contenedor:

docker compose pull && docker compose up

Luego abre http://localhost:8766 en tu navegador, haz clic en el botón de Iniciar sesión, obtén el enlace de autorización de Google desde los logs del contenedor y confirma el acceso.

Ejecución a través de Python y uv

Si no quieres configurar Docker, puedes ejecutar el script directamente a través de uv:

uv sync
uv run python main.py

La interfaz estará disponible en la misma dirección http://localhost:8766.

Filtros y exportación de datos

Más allá de la limpieza simple, el proyecto incluye filtros avanzados. Puedes ordenar correos por tamaño de adjuntos, rango de fechas o categorías estándar de Gmail (Promociones, Social, Actualizaciones, Foros, Principal).

Si necesitas preservar información sobre remitentes y fechas antes de eliminar correspondencia de trabajo antigua, la interfaz puede exportar metadatos a CSV.

¿A quién le resultará útil?

El proyecto es ideal para cualquier persona cuya bandeja de entrada haya superado la marca de 50.000 mensajes y se acerque al límite de almacenamiento gratuito de Google Drive.

Sí, la configuración inicial requiere de 5 a 10 minutos de trabajo con Google Cloud Console y la creación de claves OAuth. Pero a cambio, obtienes una herramienta que no lee tus correos en servidores de terceros y no requiere una suscripción mensual para la funcionalidad básica de limpieza.