Nó Gmail

O nó de workflow Gmail chama a Gmail API para listar, ler e enviar e-mails, criar rascunhos e gerenciar labels. Use-o para enviar confirmações, relatórios ou alertas por e-mail junto com WhatsApp nas suas automações.

Node ID no editor: google_gmail_request
Base URL: https://gmail.googleapis.com/gmail/v1/
Auth: Authorization: Bearer {{google_gmail_token}}

O que faz

• Envia requisições HTTP autenticadas para endpoints da Gmail API
• Suporta GET, POST, PUT, PATCH e DELETE
• Retorna status HTTP, data de resposta e headers de resposta
• Inclui templates de operação para ações comuns (listar mensagens, enviar e-mail, criar rascunho, listar labels)
• Suporta serviços conectados OAuth (recomendado) ou modo REST API manual com Bearer token

Pré-requisitos

Opção A — OAuth (recomendado)

1. Uma conta Google com Gmail habilitado
2. Conecte o Gmail em Configurações → Chaves de API → Serviços conectados:
   1. Clique em Add service
   2. Escolha Gmail
   3. Dê um nome (ex.: "Support inbox")
   4. Clique em Authorize with Google e faça login
3. O WhatsWave armazena e renova o token OAuth automaticamente — injetado como {{google_gmail_token}} em runtime

Opção B — Token REST API manual

1. Obtenha um access token da Gmail API via OAuth 2.0 (veja Gmail API authorization)
2. Armazene o token em uma chave de integração chamada google_gmail_token, ou use variáveis de workflow
3. Na config do nó, ative o toggle Gmail via REST API (manual token)
4. Configure URL, method, headers e body manualmente

Dica: OAuth é mais simples e trata a renovação de token. Use o modo REST manual somente quando você gerencia tokens externamente.

Como configurar

Passo 1 — Conectar Gmail (modo OAuth)

1. Abra Configurações → Chaves de API
2. Em Connected Services, adicione Gmail e conclua a autorização Google
3. No editor de workflow, adicione o nó Gmail
4. Selecione a conta Gmail conectada no campo Connected Gmail service

O WhatsWave injeta Authorization: Bearer {{google_gmail_token}} automaticamente quando um serviço conectado é selecionado.

Passo 2 — Adicionar o nó

1. Abra Automações e edite seu workflow
2. Na paleta, abra a categoria Communication
3. Arraste Gmail para o canvas
4. Conecte após o gatilho ou nós de preparação de dados

Passo 3 — Escolher um template de operação

Passo 4 — Configurar campos da requisição

Exemplo — enviar e-mail (POST):

O Gmail exige o body da mensagem como mensagem MIME RFC 2822 codificada em base64url no campo raw:

• URL: https://gmail.googleapis.com/gmail/v1/users/me/messages/send
• Method: POST
• Body:

{
  "raw": "VG8gOiBkZXN0aW5vQGVtYWlsLmNvbQpGcm9tOiBzdXBwb3J0QHlvdXJkb21haW4uY29tClN1YmplY3Q6IE9yZGVyIGNvbmZpcm1hdGlvbiB7e3RyaWdnZXIuYm9keS5vcmRlcl9pZH19CkNvbnRlbnQtVHlwZTogdGV4dC9wbGFpbjsgY2hhcnNldD11dGYtOAoKSGkge3tjb250YWN0Lm5hbWV9fSwgeW91ciBvcmRlciBpcyBjb25maXJtZWQu"
}

O valor raw acima é uma mensagem MIME codificada em base64url. Monte-a com um nó JavaScript ou pré-codifique offline. Uma estrutura MIME em texto simples fica assim:

To: {{contact.email}}
From: support@yourdomain.com
Subject: Order confirmation {{trigger.body.order_id}}
Content-Type: text/plain; charset=utf-8

Hi {{contact.name}}, your order is confirmed.

Exemplo — listar mensagens recentes (GET):

• URL: https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10&q=is:unread
• Method: GET
• Body não necessário

