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.
• Cada chave (e cada credencial SMTP) envia por todos os domínios da conta ou só pelos selecionados — a escolha fica em Credenciais, no painel da credencial, e vale na hora. Um from fora do conjunto → 422 domain_not_allowed_for_credential (no SMTP, 550 5.7.1): o domínio está em ordem, é esta credencial que não o usa. Rotacionar herda a escolha.
• 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. · bad_request — no publish, version que não é inteiro ≥ 1.
• 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",
  "log_window": { "days": 15, "since": "2026-07-06T13:02:11.000Z" }
}

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": "..." }
  ]
}

Registro de chamadas

Toda chamada autenticada que as chaves da conta fazem à API fica registrada por 90 dias: a rota, o status, a duração, o IP, o user-agent e os corpos do pedido e da resposta. São os dados da tela Registro de chamadas do painel, que também explica cada erro e prepara o texto para colar numa IA.

• Os corpos são redigidos antes de gravar. Cabeçalho não é guardado — nem o Authorization. Campo com nome de segredo (password, secret, token…) e valor com cara de chave (ov_…, Bearer …) viram «redigido»; o corpo da mensagem e o anexo (html, text, content…) viram o tamanho, e cada variável de template (data) guarda o nome e perde o valor. Das rotas de conteúdo da recepção e das duas rotas do registro, a resposta não é guardada: só o tamanho dela.
• Teto de 32 KB por corpo. Acima disso o texto é cortado, truncated vem true e o que sobrou pode não ser mais JSON válido.
• O que fica de fora: a chamada recusada antes de a chave ser identificada (chave inválida, limite por IP) — não há conta a quem atribuí-la. A recusa de uma chave boa entra: desligada (key_disabled), conta suspensa (account_suspended), IP fora da amarração (ip_not_allowed).
• A gravação é assíncrona: a chamada aparece aqui alguns segundos depois de responder.

curl "https://api.oveyon.com/v1/logs?status=error&route=/v1/send&limit=25" \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  "data": [
    {
      "id": 48213,
      "createdAt": "2026-10-08T14:03:27.481Z",
      "method": "POST",
      "route": "/v1/send",
      "path": "/v1/send",
      "status": 403,
      "durationMs": 21,
      "credential": { "id": 12, "name": "backend", "prefix": "ov_3f9a1" },
      "ip": "203.0.113.24",
      "userAgent": "curl/8.5.0",
      "sdk": { "name": "curl", "version": "8.5.0" },
      "error": "insufficient_scope",
      "messageId": null
    }
  ],
  "next_cursor": "bDoxNzU5OTMyMjA3NDgxLjQ4MjEz"
}

{
  "id": 48213,
  "createdAt": "2026-10-08T14:03:27.481Z",
  "method": "POST",
  "route": "/v1/send",
  "path": "/v1/send",
  "status": 403,
  "durationMs": 21,
  "credential": { "id": 12, "name": "backend", "prefix": "ov_3f9a1" },
  "ip": "203.0.113.24",
  "userAgent": "curl/8.5.0",
  "sdk": { "name": "curl", "version": "8.5.0" },
  "error": "insufficient_scope",
  "messageId": null,
  "query": null,
  "request": {
    "body": "{\"from\":\"app@example.com\",\"to\":\"customer@example.com\",\"html\":{\"omitted\":\"content\",\"length\":5120},\"headers\":{\"X-Api-Key\":\"«redigido»\"}}",
    "bytes": 5302,
    "truncated": false
  },
  "response": {
    "body": "{\"error\":\"insufficient_scope\",\"required\":\"send\",\"have\":[\"read:messages\"]}",
    "bytes": 74,
    "truncated": false
  }
}

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.e-mailbox.com.

