Gmail

Ler, enviar e organizar e-mails do Gmail (Gmail API)

Conectar ao Gmail

gmail.connect

Autentica com OAuth ou conta de serviço do Workspace

Como usar

Autentica no Gmail pela API do Google e guarda a conexão. Use OAuth (client ID, secret e refresh token no cofre) ou uma conta de serviço do Google Workspace agindo como um usuário. Funciona sem login interativo.

Exemplo: Conecte com OAuth usando GMAIL_SECRET e GMAIL_REFRESH em {gmail}.

Campos

Campo	Tipo	Padrão	Detalhes
Autenticação *	Opção	`Conta de usuário (OAuth refresh token)`	Robôs autônomos: guarde tokens e chaves no cofre do OrchestratorOpções: Conta de usuário (OAuth refresh token), Conta de serviço
Client ID do OAuth *	Texto		Só quando «Autenticação» = «Conta de usuário (OAuth refresh token)»
Client secret do OAuth (cofre) *	Credencial do cofre		Só quando «Autenticação» = «Conta de usuário (OAuth refresh token)»
Refresh token (cofre) *	Credencial do cofre		Só quando «Autenticação» = «Conta de usuário (OAuth refresh token)»
JSON da chave da conta de serviço (cofre) *	Credencial do cofre		Só quando «Autenticação» = «Conta de serviço»
Agir como o usuário (delegação em todo o domínio)	Texto		Obrigatório para conta de serviço (somente Google Workspace)Ex.: `usuario@empresa.com`Só quando «Autenticação» = «Conta de serviço»
Salvar conexão na variável *	Variável de saída	`gmail`

Resultado: guardado na variável gmail (Objeto).

Enviar E-mail

gmail.send_email

Envia uma mensagem com anexos opcionais

Como usar

Envia um e-mail pela conta conectada, com Cc, Cco, corpo em HTML ou texto e anexos, e guarda o ID da mensagem.

Exemplo: Envie para {email_cliente} o assunto "Seu boleto" com {caminho_boleto} anexo.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão do Gmail *	Variável	`gmail`
Para *	Texto		Separe endereços com ;
Cc	Texto
Cco	Texto
Assunto *	Texto
Corpo *	Texto (várias linhas)
Formato do corpo	Opção	`HTML`	Opções: HTML, Texto simples
Anexos (caminhos dos arquivos)	Lista
Salvar ID da mensagem na variável *	Variável de saída	`message_id`

Resultado: guardado na variável message_id (Texto).

Ler E-mails

gmail.read_emails

Lista mensagens de um marcador com filtros

Como usar

Lista as mensagens de um marcador (INBOX por padrão) com filtros, e guarda a lista. Cada e-mail traz id, assunto, remetente, data, corpo e anexos; use o id nos comandos de anexos, resposta e marcadores.

Exemplo: Leia os não lidos de INBOX com o filtro has:attachment e baixe os anexos de cada {item.id}.

Campos

Campo	Tipo	Padrão
Conexão do Gmail *	Variável	`gmail`
Marcador	Texto	`INBOX`
Somente não lidos	Sim/Não	`Sim`
Máximo de resultados	Número	`50`
Marcar como lidos	Sim/Não	`Não`
Salvar resultado na variável *	Variável de saída	`emails`

+ Avançado (2)

Campo	Tipo	Padrão	Detalhes
Filtro de busca do Gmail	Texto		Ex.: `from:cobranca@empresa.com has:attachment`
Incluir corpo completo	Sim/Não	`Sim`

Resultado: guardado na variável emails (Lista).

Buscar E-mails

gmail.search_emails

Busca com a sintaxe do Gmail (from:, subject:, after:…)

Como usar

Busca mensagens com a mesma sintaxe da caixa de pesquisa do Gmail (from:, subject:, after:, has:attachment...).

Exemplo: Busque from:nfe@fornecedor.com after:2026/10/01 em {emails}.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão do Gmail *	Variável	`gmail`
Busca *	Texto		Ex.: `subject:nota after:2026/01/01`
Máximo de resultados	Número	`50`
Salvar resultado na variável *	Variável de saída	`emails`

Resultado: guardado na variável emails (Lista).

Obter E-mail

gmail.get_email

Obtém uma mensagem com corpo e lista de anexos

Como usar

Obtém uma mensagem completa pelo ID, com corpo e lista de anexos.

