API HTTP

Início rápido

Do zero ao primeiro envio em três passos.

• 1. Crie uma chave em Credenciais. Ela aparece uma única vez (prefixo ov_…). Guarde num cofre de segredos.
• 2. Verifique um domínio em Domínios — sem domínio verificado o envio é recusado com 422 domain_not_verified.
• 3. Envie com POST /send:

export OVEYON_API_KEY="ov_suachaveaqui"

curl -X POST https://api.oveyon.com/v1/send \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Vendas <vendas@suaempresa.com>",
    "to": "cliente@exemplo.com",
    "subject": "Bem-vindo",
    "html": "<h1>Olá!</h1><p>Sua conta está pronta.</p>"
  }'

Resposta esperada: 202 com { "id": "<uuid>", "status": "accepted" }. Esse id é o que você usa para consultar a mensagem depois.

Autenticação

Toda requisição carrega a chave no header Authorization, esquema Bearer.

curl https://api.oveyon.com/v1/domains \
  -H "Authorization: Bearer $OVEYON_API_KEY"

• Chave ausente, inválida, revogada ou expirada → 401 unauthorized. É sempre a mesma resposta, de propósito: ela não conta se a chave existe nem de quem ela é.
• Chave válida que foi desligada no painel → 403 key_disabled, em qualquer rota. O interruptor fica em Credenciais → Chaves de API; religar devolve a chave com o mesmo segredo. Não rotacione por causa deste erro — a chave não tem nada de errado, só está desligada; use outra chave ou religue esta.
• Chave válida de uma conta bloqueada → 403 account_suspended, e vale em qualquer rota, não só no envio. Não é problema de credencial: rotacionar a chave ou criar outra não muda nada — fale com o suporte. Sem uma chave válida da conta, a resposta é o 401 acima; é por isso que este 403 não revela a ninguém que a conta existe.
• Cada chave tem um nome/tag (para você distinguir integrações) e um conjunto de permissões (escopos). Gerencie ambos em Credenciais.
• Revogar é imediato — a chave revogada para de autenticar na chamada seguinte. Rotacionar não é. A rotação emite a chave nova e deixa a anterior valendo por uma janela de carência (padrão 72 h; o painel diz o prazo exato no momento em que você rotaciona), para a sua aplicação trocar o segredo sem cair. É deliberado: sem a carência, «rotacionar» seria só «interromper», e o resultado prático seria ninguém rotacionar nunca. A consequência é a que importa — se a chave vazou, rotacionar não fecha o buraco: revogue. Rotacione quando o segredo ainda é só seu; revogue quando ele deixou de ser.
• Nunca exponha a chave no front-end nem em repositório.

Permissões (escopos)

A chave só acessa o que os escopos dela liberam. Faltou escopo para a rota chamada → 403 insufficient_scope (a resposta diz qual escopo faltou):

HTTP/1.1 403 Forbidden
{ "error": "insufficient_scope", "required": "read:stats", "have": ["send"] }

Fora da tabela, e de propósito: /disposable · /openapi.json · /ping não exige autenticação — nem chave, nem escopo, nem cota. Não procure uma caixinha para ela em Credenciais: não há o que conceder. É a única rota da API nessa condição.

Papel no painel não é permissão de chave

Esta é a confusão que aparece assim que a conta passa a ter mais de uma pessoa, e ela erra sempre para o mesmo lado — o de achar que a chave é mais fraca do que ela é. Então, com todas as letras: o painel e a chave são dois sistemas de permissão que não se tocam. Nenhum consulta o outro.

O que decorre daí, e é o que você leva para o seu código:

• Papel não enfraquece chave. Não existe «chave de viewer». Uma chave com send na mão de alguém que é viewer na conta continua enviando e-mail: a chave não sabe quem está com ela, e nunca perguntou.
• Papel não fortalece chave. Ser owner não acrescenta escopo nenhum à chave que você criou. Faltou escopo, é 403 insufficient_scope — inclusive para o dono da conta, inclusive com a chave dele. Esse 403 nunca quer dizer «seu papel é baixo demais»; ele quer dizer «esta chave não tem este escopo», e a resposta nomeia qual.
• Tirar o acesso de alguém ao painel não revoga chave nenhuma. É a consequência que morde, então ela vai sem eufemismo: uma credencial não guarda quem a criou, e por isso nada cascateia quando um acesso é retirado. Quem saiu continua com o segredo, e o segredo continua valendo em nome da conta. Ao remover uma pessoa, revogue as chaves que estiveram na mão dela — em Credenciais, e revogue, não rotacione: a rotação deixa a anterior viva pela carência.
• Nenhuma chamada do /v1 enxerga duas contas. Não há parâmetro que peça isso, nem header, nem um modo «organização» — e conta suspensa não arrasta a vizinha: o 403 account_suspended é sobre a conta daquela chave, e só. Se você opera várias contas, são várias chaves, uma por conta.

O papel decide uma coisa nesta história, e é do lado do painel: quem consegue apertar o botão. Cunhar segredo novo — criar chave de API, criar credencial SMTP e rotacionar qualquer uma das duas — é gesto de owner da conta. Matar e ajustar ficam com o admin: revogar, desativar, e também editar nome, escopos e limite de uma chave que já existe — porque um controle de acesso que proíbe reduzir exposição está pior que desligado. E owner é a titularidade da conta, não um papel que se concede: se você é admin e o botão de criar chave não está aí, não é falha da tela. Nada disso muda o que a chave faz depois de emitida — que é o assunto do resto desta página.

Enviar e-mail

O envio passa pelo mesmo pipeline do SMTP: idempotência, backpressure, domínio do remetente e do destinatário, supressão, cota e rampa — nessa ordem. O 202 só sai quando a mensagem já está no spool.

curl -X POST https://api.oveyon.com/v1/send \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8842" \
  -d '{
    "from": "Suporte <suporte@suaempresa.com>",
    "to": "cliente@exemplo.com",
    "cc": ["financeiro@exemplo.com"],
    "bcc": ["arquivo@suaempresa.com"],
    "subject": "Seu recibo",
    "html": "<p>Obrigado pela compra.</p>",
    "text": "Obrigado pela compra.",
    "headers": { "X-Campaign": "recibos" },
    "attachments": [
      { "filename": "recibo.pdf", "content": "JVBERi0xLjQK...", "contentType": "application/pdf" }
    ]
  }'

HTTP/1.1 202 Accepted
{ "id": "3f8a1c2e-9b4d-4e10-8a77-2b0c9d5e1f34", "status": "accepted", "recipients": 3 }

// `recipients` só aparece quando há mais de um destinatário, e é o número
// de endereços DISTINTOS que entraram no envelope — o mesmo que foi cobrado.

curl -X POST https://api.oveyon.com/v1/send \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "X-Oveyon-Sandbox: 1" \
  -H "Content-Type: application/json" \
  -d '{ "from": "a@suaempresa.com", "to": "cliente@exemplo.com",
        "subject": "Teste", "text": "Nada será entregue." }'

Templates

Molde de e-mail com variáveis, guardado uma vez e disparado com só os dados: {"templateId": …, "data": {…}} no POST /v1/send, em vez de 40KB de HTML repetido a cada chamada. O visual muda num lugar só, sem redeploy do seu sistema.

O ciclo: rascunho → publicada (imutável)

• Criar e editar sempre produzem rascunho — nada muda no envio até você publicar.
• A versão publicada é imutável: editar cria a vN+1 como rascunho; a vN continua exatamente como estava. Template em produção nunca muda por baixo de você.
• Publicar torna a versão a corrente do envio. Para voltar, publique de novo uma versão anterior ({"version": N}) — o ponteiro anda nos dois sentidos, a linha nunca muda.
• O envio pode fixar version; rascunho nunca é servido, nem fixando a versão dele.

Sintaxe — o catálogo é fechado, e é contrato