# Confira a propagação antes de pedir a verificação no painel:
dig +short MX suaempresa.com
# esperado:  10 mx1.e-mailbox.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.
• E toda mensagem chega com um veredito de segurança de agente. agentSafety responde a uma pergunta que nenhum dos campos acima responde: esta mensagem carrega instruções escritas para a máquina que vai lê-la? É a diferença entre «isto parece spam» e «isto está tentando dar ordens ao seu agente». Detectamos texto escondido do humano e visível ao parser — o bloco Unicode Tags (cópias invisíveis do ASCII, sem uso legítimo em e-mail), display:none, comentário de HTML, sobrescrita de direção — e o julgamos junto do que ele MANDA fazer. O veredito lê o que o seu agente lê: o assunto, o remetente com o nome de exibição (que chega a você em fromName), o corpo e os anexos de texto; e procura a instrução depois de tirar tudo o que o Unicode declara ignorável (hífen condicional, seletor de variação, largura zero…), para que esses caracteres não quebrem a frase nem empurrem a instrução para fora do trecho analisado. Rodapé oculto sem instrução não acusa; instrução oculta acusa. Links da mensagem também entram no mesmo veredito, julgados contra a base do Safe Browsing. verdict é clean, suspicious ou dangerous; score vai de 0 a 100 (cortes em 25 e 60). Os mesmos dois avisos do spamScore valem aqui: null é não avaliado, que não é clean; e o veredito é sinal, não recusa — nós não devolvemos a mensagem para o remetente por causa dele, e a régua de o que fazer com ela é sua. Com uma exceção que você liga: cada caixa pode pedir que mensagens dangerous sejam seguradas em vez de entregues. Enquanto uma mensagem está segurada ela não gera webhook nem reenvio, aparece na Recepção como «segurada para revisão», e sai de lá quando você clicar em «Soltar» — nesse momento o despacho acontece normalmente, com o veredito junto. Se a caixa não pediu isso (o padrão), o comportamento é o do parágrafo acima: entregamos e você decide. No webhook vêm também os signals, com o motivo de cada ponto — inclusive o texto que estava escondido, decodificado, para você poder ver com os próprios olhos o que o seu agente leria. E o veredito declara o que olhou. agentSafety.coverage vem junto dele (lista, detalhe e webhook): bodySampled — o motor viu cabeça e cauda (128 KiB) em vez do corpo inteiro, ou um anexo de texto cortado no teto, ou um cabeçalho absurdo que cortamos antes de ler (campo acima de 64 KiB, bloco acima de 512 KiB, ou de 5 mil linhas no cabeçalho da mensagem e mil numa parte — nenhum correio real chega perto), ou uma mensagem com mais de mil partes (lemos as primeiras mil); sanitized — o texto que entregamos (corpo, assunto ou nome do remetente) teve caracteres escondidos removidos (bloco Tags, largura zero, sobrescrita de direção; a cópia /raw os mantém, para perícia); unscannedAttachments — quantos anexos o motor não leu por não serem texto (PDF, imagem, planilha, zip): extraia antes de dar a um modelo. Mensagem anexada (.eml) é decodificada e entra no veredito; anexo de texto entra seja qual for o rótulo. Os signals também vêm no GET /v1/inbound/{id}, e ?agent_safety=dangerous (ou suspicious,dangerous; none = ainda sem veredito) filtra a caixa por ele. coverage: null é uma mensagem de antes de a cobertura ser gravada.
• E se o link armar DEPOIS, nós voltamos atrás. Um link pode estar limpo na hora em que a mensagem chega e virar malicioso seis horas depois — quando o domínio é comprometido, ou quando quem montou o ataque liga a carga. Nenhuma verificação feita no aceite resolve isso, porque ela julga o que a mensagem era. Cada caixa liga o reexame para si (é uma opção do endereço, e vem desligada): quando ligado, reexaminamos os links das mensagens recebidas nos últimos 3 dias e, se um deles passar a constar em lista de ameaça, disparamos o evento inbound.retro_flagged no seu webhook: «a mensagem X, que entregamos como limpa, ficou maliciosa», com os links em questão. Três coisas que valem dizer: a mensagem continua entregue — nós não a recolhemos nem reescrevemos o corpo, e o desfecho dela no histórico não muda; o aviso sai uma vez só por mensagem; e o eventId é próprio, então o seu dedupe não vai confundir a retratação com uma repetição do aviso de chegada. Diferente do resto do mercado, nós não trocamos o link do seu e-mail por um nosso para decidir no clique — o corpo sai como chegou, e a retratação é um aviso, não um sequestro do link. O preço dessa escolha é honesto: quem já clicou não foi protegido por nós, foi informado, e o seu agente decide o que fazer com a informação. O corpo do evento é este:

  {
    "event": "inbound.retro_flagged",
    "eventId": "9f1c…",              // único por POST — deduplique por ele
    "timestamp": "2026-09-08T11:04:22.117Z",
    "message":   { "id": "a3e1…", "subject": "Nota fiscal 4471", "fromHeader": "fin@cliente.com" },
    "recipient": { "id": "7c22…", "to": "suporte@seudominio.com" },
    "retro": {
      "reason":  "link_listed_after_delivery",
      "message": "Um ou mais links desta mensagem passaram a constar em lista de ameaça DEPOIS de nós a entregarmos.",
      "links":   [{ "url": "http://…", "threatTypes": ["MALWARE"] }]
    }
  }

  Ele vai só por webhook: Telegram e reenvio são superfícies de leitura humana, e uma retratação que chega como mensagem de chat é ruído sem ação possível — quem consome isto é o seu agente.

