Documentação da Hermes para IAs e sistemas

A Hermes funciona com o Claude, o ChatGPT e o Grok. Tudo o que a IA faz, uma pessoa da empresa também faz na tela, e cada conexão faz só o que a configuração dela permite.

Conectar o Claude

No Claude, abra Personalizar → Conectores e escolha "Adicionar conector personalizado".
Informe o endereço https://hermesinc.com.br/mcp.
Faça login na Hermes, escolha o nome, as permissões e a autonomia, e clique em "Autorizar".

No Claude Code: claude mcp add --transport http hermes https://hermesinc.com.br/mcp e depois /mcp para entrar.

Conectar o ChatGPT

No ChatGPT, abra Configurações → Apps e conectores e adicione um conector com o endereço https://hermesinc.com.br/mcp.
Faça login na Hermes e autorize, como no Claude.

Conectar o Grok

O Grok usa uma chave:

No menu da Hermes, em Conexões de IA, crie uma conexão por chave com o provedor Grok.
Na API da xAI, use a ferramenta de MCP remoto com server_url igual a https://hermesinc.com.br/mcp e authorization igual a Bearer <chave>.

API e MCP: os mesmos campos

A API (https://hermesinc.com.br/api/v1) e o MCP usam os mesmos nomes de campo, em snake_case, e as datas em ISO 8601 (2026-10-01T09:00:00.000Z). Há duas diferenças. A chave de idempotência do envio: na API, ela vai no cabeçalho Idempotency-Key de POST /api/v1/emails; no MCP, no campo idempotency_key. Repetir a mesma chave não envia de novo. E os ids: na API, eles vão no caminho (GET /api/v1/emails/:id); no MCP, como campo (id).

Pela API, e no MCP quando a conexão é por chave, mande o cabeçalho Authorization: Bearer <chave>. A chave é criada no menu da Hermes, em Conexões de IA, e aparece uma vez só.

Autonomia e aprovações

Quando a configuração pede aprovação, a ação responde "Aguardando aprovação" com um link. A IA pode mandar o link para a equipe, e a ação roda quando uma pessoa aprovar. Na API, a resposta é 202 com { "status": "aguardando_aprovacao", "aprovacao": { "id", "url" } }.

Avisos para o seu bot

Uma conexão por chave pode ter um endereço https para receber avisos (mensagem entregue, devolvida, reclamação, descadastro, franquia, pausa e as decisões dos pedidos de aprovação). O corpo de cada aviso traz só ids e um resumo, nunca o conteúdo do e-mail:

{ "id": "evt_…", "type": "mensagem.entregue", "created_at": "2026-10-01T09:00:00.000Z", "objects": { "message_id": "msg_…" }, "summary": "Mensagem entregue.", "workspace_id": "…" }

Cada aviso chega assinado no cabeçalho Hermes-Assinatura: t=<segundos>,v1=<assinatura>, em que a assinatura é o HMAC-SHA256 de <t>.<corpo> com o segredo mostrado ao salvar o endereço. Recuse avisos com t mais de 5 minutos fora da hora atual e ignore um Hermes-Aviso-Id repetido.

import { createHmac, timingSafeEqual } from 'node:crypto';
export function avisoValido(segredo, cabecalho, corpo) {
  const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(cabecalho) ?? [];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const esperado = createHmac('sha256', segredo).update(`${t}.${corpo}`).digest();
  return timingSafeEqual(esperado, Buffer.from(v1, 'hex'));
}

As IAs conectadas por login não recebem avisos: elas usam a ação listar_eventos_desde quando você pergunta o que aconteceu. Pela API, é GET /api/v1/events. A primeira chamada vai com since (uma data ISO, até 30 dias atrás) e a resposta é { "items", "next_cursor" }, com os mesmos itens do corpo do aviso, sem o workspace_id. Para continuar, inclusive mais tarde para ver o que chegou depois, chame de novo só com cursor igual ao next_cursor da resposta. O next_cursor sempre vem, mesmo quando a lista está vazia.

Erros

Toda resposta de erro traz { "code", "message" }, com a mensagem em português dizendo o que fazer. Um campo inválido responde 400 VALIDATION_ERROR, com a lista details de { "path", "message" }. Um campo que a Hermes não conhece também é recusado, com "Campo desconhecido. Confira o nome na documentação.": confira os nomes, que são em snake_case. No MCP, o mesmo erro volta como resultado de erro da ferramenta, um campo por linha.

Onde vai cada campo na API

Na API, o id vai no caminho e o idempotency_key vai no cabeçalho Idempotency-Key; os outros campos vão na query do GET e no corpo do POST. No MCP, todos vão nos argumentos da ferramenta.

Ações

`alterar_remetente`

Altera o nome de exibição, o responder para ou a situação de um remetente. Com active: false, desativa: os envios com esse remetente passam a ser recusados. Desativar e trocar ou tirar o responder para pedem aprovação, a não ser no "Tudo automático".

Área: Mensagens e envios (ver e mudar)
Efeito: Depende do pedido
API: POST /api/v1/senders/:id

Campo	Tipo	Obrigatório
`id`	texto	sim
`display_name`	texto	não
`reply_to`	texto ou nulo	não
`active`	sim ou não	não

`bloquear_endereco`

Bloqueia um endereço. Com scope "tudo", ele não recebe nenhum e-mail da empresa; com "marketing", deixa de receber só o marketing. Não envia nem apaga nada.

Área: Contatos (ver e mudar)
Efeito: Rascunho
API: POST /api/v1/suppressions

Campo	Tipo	Obrigatório
`address`	texto	sim
`scope`	`tudo`, `marketing`	sim

`cadastrar_dominio`

Cadastra um domínio de envio (por exemplo, mail.suaempresa.com.br) e devolve os registros DNS que a empresa precisa publicar. Depois de publicar, use verificar_dominio.

Área: Mensagens e envios (ver e mudar)
Efeito: Rascunho
API: POST /api/v1/domains

Campo	Tipo	Obrigatório
`domain`	texto	sim

`criar_remetente`

Cria um remetente num domínio verificado da empresa: informe o id do domínio, o começo do endereço (antes do @) e o nome de exibição.

Área: Mensagens e envios (ver e mudar)
Efeito: Rascunho
API: POST /api/v1/senders

Campo	Tipo	Obrigatório
`domain_id`	texto	sim
`local`	texto	sim
`display_name`	texto	sim
`reply_to`	texto ou nulo	não

`desbloquear_endereco`

Tira um bloqueio pelo id, com o motivo (mínimo de 5 caracteres). Só sai bloqueio por devolução, manual ou por exclusão; reclamação e descadastro são decisão da pessoa, e a empresa não tira.

Área: Contatos (ver e mudar)
Efeito: Exclusão
API: POST /api/v1/suppressions/:id/lift

Campo	Tipo	Obrigatório
`id`	texto	sim
`reason`	texto	sim

`enviar_mensagem`

Envia um e-mail de um remetente verificado da empresa para um destinatário. Use category "transacional" para e-mails do sistema (pedido, senha, nota) e "marketing" para ofertas. Exige Idempotency-Key: repetir a mesma chave não envia de novo.

Área: Mensagens e envios (ver e mudar)
Efeito: Envio
API: POST /api/v1/emails

Campo	Tipo	Obrigatório
`from`	texto	sim
`to`	texto	sim
`subject`	texto	sim
`html`	texto	não
`text`	texto	não
`category`	`transacional`, `marketing`	sim
`reply_to`	texto	não
`idempotency_key`	texto	sim

`listar_bloqueios`

Lista os 200 bloqueios mais recentes da empresa, com o motivo (devolução, reclamação, descadastro, bloqueio manual ou exclusão) e se vale para tudo ou só para marketing. Para conferir se um endereço está bloqueado, use o filtro address: um endereço fora da lista pode estar bloqueado.

Área: Contatos (ver)
Efeito: Leitura
API: GET /api/v1/suppressions

Campo	Tipo	Obrigatório
`address`	texto	não

`listar_dominios`

Lista os domínios de envio da empresa, com o estado de cada um (aguardando, verificando, verificado, degradado, suspenso ou liberado) e os registros DNS pedidos.

Área: Mensagens e envios (ver)
Efeito: Leitura
API: GET /api/v1/domains

Sem campos.

`listar_eventos_desde`

Mostra o que aconteceu na Hermes desde uma data (até 30 dias atrás): mensagens entregues e devolvidas, descadastros, franquia, pausas e as decisões dos seus pedidos de aprovação. Use quando a pessoa perguntar "o que aconteceu desde…". Na primeira chamada, informe since; para continuar, inclusive mais tarde para ver o que chegou depois, chame só com o next_cursor da resposta. Devolve só o que esta conexão pode ver.

Área: Qualquer (filtra pela configuração)
Efeito: Leitura
API: GET /api/v1/events

Campo	Tipo	Obrigatório
`since`	texto	não
`cursor`	texto	não
`limit`	inteiro	não

`listar_mensagens`

Lista as mensagens da empresa, das mais novas para as mais antigas, com filtros por estado, categoria e período (24h, 7d, 30d). Use o cursor devolvido para a próxima página.

Área: Mensagens e envios (ver)
Efeito: Leitura
API: GET /api/v1/emails

Campo	Tipo	Obrigatório
`status`	`na_fila`, `encaminhada`, `entregue`, `adiada`, `devolvida`, `reclamacao`, `suprimida`, `falhou`, `resultado_incerto`, `cancelada`, `expirada`	não
`category`	`transacional`, `marketing`, `confirmacao`	não
`period`	`24h`, `7d`, `30d`	não
`cursor`	texto	não
`limit`	inteiro	não

`listar_remetentes`

Lista os remetentes da empresa (endereço, nome de exibição, responder para e se está ativo). Só remetente ativo de domínio verificado envia.

Área: Mensagens e envios (ver)
Efeito: Leitura
API: GET /api/v1/senders

Sem campos.

`ver_dominio`

Mostra um domínio de envio pelo id, com os registros DNS que a empresa precisa publicar e o estado de cada um. Use para dizer à pessoa o que falta configurar.

Área: Mensagens e envios (ver)
Efeito: Leitura
API: GET /api/v1/domains/:id

Campo	Tipo	Obrigatório
`id`	texto	sim

`ver_mensagem`

Mostra uma mensagem pelo id, com o estado e a linha do tempo (tentativas e avisos do provedor).

Área: Mensagens e envios (ver)
Efeito: Leitura
API: GET /api/v1/emails/:id

Campo	Tipo	Obrigatório
`id`	texto	sim

`verificar_dominio`

Pede agora a conferência do DNS de um domínio. A resposta traz o estado; a conferência roda em segundo plano, e o domínio passa a verificado quando os registros estiverem publicados.

Área: Mensagens e envios (ver e mudar)
Efeito: Rascunho
API: POST /api/v1/domains/:id/verify

Campo	Tipo	Obrigatório
`id`	texto	sim