• Nada além disso existe — helper, partial, comentário e afins são recusados na gravação (400 template_parse_error, citando a tag). O catálogo cresce por decisão nossa, nunca por aceitação silenciosa.
• Estrito por padrão: variável referenciada e ausente do data recusa o envio com 400 template_var_missing — nunca um {{buraco}} visível no inbox. O opt-out é por variável, com | "padrão".
• O dado nunca vira template: um valor contendo {{outravar}} sai como texto literal — a substituição é de passo único, nada é re-interpretado.
• Tetos: 256KB por campo na gravação; na expansão, 1MB de saída e 10.000 iterações somadas de {{#each}} — estourou, o envio é recusado com erro nomeado.
• Mensagem enviada por template carrega templateId/templateVersion no GET /v1/messages e no detalhe — o rastro de qual molde/versão gerou o quê.

curl -X POST https://api.oveyon.com/v1/templates \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pedidoChegou",
    "subject": "{{nome}}, seu pedido chegou",
    "html": "<p>Olá {{nome}}, use o cupom {{ cupom | \"SEM10\" }}.</p>",
    "text": "Olá {{nome}}, use o cupom {{ cupom | \"SEM10\" }}."
  }'

curl -X POST https://api.oveyon.com/v1/templates/pedidoChegou/publish \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

Exemplo ponta a ponta

Criar → publicar → disparar com só os dados. O corpo no fio sai com as variáveis substituídas e com o pipeline inteiro por cima (footer, tracking, DKIM — template não pula guarda nenhuma).

curl -X POST https://api.oveyon.com/v1/templates \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pedidoChegou",
    "subject": "{{nome}}, seu pedido chegou",
    "html": "<p>Olá {{nome}}, use o cupom {{ cupom | \"SEM10\" }}.</p>",
    "text": "Olá {{nome}}, use o cupom {{ cupom | \"SEM10\" }}."
  }'

curl -X POST https://api.oveyon.com/v1/templates/pedidoChegou/publish \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

curl -X POST https://api.oveyon.com/v1/send \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Loja <vendas@suaempresa.com>",
    "to": "cliente@exemplo.com",
    "templateId": "pedidoChegou",
    "data": { "nome": "Ana" }
  }'

Erros

• 400 template_invalid (traz field) · template_parse_error (traz tag) · template_source_too_large — recusas de gravação.
• 400 template_var_missing (traz variable) — no envio, dado incompleto para o template.
• 404 template_not_found — inexistente, de outra conta, sem versão publicada, ou a version pedida não está publicada. No POST /v1/send a mesma condição sai como 422.
• 409 template_name_taken · template_no_draft.
• 422 template_var_invalid · template_each_not_list (trazem variable) · template_output_too_large · template_too_many_iterations (trazem limit) — recusas de render no envio. Ramifique sempre no error. · template_too_much_work (o render excedeu 500.000 nós visitados — laços vezes tamanho do corpo)

Consultar

Listagem, estatísticas agregadas e a timeline de uma mensagem. Toda leitura é cercada pelo tenant da chave — você nunca vê dados de outra conta.

curl "https://api.oveyon.com/v1/messages?status=delivered&limit=25" \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  "data": [
    {
      "id": "3f8a1c2e-9b4d-4e10-8a77-2b0c9d5e1f34",
      "from": "vendas@suaempresa.com",
      "to": "cliente@exemplo.com",
      "subject": "Bem-vindo",
      "status": "delivered",
      "statusDetail": null,
      "route": "mailchannels",
      "acceptedAt": "2026-07-21T13:02:11.000Z",
      "deliveredAt": "2026-07-21T13:02:14.000Z"
    }
  ],
  "next_cursor": "eyJpZCI6MTg0Mn0"
}

curl "https://api.oveyon.com/v1/stats?group_by=day&from=2026-07-01&to=2026-07-21" \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  "series": [
    {
      "day": "2026-07-21",
      "sent": 1200, "delivered": 1176, "bounced": 12,
      "opened": 640, "clicked": 210, "complained": 1,
      "rates": { "delivery": 98.0, "bounce": 1.0, "complaint": 0.08 }
    }
  ]
}

curl "https://api.oveyon.com/v1/stats?breakdown=provider,reason,credential&from=2026-07-01&to=2026-07-30" \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  "series": [ ... ],
  "breakdown": {
    "provider": {
      "total": 4210,
      "items": [
        { "value": "Google",        "label": "Google",        "count": 2604, "pct": 61.8 },
        { "value": "Microsoft",     "label": "Microsoft",     "count": 812,  "pct": 19.3 },
        { "value": "empresa.com.br","label": "empresa.com.br","count": 519,  "pct": 12.3 },
        { "value": "Outros",        "label": "Outros",        "count": 275,  "pct": 6.5 }
      ]
    },
    "reason": {
      "total": 63,
      "items": [
        { "value": "invalid_recipient", "label": "Endereço ou domínio inexistente", "count": 41, "pct": 65.1 },
        { "value": "spam_content",      "label": "Filtro de spam ou conteúdo",      "count": 14, "pct": 22.2 },
        { "value": "mailbox_full",      "label": "Caixa do destinatário cheia",     "count": 8,  "pct": 12.7 }
      ]
    },
    "credential": {
      "total": 4210,
      "items": [
        { "value": "s:12", "label": "suporte@empresa.com.br", "count": 2180, "pct": 51.8 },
        { "value": "k:3",  "label": "producao",               "count": 1602, "pct": 38.1 },
        { "value": "s:9",  "label": "faturas@empresa.com.br", "count": 375,  "pct": 8.9 },
        { "value": "-",    "label": "Origem não identificada", "count": 53,  "pct": 1.3 }
      ]
    }
  }
}

curl https://api.oveyon.com/v1/messages/3f8a1c2e-9b4d-4e10-8a77-2b0c9d5e1f34 \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  "id": "3f8a1c2e-9b4d-4e10-8a77-2b0c9d5e1f34",
  "status": "delivered",
  "statusDetail": null,
  "route": "mailchannels",
  "from": "vendas@suaempresa.com",
  "to": "cliente@exemplo.com",
  "subject": "Bem-vindo",
  "sizeBytes": 4821,
  "acceptedAt": "2026-07-21T13:02:11.000Z",
  "deliveredAt": "2026-07-21T13:02:14.000Z",

  // UMA ENTREGA POR DESTINATÁRIO. `status` e `to` acima são o resumo e o
  // primeiro endereço; o desfecho de cada um está aqui. O resumo é
  // pessimista: se um destinatário não recebeu, a mensagem não é "delivered".
  "deliveries": [
    { "id": "d_8f2a…", "to": "cliente@exemplo.com", "kind": "to",  "status": "delivered", "statusDetail": null,
      "deliveredAt": "2026-07-21T13:02:14.000Z", "completedAt": "2026-07-21T13:02:14.000Z", "latencyMs": 2900 },
    { "id": "d_1c07…", "to": "copia@exemplo.com", "kind": "bcc", "status": "bounced",
      "statusDetail": "550 5.1.1 User unknown", "deliveredAt": null, "completedAt": "2026-07-21T13:02:13.000Z", "latencyMs": 1800 }
  ],

  // `deliveryId`/`to` dizem de QUAL entrega é o evento; null = evento da
  // mensagem (aceite, por exemplo), que não pertence a destinatário nenhum.
  "events": [
    { "event": "accepted",  "deliveryId": null,      "to": null,                  "detail": { "source": "api" }, "at": "2026-07-21T13:02:11.000Z" },
    { "event": "delivered", "deliveryId": "d_8f2a…", "to": "cliente@exemplo.com", "detail": {},                  "at": "2026-07-21T13:02:14.000Z" },
    { "event": "bounced",   "deliveryId": "d_1c07…", "to": "copia@exemplo.com",   "detail": { "smtpResponse": "550 5.1.1 User unknown" }, "at": "2026-07-21T13:02:13.000Z" }
  ],
  "tracking": [
    { "type": "open",  "url": null, "host": "email.suaempresa.com", "readMsEstimate": 3200, "at": "..." },
    { "type": "click", "url": "https://loja.suaempresa.com/x", "host": "email.suaempresa.com", "readMsEstimate": null, "at": "..." }
  ]
}

Domínio descartável

O domínio de um endereço é de e-mail descartável/temporário (Mailinator, 10minutemail e afins)? Use no cadastro, antes de aceitar um e-mail que nunca vai ser lido duas vezes.

Esta é a única rota da API que não exige autenticação. Sem Authorization, sem chave, sem conta: a base é uma lista pública e não há nada seu envolvido na resposta. Também não consome cota. Em troca, o teto é por IP e é apertado — veja o fim desta seção.

# sem Authorization: esta rota e publica
curl "https://api.oveyon.com/v1/disposable?email=alguem@mailinator.com"

HTTP/1.1 200 OK
{
  "domain": "mailinator.com",
  "result": "disposable",
  "disposable": true,
  "list": {
    "updatedAt": "2026-08-07T00:10:34.812Z",
    "domains": 8201,
    "source": "https://raw.githubusercontent.com/disposable-email-domains/disposable-email-domains/main/disposable_email_blocklist.conf"
  }
}

curl "https://api.oveyon.com/v1/disposable?domain=gmail.com"

HTTP/1.1 200 OK
{
  "domain": "gmail.com",
  "result": "not_listed",
  "disposable": false,
  "list": { "updatedAt": "2026-08-07T00:10:34.812Z", "domains": 8201, "source": "…" }
}

HTTP/1.1 503 Service Unavailable
Retry-After: 3600
{
  "error": "list_unavailable",
  "domain": "mailinator.com",
  "result": "unknown",
  "disposable": null,
  "message": "não foi possível consultar: a base ainda não foi carregada neste servidor"
}