• E se a caixa segura pelo veredito, você fica sabendo na hora. Caixas com «Segurar o que parecer perigoso» ligado não recebem o corpo de uma mensagem com veredito dangerous: ela fica retida para revisão humana, e no mesmo instante você recebe inbound.quarantined no webhook (e um aviso no Telegram/Slack, se a caixa tiver). Nunca retemos sem avisar. O mesmo evento sai quando uma das suas políticas da recepção pede para segurar: reason: "policy" e o nome da regra em quarantine.policy (na quarentena de segurança, policy vem null). A retenção é por caixa: numa mensagem para duas caixas, só a cópia da caixa que pediu fica segurada — a outra é entregue, a mensagem vem com outcome: "partial" e cada item de recipients traz o desfecho da sua cópia. Caixa que só encaminha para uma pessoa também segura: o aviso vai por e-mail ao endereço do encaminhamento (sem ele, pelo Telegram da conta; sem este, por e-mail aos donos). Responder por API quando TODAS as cópias estão retidas devolve 409 message_quarantined até alguém soltá-las; com parte entregue, a resposta sai pela caixa entregue.

  {
    "event": "inbound.quarantined",
    "eventId": "2b7d…",              // único por POST — deduplique por ele
    "timestamp": "2026-09-16T18:40:07.221Z",
    "message":   { "id": "a3e1…", "subject": "Liberação de pagamento", "fromHeader": "financeiro@acme-pagamentos.com" },
    "recipient": { "id": "7c22…", "to": "suporte@seudominio.com" },
    "quarantine": {
      "reason":      "agent_safety_dangerous",
      "heldAt":      "2026-09-16T18:40:07.221Z",
      "expiresAt":   null,
      "agentSafety": { "verdict": "dangerous", "score": 65 },
      "policy":      null,
      "release":     { "panel": "https://app.oveyon.com/app/recepcao/entregas", "note": "O corpo está segurado, não entregue. A resposta por API devolve 409 message_quarantined até que uma pessoa solte a mensagem no painel." }
    }
  }

