SEARCH_EMAILS - Buscar Emails Avançado

O que é este Node?

O SEARCH_EMAILS é um alias para GET_EMAILS com foco em queries de busca avançadas do Gmail, permitindo filtros complexos e pesquisa textual refinada.

Por que este Node existe?

Buscar emails com critérios específicos é essencial para automação inteligente. O SEARCH_EMAILS existe para:

Busca refinada: Encontrar emails com filtros complexos
Queries Gmail: Usar sintaxe avançada de busca do Gmail
Filtragem precisa: Combinar múltiplos critérios
Automação contextual: Processar apenas emails relevantes

Como funciona internamente?

SEARCH_EMAILS usa a mesma implementação de GET_EMAILS, mas com ênfase no parâmetro query. O sistema:

Monta query: Combina filtros de busca Gmail
Executa busca: Usa gmail.users.messages.list() com query
Recupera resultados: Busca detalhes de cada email encontrado
Filtra servidor-side: Gmail processa filtros antes de retornar
Se sucesso: Retorna apenas emails que atendem critérios

Código interno: Usa getAllMessages() do gmail-executor.service.ts (linhas 370-391)

Quando você DEVE usar este Node?

Use SEARCH_EMAILS sempre que precisar de busca filtrada de emails:

Casos de uso

Monitorar remetente: "Buscar todos emails de cliente@example.com"
Filtrar por período: "Emails recebidos nos últimos 7 dias"
Anexos específicos: "Emails com PDFs anexados"
Assunto específico: "Emails sobre 'fatura' ou 'boleto'"

Quando NÃO usar SEARCH_EMAILS

Email conhecido: Use GET_EMAIL_BY_ID se tem messageId
Todos emails: Use GET_EMAILS sem query
ID direto: Use GET_EMAIL_BY_ID para acesso direto

Parâmetros

Campo	Tipo	Obrigatório	Descrição
oauth2	object	Sim	Credenciais OAuth2
operation	string	Sim	Use "getAll"
query	string	Sim	Query de busca Gmail
maxResults	number	Não	Quantidade máxima (padrão: 10)

Queries Avançadas Gmail

Busca por Remetente

from:email@example.com
from:*@dominio.com

Busca por Assunto

subject:"Pedido Aprovado"
subject:(fatura OR boleto)

Busca por Datas

after:2025/10/01
before:2025/10/31
newer_than:7d
older_than:1m

Busca por Anexos

has:attachment
filename:pdf
filename:contrato.pdf

Busca por Status

is:unread
is:read
is:starred
is:important

Combinar Critérios

from:cliente@example.com subject:fatura has:attachment
is:unread after:2025/10/01

Exemplo 1: Buscar Faturas Não Lidas

Objetivo: Encontrar emails de fatura não lidos com anexo

JSON para Importar

{
  "name": "Buscar Faturas Pendentes",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "gmail_1",
      "type": "gmail",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Buscar Faturas",
        "operation": "getAll",
        "oauth2": {
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_SECRET",
          "refreshToken": "YOUR_TOKEN"
        },
        "query": "subject:fatura is:unread has:attachment",
        "maxResults": 20
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Encontrou?",
        "parameters": {
          "condition": "{{gmail_1.messages.length}} > 0"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 50 },
      "data": {
        "label": "Listar Faturas",
        "parameters": {
          "message": "🧾 {{gmail_1.messages.length}} faturas pendentes encontradas"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 700, "y": 150 },
      "data": {
        "label": "Nenhuma",
        "parameters": {
          "message": "✅ Nenhuma fatura pendente"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "gmail_1" },
    { "source": "gmail_1", "target": "condition_1" },
    { "source": "condition_1", "target": "message_1", "label": "true" },
    { "source": "condition_1", "target": "message_2", "label": "false" },
    { "source": "message_1", "target": "end_1" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 🧾 3 faturas pendentes encontradas

Exemplo 2: Monitorar Cliente Específico

Objetivo: Buscar emails de cliente nos últimos 7 dias

JSON para Importar

{
  "name": "Monitorar Comunicação Cliente",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Email Cliente",
        "parameters": {
          "message": "Email do cliente a monitorar?",
          "variable": "emailCliente"
        }
      }
    },
    {
      "id": "gmail_1",
      "type": "gmail",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar Emails",
        "operation": "getAll",
        "oauth2": {
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_SECRET",
          "refreshToken": "YOUR_TOKEN"
        },
        "query": "from:{{emailCliente}} newer_than:7d",
        "maxResults": 50
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Resultado",
        "parameters": {
          "message": "📊 Encontrados {{gmail_1.messages.length}} emails de {{emailCliente}} nos últimos 7 dias"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "gmail_1" },
    { "source": "gmail_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Email do cliente a monitorar?
Usuário: cliente@empresa.com
Sistema: 📊 Encontrados 12 emails de cliente@empresa.com nos últimos 7 dias

Resposta do Node

Idêntica a GET_EMAILS - retorna array de mensagens filtradas.

Boas Práticas

✅ SIM: - Use queries específicas para reduzir resultados - Combine múltiplos critérios com espaço - Teste queries no Gmail web primeiro - Use aspas para textos exatos

❌ NÃO: - Não faça queries muito amplas (performance) - Não ignore maxResults (limite de API) - Não confie em case-sensitive (Gmail ignora)

Dicas

💡 Dica 1: Teste queries complexas no Gmail web antes 💡 Dica 2: Use newer_than:Xd para período relativo 💡 Dica 3: OR deve ser maiúsculo na query 💡 Dica 4: -palavra exclui emails com palavra 💡 Dica 5: Combine com LOOP para processar resultados

Próximo Node

→ GET_EMAILS - Listar emails → GET_EMAIL_BY_ID - Email específico → MARK_AS_READ - Marcar como lido