Pular para conteúdo

GET_EMAILS - Buscar Emails da Caixa de Entrada

O que é este Node?

O GET_EMAILS é o node responsável por recuperar lista de emails da caixa de entrada do Gmail com suporte a filtros, queries de busca e limite de resultados.

Por que este Node existe?

Acessar emails programaticamente permite automação de processos baseados em comunicações recebidas. O GET_EMAILS existe para:

  1. Monitorar inbox: Verificar novos emails automaticamente
  2. Processar em lote: Recuperar múltiplos emails de uma vez
  3. Filtrar conteúdo: Buscar emails específicos com queries
  4. Integrar sistemas: Conectar email com outros sistemas

Como funciona internamente?

Quando o GET_EMAILS é executado, o sistema:

  1. Valida OAuth2: Confirma autenticação
  2. Monta query: Prepara filtro de busca (se fornecido)
  3. Define limite: Aplica maxResults (padrão: 10)
  4. Busca lista: Chama gmail.users.messages.list()
  5. Recupera detalhes: Para cada ID, busca email completo
  6. Extrai dados: Processa headers, body e metadata
  7. Se sucesso: Retorna array de emails com todos detalhes

Código interno (gmail-executor.service.ts:370-391):

private async getAllMessages(gmail: any, data: GmailNodeData): Promise<any> {
  const response = await gmail.users.messages.list({
    userId: 'me',
    q: data.query || '',
    maxResults: data.maxResults || 10
  });

  const messages: any[] = [];

  if (response.data.messages) {
    for (const message of response.data.messages.slice(0, data.maxResults || 10)) {
      const fullMessage = await this.getMessage(gmail, { ...data, messageId: message.id });
      messages.push(fullMessage);
    }
  }

  return {
    messages,
    resultSizeEstimate: response.data.resultSizeEstimate,
    nextPageToken: response.data.nextPageToken
  };
}

Quando você DEVE usar este Node?

Use GET_EMAILS sempre que precisar de listar emails da caixa de entrada:

Casos de uso

  1. Monitoramento: "Verificar novos emails a cada hora"
  2. Processamento automático: "Ler emails e extrair informações"
  3. Relatórios: "Listar emails recebidos hoje"
  4. Triagem: "Buscar emails não lidos para processar"

Quando NÃO usar GET_EMAILS

  • Email específico: Use GET_EMAIL_BY_ID se tem o messageId
  • Busca complexa: Use SEARCH_EMAILS para queries avançadas
  • Tempo real: Gmail não oferece webhooks, considere polling

Parâmetros

Campo Tipo Obrigatório Descrição
oauth2 object Sim Credenciais OAuth2
operation string Sim Deve ser "getAll"
query string Não Query de busca Gmail (padrão: vazio = todos)
maxResults number Não Quantidade máxima de emails (padrão: 10, máx: 100)

Exemplo 1: Listar Últimos Emails

Objetivo: Recuperar os 5 emails mais recentes

JSON para Importar

{
  "name": "Listar Últimos 5 Emails",
  "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 Emails",
        "operation": "getAll",
        "oauth2": {
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_SECRET",
          "refreshToken": "YOUR_TOKEN"
        },
        "maxResults": 5
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Quantidade",
        "parameters": {
          "message": "Encontrados {{gmail_1.messages.length}} emails"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "gmail_1" },
    { "source": "gmail_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Encontrados 5 emails

Exemplo 2: Filtrar Emails Não Lidos

Objetivo: Buscar apenas emails não lidos da caixa de entrada

JSON para Importar

{
  "name": "Emails Não Lidos",
  "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 Não Lidos",
        "operation": "getAll",
        "oauth2": {
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_SECRET",
          "refreshToken": "YOUR_TOKEN"
        },
        "query": "is:unread",
        "maxResults": 20
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Tem Emails?",
        "parameters": {
          "condition": "{{gmail_1.messages.length}} > 0"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 50 },
      "data": {
        "label": "Listar",
        "parameters": {
          "message": "Você tem {{gmail_1.messages.length}} emails não lidos"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 700, "y": 150 },
      "data": {
        "label": "Sem Emails",
        "parameters": {
          "message": "Nenhum email não lido!"
        }
      }
    },
    {
      "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: Você tem 3 emails não lidos

Queries Úteis

Filtros comuns para query: - is:unread - Apenas não lidos - is:starred - Apenas destacados - from:email@example.com - De remetente específico - subject:assunto - Com assunto específico - has:attachment - Com anexos - after:2025/10/01 - Após data - before:2025/10/31 - Antes de data - label:importante - Com label específica

Resposta do Node

{
  "success": true,
  "action": "get_emails",
  "messages": [
    {
      "id": "18f2b9c4d5e6a7f8",
      "threadId": "18f2b9c4d5e6a7f8",
      "subject": "Assunto do Email",
      "from": "remetente@example.com",
      "to": "destinatario@example.com",
      "date": "Mon, 12 Oct 2025 10:30:00 -0300",
      "body": "Corpo do email...",
      "snippet": "Prévia do conteúdo...",
      "labelIds": ["INBOX", "UNREAD"]
    }
  ],
  "resultSizeEstimate": 127,
  "nextPageToken": "CAUQAA",
  "timestamp": "2025-10-12T21:30:00.000Z"
}

Boas Práticas

✅ SIM: - Use maxResults para limitar consumo de API - Aplique queries para filtrar resultados - Processe emails em lote eficientemente - Armazene nextPageToken para paginação

❌ NÃO: - Não busque todos emails (limite de API) - Não faça polling muito frequente (respeite quotas) - Não processe duplicados (verifique IDs)

Dicas

💡 Dica 1: Use query para filtrar no servidor, não localmente 💡 Dica 2: resultSizeEstimate mostra total disponível 💡 Dica 3: nextPageToken permite buscar próxima página 💡 Dica 4: Combine com LOOP para processar todos emails 💡 Dica 5: Use maxResults baixo em testes (economiza quota)

Próximo Node

→ GET_EMAIL_BY_ID - Buscar email específico → SEARCH_EMAILS - Busca avançada → MARK_AS_READ - Marcar como lido