Exemplo — obter mensagem por ID (GET):

• URL: https://gmail.googleapis.com/gmail/v1/users/me/messages/{{variables.gmail_message_id}}?format=full
• Method: GET

Todos os campos suportam variáveis de workflow.

Passo 5 — Usar dados da resposta

O Gmail retorna metadados e conteúdo da mensagem em data. Referencie em nós posteriores:

Message ID: {{gmail_1.data.id}}
Thread ID: {{gmail_1.data.threadId}}
Label IDs: {{gmail_1.data.labelIds}}

Para mensagens enviadas, armazene {{gmail_1.data.id}} em um nó Variable para ações de acompanhamento.

Saídas do nó

Dicas e boas práticas

• Prefira OAuth a tokens manuais — o WhatsWave renova tokens expirados automaticamente para serviços conectados
• O send do Gmail exige MIME codificado em base64url no campo raw — use um nó JavaScript para montar e codificar a mensagem quando o conteúdo for dinâmico
• Use o parâmetro de query q em chamadas de listagem para a sintaxe de busca do Gmail (ex.: q=is:unread from:customer@email.com)
• Para e-mails HTML, defina Content-Type: text/html; charset=utf-8 nos headers MIME antes de codificar
• Se precisar de um setup de e-mail mais simples sem codificação MIME, considere os nós Resend ou SMTP
• Reconecte em Connected Services se receber erros 401 após longos períodos de inatividade (somente no modo token manual)
• Armazene IDs de mensagens enviadas em campos customizados do contato para trilhas de auditoria

Exemplos de casos de uso

E-mail de confirmação de pedido após webhook

1. Gatilho Webhook — novo pedido com e-mail do cliente
2. JavaScript — montar mensagem MIME e codificar em base64url em variables.gmail_raw
3. Gmail POST — enviar e-mail com {"raw": "{{variables.gmail_raw}}"}
4. Send message — resumo do pedido no WhatsApp

Verificação de caixa de entrada não lida → alerta WhatsApp

1. Gatilho Schedule — a cada hora
2. Gmail GET — listar mensagens com q=is:unread label:inbox
3. Condition — se data.resultSizeEstimate > 0
4. Send message — alertar equipe no WhatsApp

Registro de resposta de suporte ao cliente

1. Gatilho — agente envia resposta no WhatsApp
2. Gmail POST — criar rascunho com resumo da conversa para revisão interna
3. CRM update — registrar ID do rascunho no card do contato

FAQ

Por que o nó retorna 401 Unauthorized?
A conexão OAuth expirou (modo manual), o serviço conectado foi removido ou o Bearer token é inválido. Reconecte o Gmail em Configurações → Chaves de API → Serviços conectados.

Por que o envio de e-mail falha com 400 Bad Request?
O campo raw deve ser uma mensagem MIME válida codificada em base64url. Verifique a codificação, quebras de linha (\r\n) e headers obrigatórios (To, From, Subject).

Posso enviar anexos?
Sim, mas é necessária codificação MIME multipart. Monte a estrutura MIME em um nó JavaScript ou use Resend para e-mail HTML com anexos de forma mais simples.

Qual a diferença entre modo OAuth e modo REST API?
O modo OAuth seleciona um serviço conectado e injeta o token automaticamente. O modo REST API permite chamar qualquer endpoint Gmail com Bearer token configurado manualmente — útil para provedores externos de token.

Qual a diferença entre este nó e o nó HTTP?
Este nó pré-configura base URLs do Gmail, header de auth, seletor de serviço conectado e templates de operação comuns. Use HTTP somente para endpoints Gmail não suportados.

Posso usar a mesma conta Google para Calendar e Gmail?
Sim, mas cada serviço exige uma conexão separada em Connected Services (Gmail e Google Calendar são escopos OAuth independentes).

Referência da API

Relacionados

• Visão geral de Comunicação
• Nó Resend — e-mail transacional mais simples
• Nó SMTP — relay SMTP genérico
• Variáveis no workflow
• Nó JavaScript