Exemplo: Obtenha o e-mail {message_id} e leia {email.body}.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão do Gmail *	Variável	`gmail`
ID da mensagem *	Texto		Geralmente vem de "Ler e-mails" ({email["id"]})
Salvar resultado na variável *	Variável de saída	`email`

Resultado: guardado na variável email (Dicionário).

Baixar Anexos

gmail.download_attachments

Salva os anexos de uma mensagem

Como usar

Salva os anexos de uma mensagem numa pasta, opcionalmente só algumas extensões, e guarda os caminhos.

Exemplo: Baixe só pdf e xml de {item.id} para C:\Robos\entrada.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão do Gmail *	Variável	`gmail`
ID da mensagem *	Texto		Geralmente vem de "Ler e-mails" ({email["id"]})
Salvar na pasta *	Pasta
Somente extensões	Texto		Ex.: `.pdf;.xlsx`
Salvar caminhos na variável *	Variável de saída	`attachments`

Resultado: guardado na variável attachments (Lista).

Responder E-mail

gmail.reply_email

Responde mantendo a conversa

Como usar

Responde a uma mensagem mantendo a conversa, ao remetente ou a todos, com anexos opcionais.

Exemplo: Responda {item.id} com "Nota recebida e lançada."

Campos

Campo	Tipo	Padrão	Detalhes
Conexão do Gmail *	Variável	`gmail`
ID da mensagem *	Texto		Geralmente vem de "Ler e-mails" ({email["id"]})
Corpo *	Texto (várias linhas)
Formato do corpo	Opção	`HTML`	Opções: HTML, Texto simples
Responder a todos	Sim/Não	`Não`
Anexos (caminhos dos arquivos)	Lista

Encaminhar E-mail

gmail.forward_email

Encaminha uma mensagem com os anexos

Como usar

Encaminha uma mensagem, com os anexos, para outro endereço, com um comentário.

Exemplo: Encaminhe {item.id} para fiscal@empresa.com.br com o comentário "Nota com divergência".

Campos

Campo	Tipo	Padrão	Detalhes
Conexão do Gmail *	Variável	`gmail`
ID da mensagem *	Texto		Geralmente vem de "Ler e-mails" ({email["id"]})
Para *	Texto		Separe endereços com ;
Comentário	Texto (várias linhas)

Adicionar/Remover Marcadores

gmail.modify_labels

Altera os marcadores de uma mensagem (move entre "pastas")

Como usar

Adiciona e remove marcadores de uma mensagem. No Gmail, mover para uma "pasta" é adicionar o marcador dela e remover INBOX.

Exemplo: Adicione o marcador Processados e remova INBOX de {item.id}.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão do Gmail *	Variável	`gmail`
ID da mensagem *	Texto		Geralmente vem de "Ler e-mails" ({email["id"]})
Adicionar marcadores	Lista
Remover marcadores	Lista

Marcar como Lido/Não Lido

gmail.mark_as_read

Altera o estado de leitura

Como usar

Marca a mensagem como lida ou não lida.

Exemplo: Marque {item.id} como lida depois de processar.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão do Gmail *	Variável	`gmail`
ID da mensagem *	Texto		Geralmente vem de "Ler e-mails" ({email["id"]})
Lido	Sim/Não	`Sim`

Excluir E-mail

gmail.delete_email

Move para a lixeira ou exclui definitivamente

Como usar

Manda a mensagem para a lixeira ou a exclui de vez.

Exemplo: Mova para a lixeira os avisos automáticos já tratados.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão do Gmail *	Variável	`gmail`
ID da mensagem *	Texto		Geralmente vem de "Ler e-mails" ({email["id"]})
Excluir definitivamente	Sim/Não	`Não`

Listar Marcadores

gmail.list_labels

Lista marcadores do sistema e do usuário

Como usar

Lista os marcadores do sistema e os criados pelo usuário, com nome e ID.

Exemplo: Liste os marcadores em {labels} para conferir se Processados existe.

Campos

Campo	Tipo	Padrão	Detalhes
Conexão do Gmail *	Variável	`gmail`
Salvar resultado na variável *	Variável de saída	`labels`

Resultado: guardado na variável labels (Lista).

Criar Marcador

gmail.create_label

Cria um marcador

Como usar

Cria um marcador e guarda o ID.

Exemplo: Crie o marcador "Robô/Processados" no primeiro uso.

Campos

Campo	Tipo	Padrão
Conexão do Gmail *	Variável	`gmail`
Nome do marcador *	Texto
Salvar resultado na variável *	Variável de saída	`label_id`

Resultado: guardado na variável label_id (Texto).