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). Com a trava de aprovação humana ligada na chave, os escopos que a anulariam (approve:holds, write:send-policies, manage:webhooks, write:inbound, write:templates, write:surveys, write:domains, write:contacts, write:campaigns, send:campaigns, write:sequences) respondem 403 scope_blocked_by_approval_lock, mesmo gravados na chave:

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.

422 { "error": "return_path_not_authorized",
      "message": "return_path=sender exige que o SPF de exemplo.com.br tenha include:_spf.… — publique e envie de novo, ou envie com return_path \"platform\"",
      "reason": "spf_include_missing", "domain": "exemplo.com.br", "include": "_spf.…" }

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 180 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 — inclusive o nome do arquivo — (html, text, content, filename…) viram o tamanho, como o detalhe dos sinais de segurança (signals[].detail, que pode citar texto escondido no e-mail); cada variável de template (data) guarda o nome e perde o valor; e uma URL que pode carregar segredo no caminho vira só o host e o tamanho — o link rastreado da mensagem enviada (tracking[].url) e a URL de destino que você cadastra (channels[].url, e todo url nas rotas de webhooks e de caixas): em Zapier, Make e afins o caminho é o próprio segredo. Das rotas de conteúdo da recepção e das duas rotas do registro, a resposta não é guardada: só o tamanho dela. Nas rotas de marketing, o pedido e a query guardam só os nomes dos campos e os ids — os valores viram { "omitted": "personal" } — e a resposta de sucesso não é guardada.
• 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 —, e o 429 do teto geral por chave. 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,
      "mcpCallId": 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,
  "mcpCallId": 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
  }
}

Registro do MCP

O que os agentes de IA fizeram pelo servidor MCP, uma linha por mensagem JSON-RPC: a ferramenta que o agente chamou, por qual aplicativo (ChatGPT, Claude…), de onde, como terminou e quais chamadas à API ela fez. O mesmo prazo, 180 dias, e o mesmo escopo, read:logs. No painel é a aba MCP do Registro de chamadas.

• Este registro não guarda o resultado das ferramentas — o e-mail lido, a lista de mensagens: só o tamanho (resultBytes). A chamada que a ferramenta faz à API fica no registro de chamadas, redigida como qualquer outra (e a resposta das rotas de conteúdo, como GET /v1/inbound/:uid/content, nem lá).
• Os argumentos são gravados redigidos: só os campos do esquema da ferramenta (outro campo vira { "omitted": "unknown_field" }), com as mesmas regras dos corpos acima; teto de 8 KB — o que não cabe no teto como JSON válido vira { "omitted": "too_large", "bytes": N }, com o tamanho em bytes dos argumentos como chegaram, e argumentsTruncated vem true.
• O elo com o registro de chamadas: cada chamada à API que uma ferramenta fez leva em mcpCallId o callId da mensagem — a tela e a API ligam uma à outra, nos dois sentidos.
• O que fica de fora: a requisição cuja credencial não foi identificada, como no registro de chamadas (a chave conhecida e recusada — desligada, por exemplo — entra).

curl "https://api.oveyon.com/v1/logs/mcp?tool=get_inbound_content&limit=25" \
  -H "Authorization: Bearer $OVEYON_API_KEY"

{
  "data": [
    {
      "id": 9120,
      "createdAt": "2026-10-14T03:12:08.204Z",
      "callId": "5f0c8e2a9b1d4c7e8a3f6b2d1e9c0a47",
      "credential": { "id": 41, "name": "ChatGPT (OAuth)", "prefix": "ov_7d2e1" },
      "application": { "name": "ChatGPT", "origin": "chatgpt.com" },
      "method": "tools/call",
      "tool": "get_inbound_content",
      "outcome": "ok",
      "error": null,
      "status": 200,
      "durationMs": 184,
      "apiCalls": 1,
      "apiStatuses": [200],
      "client": null,
      "batch": { "size": 1, "index": 0 }
    }
  ],
  "next_cursor": "bToxNzYwNDExNTI4MjA0LjkxMjA"
}

{
  "id": 9120,
  "createdAt": "2026-10-14T03:12:08.204Z",
  "callId": "5f0c8e2a9b1d4c7e8a3f6b2d1e9c0a47",
  "credential": { "id": 41, "name": "ChatGPT (OAuth)", "prefix": "ov_7d2e1" },
  "application": { "name": "ChatGPT", "origin": "chatgpt.com" },
  "method": "tools/call",
  "tool": "get_inbound_content",
  "outcome": "ok",
  "error": null,
  "status": 200,
  "durationMs": 184,
  "apiCalls": 1,
  "apiStatuses": [200],
  "client": null,
  "batch": { "size": 1, "index": 0 },
  "target": "get_inbound_content",
  "httpMethod": "POST",
  "rpcId": "7",
  "rpcError": null,
  "arguments": { "uid": "3b8f1c52-6a0e-4d3b-9f27-0c5e8a1d6b94" },
  "argumentsTruncated": false,
  "requestBytes": 142,
  "resultBytes": 4183,
  "apiRoute": "GET /v1/inbound/:uid/content",
  "apiError": null,
  "ip": "203.0.113.77",
  "userAgent": "openai-mcp/1.0.0",
  "protocolVersion": "2025-06-18",
  "sessionId": null,
  "apiLogIds": [48230]
}

Servidor MCP (para agentes de IA)

A mesma API como ferramentas que um agente de IA (Claude Code, Cursor, VS Code, Codex, Windsurf…) chama pelo nome, pelo Model Context Protocol. Um endpoint só, Streamable HTTP, sem estado: POST https://mcp.oveyon.com/v1 (o endereço https://api.oveyon.com/v1/mcp também responde, para sempre). A tela MCP do painel imprime a configuração de cada cliente.

