Pular para conteúdo

GET_EMAIL_BY_ID - Buscar Email Específico por ID

O que é este Node?

O GET_EMAIL_BY_ID é o node responsável por recuperar detalhes completos de um email específico usando seu messageId único no Gmail.

Por que este Node existe?

Acessar email específico é essencial para processar comunicações individuais com precisão. O GET_EMAIL_BY_ID existe para:

  1. Acesso direto: Recuperar email conhecido por ID
  2. Detalhes completos: Obter headers, corpo, anexos e metadata
  3. Processamento preciso: Trabalhar com email específico
  4. Validação: Confirmar existência e conteúdo de email

Como funciona internamente?

Quando o GET_EMAIL_BY_ID é executado, o sistema:

  1. Valida messageId: Confirma que ID foi fornecido
  2. Busca email: Chama gmail.users.messages.get() com format=full
  3. Extrai headers: Processa Subject, From, To, Date
  4. Decodifica corpo: Converte base64 para texto legível
  5. Processa partes: Extrai texto de partes multipart
  6. Se sucesso: Retorna objeto completo com todos dados

Código interno (gmail-executor.service.ts:329-368):

private async getMessage(gmail: any, data: GmailNodeData): Promise<any> {
  const response = await gmail.users.messages.get({
    userId: 'me',
    id: data.messageId,
    format: 'full'
  });

  const message = response.data;
  const headers = message.payload.headers;

  // Extract common headers
  const subject = headers.find((h: any) => h.name === 'Subject')?.value;
  const from = headers.find((h: any) => h.name === 'From')?.value;
  const to = headers.find((h: any) => h.name === 'To')?.value;
  const date = headers.find((h: any) => h.name === 'Date')?.value;

  // Extract body
  let body = '';
  if (message.payload.body.data) {
    body = Buffer.from(message.payload.body.data, 'base64').toString();
  } else if (message.payload.parts) {
    for (const part of message.payload.parts) {
      if (part.mimeType === 'text/plain' && part.body.data) {
        body += Buffer.from(part.body.data, 'base64').toString();
      }
    }
  }

  return {
    id: message.id,
    threadId: message.threadId,
    subject,
    from,
    to,
    date,
    body,
    snippet: message.snippet,
    labelIds: message.labelIds
  };
}

Quando você DEVE usar este Node?

Use GET_EMAIL_BY_ID sempre que precisar de detalhes de email específico:

Casos de uso

  1. Processar webhook: "Buscar email após notificação de chegada"
  2. Validar referência: "Confirmar conteúdo de email mencionado"
  3. Extrair dados: "Ler informações específicas de um email"
  4. Preparar resposta: "Buscar email antes de responder"

Quando NÃO usar GET_EMAIL_BY_ID

  • Lista de emails: Use GET_EMAILS para múltiplos
  • Buscar por conteúdo: Use SEARCH_EMAILS se não tem ID
  • Processar inbox: Use GET_EMAILS para varredura

Parâmetros

Campo Tipo Obrigatório Descrição
oauth2 object Sim Credenciais OAuth2
operation string Sim Deve ser "get"
messageId string Sim ID único do email no Gmail

Exemplo 1: Buscar e Exibir Email

Objetivo: Recuperar email específico e mostrar detalhes

JSON para Importar