// `disposable` vem null, NUNCA false. Se a nossa base não estiver carregada,
// a resposta é "não sei" — dizer "não é descartável" sem ter o que consultar
// seria o único erro que esta consulta não pode cometer.

Receber e-mails

Você aponta o MX de um domínio para nós e cria os endereços que quer receber. A partir daí, tudo o que chega fica guardado e você escolhe como consumir: puxar pelas rotas abaixo, ou ser avisado por webhook. As duas coisas convivem — o webhook é aviso, o armazenamento é o chão.

Primeiros passos

Cinco passos, uma vez por domínio. Do DNS ao primeiro e-mail lido.

; No DNS de suaempresa.com — um registro MX, prioridade 10, apontando
; para o nosso host de entrada. O ponto final faz parte do registro.
suaempresa.com.    IN    MX    10    mx1.oveyon.com.

# Confira a propagação antes de pedir a verificação no painel:
dig +short MX suaempresa.com
# esperado:  10 mx1.oveyon.com.

# Mande um e-mail de uma caixa sua para suporte@suaempresa.com e liste:
curl "https://api.oveyon.com/v1/inbound?limit=5" \
  -H "Authorization: Bearer $OVEYON_API_KEY"

A chave precisa do escopo — e chave antiga não ganha sozinha

Estas rotas exigem read:inbound, que é um escopo próprio: as outras leituras (read:messages) mostram o que você mandou; esta mostra o que você recebeu — corpo e anexo escritos por terceiros. Uma chave emitida antes de este escopo existir não passa a tê-lo por deploy nosso: quem entregou aquela chave a um integrador não podia consentir com um poder que ainda não existia. Marque o escopo na chave em Credenciais (gesto de admin da conta), ou emita uma nova (gesto de owner — por quê). Rotacionar não resolve — a rotação herda as permissões da chave anterior, verbatim. Sem o escopo: 403 insufficient_scope.

Cinco coisas antes de escrever código

• Um e-mail, vários destinatários. Uma mensagem que chegou para suporte@ e vendas@ na mesma transação é uma mensagem com dois itens em recipients. Nunca achatamos isso num campo só — se o seu código lê só o primeiro, ele vai perder o segundo. (No webhook é o espelho disso: a mesma mensagem vira dois eventos, um por destinatário.)
• A cópia expira. O campo expiresAt vai em toda resposta e diz até quando guardamos o original. Passado o prazo, a mensagem continua listada (assunto, remetente, manifesto de anexos), mas expiresAt vira null e as rotas de conteúdo — /content, /raw, /attachments — passam a responder 404. Se você precisa do e-mail para sempre, baixe e guarde do seu lado.
• Toda mensagem chega com um score de spam. spamScore (0-100) é a nossa heurística interna, calculada quando a mensagem entra — quanto maior, mais cara de spam. Dois avisos: null significa não calculado (mensagem recebida antes de o recurso existir, ou falha nossa ao calcular), o que não é o mesmo que 0 — zero é «olhamos e está limpa». E o score é sinal, não veredito: nós nunca recusamos nem descartamos por causa dele; se você quiser filtrar, a régua é sua. No webhook o mesmo valor vai no corpo (message.spamScore) e no header x-spam-score do POST.
• Isto é conteúdo de terceiros. Corpo, HTML, nome e bytes de anexo vieram de quem enviou, não de nós. Trate tudo como dado hostil: nunca injete o html no seu DOM sem sanitizar, e nunca use o filename de um anexo para montar caminho em disco.
• Nem toda mensagem listada foi entregue. Cada item traz outcome: "accepted" quando chegou a pelo menos um destinatário, ou "blocked" quando chegou, foi guardada e não foi entregue a ninguém — com o porquê em blockedReason. Uma mensagem blocked não disparou webhook, não tem destinatários (recipients vem []) e não foi cobrada: não conta na sua cota. Ela continua legível pelas rotas de conteúdo até o expiresAt, como qualquer outra.
  • Ramifique por outcome, nunca por blockedReason. A lista de motivos cresce — hoje só existe "inbound_disabled" (a recepção do domínio estava desligada quando a mensagem chegou); amanhã podem nascer outros. Código que enumera motivos passa a responder errado no dia em que o motivo seguinte aparecer. Trate qualquer outcome diferente de "accepted" como «não entregue a ninguém», e o blockedReason como texto para log e diagnóstico.
  • Quem já integrou não quebra. Os dois campos são novos e nada mudou de tipo ou sumiu. Se o seu código percorre recipients, uma mensagem blocked simplesmente não gera nenhuma iteração — o comportamento correto, sem alterar uma linha.
  • Quer só o que foi entregue? ?outcome=accepted na listagem. Sem o parâmetro a lista traz os dois desfechos, de propósito: filtrar por omissão esconderia de você um e-mail que chegou de verdade.

curl "https://api.oveyon.com/v1/inbound?limit=25&has_attachments=true" \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  "data": [
    {
      "id": "b71e0c34-5a2f-4d18-9c60-77ab31e2d905",
      "receivedAt": "2026-08-05T09:14:02.317Z",
      "from": "cliente@exemplo.com",        // envelope (MAIL FROM)
      "fromHeader": "vendas@exemplo.com",   // ENDEREÇO do cabeçalho From
      "fromName": "Vendas Exemplo",         // nome de exibição, ou null
      "subject": "Re: seu orçamento",
      "domain": "suaempresa.com",

      // UM E-MAIL, N DESTINATÁRIOS. Nunca achatamos num campo só: se a
      // mensagem chegou para suporte@ e para vendas@ na MESMA transação,
      // os dois estão aqui, cada um com o seu id.
      "recipients": [
        { "id": "9c1d…", "to": "suporte@suaempresa.com" },
        { "id": "3af0…", "to": "vendas@suaempresa.com" }
      ],

      "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },

      // Score interno de spam (0-100; quanto maior, mais cara de spam tem).
      // null = NÃO CALCULADO (mensagem anterior ao recurso) — não é 0.
      "spamScore": 2,

      "sizeBytes": 18422,
      "attachmentCount": 2,
      "expiresAt": "2026-09-04T09:14:02.000Z",

      // O DESFECHO. "accepted" = entregue a pelo menos um destinatário.
      "outcome": "accepted",
      "blockedReason": null
    }
  ],
  "next_cursor": "aTo3Nw"
}

{
  "id": "c04b19f7-3d5a-4a02-b7e1-6d8f0a2c4419",
  "receivedAt": "2026-08-05T11:02:40.118Z",
  "from": "cliente@exemplo.com",
  "subject": "Chegou enquanto estava desligado",
  "domain": "suaempresa.com",

  // VAZIO, e não ausente: ninguém recebeu esta mensagem.
  "recipients": [],

  "attachmentCount": 0,
  "expiresAt": "2026-09-04T11:02:40.000Z",

  // Chegou, foi guardada, não foi entregue e NÃO foi cobrada.
  "outcome": "blocked",
  "blockedReason": "inbound_disabled"
}

curl https://api.oveyon.com/v1/inbound/b71e0c34-5a2f-4d18-9c60-77ab31e2d905 \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  // … todos os campos da listagem, mais:

  // MANIFESTO DOS ANEXOS. O `ord` é o ENDEREÇO do anexo — carimbado quando
  // a mensagem entrou, estável para sempre. O download é por ele, NUNCA
  // pelo `filename` (que veio de quem enviou: pode repetir, vir vazio ou
  // trazer caminho).
  "attachments": [
    { "ord": 1, "filename": "orcamento.pdf", "contentType": "application/pdf",
      "sizeBytes": 14233, "sha256": "9f2c…",
      "url": "/v1/inbound/b71e0c34-…/attachments/1" },
    { "ord": 2, "filename": "logo.png", "contentType": "image/png",
      "sizeBytes": 3180, "sha256": "0ab7…",
      "url": "/v1/inbound/b71e0c34-…/attachments/2" }
  ],
  "links": {
    "self":    "/v1/inbound/b71e0c34-…",
    "content": "/v1/inbound/b71e0c34-…/content",
    "raw":     "/v1/inbound/b71e0c34-…/raw"
  }
}

curl https://api.oveyon.com/v1/inbound/b71e0c34-5a2f-4d18-9c60-77ab31e2d905/content \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  "id": "b71e0c34-5a2f-4d18-9c60-77ab31e2d905",
  "text": "Bom dia, segue em anexo o orçamento aprovado…",
  "html": "<p>Bom dia, segue em anexo o orçamento aprovado…</p>",
  "truncated": false
}