• Políticas da recepção: SE isto chegar, ENTÃO faça aquilo. /v1/inbound-policies (escopos read:inbound-policies e write:inbound-policies; criar e editar exigem também read:inbound, porque uma regra sobre o conteúdo, ativada, revela em quais mensagens casou) guarda até 50 regras por conta, avaliadas de cima para baixo para cada destinatário de toda mensagem recebida. mailboxes diz para quais caixas a regra vale (null = todas; uma lista de ids de GET /v1/inbound/routes = só estas): cada destinatário é julgado pelas regras da caixa dele e pelas de todas, na ordem única da conta — uma mensagem para suporte@ e vendas@ pode ser segurada para uma e entregue para a outra. Se as caixas escolhidas forem apagadas, a regra passa a valer para nenhuma (a lista volta vazia), nunca para todas. As condições enxergam o que só a recepção vê: agent_safety.verdict e agent_safety.score, o corpo (body, texto ou HTML sem tags), dmarc/spf/dkim, anexos (attachment.type, attachment.name, attachment.count), size_kb, listed_link, a conversa (thread.new, thread.replies), remetente, destinatário, assunto, hora e dia da semana no fuso da conta. Operadores equals, contains, starts_with, ends_with, matches (glob com * — nunca regex), in, at_least, at_most; campo vazio (sem veredito, por exemplo) nunca casa. O texto (assunto, corpo, nome de anexo) é comparado como o agente o lê: sem os caracteres que o Unicode declara ignoráveis (largura zero, hífen condicional, seletores de variação, bidi…) e em NFKC — ｆａｔｕｒａ em largura total é fatura, dos dois lados; um valor feito só de caracteres ignoráveis é vazio (empty_value). O corpo é julgado sobre a amostra de cabeça e cauda recortada depois dessa limpeza, e todo anexo que a borda aceita (até 1.000 partes) é julgado. Ações: hold segura para uma pessoa decidir (e avisa, como a quarentena), mute guarda sem despachar nem avisar, restrict_channels entrega só aos canais escolhidos, pass encerra a cadeia — e tag e notify (Telegram da conta) anotam e seguem. O aviso do notify é de melhor esforço: sai depois do aceite, com três tentativas, e um reinício no meio pode perdê-lo — o feed registra no_chat ou notify_failed quando dá para saber. Se a quarentena de segurança da caixa segura a mensagem, ela vem antes: a política de hold/mute que também casou aparece no feed com o motivo mailbox_quarantine (o aviso é o da quarentena, sem o prazo e fora do teto da política). A política nasce pausada: confira no simulador (POST /v1/inbound-policies/simulate, com o id de uma recebida ou uma mensagem sintética, e um rascunho opcional — ele responde por destinatário em recipients) e então /unpause. Enquanto a trava da plataforma estiver desligada, hold, mute e restrict_channels viram a etiqueta would_<ação>:<nome> — você vê o que a regra faria antes de ela valer; o mesmo acontece quando uma política chega a 200 mensagens seguradas. E nunca retemos às escuras: um hold que não consegue avisar em canal nenhum (no_notice), ou um restrict_channels cujos canais não estão ligados à caixa (no_channel), entrega a mensagem normalmente, com a etiqueta e o motivo no feed. Toda recebida traz policy (ação efetiva, nome e etiquetas) na lista, no detalhe e no webhook — a da primeira caixa na mensagem, a de cada caixa em recipients[].policy e no webhook daquela caixa; o que a política segurou você solta como a quarentena (painel ou POST /v1/inbound/{id}/release). O feed (GET /v1/inbound-policies/decisions, 90 dias) diz qual regra casou em qual mensagem, para qual caixa (recipient) e com que ação de fato. O teto de seguradas por política conta mensagens, não cópias.

  POST /v1/inbound-policies
  { "name": "PDF suspeito", "action": "hold",
    "conditions": [ { "field": "agent_safety.verdict", "op": "at_least", "value": "suspicious" },
                    { "field": "attachment.type", "op": "equals", "value": "application/pdf" } ] }
  201 { "id": 12, "position": 3, "paused": true, "version": 1, … }
  
  POST /v1/inbound-policies
  { "name": "DMARC falhou: só o humano", "action": "restrict_channels",
    "conditions": [ { "field": "dmarc", "op": "equals", "value": "fail" } ],
    "actionParams": { "channels": [ { "type": "telegram" } ] } }
  
  POST /v1/inbound-policies/simulate  { "message": "a3e1…", "policyId": 12 }
  200 { "holdEnabled": false, "matched": [ { "id": 12, "name": "PDF suspeito", "action": "hold" } ],
        "result": { "action": "tag", "policy": "PDF suspeito", "degradedReason": "hold_disabled", "tags": ["would_hold:PDF suspeito"] }, "seen": { … } }

  Sem policy nem policyId, o simulador avalia só as políticas ativas — a recém-criada (pausada) fica de fora; policyId avalia uma política salva mesmo pausada, e policy avalia um rascunho não salvo (os dois juntos são 400). Simular sobre uma recebida real lê a caixa: a chave precisa também de read:inbound; toda simulação — sintética ou não — conta no limite por chave de leitura da caixa (120/min por padrão), e o 429 dele responde Retry-After: 60: acima dos 30 s que os SDKs oficiais esperam por padrão, então eles não repetem sozinhos — o 429 chega ao seu código, com o Retry-After em mãos; espere e chame de novo, ou suba o teto de espera do SDK. O corpo das rotas de políticas tem teto de 256 KB (413 payload_too_large, com limit: 262144). Pela mesma razão da leitura da caixa, o feed só mostra assunto e remetente para chaves com read:inbound. Numa recebida real o simulador relê a mensagem guardada pelo mesmo leitor do aceite — a mesma amostra do corpo, o remetente, o assunto e os nomes de anexo inteiros — e julga o listed_link que o aceite gravou (null quando o aceite não conseguiu julgar todos os links; mensagens anteriores a 27/09/2026 só guardam o «sim»); já prevê no_notice/no_channel pelas caixas da mensagem; a conversa é lida como está agora. Sem a cópia (retenção vencida), vale o que ficou gravado, e o que foi cortado na gravação não casa pelo lado perdido. Uma política salva que o motor não lê mais (policyId) responde 409 inbound_policy_unreadable, com o motivo em reason: ela está sendo pulada no aceite até ser editada.

  O que as condições enxergam, com precisão: o body é julgado no texto e no HTML sem tags (casa se qualquer um casar), depois da mesma limpeza do veredito (caracteres invisíveis, bidi e de tag somem); as listas (recipient, attachment.*) são julgadas nos 100 primeiros itens; um endereço com mais de 320 caracteres guarda o fim (o domínio), e nele só ends_with, contains e padrões começando em * casam; listed_link é nulo — e não casa — quando a checagem não julgou todos os links. Confie com medida: sender, subject e thread.* são o que o remetente diz; dmarc/spf/dkim, agent_safety.* e listed_link são medições nossas. A etiqueta de ensaio é sempre would_<ação>:<nome> com o nome da ação da API (would_hold, would_mute, would_restrict_channels): quem integra deve tratá-la como a intenção da regra. O que uma política hold segurou corre a retenção da caixa (o prazo vem em quarantine.expiresAt no aviso e aparece no painel); sem soltar até lá, a cópia é apagada, e soltar ou responder passam a devolver 410 copy_expired. O aviso de notify vai aos chats de Telegram da conta; se nenhum recebeu, o feed diz por quê (no_chat ou notify_failed).