• A autenticação é a chave de API, como Bearer: Authorization: Bearer ov_…. O mesmo portão de toda rota: 401 sem chave, 403 para key_disabled, account_suspended e ip_not_allowed, 429 com Retry-After.
• Uma ferramenta por rota. O servidor lista só as ferramentas que os escopos da chave permitem (mais whoami e check_disposable): send_email é POST /v1/send com o escopo send, list_inbound é GET /v1/inbound com read:inbound, e assim por diante — o esquema de entrada de cada ferramenta é o deste documento.
• Toda chamada de ferramenta é uma chamada à API, com a mesma chave: escopos, cotas, políticas, idempotência e o registro de chamadas valem sem mudança; no registro elas aparecem como a família oveyon-mcp (sdk), com mcpCallId. A mensagem do agente — a ferramenta, o aplicativo, os argumentos redigidos — fica no registro do MCP.
• O erro chega inteiro ao modelo: error, message e Retry-After no resultado da ferramenta (isError) — é o que faz um agente parar num 403 e esperar num 429.
• Sem chave, por OAuth 2.1: o cliente que conecta por login (o conector personalizado do claude.ai, do Claude Desktop e do celular; o ChatGPT) recebe só o endereço. O 401 aponta o metadado do recurso (resource_metadata, RFC 9728), que aponta o emissor (/.well-known/oauth-authorization-server no host do painel); código com PKCE S256, registro dinâmico ou por documento de metadado (client_id = URL). A pessoa entra, escolhe as permissões e permite; a conexão vira uma credencial da conta (Credenciais), e o token só vale aqui no servidor MCP. Os tetos são os de uma chave: cada conexão tem o seu (600 req/min), seja qual for o IP de onde a plataforma chama, e a descoberta sem token e o token vencido não contam como falha de autenticação. No /oauth/token, só código ou refresh desconhecido conta, por origem (30/min); acima disso a resposta é 429 too_many_requests com Retry-After, e a renovação válida passa mesmo com a origem no teto, dentro de 120 consultas por minuto.
• Nada fica entre uma chamada e outra: sem sessão (GET e DELETE respondem 405); whoami diz a conta, a chave e as ferramentas; o recurso oveyon://guide é o procedimento.

Conectar

claude mcp add --transport http oveyon https://mcp.oveyon.com/v1 --header "Authorization: Bearer $OVEYON_API_KEY"

Na mão

curl -X POST https://mcp.oveyon.com/v1 \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

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 cada caixa pode ligar um filtro de spam de verdade. Além do spamScore (a nossa heurística, de toda mensagem), a caixa pode ligar o filtro de spam da caixa: o rspamd da nossa borda de recepção, que olha conteúdo, reputação de link e de IP e a autenticação. É opt-in por caixa — nasce desligado em toda caixa e só você liga, no painel (Recepção → Caixas → a caixa) ou por PATCH /v1/inbound/routes/{id} com { "spamFilter": true }; caixa com o filtro desligado nem é varrida. A mensagem passa a trazer spamFilter: status (scanned = tem nota; unavailable = o filtro não respondeu a tempo e a mensagem foi entregue sem nota; skipped = não varrida de propósito, e reason diz por quê: too_large ou bypass, correio de um dos nossos próprios domínios, numa lista explícita, assinado (DKIM) por esse mesmo domínio e com DMARC aprovado — subdomínio não entra), score (decimal; negativo é cara de legítima; réguas comuns: 6 é provável spam, 15 é spam), action (o que o rspamd sugere — nós nunca executamos) e symbols (as regras que pesaram, da mais pesada para a mais leve; no detalhe e no webhook, fora da lista paginada). null é «nenhuma caixa desta mensagem pediu o filtro», nunca «limpa». A nota é da cópia que pediu: numa mensagem para duas caixas, recipients[].spamFiltered diz qual tinha o filtro, e o webhook da caixa que não pediu vem com spamFilter: null. O filtro só anota: nada é recusado, segurado ou descartado por ele. Para agir sobre a nota, use uma política da recepção com spam_filter.score — por exemplo, «pelo menos 6 → tag», ou «pelo menos 15 → hold».
• 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. Um sinal não acusa instrução: texto_ilegivel, trecho que não se normaliza com segurança — longo demais sem nenhum caractere ASCII (um parágrafo muito longo em chinês ou japonês corrido, por exemplo) ou com marcas combinantes demais — e é lido em pedaços; sozinho, leva no máximo a suspicious. 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 (e o domínio dele, sender.domain, em que ends_with é «o domínio ou um subdomínio dele»), destinatário, assunto, a nota do filtro de spam da caixa (spam_filter.score, decimal — vazia na cópia cuja caixa não ligou o filtro, e campo vazio nunca casa), hora e dia da semana no fuso da conta. Operadores equals, contains, starts_with, ends_with, matches (glob com *), regex (só no assunto: uma expressão regular rodada num motor nosso de tempo linear — sem retrocesso, então nenhum padrão trava a recepção; até 200 caracteres; referência a grupo como \1, olhar à frente/atrás e (?…) são recusados com regex_unsupported; no máximo 10 por conta, regex_limit), 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 — e esse rascunho não consulta o DNS dos destinatários no envio (o domínio escolhido pelo agente não pode levar dado na própria consulta): o domínio é conferido na aprovação, e o que não recebe e-mail responde 422 invalid_recipient_domain com recipient; o rascunho é encerrado como rejeitado por system:recipient-domain, nada sai e a cota volta.

  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; até 190 caracteres ASCII imprimíveis sem espaço, ou um número inteiro) devolve o mesmo id em vez de responder duas vezes, por 24 h a partir de quando a resposta entrou na fila; com o primeiro pedido ainda em andamento, a repetição ouve 409 idempotency_in_progress com Retry-After. 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), e as políticas de envio nas duas ações que decidem se o correio sai: recusar responde 422 policy_refused, e reter_para_aprovacao transforma a resposta num rascunho que uma pessoa aprova (status: held) — é assim que a chave marcada «exigir aprovação humana» segura toda resposta de um agente. 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[].

  Se a chave estiver em sandbox, a resposta é aceita e congelada sem entrega, com status: "sandbox". Isso prevalece sobre hold e políticas de aprovação, sem criar link para aprovar. Nesta rota, o sandbox vem do perfil da chave; campo ou header no pedido não o define. Se o perfil não puder ser verificado, a API devolve 503 profile_unavailable e não envia a resposta; tente novamente com a mesma idempotencyKey.

  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 a caixa e o filtro de spam dela (spamFilter) 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…" } }