curl -o mensagem.eml \
  https://api.oveyon.com/v1/inbound/b71e0c34-5a2f-4d18-9c60-77ab31e2d905/raw \
  -H "Authorization: Bearer $OVEYON_API_KEY"

curl -OJ https://api.oveyon.com/v1/inbound/b71e0c34-5a2f-4d18-9c60-77ab31e2d905/attachments/1 \
  -H "Authorization: Bearer $OVEYON_API_KEY"

Erros destas rotas

• 404 not_found — a mensagem não existe, ou não é da sua conta, ou o uid está malformado. A resposta é idêntica nos três casos, de propósito: distinguir seria contar a quem tenta adivinhar se o identificador dele acertou.
• 400 bad_cursor / bad_date / bad_domain / bad_dmarc / bad_has_attachments / bad_outcome — filtro fora do formato.
• 403 insufficient_scope — a chave não tem read:inbound.
• 429 rate_limited — além do teto por IP, estas rotas têm um teto por chave (padrão 120 req/min): são as únicas do /v1 que leem bytes do disco a cada chamada. A resposta diz o limite; respeite o retry-after.

Webhook de recepção

Em vez de perguntar «chegou alguma coisa?» a cada minuto, nós avisamos: um POST assinado no seu servidor a cada e-mail aceito. O evento é inbound.received.

«Aceito» é literal: o aviso é por destinatário, então uma mensagem com outcome: "blocked" — que não foi entregue a ninguém — não gera evento nenhum. Não é uma condição que alguém tenha de lembrar de manter: sem destinatário não há por quem disparar. Se a recepção de um domínio ficou desligada por um período, o que chegou nele está em GET /v1/inbound, e só lá.

Onde se liga

O webhook de recepção é um canal do endereço, e o cadastro é no painel: Domínios → abra o domínio → na tabela de endereços de recepção, a linha «Avisar por webhook» logo abaixo do endereço. Você informa a URL e escolhe o modo; o segredo de assinatura é gerado por nós e aparece uma única vez, na criação — copie na hora, porque não há tela que o mostre de novo (perdeu, remova o webhook e crie outro).

Não é o mesmo cadastro dos webhooks de envio — aqueles assinam o que aconteceu com o que você mandou (delivered, bounced…) e inbound.received não está no vocabulário deles: não adianta pedi-lo no POST /v1/webhooks. Também não há rota de API para cadastrar canal de recepção — hoje isso é só painel. Endereços diferentes podem ter destinos diferentes, e o mesmo endereço pode ter mais de um webhook (cada um com o seu segredo, o seu modo e a sua contagem de tentativas).

A URL passa pela mesma checagem dos webhooks de envio: destino interno ou privado é recusado no cadastro, e o IP é validado no momento da conexão — trocar o DNS depois do cadastro não nos leva para dentro da sua rede.

Antes de salvar, nós batemos na sua URL uma vez

Desde 24/08/2026, uma URL de webhook de recepção só é gravada depois que o endpoint responde a um desafio. Vale nos três gestos: ao criar o canal, ao trocar a URL de um canal existente, e ao alargar o modo (de «Resumo» para «Completo», por exemplo). Se o desafio não passa, nada é salvo — e num reaponte a URL antiga continua valendo.

O motivo é a simetria com os outros canais: no encaminhamento, o dono da caixa confirma por e-mail; no Telegram, o chat_id nunca é digitado, ele vem de um /start com nonce nosso; no Slack, é OAuth. O webhook era o único em que bastava digitar um endereço para ele passar a valer — e apontar correio para o endpoint de um terceiro que nunca disse sim é um jeito de nos transformar em instrumento.

O que a prova cobre, e o que ela não cobre: ela prova que quem controla aquele endpoint aceita receber. Ela não prova que o dono do sistema do outro lado autorizou — quem aponta para o próprio servidor passa no desafio sem esforço. Isso é deliberado, não uma lacuna a ser fechada depois.

O desafio é um POST comum, com os mesmos três cabeçalhos de assinatura das entregas de verdade e x-oveyon-event: url_verification. Timeout de 10 s.

POST https://seu-endpoint.exemplo/hook
x-oveyon-event: url_verification
x-oveyon-timestamp: 1756041600
x-oveyon-signature: sha256=…
content-type: application/json

{
  "type": "url_verification",
  "challenge": "3f9a…64 hex…",
  "url": "https://seu-endpoint.exemplo/hook",
  "sentAt": "2026-08-24T12:00:00.000Z"
}

Para passar, responda 2xx devolvendo o valor de challenge, de uma destas duas formas — as duas são aceitas:

• corpo cru: res.send(body.challenge)
• JSON: res.json({ challenge: body.challenge })

Trate o url_verification antes da sua lógica de mensagem e devolva ali mesmo: ele não é um e-mail, e processá-lo como se fosse cria uma entrega fantasma no seu sistema. Um 200 de corpo vazio não passa — é exatamente o caso que o desafio existe para pegar.

Na criação você ainda não conhece o segredo (ele só aparece depois, uma vez), então não há como verificar a assinatura desse primeiro desafio — só o eco é exigido. Numa troca de URL o segredo já é seu, e aí vale verificar a assinatura antes de ecoar, como em qualquer entrega.

E se o destino é um receptor de terceiros que você não programa (n8n, Make, webhook.site)? Ecoar o challenge pode ser impossível ali. Para esse caso existe o caminho alternativo, no painel: quando o seu endpoint aceita o POST (2xx) mas não devolve o desafio, o formulário oferece a opção «aceitar sem prova de leitura» — marque-a e a URL é salva assim mesmo, com uma marca visível no canal. Seja honesto consigo sobre o que se perde: a prova cai de «alguém lê o que chega lá» para «a URL existe e aceita POST». E o atalho só vale para esse desfecho — endpoint que responde erro ou não responde no prazo continua sendo recusado, porque ali não há receptor nenhum, só um endereço quebrado.

app.post('/hook', (req, res) => {
  // O desafio vem ANTES de tudo — e sai daqui.
  if (req.body && req.body.type === 'url_verification') {
    return res.json({ challenge: req.body.challenge });
  }
  // … daqui para baixo, o inbound.received de verdade
});

Um evento por destinatário, por canal

É o ponto que mais confunde quem integra, então vale devagar: um e-mail que chegou para três endereços seus gera três eventos, não um com uma lista.

O motivo é que cada destinatário tem desfecho próprio. Uma transação SMTP é um corpo e N destinatários, mas o aviso de um pode falhar e entrar em retentativa enquanto o do outro já foi entregue no primeiro tiro. Um evento só teria que carregar um status agregado — e status agregado de coisas que terminam diferente é sempre mentira sobre alguma delas. Pelo mesmo motivo, se o endereço tiver dois canais, cada canal tem a sua própria contagem de tentativas: o mesmo destinatário aparece uma vez por canal.

• message.id é o mesmo nos três eventos — é o e-mail.
• recipient e eventId são diferentes — é a entrega.
• Se o seu código chaveia por message.id, ele vai sobrescrever dois. Chaveie por eventId.

O payload

POST https://suaapp.com/hooks/oveyon-inbound
content-type: application/json
x-oveyon-event: inbound.received
x-oveyon-timestamp: 1786000443
x-oveyon-signature: sha256=9c4f2b7e…
x-spam-score: 2