• O agente propõe, uma pessoa decide (hold). Mande hold: true no POST /v1/send ou no /reply e a mensagem é aceita, assinada e guardada sem sair: o 202 responde status: "held" com as URLs de decisão. holdNote (até 500 caracteres) é o que o agente diz ao aprovador; holdTtl é o prazo em segundos (24 h por padrão, 7 dias no máximo). A pessoa decide no portal (Mensagens → Aprovações), no Telegram da conta ou pela API: GET /v1/holds lista, POST /v1/messages/{id}/approve envia agora sem reassinar (e conta aquecimento), POST /v1/messages/{id}/reject não envia e devolve a cota. Tudo com o escopo approve:holds — a chave que envia não é a que aprova. A primeira decisão vence; a segunda recebe 409 already_decided. Vencido o prazo, o rascunho expira e não sai (webhook hold_expired). Os quatro eventos (held, approved, rejected, hold_expired) são opt-in por endpoint e levam metadados e a URL, nunca o corpo. Teto: 500 rascunhos e 200 MB por conta (429 hold_limit). A política de envio reter_para_aprovacao produz o mesmo rascunho a partir de uma regra sua.

  POST /v1/send
  { "from": "vendas@seudominio.com", "to": "cliente@acme.com", "subject": "Proposta 4471", "text": "…",
    "hold": true, "holdTtl": 7200, "holdNote": "Desconto acima de 15% — precisa de alguém do comercial" }
  
  202 { "id": "9f2c…", "status": "held", "hold": { "expiresAt": "2026-09-23T16:02:11.000Z", "note": "…", "requestedBy": "api:ovy_a1b2",
         "approve": "/v1/messages/9f2c…/approve", "reject": "/v1/messages/9f2c…/reject" } }
  
  POST /v1/messages/9f2c…/reject  { "reason": "valor errado na proposta" }
  200 { "id": "9f2c…", "status": "rejected", "decidedAt": "…", "decidedBy": "api:ovy_c3d4", "reason": "valor errado na proposta" }

• Soltar é gesto humano — pelo painel ou pela API. POST /v1/inbound/{id}/release (escopo write:inbound, nunca o da chave que responde) despacha agora as cópias seguradas da mensagem, e o payload de cada uma traz message.quarantine: quando ela foi segurada, por quê, quando e por onde foi solta — e o veredito junto, porque soltar não é absolver. Sem corpo solta TODAS as cópias seguradas; { "recipient": "vendas@…" } solta só a daquela caixa (a resposta diz quais saíram em recipients e quantas seguem presas em stillHeld). 409 not_quarantined se nenhuma cópia está segurada (recipient_not_quarantined se é a daquela caixa que não está); 422 recipient_not_in_message se a mensagem não foi para essa caixa; 410 copy_expired se a cópia já expirou. Os números ficam em GET /v1/inbound/stats (por dia ou por destinatário, até 92 dias): recebidas, avaliadas, limpas, suspeitas, perigosas, seguradas e soltas — os mesmos do cartão «Segurança de agente» da Recepção, contados uma vez só.

  POST /v1/inbound/a3e1…/release
  200 { "id": "a3e1…", "status": "released", "deliveries": 1, "noChannel": false, "releasedAt": "2026-09-16T19:02:11.000Z", "releasedBy": "api:ovy_a1b2" }
  
  GET /v1/inbound/stats?group_by=day&from=2026-09-01&to=2026-09-16
  200 { "groupBy": "day", "data": [ { "day": "2026-09-16", "received": 41, "evaluated": 41, "clean": 39, "suspicious": 1, "dangerous": 1, "quarantined": 1, "released": 1 }, … ] }

