noambrand/gmail-label-cleanup

Limpeza de rótulos do Gmail

Organize um grande backlog de e-mails do Gmail nos próprios rótulos do proprietário e faça com que e-mails futuros se rotulem automaticamente.

Os conectores Gmail integrados na maioria dos assistentes rotulam uma thread por chamada e não têm API de filtros. Isso é muito lento para milhares de mensagens e não impede que a pilha cresça novamente. Esta skill usa um servidor MCP completo para Gmail, que oferece filtros reais do lado do servidor e lotes de 50 mensagens.

Antes da primeira execução

1. Instale o servidor MCP. Veja install/INSTALL.md. Ele precisa de um cliente OAuth desktop do Google Cloud e um login no navegador. Aproximadamente dez minutos, uma vez.
2. Crie o arquivo de regras. Copie references/rules-TEMPLATE.md para um arquivo privado (o modelo sugere my-rules.md, que já está excluído pelo .gitignore) e preencha-o com base no histórico da própria conta. Nunca invente as regras. Veja "Aprendendo as regras" abaixo.

A única regra que faz isso funcionar

As regras são aprendidas da rotulagem passada do próprio proprietário, nunca inventadas.

Para cada remetente ou assunto, veja onde aquela pessoa já arquivou aquele remetente e copie. Apenas quando um remetente não aparece em lugar nenhum do histórico é permitido um palpite, e então ele é registrado em uma seção "adivinhado" para que possa ser corrigido. Um rótulo errado é barato de corrigir; um rótulo errado aplicado silenciosamente a 300 mensagens não é.

A segunda regra, aprendida da maneira mais difícil: o conteúdo conta, não apenas o remetente. Um remetente é uma dimensão. Um boletim informativo sobre dinheiro de uma editora de bem-estar merece o rótulo de dinheiro também. Uma thread pode carregar mais de um rótulo.

Aprendendo as regras

Pergunte à conta, não à pessoa. Para cada rótulo, leia o que já está nele:

search_emails: label:"<nome do rótulo>"

Leia de 30 a 50 resultados e anote os remetentes. Essa lista é a regra. Repita para cada rótulo. Depois, use list_email_labels para obter os IDs dos rótulos, que são o que batch_modify_emails realmente aceita.

Faça isso uma vez, escreva no arquivo de regras e continue adicionando a cada passagem. Cada passagem descobre remetentes que a anterior não tinha visto.

Executando uma passagem

Uma passagem é um pedaço de trabalho limitado, registrado e reversível. Mire em 200 a 300 mensagens. Não tente fazer tudo de uma vez.

1. Confirme que os filtros existem.

list_filters

Se os filtros do arquivo de regras estiverem faltando, crie-os primeiro com create_filter, um por grupo de rótulos, usando critérios from:. Os filtros são a parte que impede o problema de voltar.

2. Encontre e-mails não rotulados.

Caixa de entrada primeiro:

search_emails: has:nouserlabels in:inbox

Depois que a caixa de entrada estiver reduzida às mensagens que estão deliberadamente vazias, o resto do trabalho é arquivo. Navegue por data, movendo o limite mais antigo a cada vez:

search_emails: has:nouserlabels -in:inbox -in:sent -in:draft -in:trash -in:spam -in:chats before:YYYY/MM/DD

Pegue de 50 a 60 por página. Defina before: como a data do resultado mais antigo que você acabou de tratar, e a próxima chamada continua de onde você parou. Isso é mais confiável do que tokens de paginação e sobrevive a interrupções.

3. Agrupe por rótulo, depois em lote.

Organize a página em uma lista de IDs de mensagens por rótulo e, em seguida, uma chamada batch_modify_emails por rótulo com addLabelIds. Nunca uma chamada por mensagem.

Se um lote retornar Too many concurrent requests for user, tente novamente apenas os IDs com falha. A chamada informa exatamente quais falharam.

4. Registre. Anexe uma entrada datada ao log de desfazimento. Veja "O log de desfazimento" abaixo.

Nunca toque

• Códigos de login únicos, links mágicos, redefinições de senha e alertas de segurança. Estes permanecem sem rótulo e nunca são movidos para a lixeira. Se uma pessoa precisa encontrar um código de login rapidamente, um rótulo não ajuda e uma regra de lixeira atrapalha ativamente.
• Qualquer coisa na lista "nunca rotular" do próprio proprietário. As pessoas têm publicações e remetentes que querem deixar vazios, e elas lhe dirão. Escreva cada um no arquivo de regras no momento em que disserem, em suas palavras.
• E-mails familiares e pessoais, a menos que o proprietário já tenha rotulado essa pessoa.

Movendo para a lixeira

Mova para a lixeira apenas o que o proprietário autorizou explicitamente, e apenas por correspondência de assunto. O conjunto padrão seguro são avisos de termos de serviço e política de privacidade:

subject:("terms of service" OR "terms and conditions" OR "terms of use"
         OR "privacy policy" OR "user agreement")
negatedQuery: subject:(code OR verification OR verify OR "security alert" OR password)

A consulta negada não é opcional. Sem ela, um e-mail "Verify your account - updated terms" vai para a Lixeira.

A Lixeira do Gmail é recuperável por 30 dias. Nada nesta skill jamais exclui.

O log de desfazimento

Cada passagem anexa uma entrada datada. É o registro que torna o trabalho reversível e revisável:

• A data e o número da passagem.
• Se os filtros existiam, e quais foram criados.
• A quantidade rotulada e a quantidade por rótulo.
• Decisões de julgamento, nomeadas. Quais remetentes não tinham precedente, o que foi decidido e por quê. Esta é a parte que é corrigida depois.
• O que foi confirmado como vazio e intocado.

Veja examples/undo-log-EXAMPLE.md. Escreva mesmo quando a passagem for entediante. Especialmente nesse caso.

Filtros não tocam em e-mails antigos

Isso pega todo mundo, então diga em voz alta para o proprietário:

Um filtro do Gmail só é executado em e-mails que chegam após a criação do filtro. Ele nunca alcança para trás. Portanto, as duas metades deste trabalho são genuinamente separadas: os filtros lidam com o futuro automaticamente, e o backlog do arquivo precisa ser trabalhado manualmente, passagem por passagem, exatamente como descrito acima.

O que significa: depois que algumas passagens descobrirem os remetentes reais de alto volume, volte e adicione filtros para eles também. Caso contrário, esses remetentes continuarão chegando sem rótulo e o backlog se reconstruirá atrás de você.

Revertendo uma passagem

Leia a entrada do log de desfazimento para a passagem e, em seguida, use batch_modify_emails com removeLabelIds nos mesmos IDs de mensagem. Para qualquer coisa movida para a lixeira, untrash funciona por 30 dias. É por isso que o log registra contagens e raciocínio, em vez de apenas "feito".