• A caixa instantânea: um endereço pronto, sem DNS. Toda conta pode receber no domínio da casa, com o código curto da conta — a conta 80001 recebe em 80001.oveyon.app. POST /v1/inbound/instant (escopo write:inbound) sem corpo liga a caixa — o domínio e o pega-tudo *@80001.oveyon.app — e devolve o pega-tudo (201 na primeira vez, 200 depois); com localPart, cria a caixa nomeada de um agente, bot@80001.oveyon.app, com o fio, os canais e as políticas dela: a mesma forma, os mesmos tetos e o mesmo webhook na chamada do POST /v1/inbound/routes. GET /v1/inbound/instant (escopo read:inbound) diz o endereço, as caixas e o estado, sem ligar nada. Criadas, elas são caixas como as outras — PATCH e DELETE /v1/inbound/routes/{id}, o mesmo veredito, a mesma quarentena; desligue o pega-tudo e os endereços sem caixa nomeada voltam a ser recusados na porta (550). Receber vale em todo plano; enviar a partir dela, inclusive responder, só no plano pago: no gratuito, /v1/send e /v1/inbound/{id}/reply respondem 422 managed_domain_requires_paid_plan (no SMTP, 550 5.7.1). Encaminhar dela segue a regra de toda caixa: só para destino verificado. Cada conta recebe até limits.perHour mensagens por hora ali — acima disso o MX responde 450 4.2.1 e o remetente retenta na hora seguinte —, e no plano gratuito o recebido fica o prazo do plano (limits.retentionDays). Enquanto a caixa instantânea não estiver ligada na plataforma, as duas rotas respondem 404 not_found, como uma rota que não existe. Religar a caixa depois de desligar a recepção dela (o interruptor da página do domínio) espera como esse interruptor: no máximo um ligar a cada 5 s por domínio e 20 por minuto por conta — antes disso, 429 rate_limited com Retry-After (em segundos, também em retryAfter), e nada muda: a recepção segue desligada. Desligar nunca espera.

  POST /v1/inbound/instant
  { "localPart": "bot", "channels": [ { "type": "webhook", "url": "https://app.acme.com/hooks/bot" } ] }
  
  201 { "id": 512, "address": "bot@80001.oveyon.app", "domain": "80001.oveyon.app", "matchType": "exact", "active": true, "createdBy": "api:ovy_a1b2",
        "webhook": { "url": "https://app.acme.com/hooks/bot", "mode": "full", "secret": "…64 hex, mostrado uma vez…" } }
  
  GET /v1/inbound/instant
  200 { "domain": "80001.oveyon.app", "available": true, "active": true,
        "catchAll": { "id": 511, "address": "*@80001.oveyon.app", "active": true },
        "mailboxes": [ { "id": 512, "address": "bot@80001.oveyon.app", "active": true } ],
        "sending": { "allowed": false, "reason": "managed_domain_requires_paid_plan" },
        "limits": { "perHour": 200, "thisHour": 3, "retentionDays": 3 } }