• A conversa é um objeto. Cada recebida traz thread.id (na lista, no detalhe e no webhook): mensagens agrupadas por In-Reply-To/References dentro da sua conta, incluindo as respostas que você mandou pela OVEYON (portal, Telegram, Slack ou API) — quando o cliente responde à sua resposta, ela cai na mesma conversa. Nunca por assunto. GET /v1/inbound/threads lista as conversas por última atividade (cursor opaco), GET /v1/inbound/threads/{id} devolve as recebidas em ordem e as respostas enviadas, e GET /v1/inbound?thread=<id> filtra a caixa por uma conversa. thread: null é uma mensagem de antes do agrupamento ou uma que o aceite não conseguiu resolver — nunca uma recusa.

  GET /v1/inbound/threads/2b7d…
  {
    "id": "2b7d…", "subject": "pedido 4471", "firstAt": "2026-09-16T14:02:11.000Z", "lastAt": "2026-09-16T18:40:07.221Z",
    "messageCount": 2, "replyCount": 1,
    "messages": [ { "id": "a3e1…", "subject": "Pedido 4471", "thread": { "id": "2b7d…" }, … }, { "id": "c9f0…", "subject": "Re: Pedido 4471", … } ],
    "replies":  [ { "id": "bbcd…", "at": "2026-09-16T15:10:00.000Z", "origin": "api", "from": "suporte@seudominio.com", "to": "cliente@acme.com", "subject": "Re: Pedido 4471", "preview": "Olá! Segue a nota fiscal…" } ]
  }

• O agente responde por API. POST /v1/inbound/{id}/reply (escopo reply:inbound) manda uma resposta em texto da caixa que recebeu para o Reply-To/From do original, com In-Reply-To e References preenchidos por nós — a resposta cai na mesma conversa do lado de lá e na sua (thread). Conta uma unidade de cota e consome aquecimento como qualquer correio que sai em nome do domínio; o id devolvido é o da mensagem enviada, para você acompanhar em GET /v1/messages/{id} e nos webhooks de entrega. idempotencyKey (ou o header) devolve o mesmo id em vez de responder duas vezes. Guarda de laço, porque o caso é agente contra agente: a resposta sai com Auto-Submitted: auto-replied; responder a correio automático (Auto-Submitted, Precedence bulk/list/junk, remetente nulo) é 422 auto_submitted; no máximo 5 respostas por mensagem e 10 respostas automáticas por conversa por hora (429). Mensagem segurada responde 409 message_quarantined com a pontuação e o link de soltar — soltar é gesto humano, nunca ferramenta do modelo. Com várias caixas e só parte das cópias segurada, a resposta sai pela primeira caixa cuja cópia foi entregue; from escolhe outra caixa da mensagem (422 from_not_recipient se ela não recebeu a mensagem; 409 recipient_quarantined se a cópia dela está segurada). Suas listas de bloqueio/permissão de destinatário valem aqui também (422). A chave limitada a domínios selecionados só responde por caixa de um domínio permitido — fora deles, 422 domain_not_allowed_for_credential, sem consumir a idempotencyKey. O detalhe da recebida traz replies[].

  POST /v1/inbound/a3e1…/reply
  { "text": "Olá! A nota fiscal 4471 foi reemitida e segue em anexo no portal.", "idempotencyKey": "ticket-8812-r1" }
  
  202 { "id": "bbcd…", "status": "accepted", "from": "suporte@seudominio.com", "to": "cliente@acme.com",
        "subject": "Re: Pedido 4471", "thread": { "id": "2b7d…" }, "url": "/v1/messages/bbcd…" }