{
  "event": "inbound.received",

  // ID ESTÁVEL desta entrega — este destinatário, neste canal. Retentativa e
  // reentrega repetem o MESMO valor: é por ele que você deduplica.
  "eventId": "6e5a1b90-3c77-4f02-b1ad-8e4409c2d611",

  // Versão do FORMATO deste corpo. Só sobe em mudança incompatível — guarde-a
  // e recuse o que não souber ler, em vez de adivinhar.
  "schemaVersion": 1,
  "timestamp": "2026-08-05T09:14:03.902Z",

  // O e-mail. Quase o mesmo objeto do GET /v1/inbound/:uid, com três
  // diferenças: aqui vêm `messageIdHeader` e `inReplyTo`, as URLs são
  // absolutas (`url`/`rawUrl`, não o objeto `links`), e NÃO há `recipients` —
  // este aviso é de UM destinatário, e ele está fora, em `recipient`.
  // `message.id` é o uid: é ele que vai nas rotas /v1/inbound/*.
  "message": {
    "id": "b71e0c34-5a2f-4d18-9c60-77ab31e2d905",
    "receivedAt": "2026-08-05T09:14:02.317Z",
    "domain": "suaempresa.com",
    "from": "cliente@exemplo.com",
    "fromHeader": "vendas@exemplo.com",
    "fromName": "Vendas",
    "subject": "Re: seu orçamento",
    "messageIdHeader": "<a1b2@exemplo.com>",
    "inReplyTo": "<z9@suaempresa.com>",
    "sizeBytes": 18422,
    "attachmentCount": 1,
    "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },

    // Score interno de spam (0-100), o mesmo do GET /v1/inbound. Também vai
    // no header `x-spam-score` do POST — presente SÓ quando há score; se o
    // campo é null, o header simplesmente não existe. null = não calculado
    // (mensagem anterior ao recurso), que NÃO é o mesmo que 0 (= limpa).
    "spamScore": 2,
    "url":    "https://api.oveyon.com/v1/inbound/b71e0c34-…",
    "rawUrl": "https://api.oveyon.com/v1/inbound/b71e0c34-…/raw"
  },

  // A QUEM esta cópia se refere — um OBJETO, não uma string. Um e-mail que
  // chegou para suporte@ E vendas@ gera DOIS eventos: mesmo `message.id`,
  // `recipient` e `eventId` distintos.
  "recipient": { "id": "4d2f77a1-…", "to": "suporte@suaempresa.com" },

  // MANIFESTO, no TOPO do corpo (não dentro de `message`): nome, tipo,
  // tamanho, sha256 e a URL de onde se buscam os bytes. Vem em TODOS os
  // modos, inclusive `summary`. O endereço do anexo é o `ord`, NUNCA o
  // `filename`.
  "attachments": [
    { "ord": 1, "filename": "orcamento.pdf", "contentType": "application/pdf",
      "sizeBytes": 14233, "sha256": "e3b0c442…",
      "url": "https://api.oveyon.com/v1/inbound/b71e0c34-…/attachments/1" }
  ],

  // SEMPRE presente — inclusive quando nada foi cortado. Cheque sempre.
  "truncation": {
    "degraded": false,          // saiu menos do que você pediu?
    "requestedMode": "full",    // o modo cadastrado no canal
    "mode": "full",             // o modo que de fato saiu
    "reason": null,             // texto legível quando degradou; null quando não
    "maxBytes": 262144,         // o teto em vigor para ESTE POST
    "attachmentsInline": false, // os bytes vieram embutidos em `content`?
    "attachmentsListed": 1,     // quantos anexos couberam no manifesto
    "attachmentCount": 1,       // quantos a mensagem tem, no total
    "textTruncated": false,
    "htmlTruncated": false
  },

  // Nos modos `full` e `full+attachments`, e também no TOPO do corpo. São
  // `null` quando a mensagem não tem aquela parte; no modo `summary` as duas
  // chaves simplesmente não existem.
  "text": "Bom dia, segue em anexo o orçamento aprovado…",
  "html": "<p>Bom dia, segue em anexo o orçamento aprovado…</p>"
}

Três modos — você escolhe quanto volume quer no aviso

O manifesto dos anexos vem nos três modos — o que muda de um para o outro é o volume (corpo e bytes), nunca a lista. E o modo que vem marcado por padrão na tela é o full+attachments: quem não escolhe recebe tudo o que couber.

// modo `summary` — sem `text` e sem `html` (as chaves nem aparecem). Tudo o
// mais continua: cabeçalho, vereditos, URLs e o MANIFESTO dos anexos.
{ "event": "inbound.received", "eventId": "…", "schemaVersion": 1,
  "message": { … }, "recipient": { "id": "…", "to": "…" },
  "attachments": [ { "ord": 1, "filename": "orcamento.pdf", "sha256": "…", "url": "…" } ],
  "truncation": { "degraded": false, "requestedMode": "summary", "mode": "summary", … } }

// modo `full+attachments` — cada item do manifesto ganha os BYTES em base64,
// no mesmo formato do `attachments[].content` do POST /send. É TUDO OU NADA:
// ou todos os anexos vêm embutidos, ou nenhum vem.
"attachments": [
  { "ord": 1, "filename": "orcamento.pdf", "contentType": "application/pdf",
    "sizeBytes": 14233, "sha256": "e3b0c442…",
    "url": "https://api.oveyon.com/v1/inbound/b71e0c34-…/attachments/1",
    "content": "JVBERi0xLjQK…" }
]
"truncation": { …, "mode": "full+attachments", "attachmentsInline": true }

// … e quando não coube, o payload DEGRADA e DIZ. Aqui pediram
// `full+attachments` e saiu `full`: o manifesto ficou, os bytes não.
"truncation": {
  "degraded": true,
  "requestedMode": "full+attachments",
  "mode": "full",
  "reason": "payload com anexos embutidos passaria de 262144 bytes: vão por link",
  "maxBytes": 262144,
  "attachmentsInline": false,
  "attachmentsListed": 1,
  "attachmentCount": 1,
  "textTruncated": false,
  "htmlTruncated": false
}

O teto do POST

Todo aviso tem um teto de tamanho, e ele vale para o corpo inteiro do POST — não só para os anexos. O padrão é 256 KB (262 144 bytes). O valor em vigor para aquele POST vem declarado dentro dele, em truncation.maxBytes: leia dali em vez de fixar o número no seu código.

O teto é aplicado quando o aviso é montado, não na hora de entregar. Um e-mail de 15 MB nunca vira um POST de 20 MB que nós tentaríamos seis vezes: o payload grande não chega nem a existir. Duas consequências práticas para quem integra: text e html entram cada um cortado em no máximo um quarto do teto (o corte é por byte, e nunca parte um caractere no meio), e os bytes de anexo só são embutidos se todos couberem no que sobrar.

Degradação é declarada, nunca silenciosa

Quando o payload não cabe no modo pedido, ele degrada e diz que degradou. O bloco truncation está sempre presente — com degraded: false no caminho normal — justamente para você poder checar sempre, com uma linha só, sem descobrir a existência do assunto no dia do primeiro e-mail grande.

Não existe campo level: o que responde «quanto saiu?» é o par requestedMode / mode, no mesmo vocabulário dos três modos acima.

• degraded — true quando saiu menos do que você pediu. É o único campo que você precisa checar.
• requestedMode e mode — o que foi pedido no cadastro e o que de fato saiu. Pediu full+attachments e recebeu mode: "full"? Os bytes ficaram de fora; o manifesto e as URLs continuam lá.
• reason — frase legível com tudo o que se perdeu, não só o último motivo (dois problemas na mesma mensagem viram dois trechos separados por ;). É null quando nada degradou.
• maxBytes — o teto em vigor para este POST.
• attachmentsInline — true só quando os bytes vieram em attachments[].content. É tudo ou nada: nunca metade dos anexos embutidos.
• attachmentsListed vs. attachmentCount — quantos anexos vieram no manifesto e quantos a mensagem tem no total. Diferentes? A cauda da lista não coube; os que faltam estão na API.
• textTruncated / htmlTruncated — aquele campo veio cortado (ou removido). Detalhe, não substituto: quando um deles é true, degraded também é.

O que degradou não se perdeu: está na API, sob o mesmo message.id. Degradar é tirar volume do aviso, nunca do arquivo.

Deduplique por eventId

Nós preferimos entregar duas vezes a perder um aviso. Se o seu servidor processar e o 200 se perder no caminho, a tentativa seguinte traz o mesmo eventId — ele é estável por entrega e sobrevive a retentativa e a reentrega. Guarde-o, e trate repetido como sucesso silencioso. Não deduplique por hash do corpo: uma reentrega remonta o payload, e o que chega pode não ser byte a byte o que chegou antes.

// A MESMA entrega pode bater duas vezes: retentativa depois de um timeout no
// qual você já tinha processado, ou reentrega nossa. `eventId` é estável
// nos dois casos — é a chave de deduplicação.
async function processar(evento) {
  // INSERT com chave única no eventId: quem perder a corrida já sabe que
  // é repetido, sem depender de um SELECT-antes-do-INSERT (que corre).
  const novo = await marcarComoVisto(evento.eventId);
  if (!novo) return;               // já processado — responda 2xx e siga

  if (evento.truncation.degraded) {
    // Faltou volume no aviso: busque o que falta na API, pelo message.id.
    await baixarDaApi(evento.message.id);
  }
  await salvar(evento);
}

Assinatura (HMAC-SHA256)

Mesmo esquema dos webhooks de envio. Cada POST leva três cabeçalhos:

• x-oveyon-event — o nome do evento (inbound.received).
• x-oveyon-timestamp — epoch em segundos.
• x-oveyon-signature — sha256= + HMAC-SHA256 do segredo do canal sobre timestamp + "." + corpo-cru.

O timestamp entra dentro do conteúdo assinado: um POST capturado não pode ser reenviado com carimbo novo sem quebrar a assinatura. Recuse o que chegar com |agora − timestamp| > 300 s, mesmo com HMAC válido — sem essa janela a assinatura sozinha autentica um replay de ontem.

Verificando em Node

const express = require('express');
const crypto = require('crypto');
const app = express();

