Skip to content

COMO_USAR.md

Latest commit

 

History

History
287 lines (228 loc) · 7.15 KB

COMO_USAR.md

File metadata and controls

287 lines (228 loc) · 7.15 KB
Raw

📧 Como Usar o Gmail Unsubscribe Agent

🚀 Início Rápido

1. Ativar o Ambiente Virtual

# Sempre ative o ambiente virtual antes de usar
source venv/bin/activate

2. Configurar Credenciais Gmail

  1. Baixe o arquivo credentials.json do Google Cloud Console
  2. Coloque na pasta raiz do projeto
  3. Na primeira execução, o sistema abrirá o navegador para autorização

3. Primeira Análise

# Analisar e-mails dos últimos 30 dias
python main.py analisar

# Analisar e-mails dos últimos 7 dias, máximo 50 e-mails
python main.py analisar --dias 7 --max-emails 50

📋 Comandos Disponíveis

analisar - Análise Segura (Dry Run)

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

O que faz:

  • ✅ Analisa e-mails promocionais
  • ✅ Identifica candidatos para descadastro
  • ✅ Mostra métodos de unsubscribe disponíveis
  • ✅ NUNCA executa ações - apenas mostra o que seria feito
  • ✅ Respeita whitelist automática

Exemplo de saída:

📧 CANDIDATOS PARA DESCADASTRO (5 encontrados):
------------------------------------------------------------
 1. Newsletter Tech
    E-mail: newsletter@tech.com
    Assunto: Últimas notícias de tecnologia...
    Método: One-Click (POST)

 2. Promoções Store
    E-mail: promocoes@store.com
    Assunto: Ofertas imperdíveis desta semana...
    Método: E-mail Automático
    E-mail descadastro: unsubscribe@store.com

executar - Executar Descadastros

# Modo individual (com confirmação para cada candidato)
python main.py executar [--dias 30] [--max-emails 100]

# Modo lote (processa todos de uma vez)
python main.py executar --lote

O que faz:

  • ✅ Executa descadastros reais
  • ✅ Segue prioridades corretas (One-Click → Mailto → Filtro)
  • ✅ Confirma antes de executar
  • ✅ Registra todas as ações nos logs
  • ✅ Aplica rate limiting automático

Modo Individual:

[1/5] Newsletter Tech
    E-mail: newsletter@tech.com
    Método: one_click
Deseja processar este candidato? (s/n): s
  ✅ Sucesso: POST request sent

Modo Lote:

Deseja processar TODOS os 5 candidatos? (s/n): s
🚀 Processando 5 candidatos em lote...

[1/5] Processando: newsletter@tech.com
  ✅ Sucesso: POST request sent

[2/5] Processando: promocoes@store.com
  ✅ Sucesso: Unsubscribe email sent

reverter - Reverter Ações

# Reverter última ação
python main.py reverter

# Reverter últimas 3 ações
python main.py reverter --count 3

O que faz:

  • ✅ Remove filtros Gmail criados
  • ✅ Não pode reverter e-mails enviados ou POST requests
  • ✅ Mostra quais ações foram revertidas

Exemplo:

↩️  REVERTENDO ÚLTIMAS AÇÕES...

✅ 2 ação(ões) revertida(s):
  • newsletter@tech.com - filter
  • promocoes@store.com - filter

status - Status do Sistema

python main.py status

O que mostra:

  • ✅ Ações recentes realizadas
  • ✅ Localização dos logs
  • ✅ Status do rate limiting
  • ✅ Informações do sistema

🛡️ Segurança e Whitelist

Domínios Protegidos (NUNCA descadastrados)

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

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

Localização dos Logs

logs/unsubscribe_20240115.jsonl

Formato dos Logs

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

Verificar Logs

# Ver logs em tempo real
tail -f logs/unsubscribe_$(date +%Y%m%d).jsonl

# Filtrar apenas ações
grep '"level":"ACTION"' logs/unsubscribe_*.jsonl

# Filtrar apenas erros
grep '"level":"ERROR"' logs/unsubscribe_*.jsonl

🔄 Fluxo de Unsubscribe

Prioridade 1: One-Click Unsubscribe

  • Detecta: List-Unsubscribe-Post: List-Unsubscribe=One-Click
  • Ação: Envia POST com header List-Unsubscribe: One-Click
  • Vantagem: Mais seguro e eficiente
  • Reversível: Não (POST já foi enviado)

Prioridade 2: Mailto Unsubscribe

  • Detecta: Links mailto: no header List-Unsubscribe
  • Ação: Envia e-mail automático com assunto "Unsubscribe"
  • Vantagem: Método tradicional e confiável
  • Reversível: Não (e-mail já foi enviado)

Prioridade 3: Filtro Gmail

  • Detecta: Quando não há headers de unsubscribe
  • Ação: Cria filtro Gmail para arquivar e marcar como lido
  • Vantagem: Não envia nada para o remetente
  • Reversível: Sim (pode ser removido com reverter)

⚙️ Configuração Avançada

Editar Configurações

# Editar arquivo de configuração
nano .env

Parâmetros Disponíveis

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

# Logging
LOG_LEVEL=INFO

Personalizar Whitelist

Edite o arquivo src/config.py para adicionar/remover domínios ou palavras-chave.

🚨 Dicas Importantes

✅ Sempre Faça

  1. Execute analisar antes de executar
  2. Verifique os logs após execução
  3. Mantenha backups dos logs importantes
  4. Use reverter se necessário

❌ Nunca Faça

  1. Não compartilhe credentials.json
  2. Não execute sem verificar candidatos
  3. Não ignore mensagens de erro
  4. Não desative a whitelist

🔧 Em Caso de Problemas

  1. Verifique logs: grep ERROR logs/unsubscribe_*.jsonl
  2. Teste sistema: python test_system.py
  3. Verifique status: python main.py status
  4. Re-autorize: Delete token.json e execute novamente

📞 Exemplos Práticos

Cenário 1: Primeira Vez

# 1. Ativar ambiente
source venv/bin/activate

# 2. Analisar (dry run)
python main.py analisar --dias 7 --max-emails 20

# 3. Se satisfeito, executar
python main.py executar --dias 7 --max-emails 20

Cenário 2: Manutenção Semanal

# 1. Ativar ambiente
source venv/bin/activate

# 2. Análise rápida
python main.py analisar --dias 3 --max-emails 50

# 3. Execução em lote
python main.py executar --lote --dias 3 --max-emails 50

Cenário 3: Reverter Ações

# 1. Verificar status
python main.py status

# 2. Reverter últimas ações
python main.py reverter --count 2

# 3. Verificar logs
tail -5 logs/unsubscribe_$(date +%Y%m%d).jsonl

🎯 Resultados Esperados

Antes do Uso

  • Caixa de entrada com muitos e-mails promocionais
  • Dificuldade para encontrar e-mails importantes
  • Tempo perdido organizando e-mails

Após o Uso

  • ✅ Caixa de entrada mais limpa
  • ✅ E-mails importantes mais visíveis
  • ✅ Menos tempo organizando e-mails
  • ✅ Logs completos de todas as ações
  • ✅ Possibilidade de reverter filtros se necessário