Gmail Nodes - Documentação Completa

📧 Visão Geral

Esta pasta contém a documentação completa de 16 tools do Gmail Executor para o Lumina Flow Builder. Essas ferramentas permitem automação completa de email através da API do Gmail usando autenticação OAuth2.

🔑 Configuração OAuth2

Todas as tools Gmail requerem credenciais OAuth2:

{
  clientId: "YOUR_CLIENT_ID.apps.googleusercontent.com",
  clientSecret: "YOUR_CLIENT_SECRET",
  refreshToken: "YOUR_REFRESH_TOKEN"
}

Como obter: 1. Google Cloud Console 2. Criar projeto > APIs e Serviços > Credenciais 3. Criar credenciais > ID do cliente OAuth 2.0 4. Usar OAuth Playground para obter refresh_token

📚 Tools Documentadas

✅ Envio de Emails (3 tools)

Tool	Status	Descrição
send_email	✅ Implementada	Enviar email texto simples
send_html_email	✅ Implementada	Enviar email com HTML formatado
send_with_attachment	✅ Implementada	Enviar email com anexos (PDF, imagens, etc)

✅ Resposta e Encaminhamento (2 tools)

Tool	Status	Descrição
reply_to_email	✅ Implementada	Responder email mantendo thread
forward_email	✅ Implementada	Encaminhar email para outros destinatários

✅ Busca e Leitura (3 tools)

Tool	Status	Descrição
get_emails	✅ Implementada	Listar emails da caixa de entrada
get_email_by_id	✅ Implementada	Buscar email específico por ID
search_emails	✅ Implementada	Busca avançada com queries Gmail

⚠️ Gerenciamento de Status (2 tools - NÃO IMPLEMENTADAS)

Tool	Status	Descrição
mark_as_read	⚠️ Não Implementada	Marcar email como lido
mark_as_unread	⚠️ Não Implementada	Marcar email como não lido

✅ Exclusão (1 tool)

Tool	Status	Descrição
delete_email	✅ Implementada	Deletar email permanentemente

⚠️ Organização (3 tools - NÃO IMPLEMENTADAS)

Tool	Status	Descrição
trash_email	⚠️ Não Implementada	Mover para lixeira (recuperável)
archive_email	⚠️ Não Implementada	Arquivar email (remove da inbox)

⚠️ Labels (2 tools - NÃO IMPLEMENTADAS)

Tool	Status	Descrição
add_label	⚠️ Não Implementada	Adicionar label/etiqueta ao email
remove_label	⚠️ Não Implementada	Remover label/etiqueta do email

⚠️ Rascunhos (1 tool - NÃO IMPLEMENTADA)

Tool	Status	Descrição
create_draft	⚠️ Não Implementada	Criar rascunho para revisão

📊 Status da Implementação

✅ Implementadas: 9/16 (56%)
⚠️ Não Implementadas: 7/16 (44%)

Tools Implementadas no Código

O arquivo /home/zielinski/develop/gptapi/src/whatsapp-flows/executors/gmail-executor.service.ts atualmente implementa:

✅ send - Envio de emails (texto, HTML, com anexos)
✅ get - Buscar email específico por ID
✅ getAll - Listar/buscar múltiplos emails
✅ delete - Deletar email permanentemente
✅ reply - Responder email mantendo thread
✅ forward - Encaminhar email

Tools Que Precisam Implementação

Para completar as 16 tools, implementar:

⚠️ mark_as_read - Modificar email removendo UNREAD label
⚠️ mark_as_unread - Modificar email adicionando UNREAD label
⚠️ trash - Mover email para lixeira
⚠️ archive - Arquivar email (remover INBOX label)
⚠️ add_label - Adicionar label customizada
⚠️ remove_label - Remover label customizada
⚠️ create_draft - Criar rascunho

🚀 Exemplos Rápidos

Enviar Email Simples

{
  "type": "gmail",
  "operation": "send",
  "oauth2": { "clientId": "...", "clientSecret": "...", "refreshToken": "..." },
  "to": "destinatario@example.com",
  "subject": "Assunto",
  "message": "Corpo do email"
}

Buscar Emails Não Lidos

{
  "type": "gmail",
  "operation": "getAll",
  "oauth2": { "clientId": "...", "clientSecret": "...", "refreshToken": "..." },
  "query": "is:unread",
  "maxResults": 10
}

Responder Email

{
  "type": "gmail",
  "operation": "reply",
  "oauth2": { "clientId": "...", "clientSecret": "...", "refreshToken": "..." },
  "messageId": "18f2b9c4d5e6a7f8",
  "replyMessage": "Obrigado pela mensagem!"
}

📖 Documentação de Referência

Cada tool possui documentação completa incluindo:

✅ O que é e por que existe
✅ Como funciona internamente (código TypeScript)
✅ Quando usar e quando NÃO usar
✅ Parâmetros detalhados com flows testáveis
✅ Exemplos práticos com JSON completo
✅ Resposta esperada do node
✅ Boas práticas e dicas

🔗 Links Úteis

💡 Dicas Gerais

Teste OAuth2 primeiro: Use testConnection() antes de enviar emails
Respeite limites: Gmail tem quotas de API (verifique no Console)
Use queries específicas: Filtrar no servidor é mais eficiente
Armazene tokens com segurança: refreshToken nunca expira se bem mantido
Erros 401: Indicam problema de autenticação OAuth2

🆘 Troubleshooting

Erro "invalid_grant"

refreshToken expirado ou revogado
Reautenticar via OAuth Playground

Erro 401 "Authentication failed"

clientId ou clientSecret incorretos
Verificar credenciais no Google Cloud Console

Erro 403 "Rate limit exceeded"

Muitas requisições em curto período
Implementar backoff exponencial

Email não enviado

Verificar se conta Gmail está ativa
Conferir se API Gmail está habilitada no projeto

📝 Contribuindo

Para adicionar nova funcionalidade:

Implementar método no gmail-executor.service.ts
Adicionar case no switch do execute()
Atualizar validate() e getSupportedOperations()
Criar documentação seguindo padrão dos arquivos existentes
Atualizar este README

Criado em: 12 de Outubro de 2025 Última atualização: 12 de Outubro de 2025 Status: 9/16 tools implementadas, 7/16 documentadas mas pendentes de implementação