// O CORPO CRU é o que foi assinado. Capture os bytes ANTES de qualquer parse
// — reserializar o JSON muda um espaço e a assinatura não fecha mais.
app.post('/hooks/oveyon-inbound', express.raw({ type: 'application/json' }), (req, res) => {
  const ts  = req.get('x-oveyon-timestamp') || '';
  const sig = (req.get('x-oveyon-signature') || '').replace(/^sha256=/, '');
  const raw = req.body; // Buffer

  // Janela anti-replay: 300 s. Fora dela, recuse — mesmo com HMAC válido.
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);

  const esperado = crypto.createHmac('sha256', process.env.OVEYON_WEBHOOK_SECRET)
    .update(ts + '.').update(raw).digest('hex');

  const a = Buffer.from(esperado, 'hex');
  const b = Buffer.from(sig, 'hex');
  // Comparação em tempo constante (o == vaza o prefixo certo por timing).
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  const evento = JSON.parse(raw.toString('utf8'));
  enfileireParaProcessar(evento);   // trabalho pesado FORA da requisição
  res.sendStatus(200);              // 2xx rápido: a tentativa expira em 10 s
});

Verificando em PHP

<?php
// O corpo CRU, byte a byte. Nada de json_decode antes de conferir.
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_OVEYON_TIMESTAMP'] ?? '';
$sig = preg_replace('/^sha256=/', '', $_SERVER['HTTP_X_OVEYON_SIGNATURE'] ?? '');

// Janela anti-replay: 300 s.
if ($ts === '' || abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }

$esperado = hash_hmac('sha256', $ts . '.' . $raw, getenv('OVEYON_WEBHOOK_SECRET'));

// hash_equals: comparação em tempo constante.
if (!hash_equals($esperado, $sig)) { http_response_code(401); exit; }

$evento = json_decode($raw, true);
enfileireParaProcessar($evento);   // trabalho pesado depois de responder
http_response_code(200);

Retentativas

Entrega é 2xx. Qualquer outra coisa conta como falha e entra na fila de retentativa: 4xx, 5xx, timeout de 10 s, conexão recusada — e também 3xx, porque redirecionamento não é seguido (seguir um redirect de endpoint de cliente é como um SSRF entra pela porta da frente).

São 6 tentativas, dentro de uma janela de pouco mais de 7 horas. Esse é o número que importa para quem opera: uma queda de manutenção de duas horas é absorvida sem perder nada; uma queda de um dia inteiro, não.

Esgotadas as seis, a entrega é marcada como falha e não há sétima — a fila para de bater no seu endpoint em vez de martelá-lo para sempre. Nada se perde por isso: o e-mail continua guardado, e GET /v1/inbound é a rede de segurança. Endpoint que ficou fora do ar? Reconcilie listando a janela da queda (?from=…&to=…) e deduplicando pelo que você já tinha — é por isso que a API existe mesmo para quem usa webhook.

Onde você vê isso acontecendo: no painel, na mesma linha em que o webhook foi cadastrado (Domínios → o domínio → o endereço), a coluna Último envio mostra o desfecho de cada aviso e o motivo em texto: pending (vai haver nova tentativa), delivered, failed (as seis se esgotaram) e dropped. Este último é o caso em que não havia mais para onde entregar — o webhook foi removido ou desativado entre a chegada do e-mail e a tentativa. dropped não é falha sua nem nossa, e não tem retentativa.

Responda 2xx rápido e faça o trabalho pesado depois. Um endpoint que processa 12 segundos antes de responder falha por timeout mesmo tendo feito tudo certo — e aí você recebe o mesmo evento seis vezes.

Endpoint atrás de Cloudflare (ou WAF): se você vê 403 nas tentativas e o seu código nunca roda, quem está recusando é a borda, não o seu servidor — bot-fight e regras de WAF adoram matar POST de máquina. Nossas entregas se identificam como User-Agent: OVEYON-Webhook/1.0: crie uma exceção de WAF para esse UA (ou para o caminho do seu webhook) e o problema some. Dica de diagnóstico que vale para tudo: o código que o SEU código devolve você encontra no seu log de aplicação; 403 sem linha de log nenhuma = a borda comeu a requisição antes.

Anexos

O payload carrega o manifesto — ord, nome, tipo, tamanho, sha256 e a URL de cada anexo — nos três modos. Os bytes se buscam pela API, com a sua chave: é a mesma rota da seção anterior.

curl -OJ https://api.oveyon.com/v1/inbound/b71e0c34-5a2f-4d18-9c60-77ab31e2d905/attachments/1 \
  -H "Authorization: Bearer $OVEYON_API_KEY"

• Por que não vêm sempre inline: base64 infla o arquivo em cerca de um terço, e um anexo de 15 MB viraria um POST de ~20 MB que nós tentaríamos até seis vezes, com 10 s de timeout. A maioria dos servidores recusa um corpo desse tamanho antes mesmo de conferir a assinatura — e aí o anexo derruba o aviso inteiro, não só a si mesmo.
• O modo full+attachments embute os bytes só enquanto o POST inteiro couber no teto (256 KB por padrão; o valor daquele POST está em truncation.maxBytes). Não coube? Os anexos passam a ir por link, attachmentsInline vem false, reason explica, e as URLs continuam válidas.
• É tudo ou nada. Nunca chegam alguns anexos embutidos e outros por link — ou o lote inteiro cabe, ou nenhum vem com content.
• O endereço do anexo é o ord, nunca o filename: dois anexos podem ter o mesmo nome, e o nome pode vir vazio ou com caminho dentro.

⚠ O que chega no seu endpoint é conteúdo de terceiro

Assunto, corpo, HTML, nome e bytes de anexo foram escritos por quem enviou o e-mail — não por nós, e não por você. Qualquer pessoa na internet pode mandar um e-mail para um endereço seu, e portanto qualquer pessoa na internet escolhe o que vai dentro deste payload. A assinatura HMAC prova que nós enviamos o POST; ela não diz nada sobre o conteúdo dele.

• Nunca renderize o html sem sanitizar. Injetá-lo no seu DOM, num painel de atendimento ou num e-mail que você reenvia é XSS na sua origem, com a sessão do seu usuário. Passe por um sanitizador (DOMPurify e afins) ou use só o text.
• Nunca use o filename para montar caminho em disco. Ele pode conter ../, barra, caractere nulo ou nome de arquivo do sistema. É path traversal servido de bandeja. Salve pelo ord (ou por um id seu) e guarde o nome original só como rótulo de exibição.
• Não confie no contentType declarado pelo remetente, e não sirva o anexo de volta como documento na sua origem. Se precisar disponibilizar download, force Content-Disposition: attachment e X-Content-Type-Options: nosniff — é o que fazemos nas nossas rotas.
• Leia message.authentication antes de acreditar em quem assina o e-mail. fromHeader é o que o remetente declarou; SPF, DKIM e DMARC são o que se pôde provar. Fluxo que aciona algo importante a partir de um e-mail deve exigir dmarc: "pass" — sem isso, o «de: chefe@suaempresa.com» é digitável por qualquer um.
• O fromName é o campo mais fácil de forjar do e-mail inteiro. Ele é o nome de exibição que o remetente escreveu — não precisa registrar domínio parecido nem quebrar nada: basta digitar. Um e-mail com "fromName": "Banco do Brasil" e "fromHeader": "x@dominio-qualquer.top" é o phishing mais comum que existe, e ele passa por SPF e DKIM sem problema (o domínio dele é legítimo — só não é o que o nome sugere). Exiba o nome se quiser, mas decida pelo endereço, nunca pelo nome.

Supressões

Endereços que você nunca quer atingir. Só as linhas do seu tenant são listadas; as supressões globais da plataforma também bloqueiam, mas não aparecem aqui.

curl "https://api.oveyon.com/v1/suppressions?reason=hard_bounce&limit=100" \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  "suppressions": [
    { "email": "invalido@exemplo.com", "reason": "hard_bounce",
      "source": "bounce", "createdAt": "2026-07-20T09:11:00.000Z" }
  ],
  "total": 1, "limit": 100, "offset": 0
}

curl -X POST https://api.oveyon.com/v1/suppressions \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "naoenviar@exemplo.com", "reason": "manual" }'

curl -X DELETE https://api.oveyon.com/v1/suppressions/naoenviar%40exemplo.com \
  -H "Authorization: Bearer $OVEYON_API_KEY"

Regras de envio e recebimento (allow/block)

Quatro listas por conta: allow e block, para outbound (julga o destinatário) e inbound (julga o remetente, no nosso MX). Entrada é um e-mail exato, um domínio exato ou *.dominio.com (cobre subdomínios em qualquer profundidade, nunca o próprio domínio). Semântica: block vence allow; a allow só restringe quando tem pelo menos uma entrada; no block, user+tag@ conta como user@. É a cerca recomendada para caixas operadas por agentes de IA: uma allow list de destinatários limita o estrago de qualquer prompt que dê errado.