{
  "name": "Buscar Email por ID",
  "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": "ID do Email",
        "parameters": {
          "message": "Digite o ID do email:",
          "variable": "emailId"
        }
      }
    },
    {
      "id": "gmail_1",
      "type": "gmail",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar Email",
        "operation": "get",
        "oauth2": {
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_SECRET",
          "refreshToken": "YOUR_TOKEN"
        },
        "messageId": "{{emailId}}"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Mostrar Detalhes",
        "parameters": {
          "message": "📧 Email encontrado!\n\nDe: {{gmail_1.from}}\nAssunto: {{gmail_1.subject}}\nData: {{gmail_1.date}}\n\nPrévia: {{gmail_1.snippet}}"
        }
      }
    },
    {
      "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: Digite o ID do email:
Usuário: 18f2b9c4d5e6a7f8
Sistema: 📧 Email encontrado!

De: contato@example.com
Assunto: Proposta Comercial
Data: Mon, 12 Oct 2025 10:30:00 -0300

Prévia: Olá, segue nossa proposta comercial...

Exemplo 2: Validar Email Antes de Responder

Objetivo: Buscar email para validar conteúdo antes de responder

JSON para Importar

{
  "name": "Validar e Responder Email",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Processar Email" }
    },
    {
      "id": "gmail_get_1",
      "type": "gmail",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Buscar Email",
        "operation": "get",
        "oauth2": {
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_SECRET",
          "refreshToken": "YOUR_TOKEN"
        },
        "messageId": "{{triggerEmailId}}"
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "É Urgente?",
        "parameters": {
          "condition": "{{gmail_get_1.subject}} contains 'URGENTE'"
        }
      }
    },
    {
      "id": "gmail_reply_1",
      "type": "gmail",
      "position": { "x": 700, "y": 50 },
      "data": {
        "label": "Resposta Urgente",
        "operation": "reply",
        "oauth2": {
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_SECRET",
          "refreshToken": "YOUR_TOKEN"
        },
        "messageId": "{{gmail_get_1.id}}",
        "to": "{{gmail_get_1.from}}",
        "subject": "{{gmail_get_1.subject}}",
        "replyMessage": "Recebemos sua solicitação URGENTE e já estamos processando. Retornaremos em breve."
      }
    },
    {
      "id": "gmail_reply_2",
      "type": "gmail",
      "position": { "x": 700, "y": 150 },
      "data": {
        "label": "Resposta Normal",
        "operation": "reply",
        "oauth2": {
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_SECRET",
          "refreshToken": "YOUR_TOKEN"
        },
        "messageId": "{{gmail_get_1.id}}",
        "to": "{{gmail_get_1.from}}",
        "subject": "{{gmail_get_1.subject}}",
        "replyMessage": "Recebemos sua mensagem e responderemos em até 24 horas."
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Resposta automática enviada"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "gmail_get_1" },
    { "source": "gmail_get_1", "target": "condition_1" },
    { "source": "condition_1", "target": "gmail_reply_1", "label": "true" },
    { "source": "condition_1", "target": "gmail_reply_2", "label": "false" },
    { "source": "gmail_reply_1", "target": "message_1" },
    { "source": "gmail_reply_2", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Resposta automática enviada

Resposta do Node

{
  "success": true,
  "action": "get_email",
  "id": "18f2b9c4d5e6a7f8",
  "threadId": "18f2b9c4d5e6a7f8",
  "subject": "Proposta Comercial",
  "from": "contato@example.com",
  "to": "voce@example.com",
  "date": "Mon, 12 Oct 2025 10:30:00 -0300",
  "body": "Conteúdo completo do email...",
  "snippet": "Prévia curta do email...",
  "labelIds": ["INBOX", "UNREAD"],
  "timestamp": "2025-10-12T21:30:00.000Z"
}

Boas Práticas

✅ SIM: - Valide se messageId existe antes de buscar - Use snippet para pré-visualizações rápidas - Processe body para extrair informações - Verifique labelIds para status do email

❌ NÃO: - Não assuma que ID sempre existe - Não ignore erros de email não encontrado - Não busque repetidamente o mesmo email

Dicas

💡 Dica 1: threadId permite encontrar emails relacionados 💡 Dica 2: snippet é útil para mostrar prévia sem processar body 💡 Dica 3: labelIds indica status (UNREAD, STARRED, etc) 💡 Dica 4: Combine com REPLY_TO_EMAIL para responder 💡 Dica 5: Use body para análise completa de conteúdo

Próximo Node

→ GET_EMAILS - Listar múltiplos emails → SEARCH_EMAILS - Buscar por critérios → REPLY_TO_EMAIL - Responder email