📧 Gmail Unsubscribe Agent

⚠️ VERSÃO BETA - Este projeto está em fase ativa de desenvolvimento e testes. Use com cautela e sempre revise as ações antes da execução.

Agente local em Python para cancelar inscrições de e-mails de propaganda de forma segura, reversível e auditável usando a Gmail API.

🎯 Características

• ✅ APIs oficiais apenas (Gmail API via OAuth Desktop App)
• ✅ Fluxo de unsubscribe correto com prioridades:
  1. List-Unsubscribe-Post: List-Unsubscribe=One-Click → POST com header
  2. mailto: → e-mail automático "unsubscribe"
  3. Sem cabeçalho → filtro Gmail (arquivar + marcar como lido)
• ✅ Dry-run obrigatório - sempre mostra o que será feito antes
• ✅ Confirmação antes de executar (batch ou individual)
• ✅ Whitelist inteligente - nunca descadastra bancos, governo, etc.
• ✅ Undo - permite reverter filtros aplicados
• ✅ Rate limiting - 30-60 ações por hora com delays aleatórios
• ✅ Logs JSONL - auditoria completa em logs/unsubscribe_YYYYMMDD.jsonl

🚀 Instalação

1. Clone e configure o ambiente

# Clone o repositório
git clone <seu-repositorio>
cd gmail-unsubscribe-agent

# Execute o setup
python setup.py

2. Configure as credenciais do Gmail

1. Acesse Google Cloud Console
2. Crie um novo projeto ou selecione um existente
3. Ative a Gmail API
4. Crie credenciais OAuth 2.0 (Aplicativo Desktop)
5. Baixe o arquivo JSON e renomeie para credentials.json
6. Coloque o arquivo na pasta raiz do projeto

3. Primeira execução

# Execute uma análise (dry run)
python main.py analisar

# Execute o descadastro
python main.py executar

📋 Comandos Disponíveis

analisar - Análise (Dry Run)

python main.py analisar [--dias 30] [--max-emails 100]

• Analisa e-mails dos últimos N dias
• Mostra candidatos para descadastro
• Nunca executa ações - apenas mostra o que seria feito

executar - Executar Descadastros

python main.py executar [--dias 30] [--max-emails 100] [--lote]

• Executa o descadastro dos candidatos encontrados
• --lote: processa todos de uma vez (sem confirmação individual)
• Sem --lote: confirma cada candidato individualmente

reverter - Reverter Ações

python main.py reverter [--count 1]

• Reverte as últimas N ações realizadas
• Funciona apenas para filtros Gmail criados

status - Status do Sistema

python main.py status

• Mostra status atual do sistema
• Lista ações recentes
• Informações sobre rate limiting

🛡️ Segurança e Whitelist

O sistema possui whitelist automática que NUNCA descadastra:

Domínios Protegidos

• Governo: gov.br, receita.fazenda.gov.br, sefaz.gov.br
• Bancos: bancodobrasil.com.br, itau.com.br, bradesco.com.br, etc.
• E-commerce: amazon.com.br, mercadolivre.com.br, americanas.com.br, etc.
• Provedores: gmail.com, outlook.com, yahoo.com, etc.
• Mídia: globo.com, folha.com.br, g1.com.br, etc.

Palavras-chave Protegidas

• banco, financeiro, cartão, conta
• nota fiscal, nf-e, fatura, boleto
• governo, receita, tribunal, polícia
• alerta, urgente, importante, oficial

📊 Logs e Auditoria

Todos os logs são salvos em formato JSONL em logs/unsubscribe_YYYYMMDD.jsonl:

{
  "timestamp": "2024-01-15T10:30:00",
  "level": "ACTION",
  "message": "Action: one_click_unsubscribe",
  "data": {
    "sender": "newsletter@example.com",
    "url": "https://example.com/unsubscribe",
    "status_code": 200,
    "description": "One-click unsubscribe sent to newsletter@example.com"
  }
}

⚙️ Configuração

Edite o arquivo .env para personalizar:

# Rate Limiting
MAX_ACTIONS_PER_HOUR=50
MIN_DELAY_SECONDS=1
MAX_DELAY_SECONDS=3

# Logging
LOG_LEVEL=INFO

🔄 Fluxo de Unsubscribe

Prioridade 1: One-Click Unsubscribe

• Detecta header List-Unsubscribe-Post: List-Unsubscribe=One-Click
• Envia POST com header List-Unsubscribe: One-Click
• Mais seguro e eficiente

Prioridade 2: Mailto Unsubscribe

• Detecta links mailto: no header List-Unsubscribe
• Envia e-mail automático com assunto "Unsubscribe"
• Método tradicional

Prioridade 3: Filtro Gmail

• Quando não há headers de unsubscribe
• Cria filtro Gmail para arquivar e marcar como lido
• Reversível - pode ser desfeito com reverter

🚨 Importante

• ⚠️ Sempre execute analisar antes de executar
• ⚠️ O sistema NUNCA clica em links HTML - apenas usa headers
• ⚠️ Rate limiting automático - respeita limites da API
• ⚠️ Whitelist rigorosa - protege e-mails importantes
• ⚠️ Logs completos - auditoria de todas as ações

🆘 Suporte

Em caso de problemas:

1. Verifique os logs em logs/
2. Execute python main.py status para diagnóstico
3. Use python main.py reverter para desfazer ações
4. Verifique se credentials.json está configurado corretamente

📄 Licença

Este projeto é para uso pessoal e educacional. Use com responsabilidade e sempre respeite os termos de serviço do Gmail.