• 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 filtro de spam da CAIXA (opt-in): null = nenhuma caixa pediu.
      "spamFilter": { "status": "scanned", "score": -0.4, "action": "no action", "reason": null },
      // 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). `contentType` é o rótulo do remetente, cru;
  // `detectedType` é o tipo lido dos primeiros bytes do arquivo (null =
  // sem assinatura reconhecida), e `typeMismatch` diz quando os dois
  // discordam — como no 2º item: um .doc rotulado como imagem.
  "attachments": [
    { "ord": 1, "filename": "orcamento.pdf", "contentType": "application/pdf",
      "detectedType": "application/pdf", "typeMismatch": false,
      "sizeBytes": 14233, "sha256": "9f2c…",
      "url": "/v1/inbound/b71e0c34-…/attachments/1" },
    { "ord": 2, "filename": "contrato.doc", "contentType": "image/png",
      "detectedType": "application/x-ole-storage", "typeMismatch": true,
      "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 geral por chave, estas rotas têm um teto por chave próprio (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,
    // O filtro de spam da caixa DESTA cópia (null se ela não pediu).
    "spamFilter": { "status": "scanned", "score": -0.4, "action": "no action", "reason": null,
                    "symbols": [{ "name": "R_DKIM_ALLOW", "score": -0.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`. `detectedType` é o tipo pelos primeiros bytes (null = sem
  // assinatura reconhecida); `typeMismatch` avisa quando o rótulo
  // (`contentType`) e o conteúdo discordam — não descarte pelo rótulo.
  "attachments": [
    { "ord": 1, "filename": "orcamento.pdf", "contentType": "application/pdf",
      "detectedType": "application/pdf", "typeMismatch": false,
      "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",
    "detectedType": "application/pdf", "typeMismatch": false,
    "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.

Dois tipos por anexo. contentType é o rótulo do remetente, cru; detectedType é o tipo lido dos primeiros bytes do arquivo (PDF, Office antigo e novo, imagens, compactados, áudio e vídeo, executáveis — null quando não há assinatura reconhecida, como em texto puro). typeMismatch vem true quando os dois existem e são de famílias diferentes — imagem, áudio e vídeo, PDF, PostScript, documento de escritório (Office antigo e novo, OpenDocument, RTF), compactado, executável, texto. Sinônimos do mesmo tipo (image/jpg, o application/x-zip-compressed do Outlook) e o mesmo contêiner (application/zip para um .docx) não contam; rótulo genérico (application/octet-stream) nunca discorda. Um rótulo fora dessas famílias só discorda quando o conteúdo é executável — o executável discorda de todo rótulo que não o declare. Não descarte um anexo pelo rótulo; prefira detectedType quando existir — um .doc já chegou rotulado image/png pelo programa de e-mail de quem mandou, e um filtro «só imagens» o jogaria fora.

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": "lotada@exemplo.com", "reason": "mailbox_full", "source": "dsn",
      "domainId": null, "expiresAt": "2026-07-21T10:02:00.000Z", "createdAt": "2026-07-20T10:02:00.000Z" },
    { "email": "invalido@exemplo.com", "reason": "hard_bounce", "source": "bounce",
      "domainId": null, "expiresAt": null, "createdAt": "2026-07-20T09:11:00.000Z" }
  ],
  "total": 2, "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ê. Ela não devolve erro: o 202 do POST /v1/send mantém status: "accepted" e traz frozen: { reason: "policy", policyId }; o histórico fica no 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. A exceção é a trava de aprovação humana de uma chave (a reter_para_aprovacao com a condição única «credencial é a chave N»): ela vale em qualquer posição. Para o envio dessa chave, seguir_fluxo, forcar_transacional, exigir_footer e limitar_hora não decidem: nada dessa chave sai sem uma pessoa. recusar continua barrando em qualquer posição, e reter acima da trava congela a mensagem (só o suporte solta). Na resposta (POST /v1/inbound/{id}/reply), que não aplica reter, a chave travada sempre gera um rascunho para aprovação, a não ser que recusar decida.

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 geral da chave: 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), e diz por onde ela casou em matchedBy: recipient (ela tem condição de destinatário) ou message (só olha a mensagem e recusa qualquer destinatário). Com condição de hora, vem também retryAfter (ISO 8601): o fim da faixa. Vale para o /v1/send e para a resposta da recepção (POST /v1/inbound/{id}/reply). 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 geral da chave: 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)", "optional": true },
    { "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" },
  "spfProblem": null
}

Marketing (experimental)

Contatos, propriedades, tags, listas de newsletter, campanhas e sequências. Experimental: o módulo é ligado conta a conta, e sem ele toda rota desta seção responde 403 module_disabled. Escopos read:contacts (ler) e write:contacts (gravar — e, na lista com confirmação dupla, inscrever manda à pessoa o e-mail de confirmação, que conta na cota de envio da conta).

O modelo

• Um contato por e-mail na conta: o endereço é normalizado antes de comparar (em minúsculas; das pontas sai só o branco ASCII — espaço, TAB, LF, VT, FF, CR), e a mesma pessoa em três listas é um contato só, com uma inscrição por lista. Espaço Unicode na ponta (NBSP, U+3000…) não é aparado: o endereço é recusado com 400 invalid_email. O endereço é só ASCII (veja Endereços só em ASCII): o domínio internacionalizado (IDN) entra só em punycode — ana@xn--exmple-cua.com; ana@exämple.com é recusado com 400 invalid_email e reason: "address_not_ascii". O mesmo vale para achar, etiquetar, descadastrar e apagar um contato: ele só existe na forma ASCII, e só ela é procurada.
• A lista é de uma marca (o domínio de envio dela) e tem o próprio remetente. Cada inscrição tem estado próprio: pending, subscribed (já confirmada) ou unsubscribed.
• Sair da lista não é supressão. Quem se descadastra da newsletter continua recebendo o e-mail transacional da sua conta.
• Quem saiu pela própria mão só volta pela própria mão. Saiu pelo link de descadastro ou pela central de preferências, marcou um e-mail como spam ou teve o endereço devolvido: a API não reinscreve — 409 unsubscribed_by_contact, 409 complained ou 409 bounced.
• Propriedades (attributes): nomes no formato ^[a-z][a-zA-Z0-9_]{0,63}$, nunca email, firstName ou lastName; o tipo fica registrado pelo primeiro valor (ou por POST /v1/contacts/properties). Tetos: 100 nomes por conta (422 too_many_properties), 8 KB por contato (422 attributes_too_large) e 1 KB por valor (400 invalid_property_value).
• Apagar tira o contato de toda lista na hora; 30 dias depois os dados dele são apagados de vez (purgeAfter). Fica só um hash do endereço, para uma reimportação não devolver à lista quem tinha saído. Recriar o mesmo e-mail depois começa do zero (201): nada do contato anterior volta — nome, propriedades, tags e inscrições —, e os descadastros que a pessoa fez continuam valendo.
• Corpo fechado: campo desconhecido é 400 bad_request com field (o nome só volta quando parece nome de campo: sem espaço e sem arroba). Contato, lista ou tag de outra conta respondem igual ao inexistente (404).
• Escritas ao mesmo tempo: se escritas simultâneas — de qualquer origem, não só desta conta — seguram o contato (ou a mesma tag nova) por alguns segundos, a escrita desiste em vez de esperar mais — 503 contact_busy com Retry-After (5 s, também em retryAfter). Repetir é seguro.
• O registro de chamadas destas rotas guarda os nomes dos campos, os ids e o erro; os valores (e-mail, nome, propriedades, IP de consentimento) aparecem só como { "omitted": "personal" }.

curl -X POST https://api.oveyon.com/v1/contacts \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ana@example.com", "firstName": "Ana",
        "attributes": { "plan": "pro", "points": 120 } }'

HTTP/1.1 201 Created
{
  "contact": {
    "id": 1001, "email": "ana@example.com", "firstName": "Ana", "lastName": null,
    "attributes": { "plan": "pro", "points": 120 },
    "source": "api", "externalId": null,
    "createdAt": "2026-10-17T12:00:00.000Z", "updatedAt": "2026-10-17T12:00:00.000Z"
  },
  "created": true
}

curl -X POST https://api.oveyon.com/v1/lists/7/subscribe \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ana@example.com",
        "consent": { "ip": "203.0.113.9", "source": "https://example.com/newsletter" } }'

{ "contactId": 1001, "listId": 7, "status": "pending", "changed": true, "contactCreated": false }

Campanhas

Uma campanha é uma edição para uma lista: a marca, o remetente, o rodapé e a língua vêm da lista. O rodapé de toda mensagem de campanha leva o endereço postal da lista (a lei americana de e-mail comercial o exige), o link de descadastro e a central de preferências; sem o endereço nada sai — o check acusa list_missing_postal_address, e a campanha que já está saindo espera com o mesmo motivo em pauseReason e continua sozinha quando ele volta. A plataforma compõe a mensagem final: o rodapé entra como o último elemento do corpo, com estilo inline próprio, e o resultado é lido de novo e conferido; o HTML do layout ou do template que não o deixa entrar (um frameset, ou um aninhamento muito além do que um e-mail usa) aparece no check como footer_not_guaranteed e nada sai. O e-mail composto, com os links rastreados, tem teto de 100 KB medidos como ele sai — a parte HTML codificada em quoted-printable ou base64, que é mais longa que o HTML (acentos e emojis pesam até cerca de 2,4 vezes os seus bytes): o Gmail corta a mensagem por volta de 102 KB, e o que some é o fim — o rodapé. Acima dele o check traz o mesmo footer_not_guaranteed com o motivo em problemReasons ({"footer_not_guaranteed": "html_too_large"}; o not_ready leva o mesmo campo), e nada sai — reduza o HTML. O CSS do layout ou do template que esconderia o rodapé também não passa: no <html> e no <body> só entram cor, fundo, fonte, texto, margem, borda e largura; em qualquer elemento, nada de position: absolute, fixed ou sticky, deslocamento, z-index positivo, margem negativa, transform ou outline largo; e a folha de fora (@import, <link rel="stylesheet">) não dá para conferir. O check traz footer_not_guaranteed com o motivo em problemReasons — css_on_html_body, css_positioning, css_negative_margin, css_transform, css_outline, css_external_stylesheet, css_unsupported_rule, css_outlook_hide — e a tela diz o que tirar. Escopos read:campaigns (ler, conferir e o relatório), write:campaigns (criar, editar, ensaiar, a prévia e pausar) e send:campaigns (aprovar, agendar, retomar, cancelar e apagar). Com a trava de aprovação humana ligada na chave, write:campaigns e send:campaigns não valem: a campanha sai para a lista inteira sem rascunho.

• Os estados: draft → approved (aprovar nunca envia) → scheduled (agendar é o gesto que dispara) → running → done; running ⇄ paused; qualquer um → cancelled. Editar uma campanha aprovada ou agendada a devolve a draft (returnedToDraft): a aprovação vale para o que foi conferido.
• A aprovação congela o que a campanha herda: a versão do template (ou do layout da lista) que foi conferida é a que sai, mesmo que uma mais nova seja publicada depois — também no envio que se espalha por dias. E o remetente, o «responder para», o endereço postal, a língua e o layout da lista ficam gravados: se a lista mudar algum deles depois da aprovação, agendar (ou a agendada, na hora de sair) devolve a campanha a draft e o dono é avisado — 409 changed com returnedToDraft: true.
• Conferir antes: o check devolve problems (vazio = ready), a audiência e a prontidão da marca (readiness), item a item, com quem resolve cada um: account (você), staff (a nossa equipe de suporte) ou automatic. Aprovar ou agendar com problema → 422 not_ready com os mesmos problems. A audiência é conferida dentro do teto de 30 contagens por conta por minuto e de um tempo máximo: sem resposta, o problema é audience_check_inconclusive (com audienceError rate_limited, filter_too_slow ou busy, quando há conferências de audiência demais da conta ao mesmo tempo) — nunca «vazia», nunca «pronta»: confira de novo em um minuto. Na daily_capacity, capacity e limitedBy contam só o limite diário da marca e os tetos da própria conta (aquecimento do domínio, cotas, ritmo), e o estimatedDays sai só deles: a folga da capacidade de envio de marketing compartilhada da plataforma não é divulgada (a campanha que espera por ela pausa com ip_capacity e continua sozinha).
• O custo do conteúdo: converter e compilar uma campanha que mudou — e criar ou editar uma — gasta uma unidade por 256 KB de conteúdo, até 60 por conta por minuto; acima, 429 rate_limited com Retry-After. A campanha que não mudou é conferida de um cache e não gasta.
• A marca aquece em dias: nas primeiras semanas a edição se espalha por dias, dos inscritos mais recentes para os mais antigos (estimatedDays). Uma pausa pelos limiares de devolução ou de reclamação segura a marca inteira, e só o suporte retoma: 409 paused_for_review. Os mesmos limiares valem para a soma das campanhas da marca nas últimas 24 horas: a marca é segurada mesmo que nenhuma campanha sozinha passe deles (dividir a audiência em campanhas pequenas não escapa). A edição também respeita a capacidade de envio de marketing de hoje: quando ela acaba, a campanha espera com pauseReason ip_capacity e continua sozinha quando houver vaga.
• O filtro de audiência é TEXTO: audienceFilter é o JSON do filtro dentro de uma string, até 64 KB — o tamanho é conferido antes da leitura (400 filter_too_large). O corpo inteiro tem teto de 320 KB (413 payload_too_large).
• A prévia só vai para o e-mail verificado de um usuário ativo da conta (400 preview_recipient_not_allowed; com reason: address_not_ascii quando o endereço tem caractere fora do ASCII), até 20 por dia e 60 tentativas por dia — as recusadas e as que não saem contam também (429 preview_limit).
• O envio semanal: uma campanha kind model é o modelo de um envio recorrente — não envia, não é aprovada nem agendada. Com a recurrence (weekday de 1 a 7, segunda = 1; time HH:MM; leadDays de 1 a 6), no fuso timezone do modelo, o activate liga a recorrência (running): a cada semana nasce em draft a edição (kind edition, com parentId e editionDate), leadDays antes do horário. Nada sai sem a aprovação daquela edição, e aprovar a edição já a agenda para o horário dela. A que não foi aprovada até o horário vira skipped e o dono é avisado; ela só sai com sendNow, até a próxima edição (409 edition_superseded depois). A edição anterior nunca é reenviada: se ainda estiver saindo quando a seguinte começar, o resto dela é encerrado (errorCode superseded no relatório). pause e resume desligam e religam a recorrência; cancel encerra o modelo e as edições dele em rascunho. Uma variável da AWeber colada ({!firstname_fix}) deixa a campanha não pronta (aweber_merge_tag): troque pela sintaxe {{firstName}} com um padrão.
• O corpo em HTML: a campanha aceita contentHtml no lugar de contentMd. O HTML passa por uma lista branca (p, h1 a h4, strong, em, code, pre, a, img, ul, ol, li, blockquote, hr, br) e entra no layout da lista, com o rodapé de sempre. Um link com class="ovy-botao" sai como botão. Scripts, CSS, tabelas e formulários saem, e a resposta diz o que saiu em contentRemoved. Grava-se o HTML já limpo, que é o que a leitura devolve. Vale uma fonte só: mande null na outra (400 invalid_content).
• O HTML volta normalizado: a leitura devolve o contentHtml da lista branca, não o que foi mandado. b vira strong, i vira em, div vira p, h5 e h6 viram h4; os brancos repetidos viram um, e o branco da ponta de um link, negrito ou itálico vai para fora dele (um negrito dentro de outro vira um só); {, } e ' saem em entidade ({, }, '), como &, < e >. Na tag de variável, o padrão volta com &, < e > em entidade: {{firstName|"Tom & Jerry"}} volta {{firstName|"Tom & Jerry"}}, e o e-mail mostra «Tom & Jerry». Reenviar o valor como veio dá o mesmo resultado.
• Escritas ao mesmo tempo: se escritas simultâneas — de qualquer origem, não só desta conta — seguram a campanha por alguns segundos, a alteração desiste em vez de esperar mais — 503 campaign_busy com Retry-After (5 s, também em retryAfter). Nada mudou; repetir é seguro.
• Campanha de outra conta responde igual à inexistente (404 campaign_not_found). O registro de chamadas destas rotas guarda os ids, os estados e a agenda; o assunto, o conteúdo, o nome, o filtro e o to da prévia aparecem só como { "omitted": "personal" }.

curl -X POST https://api.oveyon.com/v1/campaigns \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listId": 7, "name": "October edition",
        "subject": "Hi {{firstName|\"there\"}}",
        "contentMd": "# News\n\nRead [the post](https://example.com/post).",
        "audienceFilter": "{\"all\":[{\"kind\":\"tag\",\"op\":\"has\",\"tag\":\"vip\"}]}" }'

HTTP/1.1 200 OK
{
  "problems": ["tracking_host_without_tls"],
  "ready": false,
  "audience": 58210, "audienceError": null,
  "schedule": { "dailyLimit": 10000, "sentToday": 0, "warmed": false, "estimatedDays": 4 },
  "readiness": [
    { "name": "tracking_host_tls", "state": "blocking", "owner": "automatic", "effect": "blocking",
      "detail": "certificate_invalid", "numbers": null },
    { "name": "marketing_ips", "state": "ok", "owner": "staff", "effect": "blocking",
      "detail": "has_ips", "numbers": null },
    { "name": "daily_capacity", "state": "ok", "owner": "staff", "effect": "warning",
      "detail": "brand_limit", "numbers": { "capacity": 10000, "limitedBy": "brand", "brandRemaining": 10000 } }
  ]
}

curl -X POST https://api.oveyon.com/v1/campaigns/42/approve \
  -H "Authorization: Bearer $OVEYON_API_KEY"
curl -X POST https://api.oveyon.com/v1/campaigns/42/schedule \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduledAt": "2026-11-03T09:00", "timezone": "America/New_York" }'

HTTP/1.1 200 OK
{
  "campaign": { "id": 42, "name": "October edition", "status": "running" },
  "run": { "id": 9, "status": "pending", "rehearsal": false, "audience": 58210, "cap": null,
           "sent": 10000, "queued": 48210, "inFlight": 0, "skipped": 0, "failed": 0, "rehearsed": 0,
           "pauseReason": "daily_limit", "errorCode": null, "resumeAt": "2026-11-04T05:00:00.000Z",
           "startedAt": "2026-11-03T14:00:00.000Z", "finishedAt": null },
  "outcome": { "delivered": 9810, "bounced": 150, "hardBounced": 41, "routeFailures": 0, "ipBlocks": 0, "complaints": 2,
               "unsubscribes": 23, "opens": 4120, "clicks": 610, "inTransit": 40 },
  "rates": { "delivery": 0.981, "bounce": 0.015, "complaint": 0.0002, "unsubscribe": 0.0023,
             "open": 0.42, "click": 0.0622 },
  "skippedByReason": {}, "tracking": { "opens": true, "clicks": true },
  "rehearsal": null, "rehearsals": 1
}

Sequências

Uma sequência é uma série de e-mails para uma lista: a pessoa entra na lista (ou recebe uma tag) e recebe e-mail → espera → e-mail… até a saída. O remetente, o rodapé (com o endereço postal da lista), a língua e a marca são os da lista, como nas campanhas, e cada e-mail é Markdown dentro do layout da lista. Cada e-mail é reconferido na hora de sair: quem saiu da lista no meio, foi apagado ou está suprimido não recebe o próximo e sai da sequência. Escopos read:sequences (ler e o funil) e write:sequences (criar, editar, ligar, pausar, encerrar e apagar). Com a trava de aprovação humana na chave, write:sequences não funciona: ligar uma sequência é mandar a todo inscrito novo, sem rascunho.

• O grafo: o formato do Loops — rootId, nodeDataById e, em cada nó, typeName, nextNodeIds e payload. A primeira versão é linear: a raiz é o gatilho (ListTrigger: alguém se inscreveu na lista ou confirmou a inscrição; TagTrigger: alguém inscrito na lista recebeu a tag), depois SendEmailAction e TimerAction em qualquer ordem, e ExitAction no fim — sempre depois de um e-mail. Até 50 nós. BranchNode, AudienceFilter e ExperimentBranchNode ainda não existem: 400 unsupported_node. O grafo errado é 400 invalid_graph com o field (o caminho do nó) e o reason. O rootId não muda depois que a sequência é criada: o grafo com outra raiz é 400 invalid_graph com o reason root_changed, e a mensagem diz a raiz gravada.
• As esperas: amount de unit m, h ou d, até um ano; com at (HH:MM, só com dias) a espera termina naquele horário no timezone da sequência — «3 dias às 09:00» é o 3º dia de calendário às 09:00 de lá, também na troca de horário de verão.
• A importação nunca dispara: nem a da AWeber, nem a inscrição com método de importação, nem a tag que a importação aplica. Pausada: quem entra espera. Encerrada: ninguém mais entra. Quem se inscreve com a sequência pausada entra e espera no começo: quando ela for ligada de novo, anda — e as esperas só começam a contar aí. reEligible deixa quem terminou entrar de novo no próximo gatilho — nunca enquanto ainda está dentro.
• Os estados: draft → active (start confere tudo e liga: é o gesto que manda) ⇄ paused; qualquer um → stopped (quem esperava sai). Ligar congela o layout da lista que foi conferido e o remetente: se o remetente ou o «responder para» da lista mudar depois, a sequência pausa (sender_changed) e o dono é avisado. O envio que recusa a conta ou o conteúdo também pausa a sequência (pauseReason).
• Editar exige a revision que você leu (outra → 409 changed com a de agora) e a sequência fora do ar (draft ou paused; no ar, só o name muda). Quem espera num passo que a edição tirou sai da sequência (revision) quando ela voltar a rodar.
• O corpo do e-mail: o payload do SendEmailAction leva contentMd ou contentHtml, nunca os dois, com a mesma lista branca das campanhas, e volta normalizado como o delas. Em HTML, contentRemoved na resposta diz o que saiu. E-mail escrito em Markdown não tem o campo contentHtml.
• Escritas ao mesmo tempo: se escritas simultâneas — de qualquer origem, não só desta conta — seguram a sequência por alguns segundos, a alteração desiste em vez de esperar mais — 503 sequence_busy com Retry-After (5 s, também em retryAfter). Nada mudou; repetir é seguro.
• Até 100 sequências vivas por conta e 50 criadas por dia (UTC): 422 sequence_limit. A sequência de outra conta responde igual à inexistente (404 sequence_not_found). O registro de chamadas destas rotas guarda os ids, os estados e a revisão; o nome e o grafo só aparecem como { "omitted": "personal" }.

curl -X POST https://api.oveyon.com/v1/sequences \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listId": 7, "name": "Welcome", "timezone": "America/New_York",
        "graph": { "rootId": "n1", "nodeDataById": {
          "n1": { "typeName": "ListTrigger", "nextNodeIds": ["n2"], "payload": {} },
          "n2": { "typeName": "SendEmailAction", "nextNodeIds": ["n3"],
                  "payload": { "subject": "Welcome, {{firstName|\"friend\"}}", "contentMd": "Thanks for joining." } },
          "n3": { "typeName": "TimerAction", "nextNodeIds": ["n4"], "payload": { "amount": 3, "unit": "d", "at": "09:00" } },
          "n4": { "typeName": "SendEmailAction", "nextNodeIds": ["n5"],
                  "payload": { "subject": "Three tips", "contentMd": "1. Read the guide." } },
          "n5": { "typeName": "ExitAction", "nextNodeIds": [], "payload": {} } } } }'
curl -X POST https://api.oveyon.com/v1/sequences/12/start \
  -H "Authorization: Bearer $OVEYON_API_KEY"

HTTP/1.1 200 OK
{
  "id": 12, "status": "active", "revision": 3,
  "nodes": [
    { "nodeId": "n1", "typeName": "ListTrigger", "entered": 240, "sent": 0, "exited": 0, "waiting": 0 },
    { "nodeId": "n2", "typeName": "SendEmailAction", "entered": 240, "sent": 238, "exited": 2, "waiting": 0 },
    { "nodeId": "n3", "typeName": "TimerAction", "entered": 238, "sent": 0, "exited": 0, "waiting": 61 },
    { "nodeId": "n4", "typeName": "SendEmailAction", "entered": 177, "sent": 171, "exited": 6, "waiting": 0 },
    { "nodeId": "n5", "typeName": "ExitAction", "entered": 171, "sent": 0, "exited": 0, "waiting": 0 }
  ],
  "totals": { "entered": 240, "finished": 171, "exited": 8, "inProgress": 61 },
  "exitsByReason": { "unsubscribed": 7, "removed": 1 }
}

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.

Endereços só em ASCII

A plataforma só aceita endereço de e-mail sem acento: o local-part e o domínio em ASCII, sem caractere de controle. Um domínio internacionalizado (IDN) entra só na forma punycode — xn--…, e um xn-- válido; escrito em Unicode, ele é recusado. Nada é convertido por você: trocar a letra acentuada pela sem acento mandaria para outra caixa.

• Na API, toda entrada de endereço recusa com 400, reason: "address_not_ascii" e o field do campo. O error é o da família do campo: bad_recipient nos destinatários de POST /v1/send, invalid_email nos contatos e bad_request nos demais (o from, os cabeçalhos de endereço, as supressões, as pesquisas, as listas allow/block de saída e as políticas de envio). A mensagem não repete o endereço. Ramifique no reason.
• Na resposta a uma mensagem recebida (POST /v1/inbound/:uid/reply), a caixa que recebeu ou o remetente original fora do ASCII viram 409 no_mailbox ou 422 no_reply_address, com o mesmo reason.
• Na submissão SMTP, MAIL FROM e RCPT TO fora do ASCII levam 553 5.6.7; o From e os cabeçalhos de endereço do DATA (Reply-To, Sender, To, Cc…) fora do ASCII levam 550 5.6.7 — a mensagem não é assinada nem entra na fila.
• Nas importações da Central de migração, a linha com endereço fora do ASCII é pulada e contada no relatório — a supressão com o motivo próprio, o contato da AWeber entre os endereços inválidos; o resto do lote entra. A exceção é a saída (descadastro, reclamação ou devolução) com a parte antes do @ em ASCII e o domínio internacional escrito com acento: ela entra na forma xn-- do mesmo domínio, para continuar valendo, e o relatório a conta à parte.
• Endereço sem ambiguidade. Nos campos de endereço de POST /v1/send — to, cc, bcc, from e os cabeçalhos de endereço de headers — o endereço tem de estar escrito por inteiro: "a@b.com" ou "Nome <a@b.com>", um por item (lista, ou separados por vírgula). O que um leitor de e-mail leria de dois jeitos é 400: dois endereços separados por espaço, o nome sem <…>, o comentário depois do endereço solto (a@b.com (Nome)), o grupo (Nome: …;) em to/cc/bcc, o item sem endereço numa lista e o @ (ou o ＠ de largura cheia) no nome de exibição. O espaço Unicode colado ao endereço (NBSP, U+3000…) é reason: "address_not_ascii". O error é bad_recipient nos destinatários e bad_request no from e nos cabeçalhos. Nada é reescrito por você: a forma ambígua é recusada inteira.
• O que não muda: o nome de exibição pode ter acento ("Zoë" <zoe@example.com>); a recepção segue aceitando remetente com acento, e a lista allow/block de entrada continua aceitando um padrão com acento para barrá-lo.

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.
• 400 request_too_complex — a estrutura do corpo passou de um teto (com limit): uma lista com mais de 10.000 itens, mais de 60.000 valores no total (itens de lista e campos de objeto), mais de 64 níveis de aninhamento ou um número ou literal com mais de 32 caracteres. Texto não conta — um anexo grande é um valor só. Divida o trabalho em mais de uma chamada.
• 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. A chave é validada antes de o corpo ser lido: sem chave válida a resposta é 401 (ou 403) e o corpo não é lido.
• 415 unsupported_media_type — mande o corpo como application/json (formulário e texto puro não são aceitos).
• 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 chave — com credencial válida, o teto geral é da chave (ou da conexão OAuth do MCP): 600 req/min por padrão, venha a chamada de qualquer IP. Estourou → 429 rate_limited com header Retry-After: 60. Aguarde e repita.
• Por IP — sem credencial válida (sem Authorization, ou chave desconhecida, desligada ou revogada), o teto é do IP: 600 req/min por padrão. As falhas de credencial — só chave ou token desconhecido ou malformado — têm teto próprio de 20/min por IP (em IPv6, por /48): 429 too_many_auth_failures. Não contam como falha a chamada sem Authorization, o token OAuth vencido ou revogado e a chave desligada. Uma chave válida que chega de um IP no teto ainda passa: o IP no teto tem 120 consultas de credencial por minuto, e só acima delas a resposta é 429 too_many_auth_failures, até a virada do minuto, para toda credencial que não tenha sido validada nos últimos 5 minutos (a que foi segue passando). O que não tem a forma de uma chave nossa (ov_ + 48 hexadecimais minúsculos) conta como falha sem ser consultado. 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.

Mudanças na API

O que pode mudar a resposta de uma chamada que já funcionava — a entrada mais nova primeiro.

• 03/11/2026 — o SPF acima de 4096 bytes deixa de ser avaliado. Em POST /v1/domains/:id/verify, um registro da cadeia do SPF (o do domínio, ou o de um include ou redirect) com mais de 4096 bytes não é mais lido: o SPF não conta como verificado, spfProblem.code é record_too_large e o detail.spf diz qual registro encurtar (veja a rota). Antes ele era avaliado inteiro e podia passar.
• 03/11/2026 — this_outside_loop e loop_never_repeats na conferência das campanhas e das sequências. Em POST /v1/campaigns/:id/check, problems ganhou dois códigos. this_outside_loop: o conteúdo usa {{this}} ou {{this.nome}} fora de um {{#each}} — ali não há item: sem padrão, o envio pulava quem chegava a esse trecho; com padrão, todo contato recebia o padrão. Use {{nome}} (o motor não lê {{this.nome}} nem dentro de um laço: lá também é {{nome}}). loop_never_repeats: o conteúdo (ou o template) tem um {{#each}} — os campos do contato nunca são listas, e o envio pulava quem tinha o campo (quem não tinha recebia o trecho vazio): tire o laço. Aprovar ou agendar com qualquer um dos dois dá 422 not_ready, e os mesmos códigos impedem ligar uma sequência (POST /v1/sequences/:id/start).
• 03/11/2026 — teto de verificações de domínio por conta. POST /v1/domains/:id/verify passa a responder 429 rate_limited acima de 60 verificações por minuto na conta, somadas às do painel (veja a rota). Antes, só o limite geral da chave valia. Com o 429 nada é conferido: espere o Retry-After (também em retryAfter) e chame de novo.
• 03/11/2026 — o assunto do e-mail de teste da campanha passa a «[Teste]». Em POST /v1/campaigns/:id/preview, o prefixo do assunto era [Prévia] (lista em português) e [Preview] (em inglês); agora é [Teste] e [Test] (veja a rota). A rota, o corpo, a resposta e os códigos (preview_limit…) não mudam: muda só o texto do assunto. Quem filtra o e-mail de teste pelo prefixo antigo precisa trocar o filtro.
• 02/11/2026 — o SPF da raiz com optional: true em POST /v1/domains. No modo de sempre, o registro SPF do domínio passou a vir com optional: true, como o CNAME de tracking: o e-mail que sai por nós passa no SPF pelo nosso endereço de retorno (veja Cadastrar domínio). Com o Return-Path no próprio remetente (plano pago), ele segue sem optional. O painel mostra o mesmo: «Recomendado» num modo, «Obrigatório» no outro.
• 20/10/2026 — Sequências na API (marketing, experimental). Rotas novas em /v1/sequences e dois escopos novos: read:sequences e write:sequences (veja Sequências). Nenhuma chave existente ganha esses escopos — nem a de escopos antigos. Com a trava de aprovação humana ligada na chave, write:sequences responde 403 scope_blocked_by_approval_lock, como os outros escopos que a anulariam.
• 19/10/2026 — Campanhas na API (marketing, experimental). Rotas novas em /v1/campaigns e três escopos novos: read:campaigns, write:campaigns e send:campaigns (veja Campanhas). Nenhuma chave existente ganha esses escopos — nem a de escopos antigos. Com a trava de aprovação humana ligada na chave, write:campaigns e send:campaigns respondem 403 scope_blocked_by_approval_lock, como os outros escopos que a anulariam.
• 19/10/2026 — o endereço ambíguo de POST /v1/send passa a 400. O que o leitor de endereço reescrevia calado agora é recusado (veja Endereço sem ambiguidade): em to/cc/bcc, no from e nos cabeçalhos de endereço de headers, dois endereços separados por espaço (antes um virava o nome e só o outro recebia), o nome sem <…> e o comentário depois do endereço, o grupo em to/cc/bcc (antes os membros sumiam do envelope), o item sem endereço numa lista (antes descartado), o @ no nome de exibição e o espaço Unicode colado ao endereço (antes o NBSP no meio da parte local mandava para outra caixa). O espaço Unicode nas pontas de to/cc/bcc deixou de ser aparado: é address_not_ascii, como na /v1/suppressions. O valor de um cabeçalho de headers tem de ser texto ou lista de textos: um objeto é 400. Também: as importações gravam a saída com domínio internacional em Unicode na forma xn--, e a submissão SMTP recusa o From e os cabeçalhos de endereço do DATA fora do ASCII com 550 5.6.7. Endereços escritos como "a@b.com" ou "Nome <a@b.com>" não mudam.
• 18/10/2026 — só endereço em ASCII. Toda entrada de endereço passou a recusar caractere fora do ASCII com 400 e reason: "address_not_ascii" (veja Endereços só em ASCII). O que muda para quem já chamava: um destinatário com acento em POST /v1/send, que antes era aceito, agora é 400 bad_recipient; o domínio internacionalizado de um contato (POST /v1/contacts), que antes era convertido para punycode, agora tem de chegar já em xn-- — e achar, etiquetar, descadastrar ou apagar pela grafia Unicode (GET /v1/contacts/find e as outras buscas por e-mail), que antes achava o contato convertido, passa a 400 invalid_email com o mesmo reason; e a submissão SMTP recusa MAIL FROM/RCPT TO com acento com 553 5.6.7. Endereços ASCII não mudam.
• 15/10/2026 — detectedType e typeMismatch no manifesto de anexos. Cada item de attachments — em GET /v1/inbound/:uid e no payload do webhook inbound.received — ganhou detectedType (o tipo lido dos primeiros bytes do arquivo; null = sem assinatura reconhecida) e typeMismatch (true quando o rótulo do remetente e o conteúdo são de famílias diferentes). Quem confere a resposta contra um esquema fechado precisa aceitar os campos novos. Mensagens anteriores a esta data vêm com null e false. Veja Anexos.
• 14/10/2026 — mcpCallId no registro de chamadas. Cada item de GET /v1/logs e GET /v1/logs/:id ganhou o campo mcpCallId (null fora do servidor MCP), e há duas rotas novas: GET /v1/logs/mcp e GET /v1/logs/mcp/:id (Registro do MCP). Quem confere a resposta contra um esquema fechado precisa aceitar o campo novo. Nos corpos guardados, o nome do arquivo dos anexos e o detalhe dos sinais de segurança passam a aparecer só pelo tamanho.
• 13/10/2026 — return_path no POST /v1/send. O campo passou a existir e aceita só "sender" e "platform" (veja Endereço de retorno). Antes ele era ignorado, como todo campo que a rota não conhece; agora qualquer outro valor responde 400 bad_request e nada é enviado — inclusive um endereço de e-mail. Quem vem da SparkPost, onde return_path é o endereço do envelope: tire o campo (o endereço de retorno da plataforma é o padrão) ou, se o endereço era o próprio remetente, use "sender" (de plano pago, com o include no SPF do domínio).