curl -X POST https://api.oveyon.com/v1/policies   -H "Authorization: Bearer $OVEYON_KEY" -H "Content-Type: application/json"   -d '{ "scope": "outbound", "kind": "allow", "pattern": "cliente.com.br" }'

curl -X POST https://api.oveyon.com/v1/credentials/ip-rules   -H "Authorization: Bearer $OVEYON_KEY" -H "Content-Type: application/json"   -d '{ "credentialType": "smtp", "credentialId": 42, "cidr": "203.0.113.0/24" }'

curl -X POST https://api.oveyon.com/v1/credentials/ip-rules/pause   -H "Authorization: Bearer $OVEYON_KEY" -H "Content-Type: application/json"   -d '{ "credentialType": "smtp", "credentialId": 42 }'

Erros que o /send passa a devolver

• 422 recipient_blocked — destinatário na sua block list; o campo entry nomeia a entrada que casou.
• 422 recipient_not_allowed — sua allow list está ativa e o destinatário não está nela. A chamada é recusada INTEIRA (mesmo contrato da supressão).

Políticas de envio

Um motor SE→ENTÃO ordenado avaliado em todo envio, na API e no SMTP autenticado. As regras allow/block acima só enxergam endereço; aqui a condição pode falar de assunto, remetente, credencial e hora do dia — e a ação pode recusar, reter, exigir rodapé, forçar o tier ou limitar por hora. As duas peças são restritivas e ordenadas: uma política nunca reabre o que uma lista, uma supressão ou a cota já fecharam.

A forma de uma política

• name — até 120 caracteres. É ele que aparece na recusa e no histórico, e ele fica congelado no rastro: renomear a política não reescreve o que ela já decidiu.
• conditions — de 1 a 5, e todas precisam casar (E). Cada uma é { campo, op, valor }. Uma política sem condição casaria com TODAS as suas mensagens, e por isso a lista vazia é recusada.
• action — uma só, do catálogo abaixo.
• actionParams — só para as ações que declaram parâmetro. Hoje só limitar_hora, que exige { "max": N }. Parâmetro a mais, a menos ou desconhecido é 400.
• position — a ordem de julgamento, de cima para baixo. Ela é atribuída por nós (criar sempre põe no fim) e se muda por /reorder.

Sem regex e sem negação, e isso é decisão de segurança e não falta de tempo: uma expressão escrita pelo cliente e avaliada no caminho de toda mensagem é a definição de superfície de ReDoS. O vocabulário é fechado e está inteiro na tabela abaixo.

Condições — o catálogo fechado

Ações

• recusar — a mensagem não é aceita: 422 policy_refused na API, 550 5.7.1 no SMTP. Não consome cota — e não por estorno: o motor roda antes do contador.
• reter — a mensagem é aceita (202/250) e fica congelada, sem sair. Só o suporte solta retenção de política de envio — não há rota nem botão de liberar para você. Como ela não devolve erro nenhum, o jeito de vê-la pela API é o feed de decisões.
• exigir_footer — obriga o rodapé de descadastro. Na API, com mais de um destinatário na mesma chamada, o envio é recusado com 422 unsub_footer_multi_recipient: o link é individual.
• forcar_transacional — carimba a mensagem como transacional (rótulo e contabilidade). Hoje não muda o IP de saída, porque o rodízio por tier está desligado nesta plataforma.
• seguir_fluxo — não faz nada e encerra a avaliação das políticas. É a exceção que se põe ACIMA de uma regra mais ampla. Não isenta de listas, supressão nem cota.
• limitar_hora — ver a seção própria logo abaixo.

First-match-wins: a primeira política ativa que casar decide, e a varredura para. Não existe «a mais específica ganha» nem acúmulo de ações. Política pausada não julga nada. Se nenhuma casar, nada acontece: zero evento, zero linha.

O teto por hora (limitar_hora)

Deixa passar até max mensagens por hora de relógio para o que a política descreve, e recusa o excedente até a hora virar. É um teto da fatia, não da conta: o resto do seu tráfego não é afetado.

• Conta por destinatário, e não por chamada — a mesma unidade da cota e do teto por credencial. Um envio para 5 pessoas gasta 5.
• Conta no aceite, nunca na checagem: mensagem recusada por cota, por rate ou por falha de injeção depois da política não consome o teto (e no SMTP, o que for recusado após o DATA é devolvido ao contador).
• Folga conhecida e limitada: a checagem é uma por mensagem e a contagem é N. Com max: 100, 99 contados e uma chamada de 5 destinatários, a chamada passa e o balde termina em 104. Como o teto de destinatários por chamada é 5, o excesso máximo é de 4, uma vez por janela — a chamada seguinte já é barrada. É deliberado: apertá-lo exigiria reservar antes do aceite, trocando um excesso de 4 por reservas órfãs.
• Estourado: 429 policy_rate_limited com Retry-After (e policy, limit, used, retryAfter no corpo). No SMTP, um 4.7.1 que manda tentar de novo — nunca um 5xx, porque a janela vira sozinha.
• O rastro da recusa é uma linha por política por hora, não uma por tentativa: uma rajada contra o próprio teto encheria o feed sem dizer nada de novo.

curl -X POST https://api.oveyon.com/v1/send-policies \
  -H "Authorization: Bearer $OVEYON_KEY" -H "Content-Type: application/json" \
  -d '{
        "name": "No maximo 200/h para o dominio do cliente",
        "conditions": [{ "campo": "destinatario", "op": "termina_em", "valor": "@cliente.com" }],
        "action": "limitar_hora",
        "actionParams": { "max": 200 }
      }'

O teto de escrita destas rotas

As rotas de mutação desta seção (POST, PUT, pause, unpause, reorder, DELETE) têm um teto por chave, somado ao teto por IP: padrão 120 escritas/min. As leituras desta seção não pagam esse teto. Estourou → 429 rate_limited com Retry-After; a mensagem diz o limite.

Ele existe porque cada mutação aqui é mais cara do que parece: ela invalida o cache de avaliação de políticas, o reorder reescreve a ordem inteira e o DELETE ainda solta o ponteiro de 90 dias de rastro. É o mesmo teto que a tela Políticas aplica — nenhum uso humano ou script bem-comportado chega perto dele, já que a conta inteira só pode ter 50 políticas.

Erros que o /send passa a devolver

• 422 policy_refused — recusada por uma política sua. O corpo nomeia a política (policy) e o destinatário que casou (recipient). Não consome cota.
• 429 policy_rate_limited — o teto por hora de uma política sua foi atingido. Honre o Retry-After: a janela vira sozinha.
• 422 unsub_footer_multi_recipient — uma política exige rodapé e a chamada tem mais de um destinatário.

A mesma política vale na API e no SMTP autenticado. Não vale na porta de recepção (recepção não é envio) nem em correio de terceiro relayado.

Pesquisas (NPS / CSAT)

Dispare a pergunta pelo seu sistema (fechou o ticket, entregou o pedido) e receba a nota de volta por webhook. A pesquisa sai como e-mail normal desta plataforma — domínio verificado, DKIM, regras, supressões, políticas de envio e cota valem todas, sem exceção. A nota é coletada no clique, numa página servida no seu domínio de rastreio.

Os dois tipos, e a faixa de cada um

Toda resposta de pesquisa traz range: { min, max }. Leia dele em vez de cravar 0..10 no seu código. E distribuicao vem sempre com todas as notas da faixa, inclusive as zeradas: um gráfico que some as notas sem voto mente sobre a forma da curva, que é o que se olha primeiro. Sem nenhuma resposta, nps e media vêm null — nunca 0: «NPS 0» é um resultado ruim de verdade, e mostrá-lo onde não há dado seria o produto mentindo com um número plausível.

A nota é o clique — e o corpo do e-mail diz isso

Cada nota é um link próprio, e o clique registra o voto mesmo que a página de agradecimento não carregue: a gravação acontece antes do redirecionamento. Não há votação por responder o e-mail, e o corpo avisa isso em HTML e em texto — sem o aviso, quem responde «9» por instinto sairia achando que votou e a sua pesquisa colheria silêncio.

• Primeiro voto vale. Clicar outra nota depois não troca em silêncio: a página mostra a nota registrada e pede uma confirmação. É o que protege o seu número do scanner de link corporativo, que clica os onze links do NPS em ordem — com «último vale», todo destinatário atrás de um scanner viraria a nota do último link sem abrir o e-mail.
• Clique de robô não vota. Proxies de imagem e scanners conhecidos são reconhecidos e ignorados; a página responde igual para eles (nada que os ensine a se disfarçar), e o humano que abrir o mesmo link depois vota normalmente.
• O comentário é opcional e chega depois da nota, na mesma página. Por isso você recebe mais de um survey.response por resposta — ver o webhook abaixo.
• Encaminhamento: o link pertence ao destinatário original. Se ele encaminhar o e-mail, o voto de quem clicar conta para ele. É a limitação honesta do modelo, e todo o mercado vive com ela.

