Do cadastro ao primeiro envio

Acesse /auth/sign-up e crie sua conta com e-mail e senha, ou entre direto com Google ou GitHub. Essa conta é para você (ou seu time) acessar o painel do Hermes — não tem relação com os usuários da sua aplicação.

Um serviço é um namespace isolado: cada aplicação/produto seu deve ter o seu próprio, com credenciais, templates e configurações separadas. Em Serviços → Novo Serviço, dê um nome (ex: "App Principal", "Landing de Marketing") e confirme.

Dentro do serviço, vá em Credenciais de Disparo → Nova Conexão e escolha como o Hermes vai enviar os e-mails de fato:

• SMTP Padrão — host, porta e SSL/TLS de qualquer provedor (Gmail, SES, SendGrid, seu próprio servidor de e-mail, etc).
• Google OAuth2 — autorização segura via conta Google, sem expor senha/app password.

Ao salvar, a API Key (formato hm_...) aparece uma única vez. Copie e guarde agora — o Hermes armazena só o hash dela e não consegue mostrá-la de novo (só rotacionar e gerar uma nova).

O SDK cuida de retry, streaming de status e rotação automática de chave pra você. Se preferir não adicionar a dependência, dá pra chamar a API REST direto.

npm install @ruanlopes1350/hermes-client

Sem o SDK, o mesmo envio fica assim:

// Alternativa sem o SDK: chamando a API REST diretamente
await fetch(`${process.env.HERMES_API_URL}/api/emails`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.HERMES_API_KEY!,
  },
  body: JSON.stringify({
    to: 'cliente@empresa.com',
    subject: 'Bem-vindo!',
    template_id: 'uuid-do-template',
    variables: { nome: 'João da Silva' },
  }),
});

Guarde a URL da sua instância do Hermes e a API Key gerada no passo 3 como variáveis de ambiente — nunca direto no código:

HERMES_API_URL=https://sua-instancia-hermes.com
HERMES_API_KEY=hm_sua_chave_gerada_no_passo_3

Instancie o HermesClient uma única vez e reexporte. Em produção (VPS/servidor com processo persistente), use o EnvAdapter: se a chave rotacionar via webhook (passo 8), ele atualiza o .env sozinho.

import { HermesClient } from '@ruanlopes1350/hermes-client';
import { EnvAdapter } from '@ruanlopes1350/hermes-client/node';

export const hermes = new HermesClient({
  baseUrl: process.env.HERMES_API_URL!,
  // Lê e mantém HERMES_API_KEY sincronizada no .env quando a rotação acontecer
  storageAdapter: new EnvAdapter('.env', 'HERMES_API_KEY'),
});

Chame hermes.email() nos pontos de negócio da sua aplicação onde um e-mail deve sair — cadastro de usuário, recuperação de senha, confirmação de pedido, alertas, etc:

// src/routes/auth/signup.ts
import { hermes } from '../lib/hermes';

export async function onUserSignUp(user: { name: string; email: string }) {
  await hermes.email()
    .to(user.email)
    .subject('Bem-vindo!')
    .useTemplate('boas-vindas-tpl', { nome: user.name })
    .send();
}

// src/routes/auth/forgot-password.ts
await hermes.email()
  .to(user.email)
  .subject('Redefinição de senha')
  .useTemplate('recuperacao-senha-tpl', { resetLink })
  .priority('high')
  .send();

Se você configurou Intervalo de Validade da Chave, a API Key expira e precisa ser trocada periodicamente. Pra sua aplicação não quebrar quando isso acontecer, receba o aviso via webhook:

a) Crie a rota que recebe o aviso

// src/routes/webhook-hermes.ts (Express)
import express from 'express';
import { expressWebhookHandler } from '@ruanlopes1350/hermes-client/express';
import { hermes } from '../lib/hermes';

app.post(
  '/webhook/hermes',
  express.raw({ type: 'application/json' }),
  expressWebhookHandler(hermes, process.env.HERMES_WEBHOOK_SECRET!),
);

b) Cadastre o endpoint no Hermes

Em Serviço → Configurações → Rotação de Chaves e Webhooks, preencha:

• URL do Webhook — a rota pública que você acabou de criar.
• Segredo do Webhook — usado pra assinar o header X-Hermes-Signature (mesmo valor de HERMES_WEBHOOK_SECRET acima).
• Ativar Rotação Automática de API Keys — liga o processo.
• Dias de antecedência para rotacionar (Threshold) — quantos dias antes do vencimento a nova chave é gerada e o webhook disparado.

Em Templates → Novo Template, escolha um Escopo de Uso: 🌍 Global (disponível pra todos os serviços) ou vinculado a um serviço específico. No editor, escreva o layout em MJML — toda variável no formato {{assim}} é detectada automaticamente e listada em Variáveis Detectadas, sem precisar declarar nada à parte. O preview ao vivo mostra o resultado enquanto você edita.

Passe o id do template e um objeto com os valores de cada variável detectada. O SDK também traz helpers prontos pra formatação comum (saudação, data, moeda):

import { templateHelpers } from '@ruanlopes1350/hermes-client';

await hermes.email()
  .to('cliente@empresa.com')
  .subject('Pedido confirmado')
  .useTemplate('order-confirmation', {
    greeting:  templateHelpers.greeting('João'),
    orderDate: templateHelpers.formatDate(new Date()),
    total:     templateHelpers.formatCurrency(149.90),
  })
  .send();

Com tudo configurado, os três padrões de envio do dia a dia:

// Envio simples
await hermes.email().to('a@b.com').subject('Oi').body('<p>Olá!</p>').send();

// Agendado
await hermes.email()
  .to('a@b.com').subject('Lembrete')
  .useTemplate('lembrete-tpl')
  .schedule(new Date('2026-09-01T09:00:00Z'))
  .send();

// Em massa (até 100 por chamada)
await hermes.bulk()
  .email().to('a@b.com').subject('Oi').useTemplate('tpl', { nome: 'A' }).done()
  .email().to('c@d.com').subject('Oi').useTemplate('tpl', { nome: 'C' }).done()
  .send();