• E o detalhe conta por onde a mensagem saiu — até a última palavra do outro lado. deliveries[] traz um item por (destinatário, canal, kind): webhook, reenvio por e-mail, Telegram, Slack. Dois fatos, dois campos, de propósito: status é a nossa metade — delivered quer dizer que o seu endpoint respondeu 2xx, que o chat aceitou o aviso, ou que a cópia reenviada entrou na nossa fila de saída; não que a caixa do outro lado a tenha. No reenvio, destination é a palavra do MX de destino quando a cópia chegou lá: accepted, deferred ou bounced, com a resposta SMTP crua (response), quem respondeu (host) e quando (at) — o texto que você cola num chamado com o provedor. null nos outros canais, ou enquanto ainda não se sabe. Leia os dois antes de dizer «chegou»: um reenvio delivered com destination.status = "bounced" saiu daqui e não chegou a ninguém. kind distingue o que foi despachado para o mesmo par: a mensagem na chegada (received), o aviso de quarentena (quarantined) ou o da retro-caça de link (retro). O que fica de fora: a configuração do canal (URL, segredo, chat) — é do canal, e GET /v1/inbound/routes/{id} já a serve, sem segredo. Três limites, ditos em voz alta: destination só existe quando a cópia saiu por um dos nossos nós de disparo (a rota normal; uma cópia que o master entrega direto, em contingência, fica null); o veredito é o síncrono — o bounce assíncrono (a caixa aceita e devolve um DSN depois) não entra aqui; e accepted é o que o MX disse, não o que a caixa mostra: o Gmail, por exemplo, aceita com 250 e descarta em silêncio — sem Spam, sem Lixeira — uma cópia cujo Message-ID aquela conta já viu (supressão de duplicata), e o reenvio preserva o Message-ID de propósito, porque é ele que mantém a conversa e a assinatura DKIM do remetente. Medido em 22/09/2026: quatro cópias aceitas, nenhuma visível, até o Message-ID mudar.
• A caixa nasce por API. POST /v1/inbound/routes (escopo write:inbound) cria suporte@seudominio.com — ou o pega-tudo *@seudominio.com — num domínio da sua conta e, na mesma chamada, pendura os avisos: um webhook novo ({ "type": "webhook", "url": … }, com a prova de posse da URL e o segredo devolvido uma vez) e/ou canais que já existem no domínio ({ "channelId": … }). GET lista e detalha (com os canais, nunca com segredo), PATCH liga/desliga e acrescenta canais, DELETE remove a caixa ou, por assocId, só um vínculo. A caixa criada por máquina nasce sem escolhas de segurança: entrega tudo com o veredito; segurar é escolha que se liga no painel. Tetos: 200 caixas por domínio e 1000 por conta (422). createdBy diz quem criou (api:<prefixo da chave>), e o painel mostra o mesmo.

  POST /v1/inbound/routes
  { "domain": "seudominio.com", "matchType": "exact", "localPart": "suporte",
    "channels": [ { "type": "webhook", "url": "https://app.acme.com/hooks/oveyon", "mode": "full" } ] }
  
  201 { "id": 318, "address": "suporte@seudominio.com", "active": true, "inboundEnabled": true, "createdBy": "api:ovy_a1b2",
        "channels": [ { "assocId": 902, "channelId": 77, "type": "webhook", "destination": "https://app.acme.com/hooks/oveyon", "mode": "full", "active": true } ],
        "webhook": { "url": "https://app.acme.com/hooks/oveyon", "mode": "full", "secret": "…64 hex, mostrado uma vez…" } }