Anti-fadiga — a regra que protege a sua base

O mesmo destinatário só é pesquisado uma vez por janela. A janela é da CONTA, não da pesquisa: quem recebeu o seu NPS ontem não recebe o seu CSAT hoje — a sua base não sabe que os seus moldes são dois. O tamanho da janela vem da pesquisa que você está disparando (throttleDays, padrão 90, mínimo 7).

Pedido repetido dentro da janela → 429 recipient_recently_surveyed, com Retry-After (que pode ser de semanas — é a resposta verdadeira), mais throttleDays e lastSentAt no corpo. 429 e não 422, e a diferença importa: isto volta a passar quando a janela vencer. Envio recusado por outro motivo (supressão, cota, política) não consome a janela — a tentativa vira ata e o endereço continua livre.

curl -X POST https://api.oveyon.com/v1/surveys \
  -H "Authorization: Bearer $OVEYON_KEY" -H "Content-Type: application/json" \
  -d '{
        "kind": "nps",
        "name": "NPS pos-atendimento",
        "subject": "Como foi o seu atendimento?",
        "fromEmail": "pesquisa@suaempresa.com",
        "fromName": "Equipe",
        "throttleDays": 90,
        "brandColor": "#0b5fff"
      }'

curl -X POST https://api.oveyon.com/v1/surveys/7/send \
  -H "Authorization: Bearer $OVEYON_KEY" -H "Content-Type: application/json" \
  -d '{
        "to": "cliente@exemplo.com",
        "meta": { "ticket": 4821, "agente": "bia" },
        "idempotencyKey": "ticket-4821"
      }'

O webhook survey.response

Assine survey.response num endpoint de webhook e receba a nota no seu servidor, sem precisar perguntar. Mesma assinatura HMAC e mesma política de retentativa dos outros eventos.

{
  "event": "survey.response",
  "surveyId": 7,
  "surveyName": "NPS pos-atendimento",
  "kind": "nps",
  "sendId": 91,
  "recipient": "cliente@exemplo.com",
  "score": 9,
  "comment": "Atendimento rapido.",
  "updated": true,
  "meta": { "ticket": 4821, "agente": "bia" },
  "messageId": "8f3c...-uuid-da-mensagem",
  "timestamp": "2026-08-25T14:02:11.000Z"
}

O payload é o ESTADO ATUAL da resposta, não um delta. Case por sendId e sobrescreva. Você recebe mais de um aviso por resposta quando ela muda: o primeiro no voto (updated: false, comment: null), e outro quando a pessoa escreve o comentário ou troca a nota (updated: true). Não é duplicidade — o comentário sempre chega depois da nota, são dois gestos na página, e com um aviso só o campo mais valioso de um detrator nunca chegaria até você.

Endpoint com escopo de credencial não recebe survey.response: quem votou foi o destinatário, sem chave nenhuma, e mandar o aviso para o canal errado é pior que não mandar.

O teto de escrita destas rotas

As mutações desta seção (POST, PUT, DELETE) e o disparo têm um teto por chave, somado ao teto por IP: padrão 120/min. As leituras não o pagam. Estourou → 429 rate_limited com Retry-After.

O disparo entra nesse teto por um motivo concreto: o link de voto tem de existir antes do corpo do e-mail, então o registro nasce antes de o envio ser julgado e é cancelado quando ele é recusado. Um laço contra um destinatário sempre-recusado ficaria criando e cancelando sem parar.

Webhooks de envio

Receba eventos de entrega no seu servidor. Vários endpoints por conta; cada um assina um subconjunto de eventos: delivered, bounced, opened, clicked, complained, blocked. Estes são os eventos do que você mandou — o aviso de e-mail recebido é outro cadastro, na seção Webhook de recepção.

Timeout e retentativas: cada tentativa espera até 10 segundos pela sua resposta; entrega é 2xx dentro desse prazo. Qualquer outra coisa — 4xx, 5xx, 3xx (redirecionamento não é seguido), timeout, conexão recusada — conta como falha e entra na retentativa: são 6 tentativas no total, com esperas crescentes de 30 s, 2 min, 10 min, 1 h e 6 h (janela de ~7 h), a mesma política e a mesma tabela do webhook de recepção. Esgotadas as seis, a entrega é marcada como falha e não há sétima. Responda 2xx rápido e faça o trabalho pesado depois: um endpoint que processa por 12 s antes de responder falha por timeout mesmo tendo feito tudo certo.

O evento blocked dispara quando as suas regras de envio barram um destinatário (na API, no SMTP ou numa resposta a inbound). O corpo traz reason (block_list ou not_on_allow_list), entry (a entrada que casou, quando é block), address e origin. Endpoint com escopo de credencial não recebe blocked — o bloqueio não carrega credencial.

curl -X POST https://api.oveyon.com/v1/webhooks \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://suaapp.com/hooks/oveyon",
        "events": ["delivered", "bounced", "complained"],
        "credential": { "type": "api", "id": 42 } }'

{
  "id": 7,
  "url": "https://suaapp.com/hooks/oveyon",
  "events": ["bounced", "complained", "delivered"],
  "active": true,
  "secret": "3b1f...64hex...  (exibido UMA vez)",
  "signature": {
    "header": "x-oveyon-signature: sha256=HMAC-SHA256(secret, `${timestamp}.${rawBody}`)",
    "timestampHeader": "x-oveyon-timestamp (epoch em segundos)",
    "verify": "Recompute o HMAC sobre `timestamp + \".\" + corpo-cru` e rejeite se |agora - timestamp| > 300s."
  }
}

curl -X POST https://api.oveyon.com/v1/webhooks/7 \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Domínios

Cadastre e verifique os domínios de envio. Um domínio já de outra conta não pode ser recadastrado (anti-sequestro).

curl -X POST https://api.oveyon.com/v1/domains \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "suaempresa.com" }'

{
  "id": 42,
  "domain": "suaempresa.com",
  "records": [
    { "type": "TXT",   "name": "suaempresa.com", "value": "v=spf1 include:...", "purpose": "SPF (autoriza os IPs de envio)" },
    { "type": "CNAME", "name": "s90abc._domainkey.suaempresa.com", "value": "...", "purpose": "DKIM" }
  ],
  "verification": { "spf": false, "dkim": false, "dmarc": false }
}

curl -X POST https://api.oveyon.com/v1/domains/42/verify \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  "id": 42,
  "domain": "suaempresa.com",
  "verification": { "spf": true, "dkim": true, "dmarc": false },
  "inconclusive": [],
  "detail": { "spf": "...", "dkim": "...", "dmarc": "registro DMARC não encontrado" }
}

Erros & limites

Erros são JSON com um campo error estável (e, quando útil, message e contexto). Trate pelo código HTTP e pelo error, não pela mensagem.

# mesma chamada, mesmo erro, paises diferentes
# (o CF-IPCountry e injetado pela Cloudflare, voce nao manda nada)

BR  { "error": "bad_request", "message": "informe email OU domain, nunca os dois" }
US  { "error": "bad_request", "message": "provide email OR domain, never both" }
DE  { "error": "bad_request", "message": "provide email OR domain, never both" }
--  { "error": "bad_request", "message": "provide email OR domain, never both" }

// `error` identico nos quatro. So `message` muda.

Rate limit, cota e rampa

• Por IP — limite de requisições/min e de falhas de auth/min. Estourou → 429 com header Retry-After: 60. Aguarde e repita.
• Cota do tenant — 429 quota_exceeded com window (diária|mensal), used/limit e retryAfter no corpo. Sem window, o quota_exceeded é o limite por minuto da conta: reduza o ritmo e retente. Cota por serviço (planos) — service_quota_exceeded, com used/quota/effectiveCap no corpo.
• Conta bloqueada — 403 account_suspended (conta suspensa) e 403 account_unknown (conta não encontrada). Não são limite e não voltam sozinhos: são 403, e não 429, justamente para que o seu backoff não retente — nenhuma espera resolve. Fale com o suporte.
• Rampa (warmup) — teto diário por domínio enquanto a reputação aquece: warmup_cap_reached. Retente mais tarde.
• Backpressure — sistema saturado: queue_full. Recuo exponencial e nova tentativa.

Regra de ouro para 429 e 503: recuo exponencial com jitter e retentativa. Erros 4xx de validação (400/422) não devem ser retentados sem corrigir a requisição.