Ferramenta Local para Limpeza do Gmail Sem Enviar Correspondência para Servidores de Terceiros

Em algum momento, cada um de nós abre o email e vê dezenas de milhares de mensagens não lidas. Descontos de lojas onde compramos algo há cinco anos, informativos de serviços, notificações de rastreadores de tarefas. A limpeza manual na própria interface do Gmail se torna um pesadelo porque o cliente web do Google reluta em lidar com seleções maiores que 50–100 mensagens por vez.

A maioria dos utilitários comerciais de limpeza de email funcionam por assinatura. Eles solicitam acesso completo à conta e enviam seus emails para seus próprios servidores para análise. O autor do projeto gmail-cleaner adotou uma abordagem diferente: escreveu uma ferramenta local leve com interface web que funciona exclusivamente na sua máquina via API oficial do Gmail.

Por Que Executar a Limpeza Localmente

A ideia principal por trás do projeto é a privacidade completa. Sem backends de terceiros, sem bancos de dados externos e sem planos pagos. Toda a stack é executada localmente, e seus dados não vão a lugar nenhum.

O aplicativo resolve quatro problemas comuns:

• Encontra newsletters e ajuda você a cancelar a inscrição com um clique.
• Agrupa emails por remetente, mostrando quem polui mais sua caixa de entrada.
• Exclui ou arquiva em massa conversas de destinatários selecionados.
• Marca milhares de emails como lidos em poucos segundos.

Todos os emails excluídos vão para a lixeira padrão do Gmail. Se você excluir algo por acidente, tem 30 dias para recuperar os dados através da interface web padrão do Google.

Para acelerar, o utilitário usa requisições em lote da API do Gmail, empacotando até 100 operações em uma única chamada. É por isso que limpar vários milhares de emails leva um tempo mínimo.

O Que Há Por Dentro e Como Funciona

Por baixo dos panos está o Python 3.9+ e um servidor web que serve uma interface limpa no estilo do próprio Gmail.

De uma perspectiva de segurança, você cria seu próprio aplicativo no Google Cloud Console. Isso significa que os tokens OAuth pertencem apenas a você, e as permissões são solicitadas apenas para o mínimo necessário: acesso de leitura e modificação para mover mensagens para a lixeira e alterar o status de leitura.

Os arquivos credentials.json e token.json são armazenados localmente. No build Docker, um volume separado ./data é fornecido para esse propósito, então você não precisará reautorizar após reiniciar o container.

Como Implantar o Projeto

A maneira mais fácil de executar o projeto é via Docker. Para entusiastas de ambientes virtuais, também há uma opção usando o gerenciador de pacotes uv.

Primeiro, você precisa ir ao Google Cloud Console, criar um projeto, habilitar a API do Gmail e gerar um Client ID OAuth (tipo Web application para Docker ou Desktop app para execução direta em Python). Certifique-se de adicionar seu email à lista de usuários de teste na tela de consentimento OAuth.

Salve o arquivo baixado como credentials.json na raiz do projeto.

Executando via Docker

Clone o repositório:

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

Coloque o arquivo credentials.json ao lado dele e inicie o container:

docker compose pull && docker compose up

Depois abra http://localhost:8766 no seu navegador, clique no botão Sign In, pegue o link de autorização do Google nos logs do container e confirme o acesso.

Executando via Python e uv

Se você não quer configurar o Docker, pode executar o script diretamente via uv:

uv sync
uv run python main.py

A interface estará disponível no mesmo endereço http://localhost:8766.

Filtros e Exportação de Dados

Além da limpeza simples, o projeto inclui filtros avançados. Você pode ordenar emails por tamanho de anexo, intervalo de datas ou categorias padrão do Gmail (Promoções, Social, Atualizações, Fóruns, Principal).

Se você precisa preservar informações sobre remetentes e datas antes de excluir correspondência de trabalho antiga, a interface pode exportar metadados para CSV.

Para Quem Isso É Útil

O projeto é ideal para qualquer pessoa cuja caixa de entrada ultrapassou a marca de 50.000 mensagens e está se aproximando do limite de armazenamento gratuito do Google Drive.

Sim, a configuração inicial requer 5–10 minutos de trabalho com o Google Cloud Console e criação de chaves OAuth. Mas em troca, você obtém uma ferramenta que não lê seus emails em servidores de terceiros e não requer assinatura mensal para a funcionalidade básica de limpeza.