• O texto novo, sem o citado. No webhook (modos full) e no GET /v1/inbound/{id}/content, além de text vem replyText: só o que a pessoa escreveu desta vez, sem o «Em 16/09, Fulano escreveu:», as linhas com >, o bloco De/Enviado/Para/Assunto do Outlook, a mensagem original/encaminhada e a assinatura -- . É isso que se dá a um modelo: a conversa inteira já está na thread, e reprocessá-la a cada volta custa tokens e confusão. replyStripped diz se algo foi removido e replyMarkers o quê. Sem nada a cortar, replyText é igual a text. Português e inglês; resposta intercalada (sua resposta entre as linhas citadas) fica inteira.
• 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, "quarantined" quando todas as cópias estão seguradas para revisão, "partial" quando umas cópias foram entregues e outras estão seguradas (cada item de recipients diz o seu: outcome, heldBy e policy), 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" e de "partial" 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,
      // O veredito de segurança de agente, com o que ele OLHOU (coverage).
      "agentSafety": { "verdict": "clean", "score": 0,
                       "coverage": { "bodySampled": false, "sanitized": false, "unscannedAttachments": 1 } },

      "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" }
  ],

  // POR ONDE SAIU, E O QUE ACONTECEU. Um item por (destinatário, canal,
  // kind — a chegada, o aviso de quarentena ou o da retro-caça de link).
  // `status` é a NOSSA metade: `delivered` = seu endpoint respondeu 2xx, o
  // chat aceitou, ou a cópia reenviada entrou na nossa fila de saída — não
  // que a caixa do outro lado a tenha. No reenvio, `destination` é a palavra
  // do MX de destino (accepted | deferred | bounced) com a resposta SMTP
  // crua; `null` nos outros canais ou enquanto não se sabe. Leia os dois
  // antes de dizer «chegou».
  "deliveries": [
    { "id": "d999cc6d-…", "recipient": { "id": "d83ea519-…", "to": "suporte@suaempresa.com" },
      "channel": "webhook", "kind": "received", "status": "delivered", "detail": "HTTP 200", "attempts": 1,
      "createdAt": "2026-09-04T11:02:41.515Z", "completedAt": "2026-09-04T11:02:42.101Z",
      "destination": null },
    { "id": "ca0e76d8-…", "recipient": { "id": "d83ea519-…", "to": "suporte@suaempresa.com" },
      "channel": "forward", "kind": "received", "status": "delivered",
      "detail": "reenviado para caixa@gmail.com (aceito pela fila de saída)", "attempts": 1,
      "createdAt": "2026-09-04T11:02:41.518Z", "completedAt": "2026-09-04T11:02:48.079Z",
      "destination": { "status": "accepted", "host": "gmail-smtp-in.l.google.com",
                       "response": "250 2.0.0 OK 1790113210 d9443c01a7336… - gsmtp",
                       "at": "2026-09-04T11:02:50.428Z" } }
  ],
  "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,
  "sanitized": 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 / bad_agent_safety — 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. No painel: Domínios → abra o domínio → aba Recepção → «Canais de aviso deste domínio» → + Novo canal — ou, no Configurar de um endereço, «Avisar por webhook». Você informa a URL e escolhe o modo; o segredo de assinatura é gerado por nós e aparece na criação — e, quando você precisar conferir, em «Mostrar segredo», no painel do canal. Cada exibição fica na trilha de auditoria da conta.

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. Pela API, o webhook nasce preso a uma caixa: o POST /v1/inbound/routes cria o endereço já com ele, e o PATCH /v1/inbound/routes/{id} acrescenta um a uma caixa que já existe — com a mesma prova de posse da URL, e o segredo vem uma vez, na resposta (a caixa nasce por API); depois, só o painel o mostra. Telegram, Slack, encaminhamento e o canal solto, sem caixa, são só no 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 de criado o canal), 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,
    "agentSafety": { "verdict": "clean", "score": 0, "signals": [],
                     "coverage": { "bodySampled": false, "sanitized": false, "unscannedAttachments": 1 } },
    "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.
• A língua é a da sua conta — a mesma dos e-mails que a plataforma manda para você: português para conta do Brasil, inglês para as demais. Ela vale para o texto fixo do e-mail (o aviso de que responder não vota, as pontas da escala), para a página de voto e para a pergunta padrão. O que você escreve — assunto, pergunta, nome do remetente — sai como você escreveu.

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 da sua marca)" },
    { "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": "nenhum registro _dmarc" }
}

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.

O que é recusado antes da rota

Algumas respostas nascem antes de a rota rodar, e valem para toda operação — por isso a OpenAPI as declara em todas:

• 400 invalid_json — com Content-Type: application/json, o corpo tem de ser JSON válido e não pode vir vazio. Sem corpo, não mande o cabeçalho.
• 413 payload_too_large — o corpo passou do limite daquela rota, informado em limit (em bytes): 25 MB no geral, 256 KB nas rotas de políticas. O corpo é lido até o limite antes de a chave ser validada.
• 415 unsupported_media_type — mande o corpo como application/json.
• 500 internal_error — falha nossa. O detalhe fica nos nossos logs, nunca no corpo. Repita leituras; repita uma escrita só se ela for idempotente ou levar chave de idempotência.
• 503 ip_rules_unavailable — a chave tem faixas de IP amarradas e a conferência não pôde ser feita agora. É cautela, não recusa: repita depois do Retry-After.
• 404 not_found — também para rota ou método que não existe; sem chave, a resposta é 401.

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.