HTTP API

Quick start

From zero to your first send in three steps.

• 1. Create a key in Credentials. It is shown only once (prefix ov_…). Store it in a secrets manager.
• 2. Verify a domain in Domains — without a verified domain, sending is refused with 422 domain_not_verified.
• 3. Send with POST /send:

export OVEYON_API_KEY="ov_yourkeyhere"

curl -X POST https://api.oveyon.com/v1/send \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Sales <sales@yourcompany.com>",
    "to": "customer@example.com",
    "subject": "Welcome",
    "html": "<h1>Hello!</h1><p>Your account is ready.</p>"
  }'

Expected response: 202 with { "id": "<uuid>", "status": "accepted" }. That id is what you use to look up the message later.

Authentication

Every request carries the key in the Authorization header, using the Bearer scheme.

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

• Missing, invalid, revoked or expired key → 401 unauthorized. It is always the same response, on purpose: it does not tell anyone whether the key exists or whose it is.
• A valid key that was turned off in the dashboard → 403 key_disabled, on any route. The switch is under Credentials → API keys; turning it back on restores the key with the same secret. Do not rotate because of this error — nothing is wrong with the key, it is just turned off; use another key or turn this one back on.
• A valid key of a blocked account → 403 account_suspended, and it applies on any route, not just sending. It is not a credential problem: rotating the key or creating another one changes nothing — contact support. Without a valid key for the account, the response is the 401 above; that is why this 403 never reveals to anyone that the account exists.
• Each key has a name/tag (so you can tell integrations apart) and a set of permissions (scopes). Manage both in Credentials.
• Each key (and each SMTP credential) sends from every domain of the account or only from the selected ones — the choice lives in Credentials, in the credential panel, and applies immediately. A from outside the set → 422 domain_not_allowed_for_credential (over SMTP, 550 5.7.1): the domain is fine, it is this credential that does not use it. Rotating inherits the choice.
• Revoking is immediate — a revoked key stops authenticating on the very next call. Rotating is not. Rotation issues the new key and leaves the previous one still valid for a grace window (default 72 h; the dashboard tells you the exact deadline at the moment you rotate), so your application can swap the secret without going down. This is deliberate: without the grace period, «rotate» would just mean «interrupt», and the practical result would be that nobody ever rotates. The consequence is the one that matters — if the key leaked, rotating does not close the hole: revoke it. Rotate while the secret is still yours alone; revoke once it no longer is.
• Never expose the key in front-end code or in a repository.

Permissions (scopes)

A key only reaches what its scopes grant. Scope missing for the route you called → 403 insufficient_scope (the response says which scope was missing). With the human-approval lock on the key, the scopes that would undo it (approve:holds, write:send-policies, manage:webhooks, write:inbound, write:templates, write:surveys, write:domains, write:contacts, write:campaigns, send:campaigns, write:sequences) answer 403 scope_blocked_by_approval_lock, even when the key holds them:

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

Left out of the table, on purpose: /disposable · /openapi.json · /ping requires no authentication — no key, no scope, no quota. Do not look for a checkbox for it in Credentials: there is nothing to grant. It is the only API route like this.

Dashboard roles are not key permissions

This is the confusion that shows up as soon as an account has more than one person on it, and it always errs in the same direction — assuming the key is weaker than it is. So, to spell it out: the dashboard and the key are two permission systems that do not touch each other. Neither one consults the other.

What follows from this — and what you should carry into your code:

• A role does not weaken a key. There is no such thing as a «viewer key». A key with send in the hands of someone who is a viewer on the account keeps sending email: the key does not know who is holding it, and never asked.
• A role does not strengthen a key. Being owner adds no scope at all to the key you created. A missing scope is 403 insufficient_scope — even for the account owner, even with their own key. That 403 never means «your role is too low»; it means «this key does not have this scope», and the response names which one.
• Removing someone's access to the dashboard does not revoke any key. This is the consequence that bites, so here it is without euphemism: a credential does not record who created it, and so nothing cascades when someone's access is removed. Whoever left still has the secret, and the secret still works on behalf of the account. When you remove a person, revoke the keys that were in their hands — in Credentials, and revoke, do not rotate: rotation keeps the previous key alive through the grace period.
• No /v1 call sees two accounts. There is no parameter that asks for it, no header, no «organization» mode — and a suspended account does not drag its neighbor down: 403 account_suspended is about that key's account, and nothing else. If you operate several accounts, that means several keys, one per account.

Role decides one thing in all of this, and it is on the dashboard side: who gets to press the button. Minting a new secret — creating an API key, creating an SMTP credential, and rotating either one — is reserved for the account owner. Killing and adjusting are open to admin: revoking, disabling, and also editing the name, scopes and limit of a key that already exists — because an access control that forbids reducing exposure is worse than having it turned off. And owner is the ownership of the account itself, not a role that can be granted: if you are admin and the button to create a key is not there, the screen is not broken. None of this changes what the key does once it is issued — which is the subject of the rest of this page.

Send email

Sending goes through the same pipeline as SMTP: idempotency, backpressure, sender and recipient domain, suppression, quota and warm-up ramp — in that order. The 202 only comes back once the message is already in the spool.

422 { "error": "return_path_not_authorized",
      "message": "return_path=sender requires the SPF of example.com to have include:_spf.… — publish it and send again, or send with return_path \"platform\"",
      "reason": "spf_include_missing", "domain": "example.com", "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: order-8842" \
  -d '{
    "from": "Support <support@yourcompany.com>",
    "to": "customer@example.com",
    "cc": ["billing@example.com"],
    "bcc": ["archive@yourcompany.com"],
    "subject": "Your receipt",
    "html": "<p>Thanks for your purchase.</p>",
    "text": "Thanks for your purchase.",
    "headers": { "X-Campaign": "receipts" },
    "attachments": [
      { "filename": "receipt.pdf", "content": "JVBERi0xLjQK...", "contentType": "application/pdf" }
    ]
  }'

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

// `recipients` only appears when there is more than one recipient, and it is the number
// of DISTINCT addresses that went into the envelope — the same number you were charged for.

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@yourcompany.com", "to": "customer@example.com",
        "subject": "Test", "text": "Nothing will be delivered." }'

Templates

An email template with variables, stored once and sent with just the data: {"templateId": …, "data": {…}} in POST /v1/send, instead of 40KB of HTML repeated on every call. The look changes in one place, with no redeploy of your system.

The lifecycle: draft → published (immutable)

• Creating and editing always produce a draft — nothing changes in sending until you publish.
• A published version is immutable: editing creates vN+1 as a draft; vN stays exactly as it was. A template in production never changes out from under you.
• Publishing makes the version the current one for sending. To go back, publish an earlier version again ({"version": N}) — the pointer moves both ways; the versions themselves never change.
• A send can pin version; a draft is never served, not even by pinning its version.

Syntax — the catalog is closed, and it is a contract

• Nothing beyond this exists — helpers, partials, comments and the like are refused on save (400 template_parse_error, naming the tag). The catalog grows by our decision, never by silent acceptance.
• Strict by default: a variable that is referenced but missing from data refuses the send with 400 template_var_missing — never a visible {{gap}} in the inbox. The opt-out is per variable, with | "default".
• Data never becomes a template: a value containing {{othervar}} comes out as literal text — substitution is single-pass, and nothing is re-interpreted.
• Caps: 256KB per field on save; on expansion, 1MB of output and 10,000 {{#each}} iterations in total — go over and the send is refused with a named error.
• A message sent from a template carries templateId/templateVersion in GET /v1/messages and in the message detail — the trail of which template/version produced what.

curl -X POST https://api.oveyon.com/v1/templates \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orderArrived",
    "subject": "{{customerName}}, your order has arrived",
    "html": "<p>Hello {{customerName}}, use coupon {{ coupon | \"SAVE10\" }}.</p>",
    "text": "Hello {{customerName}}, use coupon {{ coupon | \"SAVE10\" }}."
  }'

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

End-to-end example

Create → publish → send with just the data. The body on the wire goes out with the variables substituted and the whole pipeline on top (footer, tracking, DKIM — a template skips no safeguard).

curl -X POST https://api.oveyon.com/v1/templates \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orderArrived",
    "subject": "{{customerName}}, your order has arrived",
    "html": "<p>Hello {{customerName}}, use coupon {{ coupon | \"SAVE10\" }}.</p>",
    "text": "Hello {{customerName}}, use coupon {{ coupon | \"SAVE10\" }}."
  }'

curl -X POST https://api.oveyon.com/v1/templates/orderArrived/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": "Store <sales@yourcompany.com>",
    "to": "customer@example.com",
    "templateId": "orderArrived",
    "data": { "customerName": "Ana" }
  }'

Errors

• 400 template_invalid (includes field) · template_parse_error (includes tag) · template_source_too_large — save-time refusals. · bad_request — on publish, a version that is not an integer ≥ 1.
• 400 template_var_missing (includes variable) — at send time, incomplete data for the template.
• 404 template_not_found — does not exist, belongs to another account, has no published version, or the requested version is not published. On POST /v1/send the same condition comes back as 422.
• 409 template_name_taken · template_no_draft.
• 422 template_var_invalid · template_each_not_list (include variable) · template_output_too_large · template_too_many_iterations (include limit) — render refusals at send time. Always branch on error. · template_too_much_work (the render exceeded 500,000 visited nodes — loops times body size)

Query

Listing, aggregate statistics and the timeline of a single message. Every read is confined to the key's tenant — you never see another account's data.

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": "sales@yourcompany.com",
      "to": "customer@example.com",
      "subject": "Welcome",
      "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": "company.com",   "label": "company.com",   "count": 519,  "pct": 12.3 },
        { "value": "Outros",        "label": "Others",        "count": 275,  "pct": 6.5 }
      ]
    },
    "reason": {
      "total": 63,
      "items": [
        { "value": "invalid_recipient", "label": "Address or domain does not exist", "count": 41, "pct": 65.1 },
        { "value": "spam_content",      "label": "Spam or content filter",           "count": 14, "pct": 22.2 },
        { "value": "mailbox_full",      "label": "Recipient mailbox full",           "count": 8,  "pct": 12.7 }
      ]
    },
    "credential": {
      "total": 4210,
      "items": [
        { "value": "s:12", "label": "support@company.com",  "count": 2180, "pct": 51.8 },
        { "value": "k:3",  "label": "production",           "count": 1602, "pct": 38.1 },
        { "value": "s:9",  "label": "invoices@company.com", "count": 375,  "pct": 8.9 },
        { "value": "-",    "label": "Unidentified source",  "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": "sales@yourcompany.com",
  "to": "customer@example.com",
  "subject": "Welcome",
  "sizeBytes": 4821,
  "acceptedAt": "2026-07-21T13:02:11.000Z",
  "deliveredAt": "2026-07-21T13:02:14.000Z",

  // ONE DELIVERY PER RECIPIENT. `status` and `to` above are the summary and the
  // first address; the outcome for each recipient is here. The summary is
  // pessimistic: if any recipient did not receive it, the message is not "delivered".
  "deliveries": [
    { "id": "d_8f2a…", "to": "customer@example.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": "copy@example.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` say WHICH delivery the event belongs to; null = a
  // message-level event (acceptance, for example), which belongs to no recipient.
  "events": [
    { "event": "accepted",  "deliveryId": null,      "to": null,                   "detail": { "source": "api" }, "at": "2026-07-21T13:02:11.000Z" },
    { "event": "delivered", "deliveryId": "d_8f2a…", "to": "customer@example.com", "detail": {},                  "at": "2026-07-21T13:02:14.000Z" },
    { "event": "bounced",   "deliveryId": "d_1c07…", "to": "copy@example.com",     "detail": { "smtpResponse": "550 5.1.1 User unknown" }, "at": "2026-07-21T13:02:13.000Z" }
  ],
  "tracking": [
    { "type": "open",  "url": null, "host": "email.yourcompany.com", "readMsEstimate": 3200, "at": "..." },
    { "type": "click", "url": "https://shop.yourcompany.com/x", "host": "email.yourcompany.com", "readMsEstimate": null, "at": "..." }
  ]
}

API logs

Every authenticated call your account's keys make to the API is logged for 180 days: the route, the status, the duration, the IP, the user-agent and the request and response bodies. It is the data behind the API logs screen of the dashboard, which also explains each error and prepares the text to paste into an AI.

• Bodies are redacted before they are stored. Headers are not stored — not even Authorization. A field with a secret's name (password, secret, token…) and a value shaped like a key (ov_…, Bearer …) become «redigido»; message bodies and attachments — the file name included — (html, text, content, filename…) become their size, as does the detail of the safety signals (signals[].detail, which can quote text hidden in the email); each template variable (data) keeps its name and loses its value; and a URL whose path can carry a secret becomes just its host and length — the tracked link of a sent message (tracking[].url) and the destination URL you register (channels[].url, and every url on the webhook and mailbox routes): on Zapier, Make and the like the path is the secret itself. For the inbound content routes and the two log routes the response is not stored: only its size. On the marketing routes, the request and the query keep only the field names and the ids — the values become { "omitted": "personal" } — and the success response is not stored.
• 32 KB cap per body. Above that the text is cut, truncated is true and what is left may no longer be valid JSON.
• What stays out: a call refused before the key is identified (invalid key, per-IP limits) — there is no account to attribute it to —, and the 429 of the general per-key limit. A refusal of a good key is logged: switched off (key_disabled), account suspended (account_suspended), IP outside the binding (ip_not_allowed).
• Writing is asynchronous: a call shows up here a few seconds after it answers.

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
  }
}

MCP log

What AI agents did through the MCP server, one entry per JSON-RPC message: the tool the agent called, through which app (ChatGPT, Claude…), from where, how it ended and which API calls it made. The same retention, 180 days, and the same scope, read:logs. In the dashboard it is the MCP tab of API logs.

• This log does not keep tool results — the email read, the list of messages: only their size (resultBytes). The call a tool makes to the API is in the API logs, redacted like any other (and the response of the content routes, such as GET /v1/inbound/:uid/content, not even there).
• Arguments are stored redacted: only the fields of the tool schema (any other field becomes { "omitted": "unknown_field" }), under the same rules as the bodies above; 8 KB cap — arguments that do not fit the cap as valid JSON become { "omitted": "too_large", "bytes": N }, with the size in bytes of the arguments as received, and argumentsTruncated is true.
• The link with the API logs: each API call a tool made carries the message's callId in mcpCallId — the dashboard and the API link one to the other, both ways.
• What stays out: a request whose credential could not be identified, as in the API logs (a known key that is refused — switched off, for example — is logged).

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

MCP server (for AI agents)

The same API as tools an AI agent (Claude Code, Cursor, VS Code, Codex, Windsurf…) calls by name, through the Model Context Protocol. One endpoint, Streamable HTTP, no state: POST https://mcp.oveyon.com/v1 (the address https://api.oveyon.com/v1/mcp answers too, for good). The MCP screen of the dashboard prints the configuration of each client.

• Authentication is the API key, as a Bearer: Authorization: Bearer ov_…. The same gate as every route: 401 without a key, 403 for key_disabled, account_suspended and ip_not_allowed, 429 with Retry-After.
• One tool per route. The server lists only the tools the scopes of the key allow (plus whoami and check_disposable): send_email is POST /v1/send with the scope send, list_inbound is GET /v1/inbound with read:inbound, and so on — the input schema of each tool is the one in this document.
• Every tool call is a call to the API, with the same key: scopes, quotas, policies, idempotency and the API logs apply unchanged; in the log they show up as the family oveyon-mcp (sdk), with mcpCallId. The agent's message — the tool, the app, the redacted arguments — is in the MCP log.
• The error reaches the model whole: error, message and Retry-After in the tool result (isError) — which is what makes an agent stop on a 403 and wait on a 429.
• Without a key, by OAuth 2.1: a client that connects by signing in (the custom connector of claude.ai, Claude Desktop and mobile; ChatGPT) gets only the address. The 401 points to the resource metadata (resource_metadata, RFC 9728), which points to the issuer (/.well-known/oauth-authorization-server on the dashboard host); authorization code with PKCE S256, dynamic registration or a metadata document (client_id = URL). The person signs in, picks the permissions and allows; the connection becomes a credential of the account (Credentials), and the token is valid only here on the MCP server. The limits are those of a key: each connection has its own (600 req/min), whatever IP the platform calls from, and the discovery without a token and an expired token do not count as authentication failures. On /oauth/token, only an unknown code or refresh token counts, per origin (30/min); above that the answer is 429 too_many_requests with Retry-After, and a valid refresh still gets through with the origin over the limit, within 120 checks per minute.
• Nothing is kept between calls: no session (GET and DELETE answer 405); whoami tells the account, the key and the tools; the resource oveyon://guide is the procedure.

Connect

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

By hand

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":{}}'

Disposable domain

Does an address's domain belong to a disposable/temporary email service (Mailinator, 10minutemail and the like)? Use it at sign-up, before accepting an email address that will never be read twice.

This is the only API route that requires no authentication. No Authorization, no key, no account: the data is a public list and nothing of yours is involved in the response. It doesn't consume quota either. In exchange, the cap is per IP and it's tight — see the end of this section.

# no Authorization: this route is public
curl "https://api.oveyon.com/v1/disposable?email=someone@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": "lookup unavailable: the list has not been loaded on this server yet"
}

// `disposable` comes back null, NEVER false. If our list is not loaded,
// the answer is "we do not know" — saying "not disposable" with nothing to check
// against would be the one mistake this lookup cannot make.

Receive email

You point a domain's MX at us and create the addresses you want to receive mail on. From then on, everything that arrives is stored and you choose how to consume it: pull it through the routes below, or get notified by webhook. The two coexist — the webhook is the notification, storage is the foundation.

Getting started

Five steps, once per domain. From DNS to the first email read.

; In the DNS for yourcompany.com — one MX record, priority 10, pointing
; to our inbound host. The trailing dot is part of the record.
yourcompany.com.    IN    MX    10    mx1.e-mailbox.com.

# Check propagation before requesting verification in the dashboard:
dig +short MX yourcompany.com
# expected:  10 mx1.e-mailbox.com.

# Send an email from a mailbox of your own to support@yourcompany.com, then list:
curl "https://api.oveyon.com/v1/inbound?limit=5" \
  -H "Authorization: Bearer $OVEYON_API_KEY"

The key needs the scope — and old keys don't get it on their own

These routes require read:inbound, which is a scope of its own: the other reads (read:messages) show what you sent; this one shows what you received — bodies and attachments written by third parties. A key issued before this scope existed does not gain it through a deploy on our side: whoever handed that key to an integrator couldn't consent to a power that didn't exist yet. Tick the scope on the key in Credentials (an account admin action), or issue a new one (an owner action — why). Rotating doesn't fix it — rotation inherits the previous key's permissions, verbatim. Without the scope: 403 insufficient_scope.

Five things before you write code

• One email, several recipients. A message that arrived for support@ and sales@ in the same transaction is one message with two items in recipients. We never flatten that into a single field — if your code reads only the first, it will miss the second. (The webhook mirrors this: the same message becomes two events, one per recipient.)
• The copy expires. The expiresAt field comes in every response and says until when we keep the original. After that, the message stays listed (subject, sender, attachment manifest), but expiresAt becomes null and the content routes — /content, /raw, /attachments — start answering 404. If you need the email forever, download it and keep it on your side.
• Every message arrives with a spam score. spamScore (0-100) is our internal heuristic, computed when the message arrives — the higher it is, the more it looks like spam. Two caveats: null means not computed (a message received before the feature existed, or a failure on our side while computing it), which is not the same as 0 — zero means «we looked and it's clean». And the score is a signal, not a verdict: we never refuse or discard anything because of it; if you want to filter, where to draw the line is up to you. In the webhook, the same value goes in the body (message.spamScore) and in the POST's x-spam-score header.
• And each mailbox can switch on a real spam filter. Besides spamScore (our heuristic, on every message), a mailbox can switch on the mailbox spam filter: the rspamd at our receiving edge, which looks at content, link and IP reputation and authentication. It is opt-in per mailbox — off on every mailbox until you switch it on, in the dashboard (Inbound → Mailboxes → the mailbox) or with PATCH /v1/inbound/routes/{id} and { "spamFilter": true }; a mailbox with the filter off is not even scanned. The message then carries spamFilter: status (scanned = there is a score; unavailable = the filter did not answer in time and the message was delivered without a score; skipped = not scanned on purpose, and reason says why: too_large or bypass, mail from one of our own domains, on an explicit list, DKIM-signed by that same domain and passing DMARC — subdomains are not on it), score (decimal; negative looks legitimate; common thresholds: 6 is probable spam, 15 is spam), action (what rspamd suggests — we never execute it) and symbols (the rules that weighed, heaviest first; in the detail and the webhook, not in the paginated list). null means «no mailbox of this message asked for the filter», never «clean». The score belongs to the copy that asked: in a message to two mailboxes, recipients[].spamFiltered says which one had the filter, and the webhook of the mailbox that did not ask comes with spamFilter: null. The filter only annotates: nothing is refused, held or discarded by it. To act on the score, use an inbound policy with spam_filter.score — for example, «at least 6 → tag», or «at least 15 → hold».
• And every message arrives with an agent-safety verdict. agentSafety answers a question none of the fields above answer: does this message carry instructions written for the machine that will read it? It's the difference between «this looks like spam» and «this is trying to give orders to your agent». We detect text hidden from humans but visible to the parser — the Unicode Tags block (invisible copies of ASCII, with no legitimate use in email), display:none, HTML comments, direction overrides — and judge it together with what it TELLS the reader to do. The verdict reads what your agent reads: the subject, the sender including the display name (which reaches you in fromName), the body and the text attachments; and it looks for the instruction after stripping everything Unicode declares ignorable (soft hyphen, variation selector, zero width…), so those characters can't break up the sentence or push the instruction out of the analyzed span. A hidden footer with no instruction doesn't trigger it; a hidden instruction does. One signal accuses no instruction: texto_ilegivel, a passage that cannot be normalized safely — too long without a single ASCII character (a very long paragraph of unbroken Chinese or Japanese, for example) or with too many combining marks — and is read in pieces; on its own, it leads at most to suspicious. The message's links also feed into the same verdict, checked against the Safe Browsing database. verdict is clean, suspicious or dangerous; score goes from 0 to 100 (thresholds at 25 and 60). The same two caveats as spamScore apply here: null means not evaluated, which is not clean; and the verdict is a signal, not a refusal — we don't bounce the message back to the sender because of it, and what to do with it is your call. With one exception that you switch on: each mailbox can ask for dangerous messages to be held instead of delivered. While a message is held it triggers no webhook and no forwarding, shows up in Inbound as «held for review», and comes out of there when you click «Release» — at that moment it's dispatched normally, with the verdict attached. If the mailbox didn't ask for this (the default), the behavior is the one in the paragraph above: we deliver and you decide. The webhook also carries the signals, with the reason for each point — including the text that was hidden, decoded, so you can see with your own eyes what your agent would read. And the verdict declares what it looked at. agentSafety.coverage comes with it (list, detail and webhook): bodySampled — the engine saw the head and tail (128 KiB) instead of the whole body, or a text attachment cut at the cap, or an absurd header that we cut before reading (a field over 64 KiB, a block over 512 KiB, or over 5,000 lines in the message header and 1,000 in a part — no real mail comes close), or a message with more than 1,000 parts (we read the first 1,000); sanitized — the text we hand you (body, subject or sender name) had hidden characters removed (Tags block, zero width, direction override; the /raw copy keeps them, for forensics); unscannedAttachments — how many attachments the engine didn't read because they aren't text (PDF, image, spreadsheet, zip): extract them before handing them to a model. An attached message (.eml) is decoded and goes into the verdict; a text attachment goes in regardless of its label. The signals also come in GET /v1/inbound/{id}, and ?agent_safety=dangerous (or suspicious,dangerous; none = no verdict yet) filters the inbox by it. coverage: null is a message from before coverage was recorded.
• And if the link is armed LATER, we take it back. A link can be clean when the message arrives and turn malicious six hours later — when the domain gets compromised, or when whoever set up the attack switches on the payload. No check made at arrival solves this, because it judges what the message was. Each mailbox turns re-checking on for itself (it's a setting on the address, and it comes switched off): when it's on, we re-check the links of the messages received in the last 3 days and, if one of them starts showing up on a threat list, we fire the inbound.retro_flagged event on your webhook: «message X, which we delivered as clean, has turned malicious», with the links in question. Three things worth saying: the message stays delivered — we don't recall it or rewrite its body, and its outcome in the history doesn't change; the notice goes out only once per message; and the eventId is its own, so your dedupe won't mistake the retraction for a repeat of the arrival notice. Unlike the rest of the market, we don't swap the link in your email for one of ours so we can decide at click time — the body goes out as it arrived, and the retraction is a notice, not a hijacking of the link. The price of that choice, stated plainly: whoever already clicked wasn't protected by us, they were informed, and your agent decides what to do with the information. This is the event body:

  {
    "event": "inbound.retro_flagged",
    "eventId": "9f1c…",              // unique per POST — dedupe on it
    "timestamp": "2026-09-08T11:04:22.117Z",
    "message":   { "id": "a3e1…", "subject": "Invoice 4471", "fromHeader": "fin@customer.com" },
    "recipient": { "id": "7c22…", "to": "support@yourdomain.com" },
    "retro": {
      "reason":  "link_listed_after_delivery",
      "message": "One or more links in this message were listed as threats AFTER we delivered it.",
      "links":   [{ "url": "http://…", "threatTypes": ["MALWARE"] }]
    }
  }

  It goes only by webhook: Telegram and forwarding are surfaces for humans to read, and a retraction that arrives as a chat message is noise with no possible action — what consumes this is your agent.

• And if the mailbox holds on the verdict, you find out right away. Mailboxes with «Hold the dangerous ones» switched on don't receive the body of a message with a dangerous verdict: it's held for human review, and at that same instant you receive inbound.quarantined on the webhook (and a notice on Telegram/Slack, if the mailbox has them). We never hold without telling you. The same event goes out when one of your inbound policies asks to hold: reason: "policy" and the rule's name in quarantine.policy (in the security quarantine, policy comes as null). Holding is per mailbox: in a message to two mailboxes, only the copy of the mailbox that asked for it is held — the other is delivered, the message comes with outcome: "partial" and each item in recipients carries the outcome of its own copy. A mailbox that only forwards to a person holds too: the notice goes by email to the forwarding address (without one, through the account's Telegram; without that, by email to the owners). Replying via API when ALL copies are held returns 409 message_quarantined until someone releases them; with part of it delivered, the reply goes out from the delivered mailbox.

  {
    "event": "inbound.quarantined",
    "eventId": "2b7d…",              // unique per POST — dedupe on it
    "timestamp": "2026-09-16T18:40:07.221Z",
    "message":   { "id": "a3e1…", "subject": "Payment release", "fromHeader": "billing@acme-payments.com" },
    "recipient": { "id": "7c22…", "to": "support@yourdomain.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": "The body is held, not delivered. Reply via API answers 409 message_quarantined until a human releases it in the panel." }
    }
  }

• Inbound policies: IF this arrives, THEN do that. /v1/inbound-policies (scopes read:inbound-policies and write:inbound-policies; creating and editing also require read:inbound, because a rule about content, once active, reveals which messages it matched) stores up to 50 rules per account, evaluated top to bottom for each recipient of every received message. mailboxes says which mailboxes the rule applies to (null = all; a list of ids from GET /v1/inbound/routes = only these): each recipient is judged by the rules of its own mailbox and by the all-mailbox ones, in the account's single order — a message to support@ and sales@ can be held for one and delivered for the other. If the chosen mailboxes are deleted, the rule applies to none (the list comes back empty), never to all. The conditions see what only inbound sees: agent_safety.verdict and agent_safety.score, the body (body, text or HTML without tags), dmarc/spf/dkim, attachments (attachment.type, attachment.name, attachment.count), size_kb, listed_link, the thread (thread.new, thread.replies), sender (and its domain, sender.domain, where ends_with means «the domain or a subdomain of it»), recipient, subject, the score of the mailbox spam filter (spam_filter.score, decimal — empty on a copy whose mailbox did not switch the filter on, and an empty field never matches), hour and day of the week in the account's time zone. Operators equals, contains, starts_with, ends_with, matches (a glob with *), regex (subject only: a regular expression run by our own linear-time engine — no backtracking, so no pattern can stall arrival; up to 200 characters; a back-reference such as \1, look-ahead/look-behind and (?…) are refused with regex_unsupported; at most 10 per account, regex_limit), in, at_least, at_most; an empty field (no verdict, for example) never matches. Text (subject, body, attachment name) is compared the way the agent reads it: without the characters Unicode declares ignorable (zero width, soft hyphen, variation selectors, bidi…) and in NFKC — full-width ｉｎｖｏｉｃｅ is invoice, on both sides; a value made only of ignorable characters is empty (empty_value). The body is judged on the head-and-tail sample cut after that cleanup, and every attachment the edge accepts (up to 1,000 parts) is judged. Actions: hold holds for a person to decide (and notifies, like the quarantine), mute stores without dispatching or notifying, restrict_channels delivers only to the chosen channels, pass ends the chain — and tag and notify (the account's Telegram) annotate and continue. The notify notice is best-effort: it goes out after arrival, with three attempts, and a restart midway can lose it — the feed records no_chat or notify_failed when that can be known. If the mailbox's security quarantine holds the message, it comes first: the hold/mute policy that also matched shows up in the feed with the reason mailbox_quarantine (the notice is the quarantine's, without the deadline and outside the policy's cap). A policy is born paused: check it in the simulator (POST /v1/inbound-policies/simulate, with the id of a received message or a synthetic message, and an optional draft — it answers per recipient in recipients) and then /unpause. While the platform switch is off, hold, mute and restrict_channels become the tag would_<action>:<name> — you see what the rule would do before it takes effect; the same happens when a policy reaches 200 held messages. And we never hold in the dark: a hold that can't notify on any channel (no_notice), or a restrict_channels whose channels aren't attached to the mailbox (no_channel), delivers the message normally, with the tag and the reason in the feed. Every received message carries policy (effective action, name and tags) in the list, the detail and the webhook — at message level it's the first mailbox's; each mailbox's is in recipients[].policy and in that mailbox's webhook; what a policy held you release like the quarantine (dashboard or POST /v1/inbound/{id}/release). The feed (GET /v1/inbound-policies/decisions, 90 days) says which rule matched which message, for which mailbox (recipient) and with what action in practice. The per-policy cap on held messages counts messages, not copies.

  POST /v1/inbound-policies
  { "name": "Suspicious PDF", "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 failed: human only", "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": "Suspicious PDF", "action": "hold" } ],
        "result": { "action": "tag", "policy": "Suspicious PDF", "degradedReason": "hold_disabled", "tags": ["would_hold:Suspicious PDF"] }, "seen": { … } }

  Without policy or policyId, the simulator evaluates only the active policies — the newly created (paused) one is left out; policyId evaluates a saved policy even when paused, and policy evaluates an unsaved draft (both together is a 400). Simulating against a real received message reads the mailbox: the key also needs read:inbound; every simulation — synthetic or not — counts against the per-key mailbox read limit (120/min by default), and its 429 answers Retry-After: 60: longer than the 30 s the official SDKs wait by default, so they do not retry on their own — the 429 reaches your code, with the Retry-After in hand; wait and call again, or raise the SDK's wait cap. The request body of the policy routes is capped at 256 KB (413 payload_too_large, with limit: 262144). For the same reason as reading the mailbox, the feed only shows subject and sender to keys with read:inbound. On a real received message the simulator re-reads the stored message with the same reader used at arrival — the same body sample, the sender, the subject and the full attachment names — and judges the listed_link that arrival recorded (null when arrival couldn't judge every link; messages from before September 27, 2026 only store the «yes»); it also predicts no_notice/no_channel from the message's mailboxes; the thread is read as it is now. Without the copy (retention expired), what was recorded is what counts, and whatever was cut when it was recorded can't match on the lost part. A saved policy the engine can no longer read (policyId) answers 409 inbound_policy_unreadable, with the reason in reason: it is being skipped at arrival until it's edited.

  What the conditions see, precisely: body is judged on the text and on the HTML without tags (it matches if either one matches), after the same cleanup as the verdict (invisible, bidi and tag characters are removed); the lists (recipient, attachment.*) are judged on their first 100 items; an address longer than 320 characters keeps its end (the domain), and on it only ends_with, contains and patterns starting with * match; listed_link is null — and doesn't match — when the check didn't judge every link. Calibrate your trust: sender, subject and thread.* are what the sender says; dmarc/spf/dkim, agent_safety.* and listed_link are our own measurements. The dry-run tag is always would_<action>:<name> with the API's action name (would_hold, would_mute, would_restrict_channels): integrators should treat it as the rule's intent. What a hold policy held runs on the mailbox retention clock (the deadline comes in quarantine.expiresAt in the notice and shows in the dashboard); if it isn't released by then, the copy is deleted, and releasing or replying start returning 410 copy_expired. The notify notice goes to the account's Telegram chats; if none received it, the feed says why (no_chat or notify_failed).

• The agent proposes, a person decides (hold). Send hold: true on POST /v1/send or on /reply and the message is accepted, signed and stored without going out: the 202 answers status: "held" with the decision URLs. holdNote (up to 500 characters) is what the agent tells the approver; holdTtl is the deadline in seconds (24 h by default, 7 days at most). The person decides in the portal (Messages → Approvals), in the account's Telegram or through the API: GET /v1/holds lists, POST /v1/messages/{id}/approve sends now without re-signing (and counts toward the warm-up ramp), POST /v1/messages/{id}/reject doesn't send and refunds the quota. All with the approve:holds scope — the key that sends is not the key that approves. The first decision wins; the second gets 409 already_decided. Once the deadline passes, the draft expires and doesn't go out (webhook hold_expired). The four events (held, approved, rejected, hold_expired) are opt-in per endpoint and carry metadata and the URL, never the body. Cap: 500 drafts and 200 MB per account (429 hold_limit). The reter_para_aprovacao send policy produces the same draft from a rule of yours — and that draft does not look up the recipients’ DNS at send time (a domain chosen by the agent cannot carry data in the lookup itself): the domain is checked on approval, and one that does not receive mail answers 422 invalid_recipient_domain with recipient; the draft is closed as rejected by system:recipient-domain, nothing goes out and the quota is refunded.

  POST /v1/send
  { "from": "sales@yourdomain.com", "to": "customer@acme.com", "subject": "Proposal 4471", "text": "…",
    "hold": true, "holdTtl": 7200, "holdNote": "Discount above 15% — needs someone from sales" }
  
  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": "wrong amount in the proposal" }
  200 { "id": "9f2c…", "status": "rejected", "decidedAt": "…", "decidedBy": "api:ovy_c3d4", "reason": "wrong amount in the proposal" }

• Releasing is a human act — through the dashboard or the API. POST /v1/inbound/{id}/release (scope write:inbound, never the one the replying key has) dispatches the message's held copies now, and each one's payload carries message.quarantine: when it was held, why, when and how it was released — and the verdict along with it, because releasing is not absolving. With no body it releases ALL held copies; { "recipient": "sales@…" } releases only that mailbox's copy (the response says which went out in recipients and how many are still held in stillHeld). 409 not_quarantined if no copy is held (recipient_not_quarantined if it's that mailbox's copy that isn't); 422 recipient_not_in_message if the message didn't go to that mailbox; 410 copy_expired if the copy has already expired. The numbers live in GET /v1/inbound/stats (by day or by recipient, up to 92 days): received, evaluated, clean, suspicious, dangerous, held and released — the same ones as the «Agent safety» card in Inbound, counted only once.

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

• The thread is an object. Every received message carries thread.id (in the list, the detail and the webhook): messages grouped by In-Reply-To/References within your account, including the replies you sent through OVEYON (portal, Telegram, Slack or API) — when the customer answers your reply, it lands in the same thread. Never by subject. GET /v1/inbound/threads lists threads by last activity (opaque cursor), GET /v1/inbound/threads/{id} returns the received messages in order and the replies sent, and GET /v1/inbound?thread=<id> filters the inbox by one thread. thread: null is a message from before grouping existed or one that arrival couldn't resolve — never a refusal.

  GET /v1/inbound/threads/2b7d…
  {
    "id": "2b7d…", "subject": "order 4471", "firstAt": "2026-09-16T14:02:11.000Z", "lastAt": "2026-09-16T18:40:07.221Z",
    "messageCount": 2, "replyCount": 1,
    "messages": [ { "id": "a3e1…", "subject": "Order 4471", "thread": { "id": "2b7d…" }, … }, { "id": "c9f0…", "subject": "Re: Order 4471", … } ],
    "replies":  [ { "id": "bbcd…", "at": "2026-09-16T15:10:00.000Z", "origin": "api", "from": "support@yourdomain.com", "to": "customer@acme.com", "subject": "Re: Order 4471", "preview": "Hello! Here is the invoice…" } ]
  }

• The agent replies through the API. POST /v1/inbound/{id}/reply (scope reply:inbound) sends a plain-text reply from the mailbox that received the message to the original's Reply-To/From, with In-Reply-To and References filled in by us — the reply lands in the same conversation on their side and on yours (thread). It counts one quota unit and draws on the warm-up ramp like any mail sent on behalf of the domain; the id returned is the sent message's, so you can follow it in GET /v1/messages/{id} and in the delivery webhooks. idempotencyKey (or the header; up to 190 printable ASCII characters without spaces, or an integer) returns the same id instead of replying twice, for 24 hours from when the reply was queued; while the first request is still in progress, a retry gets 409 idempotency_in_progress with Retry-After. Loop guard, because the use case is agent versus agent: the reply goes out with Auto-Submitted: auto-replied; replying to automated mail (Auto-Submitted, Precedence bulk/list/junk, null sender) is 422 auto_submitted; at most 5 replies per message and 10 automated replies per thread per hour (429). A held message answers 409 message_quarantined with the score and the release link — releasing is a human act, never a tool for the model. With several mailboxes and only some of the copies held, the reply goes out from the first mailbox whose copy was delivered; from picks another mailbox of the message (422 from_not_recipient if it didn't receive the message; 409 recipient_quarantined if its copy is held). Your recipient blocklists/allowlists apply here too (422), and so do sending policies, for the two actions that decide whether mail leaves: recusar answers 422 policy_refused, and reter_para_aprovacao turns the reply into a draft a person approves (status: held) — that is how a key marked «require human approval» holds every reply of an agent. A key limited to selected domains only replies from a mailbox of an allowed domain — outside them, 422 domain_not_allowed_for_credential, without consuming the idempotencyKey. The received message's detail carries replies[].

  If the key is in sandbox, the reply is accepted and frozen without delivery, with status: "sandbox". This takes precedence over hold and approval policies, without creating an approval link. On this endpoint, sandbox comes from the key profile; a request field or header does not set it. If the profile cannot be verified, the API returns 503 profile_unavailable without sending the reply; retry with the same idempotencyKey.

  POST /v1/inbound/a3e1…/reply
  { "text": "Hello! Invoice 4471 has been reissued and is attached in the portal.", "idempotencyKey": "ticket-8812-r1" }
  
  202 { "id": "bbcd…", "status": "accepted", "from": "support@yourdomain.com", "to": "customer@acme.com",
        "subject": "Re: Order 4471", "thread": { "id": "2b7d…" }, "url": "/v1/messages/bbcd…" }

• And the detail tells you where the message went out — down to the other side's last word. deliveries[] carries one item per (recipient, channel, kind): webhook, email forwarding, Telegram, Slack. Two facts, two fields, on purpose: status is our half — delivered means your endpoint answered 2xx, the chat accepted the notice, or the forwarded copy entered our outbound queue; not that the mailbox on the other side has it. For forwarding, destination is the destination MX's word once the copy reached it: accepted, deferred or bounced, with the raw SMTP response (response), who answered (host) and when (at) — the text you paste into a support ticket with the provider. null on the other channels, or while it isn't known yet. Read both before saying «it arrived»: a delivered forward with destination.status = "bounced" left here and reached no one. kind tells apart what was dispatched for the same pair: the message on arrival (received), the quarantine notice (quarantined) or the retroactive link-check notice (retro). What's left out: the channel's configuration (URL, secret, chat) — it belongs to the channel, and GET /v1/inbound/routes/{id} already serves it, without the secret. Three limits, stated out loud: destination only exists when the copy left through one of our sending nodes (the normal route; a copy the master delivers directly, as a fallback, stays null); the verdict is the synchronous one — an asynchronous bounce (the mailbox accepts and sends back a DSN later) isn't captured here; and accepted is what the MX said, not what the mailbox shows: Gmail, for example, accepts with 250 and silently discards — no Spam, no Trash — a copy whose Message-ID that account has already seen (duplicate suppression), and forwarding preserves the Message-ID on purpose, because it's what keeps the conversation together and the sender's DKIM signature intact. Measured on September 22, 2026: four copies accepted, none visible, until the Message-ID changed.
• Mailboxes can be created through the API. POST /v1/inbound/routes (scope write:inbound) creates support@yourdomain.com — or the catch-all *@yourdomain.com — on a domain of your account and, in the same call, hooks up the notifications: a new webhook ({ "type": "webhook", "url": … }, with proof of ownership of the URL and the secret returned once) and/or channels that already exist on the domain ({ "channelId": … }). GET lists and shows detail (with the channels, never with the secret), PATCH switches the mailbox and its spam filter (spamFilter) on/off and adds channels, DELETE removes the mailbox or, by assocId, just one channel link. A mailbox created by a machine is born without security choices: it delivers everything with the verdict; holding is a choice you switch on in the dashboard. Caps: 200 mailboxes per domain and 1000 per account (422). createdBy says who created it (api:<key prefix>), and the dashboard shows the same.

  POST /v1/inbound/routes
  { "domain": "yourdomain.com", "matchType": "exact", "localPart": "support",
    "channels": [ { "type": "webhook", "url": "https://app.acme.com/hooks/oveyon", "mode": "full" } ] }
  
  201 { "id": 318, "address": "support@yourdomain.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, shown once…" } }

• The instant inbox: an address ready to use, with no DNS. Every account can receive on our domain, under its short account code — account 80001 receives at 80001.oveyon.app. POST /v1/inbound/instant (scope write:inbound) with no body switches the inbox on — the domain and the catch-all *@80001.oveyon.app — and returns the catch-all (201 the first time, 200 after); with localPart, it creates an agent's named mailbox, bot@80001.oveyon.app, with its own thread, channels and policies: the same shape, the same caps and the same in-call webhook as POST /v1/inbound/routes. GET /v1/inbound/instant (scope read:inbound) tells the address, the mailboxes and the state, without switching anything on. Once created, they are mailboxes like any other — PATCH and DELETE /v1/inbound/routes/{id}, the same verdict, the same quarantine; switch the catch-all off and addresses without a named mailbox are refused at the door again (550). Receiving works on every plan; sending from it, replies included, only on paid plans: on the free plan, /v1/send and /v1/inbound/{id}/reply answer 422 managed_domain_requires_paid_plan (over SMTP, 550 5.7.1). Forwarding from it follows the rule of every mailbox: verified destinations only. Each account receives up to limits.perHour messages per hour there — above that the MX answers 450 4.2.1 and the sender retries in the next hour —, and on the free plan received mail is kept for the plan retention (limits.retentionDays). While the instant inbox is not enabled on the platform, both routes answer 404 not_found, like a route that does not exist. Switching the inbox back on after its receiving was switched off (the switch on the domain page) waits like that switch: at most one switch-on every 5 s per domain and 20 per minute per account — sooner than that, 429 rate_limited with Retry-After (in seconds, also in retryAfter), and nothing changes: receiving stays off. Switching off never waits.

  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, shown once…" } }
  
  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 } }

• The new text, without the quoted part. In the webhook (full modes) and in GET /v1/inbound/{id}/content, besides text you get replyText: only what the person wrote this time, without the «On Sep 16, Jane Doe wrote:», the lines starting with >, Outlook's From/Sent/To/Subject block, the original/forwarded message and the -- signature. That's what you give a model: the whole conversation is already in the thread, and reprocessing it on every turn costs tokens and causes confusion. replyStripped says whether anything was removed and replyMarkers what. With nothing to cut, replyText equals text. Portuguese and English; an interleaved reply (your reply between the quoted lines) is kept whole.
• This is third-party content. Body, HTML, attachment names and bytes came from the sender, not from us. Treat all of it as hostile data: never inject the html into your DOM without sanitizing it, and never use an attachment's filename to build a path on disk.
• Not every listed message was delivered. Each item carries outcome: "accepted" when it reached at least one recipient, "quarantined" when all copies are held for review, "partial" when some copies were delivered and others are held (each item in recipients states its own: outcome, heldBy and policy), or "blocked" when it arrived, was stored and wasn't delivered to anyone — with the reason in blockedReason. A blocked message triggered no webhook, has no recipients (recipients comes as []) and was not billed: it doesn't count against your quota. It stays readable through the content routes until expiresAt, like any other.
  • Branch on outcome, never on blockedReason. The list of reasons grows — today only "inbound_disabled" exists (the domain's inbound was turned off when the message arrived); tomorrow others may appear. Code that enumerates reasons starts answering wrong the day the next reason shows up. Treat any outcome other than "accepted" and "partial" as «not delivered to anyone», and blockedReason as text for logs and diagnostics.
  • Existing integrations don't break. Both fields are new and nothing changed type or disappeared. If your code iterates over recipients, a blocked message simply produces no iteration — the correct behavior, without changing a line.
  • Want only what was delivered? ?outcome=accepted on the list. Without the parameter the list returns both outcomes, on purpose: filtering by default would hide from you an email that really arrived.

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": "customer@example.com",       // envelope (MAIL FROM)
      "fromHeader": "sales@example.com",    // the ADDRESS in the From header
      "fromName": "Example Sales",          // display name, or null
      "subject": "Re: your quote",
      "domain": "yourcompany.com",

      // ONE EMAIL, N RECIPIENTS. We never flatten them into a single field: if the
      // message arrived for support@ and for sales@ in the SAME transaction,
      // both are here, each with its own id.
      "recipients": [
        { "id": "9c1d…", "to": "support@yourcompany.com" },
        { "id": "3af0…", "to": "sales@yourcompany.com" }
      ],

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

      // Internal spam score (0-100; the higher, the more it looks like spam).
      // null = NOT COMPUTED (message from before the feature existed) — it is not 0.
      "spamScore": 2,
      // The MAILBOX spam filter (opt-in): null = no mailbox asked for it.
      "spamFilter": { "status": "scanned", "score": -0.4, "action": "no action", "reason": null },
      // The agent-safety verdict, with what it LOOKED AT (coverage).
      "agentSafety": { "verdict": "clean", "score": 0,
                       "coverage": { "bodySampled": false, "sanitized": false, "unscannedAttachments": 1 } },

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

      // THE OUTCOME. "accepted" = delivered to at least one recipient.
      "outcome": "accepted",
      "blockedReason": null
    }
  ],
  "next_cursor": "aTo3Nw"
}

{
  "id": "c04b19f7-3d5a-4a02-b7e1-6d8f0a2c4419",
  "receivedAt": "2026-08-05T11:02:40.118Z",
  "from": "customer@example.com",
  "subject": "Arrived while it was turned off",
  "domain": "yourcompany.com",

  // EMPTY, not absent: nobody received this message.
  "recipients": [],

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

  // It arrived, was stored, was not delivered and was NOT charged.
  "outcome": "blocked",
  "blockedReason": "inbound_disabled"
}

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

{
  // … every field from the list, plus:

  // ATTACHMENT MANIFEST. `ord` is the ADDRESS of the attachment — stamped when
  // the message came in, stable forever. Download by it, NEVER
  // by `filename` (it came from the sender: it can repeat, be empty or
  // contain a path). `contentType` is the sender's label, as is;
  // `detectedType` is the type read from the first bytes of the file (null =
  // no recognized signature), and `typeMismatch` says when the two
  // disagree — as in the 2nd item: a .doc labelled as an image.
  "attachments": [
    { "ord": 1, "filename": "quote.pdf", "contentType": "application/pdf",
      "detectedType": "application/pdf", "typeMismatch": false,
      "sizeBytes": 14233, "sha256": "9f2c…",
      "url": "/v1/inbound/b71e0c34-…/attachments/1" },
    { "ord": 2, "filename": "contract.doc", "contentType": "image/png",
      "detectedType": "application/x-ole-storage", "typeMismatch": true,
      "sizeBytes": 3180, "sha256": "0ab7…",
      "url": "/v1/inbound/b71e0c34-…/attachments/2" }
  ],

  // WHERE IT WENT OUT, AND WHAT HAPPENED. One item per (recipient, channel,
  // kind — the arrival, the quarantine notice or the retroactive link-check notice).
  // `status` is OUR half: `delivered` = your endpoint answered 2xx, the
  // chat accepted it, or the forwarded copy entered our outbound queue — not
  // that the mailbox on the other end has it. On a forward, `destination` is the verdict
  // of the destination MX (accepted | deferred | bounced) with the raw SMTP
  // response; `null` on the other channels or while it is not known yet. Read both
  // before saying «it arrived».
  "deliveries": [
    { "id": "d999cc6d-…", "recipient": { "id": "d83ea519-…", "to": "support@yourcompany.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": "support@yourcompany.com" },
      "channel": "forward", "kind": "received", "status": "delivered",
      "detail": "forwarded to inbox@gmail.com (accepted by the outbound queue)", "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": "Good morning, please find the approved quote attached…",
  "html": "<p>Good morning, please find the approved quote attached…</p>",
  "truncated": false,
  "sanitized": false
}

curl -o message.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"

Errors on these routes

• 404 not_found — the message doesn't exist, or isn't in your account, or the uid is malformed. The response is identical in all three cases, on purpose: telling them apart would tell someone guessing whether their identifier hit.
• 400 bad_cursor / bad_date / bad_domain / bad_dmarc / bad_has_attachments / bad_outcome / bad_agent_safety — a filter in the wrong format.
• 403 insufficient_scope — the key doesn't have read:inbound.
• 429 rate_limited — on top of the general per-key cap, these routes have their own per-key cap (default 120 req/min): they're the only ones in /v1 that read bytes from disk on every call. The response states the limit; honor the retry-after.

Inbound webhook

Instead of you asking «did anything arrive?» every minute, we tell you: a signed POST to your server for every accepted email. The event is inbound.received.

«Accepted» is literal: the notification is per recipient, so a message with outcome: "blocked" — one that was delivered to no one — generates no event at all. It is not a condition someone has to remember to maintain: with no recipient, there is no one to fire it for. If inbound on a domain was turned off for a while, whatever arrived there is in GET /v1/inbound, and only there.

Where to turn it on

The inbound webhook is a channel of the address. In the dashboard: Domains → open the domain → Inbound tab → «Notification channels for this domain» → + New channel — or, in an address's Configure, «Notify by webhook». You provide the URL and choose the mode; the signing secret is generated by us and shown at creation — and, whenever you need to check it, under «Show secret», in the channel panel. Every reveal is recorded in the account's audit trail.

It is not the same registration as the sending webhooks — those subscribe to what happened to what you sent (delivered, bounced…), and inbound.received is not in their vocabulary: asking for it in POST /v1/webhooks gets you nowhere. Via the API, the webhook is born attached to a mailbox: POST /v1/inbound/routes creates the address with it already in place, and PATCH /v1/inbound/routes/{id} adds one to a mailbox that already exists — with the same URL ownership proof, and the secret comes back once, in the response (the mailbox is born via API); after that, only the dashboard shows it. Telegram, Slack, forwarding and the standalone channel, with no mailbox, are dashboard-only. Different addresses can have different destinations, and the same address can have more than one webhook (each with its own secret, its own mode and its own attempt count).

The URL goes through the same check as the sending webhooks: an internal or private destination is refused at registration, and the IP is validated at connection time — changing the DNS after registration does not lead us into your network.

Before saving, we hit your URL once

Since August 24, 2026, an inbound webhook URL is only saved after the endpoint answers a challenge. This applies to all three actions: creating the channel, changing the URL of an existing channel, and widening the mode (from «Summary» to «Full», for example). If the challenge does not pass, nothing is saved — and on a re-point, the old URL stays in effect.

The reason is symmetry with the other channels: for forwarding, the mailbox owner confirms by email; on Telegram, the chat_id is never typed in, it comes from a /start carrying a nonce of ours; on Slack, it is OAuth. The webhook was the only one where typing an address was enough to make it take effect — and pointing mail at the endpoint of a third party who never said yes is a way to weaponize us.

What the proof covers, and what it does not: it proves that whoever controls that endpoint agrees to receive. It does not prove that the owner of the system on the other side authorized it — someone pointing at their own server passes the challenge effortlessly. This is deliberate, not a gap to be closed later.

The challenge is an ordinary POST, with the same three signature headers as real deliveries and x-oveyon-event: url_verification. 10 s timeout.

POST https://your-endpoint.example/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://your-endpoint.example/hook",
  "sentAt": "2026-08-24T12:00:00.000Z"
}

To pass, respond 2xx returning the value of challenge, in one of these two ways — both are accepted:

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

Handle url_verification before your message logic and return right there: it is not an email, and processing it as if it were creates a phantom delivery in your system. A 200 with an empty body does not pass — that is exactly the case the challenge exists to catch.

At creation you do not know the secret yet (it only appears once the channel has been created), so there is no way to verify the signature of that first challenge — only the echo is required. On a URL change the secret is already yours, and then it is worth verifying the signature before echoing, as with any delivery.

What if the destination is a third-party receiver you do not program (n8n, Make, webhook.site)? Echoing the challenge may be impossible there. For that case there is an alternative path, in the dashboard: when your endpoint accepts the POST (2xx) but does not return the challenge, the form offers the option «accept without proof of reading» — check it and the URL is saved anyway, with a visible mark on the channel. Be honest with yourself about what is lost: the proof drops from «someone reads what arrives there» to «the URL exists and accepts POST». And the shortcut only applies to that outcome — an endpoint that answers with an error or does not answer in time is still refused, because there is no receiver there at all, just a broken address.

app.post('/hook', (req, res) => {
  // The challenge comes BEFORE anything else — and is answered right here.
  if (req.body && req.body.type === 'url_verification') {
    return res.json({ challenge: req.body.challenge });
  }
  // … from here down, the real inbound.received
});

One event per recipient, per channel

This is the point that confuses integrators the most, so let's take it slowly: an email that arrived for three of your addresses generates three events, not one with a list.

The reason is that each recipient has its own outcome. An SMTP transaction is one body and N recipients, but the notification for one may fail and go into retry while the other's was already delivered on the first try. A single event would have to carry an aggregate status — and an aggregate status of things that end differently is always a lie about one of them. For the same reason, if the address has two channels, each channel has its own attempt count: the same recipient appears once per channel.

• message.id is the same in all three events — it is the email.
• recipient and eventId are different — they are the delivery.
• If your code keys by message.id, it will overwrite two of them. Key by eventId.

The payload

POST https://yourapp.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",

  // STABLE ID of this delivery — this recipient, on this channel. Retries and
  // redeliveries repeat the SAME value: it is what you deduplicate on.
  "eventId": "6e5a1b90-3c77-4f02-b1ad-8e4409c2d611",

  // The FORMAT version of this body. It only goes up on a breaking change —
  // store it, and reject what you do not know how to read instead of guessing.
  "schemaVersion": 1,
  "timestamp": "2026-08-05T09:14:03.902Z",

  // The email. Almost the same object as GET /v1/inbound/:uid, with three
  // differences: here you get `messageIdHeader` and `inReplyTo`, the URLs are
  // absolute (`url`/`rawUrl`, not the `links` object), and there is NO `recipients` —
  // this notification is for ONE recipient, and it sits outside, in `recipient`.
  // `message.id` is the uid: it is what goes in the /v1/inbound/* routes.
  "message": {
    "id": "b71e0c34-5a2f-4d18-9c60-77ab31e2d905",
    "receivedAt": "2026-08-05T09:14:02.317Z",
    "domain": "yourcompany.com",
    "from": "customer@example.com",
    "fromHeader": "sales@example.com",
    "fromName": "Sales",
    "subject": "Re: your quote",
    "messageIdHeader": "<a1b2@example.com>",
    "inReplyTo": "<z9@yourcompany.com>",
    "sizeBytes": 18422,
    "attachmentCount": 1,
    "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },

    // Internal spam score (0-100), the same as in GET /v1/inbound. It also goes
    // in the POST `x-spam-score` header — present ONLY when there is a score; if
    // the field is null, the header simply does not exist. null = not computed
    // (the message predates the feature), which is NOT the same as 0 (= clean).
    "spamScore": 2,
    // The spam filter of THIS copy's mailbox (null if it did not ask).
    "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"
  },

  // WHO this copy is for — an OBJECT, not a string. An email that
  // arrived for support@ AND sales@ produces TWO events: same `message.id`,
  // different `recipient` and `eventId`.
  "recipient": { "id": "4d2f77a1-…", "to": "support@yourcompany.com" },

  // MANIFEST, at the TOP of the body (not inside `message`): name, type,
  // size, sha256 and the URL to fetch the bytes from. It comes in ALL
  // modes, including `summary`. The address of an attachment is its `ord`, NEVER
  // its `filename`. `detectedType` is the type by the first bytes (null = no
  // recognized signature); `typeMismatch` warns when the label
  // (`contentType`) and the content disagree — do not discard by the label.
  "attachments": [
    { "ord": 1, "filename": "quote.pdf", "contentType": "application/pdf",
      "detectedType": "application/pdf", "typeMismatch": false,
      "sizeBytes": 14233, "sha256": "e3b0c442…",
      "url": "https://api.oveyon.com/v1/inbound/b71e0c34-…/attachments/1" }
  ],

  // ALWAYS present — even when nothing was cut. Always check it.
  "truncation": {
    "degraded": false,          // did you get less than you asked for?
    "requestedMode": "full",    // the mode configured on the channel
    "mode": "full",             // the mode that actually went out
    "reason": null,             // readable text when it degraded; null when not
    "maxBytes": 262144,         // the cap in force for THIS POST
    "attachmentsInline": false, // did the bytes come embedded in `content`?
    "attachmentsListed": 1,     // how many attachments fit in the manifest
    "attachmentCount": 1,       // how many the message has in total
    "textTruncated": false,
    "htmlTruncated": false
  },

  // In `full` and `full+attachments` modes, and also at the TOP of the body. They
  // are `null` when the message has no such part; in `summary` mode the two
  // keys simply do not exist.
  "text": "Good morning, please find the approved quote attached…",
  "html": "<p>Good morning, please find the approved quote attached…</p>"
}

Three modes — you choose how much volume goes into the notification

The attachment manifest comes in all three modes — what changes from one to the next is the volume (body and bytes), never the list. And the mode selected by default on screen is full+attachments: if you do not choose, you get everything that fits.

// `summary` mode — no `text` and no `html` (the keys do not even appear). Everything
// else stays: headers, verdicts, URLs and the attachment MANIFEST.
{ "event": "inbound.received", "eventId": "…", "schemaVersion": 1,
  "message": { … }, "recipient": { "id": "…", "to": "…" },
  "attachments": [ { "ord": 1, "filename": "quote.pdf", "sha256": "…", "url": "…" } ],
  "truncation": { "degraded": false, "requestedMode": "summary", "mode": "summary", … } }

// `full+attachments` mode — each manifest item gets its BYTES in base64,
// in the same format as `attachments[].content` in POST /send. It is ALL OR NOTHING:
// either every attachment comes embedded, or none does.
"attachments": [
  { "ord": 1, "filename": "quote.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 }

// … and when it does not fit, the payload DEGRADES and SAYS SO. Here the channel
// asked for `full+attachments` and got `full`: the manifest stayed, the bytes did not.
"truncation": {
  "degraded": true,
  "requestedMode": "full+attachments",
  "mode": "full",
  "reason": "payload with inline attachments would exceed 262144 bytes: sent as links",
  "maxBytes": 262144,
  "attachmentsInline": false,
  "attachmentsListed": 1,
  "attachmentCount": 1,
  "textTruncated": false,
  "htmlTruncated": false
}

The POST cap

Every notification has a size cap, and it applies to the entire POST body — not just the attachments. The default is 256 KB (262,144 bytes). The value in effect for that POST is declared inside it, in truncation.maxBytes: read it from there instead of hardcoding the number in your code.

The cap is applied when the notification is built, not at delivery time. A 15 MB email never becomes a 20 MB POST that we would try six times: the large payload never even comes into existence. Two practical consequences for integrators: text and html are each cut to at most one quarter of the cap (the cut is by byte, and never splits a character in half), and the attachment bytes are only embedded if all of them fit in what is left.

Degradation is declared, never silent

When the payload does not fit in the requested mode, it degrades and says it degraded. The truncation block is always present — with degraded: false on the normal path — precisely so you can always check it, with a single line, instead of finding out it exists on the day of the first large email.

There is no level field: what answers «how much went out?» is the requestedMode / mode pair, in the same vocabulary as the three modes above.

• degraded — true when less went out than you asked for. It is the only field you need to check.
• requestedMode and mode — what was requested at registration and what actually went out. Asked for full+attachments and got mode: "full"? The bytes were left out; the manifest and the URLs are still there.
• reason — a human-readable sentence with everything that was lost, not just the last cause (two problems in the same message become two parts separated by ;). It is null when nothing degraded.
• maxBytes — the cap in effect for this POST.
• attachmentsInline — true only when the bytes came in attachments[].content. It is all or nothing: never half of the attachments embedded.
• attachmentsListed vs. attachmentCount — how many attachments came in the manifest and how many the message has in total. Different? The tail of the list did not fit; the missing ones are in the API.
• textTruncated / htmlTruncated — that field came cut (or removed). A detail, not a substitute: when either one is true, degraded is too.

What degraded was not lost: it is in the API, under the same message.id. Degrading takes volume out of the notification, never out of the archive.

Deduplicate by eventId

We would rather deliver twice than lose a notification. If your server processes it and the 200 gets lost on the way, the next attempt carries the same eventId — it is stable per delivery and survives both retry and redelivery. Store it, and treat a repeat as a silent success. Do not deduplicate by a hash of the body: a redelivery rebuilds the payload, and what arrives may not be byte-for-byte what arrived before.

// The SAME delivery can arrive twice: a retry after a timeout in which you had
// already processed it, or a redelivery from us. `eventId` is stable
// in both cases — it is the deduplication key.
async function processEvent(evt) {
  // INSERT with a unique key on eventId: whoever loses the race already knows
  // it is a duplicate, without relying on a SELECT-before-INSERT (which is racy).
  const isNew = await markAsSeen(evt.eventId);
  if (!isNew) return;              // already processed — answer 2xx and move on

  if (evt.truncation.degraded) {
    // The notification was trimmed: fetch what is missing from the API, by message.id.
    await fetchFromApi(evt.message.id);
  }
  await save(evt);
}

Signature (HMAC-SHA256)

Same scheme as the sending webhooks. Every POST carries three headers:

• x-oveyon-event — the event name (inbound.received).
• x-oveyon-timestamp — epoch in seconds.
• x-oveyon-signature — sha256= + HMAC-SHA256 with the channel secret over timestamp + "." + raw-body.

The timestamp goes inside the signed content: a captured POST cannot be resent with a fresh timestamp without breaking the signature. Reject anything that arrives with |now − timestamp| > 300 s, even with a valid HMAC — without that window, the signature alone authenticates a replay from yesterday.

Verifying in Node

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

// The RAW BODY is what was signed. Capture the bytes BEFORE any parsing
// — re-serializing the JSON changes a space and the signature no longer matches.
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

  // Anti-replay window: 300 s. Outside it, reject — even with a valid HMAC.
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);

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

  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(sig, 'hex');
  // Constant-time comparison (== leaks the correct prefix through timing).
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  const evt = JSON.parse(raw.toString('utf8'));
  enqueueForProcessing(evt);        // heavy work OUTSIDE the request
  res.sendStatus(200);              // fast 2xx: the attempt times out after 10 s
});

Verifying in PHP

<?php
// The RAW body, byte for byte. No json_decode before verifying.
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_OVEYON_TIMESTAMP'] ?? '';
$sig = preg_replace('/^sha256=/', '', $_SERVER['HTTP_X_OVEYON_SIGNATURE'] ?? '');

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

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

// hash_equals: constant-time comparison.
if (!hash_equals($expected, $sig)) { http_response_code(401); exit; }

$evt = json_decode($raw, true);
enqueueForProcessing($evt);        // heavy work after responding
http_response_code(200);

Retries

Delivery means 2xx. Anything else counts as a failure and goes into the retry queue: 4xx, 5xx, a 10 s timeout, connection refused — and also 3xx, because redirects are not followed (following a redirect from a customer endpoint is how an SSRF walks in through the front door).

That is 6 attempts, within a window of just over 7 hours. That is the number that matters to whoever operates the endpoint: a two-hour maintenance outage is absorbed without losing anything; a full-day outage is not.

Once all six are used up, the delivery is marked as failed and there is no seventh — the queue stops hitting your endpoint instead of hammering it forever. Nothing is lost because of this: the email stays stored, and GET /v1/inbound is the safety net. Endpoint went down? Reconcile by listing the outage window (?from=…&to=…) and deduplicating against what you already had — that is why the API exists even if you use the webhook.

Where you see this happening: in the dashboard, on the same row where the webhook was registered (Domains → the domain → the address), the Last send column shows the outcome of each notification and the reason in text: pending (there will be another attempt), delivered, failed (all six were used up) and dropped. The last one is the case where there was nowhere left to deliver to — the webhook was removed or deactivated between the email's arrival and the attempt. dropped is not a failure on your side or ours, and it is not retried.

Answer 2xx fast and do the heavy work afterwards. An endpoint that processes for 12 seconds before answering fails by timeout even though it did everything right — and then you receive the same event six times.

Endpoint behind Cloudflare (or a WAF): if you see 403 on the attempts and your code never runs, what is refusing is the edge, not your server — bot-fight and WAF rules love to kill machine POSTs. Our deliveries identify themselves as User-Agent: OVEYON-Webhook/1.0: create a WAF exception for that UA (or for your webhook's path) and the problem goes away. A diagnostic tip that applies to everything: the status code YOUR code returns is in your application log; a 403 with no log line at all = the edge ate the request first.

Attachments

The payload carries the manifest — ord, name, type, size, sha256 and the URL of each attachment — in all three modes. The bytes are fetched through the API, with your key: it is the same route as in the previous section.

Two types per attachment. contentType is the sender's label, as is; detectedType is the type read from the first bytes of the file (PDF, legacy and modern Office, images, archives, audio and video, executables — null when no signature is recognized, as with plain text). typeMismatch is true when both exist and belong to different families — image, audio and video, PDF, PostScript, office document (legacy and modern Office, OpenDocument, RTF), archive, executable, text. Synonyms of the same type (image/jpg, Outlook's application/x-zip-compressed) and the same container (application/zip for a .docx) do not count; a generic label (application/octet-stream) never mismatches. A label outside these families only mismatches when the content is an executable — an executable mismatches every label that does not declare one. Do not discard an attachment on the label alone; prefer detectedType when it exists — a .doc has already arrived labelled image/png by the sender's email program, and an «images only» filter would have thrown it away.

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

• Why they do not always come inline: base64 inflates the file by about a third, and a 15 MB attachment would become a ~20 MB POST that we would try up to six times, with a 10 s timeout. Most servers refuse a body that size before even checking the signature — and then the attachment takes down the whole notification, not just itself.
• The full+attachments mode embeds the bytes only as long as the whole POST fits within the cap (256 KB by default; the value for that POST is in truncation.maxBytes). Did not fit? The attachments go by link instead, attachmentsInline comes as false, reason explains, and the URLs remain valid.
• It is all or nothing. You never get some attachments embedded and others by link — either the whole batch fits, or none comes with content.
• An attachment's address is its ord, never its filename: two attachments can have the same name, and the name can come empty or with a path inside it.

⚠ What reaches your endpoint is third-party content

Subject, body, HTML, attachment names and bytes were written by whoever sent the email — not by us, and not by you. Anyone on the internet can send an email to one of your addresses, and therefore anyone on the internet chooses what goes inside this payload. The HMAC signature proves that we sent the POST; it does not say anything about its content.

• Never render the html without sanitizing it. Injecting it into your DOM, into a helpdesk panel or into an email you resend is XSS on your origin, with your user's session. Run it through a sanitizer (DOMPurify and the like) or use only the text.
• Never use the filename to build a path on disk. It can contain ../, a slash, a null character or a system file name. That is path traversal served on a platter. Save by the ord (or by an id of your own) and keep the original name only as a display label.
• Do not trust the contentType declared by the sender, and do not serve the attachment back as a document on your origin. If you need to offer a download, force Content-Disposition: attachment and X-Content-Type-Options: nosniff — that is what we do on our routes.
• Read message.authentication before believing who signed the email. fromHeader is what the sender declared; SPF, DKIM and DMARC are what could be proven. A flow that triggers something important from an email should require dmarc: "pass" — without it, the «From: boss@yourcompany.com» can be typed by anyone.
• The fromName is the easiest field to forge in the entire email. It is the display name the sender wrote — there is no need to register a lookalike domain or break anything: just type it. An email with "fromName": "Bank of America" and "fromHeader": "x@random-domain.top" is the most common phishing there is, and it passes SPF and DKIM without a problem (its domain is legitimate — it just is not the one the name suggests). Display the name if you like, but decide by the address, never by the name.

Suppressions

Addresses you never want to reach. Only your tenant's rows are listed; the platform's global suppressions also block, but they do not appear here.

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

{
  "suppressions": [
    { "email": "nospace@example.com", "reason": "mailbox_full", "source": "dsn",
      "domainId": null, "expiresAt": "2026-07-21T10:02:00.000Z", "createdAt": "2026-07-20T10:02:00.000Z" },
    { "email": "invalid@example.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": "donotsend@example.com", "reason": "manual" }'

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

Sending and receiving rules (allow/block)

Four lists per account: allow and block, for outbound (judges the recipient) and inbound (judges the sender, at our MX). An entry is an exact email address, an exact domain or *.domain.com (covers subdomains at any depth, never the domain itself). Semantics: block beats allow; the allow list only restricts when it has at least one entry; in the block list, user+tag@ counts as user@. It is the recommended fence for mailboxes operated by AI agents: a recipient allow list limits the damage of any prompt that goes wrong.

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": "customer.com" }'

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 }'

Errors that /send now returns

• 422 recipient_blocked — recipient on your block list; the entry field names the entry that matched.
• 422 recipient_not_allowed — your allow list is active and the recipient is not on it. The WHOLE call is refused (same contract as suppression).

Send policies

An ordered IF→THEN engine evaluated on every send, through the API and authenticated SMTP. The allow/block rules above only see the address; here a condition can look at the subject, sender, credential and time of day — and the action can refuse, hold, require a footer, force the tier or limit per hour. Both pieces are restrictive and ordered: a policy never reopens what a list, a suppression or the quota has already closed.

The shape of a policy

• name — up to 120 characters. It is what appears in the refusal and in the history, and it is frozen in the audit trail: renaming the policy does not rewrite what it has already decided.
• conditions — 1 to 5, and all of them must match (AND). Each one is { campo, op, valor }. A policy with no condition would match ALL of your messages, which is why an empty list is rejected.
• action — exactly one, from the catalog below.
• actionParams — only for actions that declare a parameter. Today that is only limitar_hora, which requires { "max": N }. An extra, missing or unknown parameter is a 400.
• position — the evaluation order, top to bottom. We assign it (creating always puts the policy at the end), and you change it with /reorder.

No regex and no negation, and that is a security decision, not a lack of time: an expression written by the customer and evaluated in the path of every message is the definition of a ReDoS surface. The vocabulary is closed, and all of it is in the table below.

Conditions — the closed catalog

Actions

• recusar — the message is not accepted: 422 policy_refused in the API, 550 5.7.1 in SMTP. It does not consume quota — and not because of a refund: the engine runs before the counter.
• reter — the message is accepted (202/250) and stays frozen, without going out. Only our support team can release a send-policy hold — there is no route or button for you to release it. It returns no error: the 202 of POST /v1/send keeps status: "accepted" and carries frozen: { reason: "policy", policyId }; the history is in the decisions feed.
• exigir_footer — makes the unsubscribe footer mandatory. In the API, with more than one recipient in the same call, the send is refused with 422 unsub_footer_multi_recipient: the link is per recipient.
• forcar_transacional — stamps the message as transactional (label and accounting). Today it does not change the outbound IP, because per-tier rotation is turned off on this platform.
• seguir_fluxo — does nothing and ends policy evaluation. It is the exception you place ABOVE a broader rule. It does not exempt the message from lists, suppression or quota.
• limitar_hora — see its own section right below.

First-match-wins: the first active policy that matches decides, and the scan stops. There is no «most specific wins» and no stacking of actions. A paused policy decides nothing. If none matches, nothing happens: zero events, zero rows. The exception is a key’s human-approval lock (the reter_para_aprovacao whose only condition is «credential is key N»): it applies in any position. For that key’s sending, seguir_fluxo, forcar_transacional, exigir_footer and limitar_hora do not decide: nothing from that key goes out without a person. recusar still blocks in any position, and reter above the lock freezes the message (only support releases it). On a reply (POST /v1/inbound/{id}/reply), which does not apply reter, the locked key always produces a draft for approval, unless recusar decides.

The hourly cap (limitar_hora)

Lets through up to max messages per clock hour for the traffic the policy describes, and refuses the excess until the hour turns over. It is a cap on that slice, not on the account: the rest of your traffic is not affected.

• Counts per recipient, not per call — the same unit as the quota and the per-credential cap. A send to 5 people uses 5.
• Counts on acceptance, never on the check: a message refused by quota, by rate limit or by an injection failure after the policy does not consume the cap (and in SMTP, whatever is refused after DATA is returned to the counter).
• Known, bounded slack: the check happens once per message and the count is N. With max: 100, 99 counted and a call with 5 recipients, the call goes through and the bucket ends at 104. Since the cap on recipients per call is 5, the maximum overshoot is 4, once per window — the next call is already blocked. This is deliberate: tightening it would require reserving before acceptance, trading an overshoot of 4 for orphaned reservations.
• When exceeded: 429 policy_rate_limited with Retry-After (and policy, limit, used, retryAfter in the body). In SMTP, a 4.7.1 that tells the client to try again — never a 5xx, because the window rolls over on its own.
• The refusal trail is one row per policy per hour, not one per attempt: a burst against the cap itself would flood the feed without saying anything new.

curl -X POST https://api.oveyon.com/v1/send-policies \
  -H "Authorization: Bearer $OVEYON_KEY" -H "Content-Type: application/json" \
  -d '{
        "name": "At most 200/h to the customer domain",
        "conditions": [{ "campo": "destinatario", "op": "termina_em", "valor": "@customer.com" }],
        "action": "limitar_hora",
        "actionParams": { "max": 200 }
      }'

The write cap on these routes

The mutation routes in this section (POST, PUT, pause, unpause, reorder, DELETE) have a per-key cap, on top of the general per-key cap: default 120 writes/min. The reads in this section do not count against that cap. Exceeded → 429 rate_limited with Retry-After; the message states the limit.

It exists because every mutation here is more expensive than it looks: it invalidates the policy-evaluation cache, reorder rewrites the entire order, and DELETE also clears the policy pointer across 90 days of trail. It is the same cap the Policies screen applies — no human use or well-behaved script comes close to it, since the whole account can only have 50 policies.

Errors that /send now returns

• 422 policy_refused — refused by one of your policies. The body names the policy (policy) and the recipient that matched (recipient), and says how it matched in matchedBy: recipient (it has a recipient condition) or message (it only looks at the message and refuses any recipient). With an hour condition it also carries retryAfter (ISO 8601): the end of the time window. This holds for /v1/send and for the inbound reply (POST /v1/inbound/{id}/reply). Does not consume quota.
• 429 policy_rate_limited — the hourly cap of one of your policies was reached. Honor the Retry-After: the window rolls over on its own.
• 422 unsub_footer_multi_recipient — a policy requires the footer and the call has more than one recipient.

The same policy applies to the API and authenticated SMTP. It does not apply on the inbound entry point (receiving is not sending), nor to relayed third-party mail.

Surveys (NPS / CSAT)

Trigger the question from your own system (ticket closed, order delivered) and get the score back by webhook. The survey goes out as a regular email from this platform — verified domain, DKIM, rules, suppressions, send policies and quota all apply, without exception. The score is collected on the click, on a page served from your tracking domain.

The two kinds, and the range of each

Every response from the survey endpoints carries range: { min, max }. Read it from there instead of hardcoding 0..10 in your code. And distribuicao always comes with every score in the range, including the ones at zero: a chart that drops the scores with no votes lies about the shape of the curve, which is the first thing anyone looks at. With no responses at all, nps and media come back null — never 0: «NPS 0» is a genuinely bad result, and showing it where there is no data would be the product lying with a plausible number.

The score is the click — and the email body says so

Each score is its own link, and the click records the vote even if the thank-you page does not load: the write happens before the redirect. There is no voting by replying to the email, and the body says so in both HTML and plain text — without that notice, someone who replies «9» on instinct would walk away thinking they had voted, and your survey would collect silence.

• The first vote counts. Clicking a different score later does not silently replace it: the page shows the recorded score and asks for confirmation. That is what protects your number from corporate link scanners, which click all eleven NPS links in order — under a «last vote counts» rule, every recipient behind a scanner would end up with the score of the last link without ever opening the email.
• Bot clicks do not vote. Known image proxies and scanners are recognized and ignored; the page responds to them the same way (nothing that would teach them to disguise themselves), and the human who opens the same link later votes normally.
• The comment is optional and arrives after the score, on the same page. That is why you receive more than one survey.response per response — see the webhook below.
• Forwarding: the link belongs to the original recipient. If they forward the email, the vote of whoever clicks counts as theirs. That is the honest limitation of the model, and the whole industry lives with it.
• The language is your account’s — the same as the emails the platform sends you: Portuguese for an account from Brazil, English for all others. It applies to the fixed text of the email (the notice that replying does not vote, the two ends of the scale), to the voting page and to the default question. What you write — subject, question, sender name — goes out as you wrote it.

Anti-fatigue — the rule that protects your list

The same recipient is surveyed only once per window. The window belongs to the ACCOUNT, not to the survey: someone who got your NPS yesterday does not get your CSAT today — the people on your list do not know you have two surveys. The length of the window comes from the survey you are sending (throttleDays, default 90, minimum 7).

A repeated request within the window → 429 recipient_recently_surveyed, with Retry-After (which can be weeks — that is the truthful answer), plus throttleDays and lastSentAt in the body. 429, not 422, and the difference matters: this will go through again once the window expires. A send refused for another reason (suppression, quota, policy) does not consume the window — the attempt is put on record and the address stays free.

curl -X POST https://api.oveyon.com/v1/surveys \
  -H "Authorization: Bearer $OVEYON_KEY" -H "Content-Type: application/json" \
  -d '{
        "kind": "nps",
        "name": "Post-support NPS",
        "subject": "How was your support experience?",
        "fromEmail": "survey@yourcompany.com",
        "fromName": "Team",
        "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": "customer@example.com",
        "meta": { "ticket": 4821, "agent": "bea" },
        "idempotencyKey": "ticket-4821"
      }'

The survey.response webhook

Subscribe to survey.response on a webhook endpoint and get the score on your server without having to poll. Same HMAC signature and same retry policy as the other events.

{
  "event": "survey.response",
  "surveyId": 7,
  "surveyName": "Post-support NPS",
  "kind": "nps",
  "sendId": 91,
  "recipient": "customer@example.com",
  "score": 9,
  "comment": "Fast service.",
  "updated": true,
  "meta": { "ticket": 4821, "agent": "bea" },
  "messageId": "8f3c...-message-uuid",
  "timestamp": "2026-08-25T14:02:11.000Z"
}

The payload is the CURRENT STATE of the response, not a delta. Key by sendId and overwrite. You receive more than one notification per response when it changes: the first on the vote (updated: false, comment: null), and another when the person writes the comment or changes the score (updated: true). It is not a duplicate — the comment always arrives after the score, they are two separate actions on the page, and with a single notification the most valuable field from a detractor would never reach you.

An endpoint scoped to a credential does not receive survey.response: the one who voted was the recipient, with no key at all, and sending the notification to the wrong channel is worse than not sending it.

The write cap on these routes

The mutations in this section (POST, PUT, DELETE) and the send have a per-key cap, on top of the general per-key cap: default 120/min. Reads do not count against it. Exceeded → 429 rate_limited with Retry-After.

The send counts against this cap for a concrete reason: the voting link has to exist before the email body, so the record is created before the send is evaluated and is canceled when the send is refused. A loop against an always-refused recipient would keep creating and canceling nonstop.

Sending webhooks

Receive delivery events on your server. Multiple endpoints per account; each one subscribes to a subset of events: delivered, bounced, opened, clicked, complained, blocked. These are the events for what you sent — notifications for received email are configured separately, in the Inbound webhook section.

Timeout and retries: each attempt waits up to 10 seconds for your response; delivery means a 2xx within that time. Anything else — 4xx, 5xx, 3xx (redirects are not followed), timeout, connection refused — counts as a failure and is retried: there are 6 attempts in total, with increasing waits of 30 s, 2 min, 10 min, 1 h and 6 h (a ~7 h window), the same policy and the same table as the inbound webhook. Once all six are exhausted, the delivery is marked as failed and there is no seventh. Respond with a 2xx quickly and do the heavy work afterwards: an endpoint that spends 12 s processing before it responds fails on timeout even though it did everything right.

The blocked event fires when your sending rules block a recipient (in the API, over SMTP, or in a reply to an inbound email). The body carries reason (block_list or not_on_allow_list), entry (the entry that matched, when it is a block), address and origin. An endpoint scoped to a credential does not receive blocked — a block carries no credential.

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

{
  "id": 7,
  "url": "https://yourapp.com/hooks/oveyon",
  "events": ["bounced", "complained", "delivered"],
  "active": true,
  "secret": "3b1f...64hex...  (shown ONCE)",
  "signature": {
    "header": "x-oveyon-signature: sha256=HMAC-SHA256(secret, `${timestamp}.${rawBody}`)",
    "timestampHeader": "x-oveyon-timestamp (epoch seconds)",
    "verify": "Recompute the HMAC over `timestamp + \".\" + raw-body` and reject if |now - 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 }'

Domains

Add and verify your sending domains. A domain that already belongs to another account cannot be registered again (anti-hijacking).

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

{
  "id": 42,
  "domain": "yourcompany.com",
  "records": [
    { "type": "TXT",   "name": "yourcompany.com", "value": "v=spf1 include:...", "purpose": "SPF (authorizes the sending IPs for your brand)", "optional": true },
    { "type": "CNAME", "name": "s90abc._domainkey.yourcompany.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": "yourcompany.com",
  "verification": { "spf": true, "dkim": true, "dmarc": false },
  "inconclusive": [],
  "detail": { "spf": "...", "dkim": "...", "dmarc": "no _dmarc record" },
  "spfProblem": null
}

Marketing (experimental)

Contacts, properties, tags, newsletter lists, campaigns and sequences. Experimental: the module is enabled account by account, and without it every route in this section answers 403 module_disabled. Scopes read:contacts (read) and write:contacts (write — and, on a list with double opt-in, subscribing sends the person the confirmation email, which counts against the account’s sending quota).

The model

• One contact per email address in the account: the address is normalized before matching (lowercase; only ASCII whitespace — space, TAB, LF, VT, FF, CR — is trimmed from the ends), and the same person on three lists is a single contact, with one subscription per list. A Unicode space at either end (NBSP, U+3000…) is not trimmed: the address is refused with 400 invalid_email. The address is ASCII only (see ASCII-only addresses): an internationalized domain (IDN) enters only in punycode — ana@xn--exmple-cua.com; ana@exämple.com is refused with 400 invalid_email and reason: "address_not_ascii". The same holds when finding, tagging, unsubscribing and deleting a contact: the contact exists only in its ASCII form, and that is the only form looked up.
• A list belongs to one brand (its sending domain) and has its own sender. Each subscription has its own state: pending, subscribed (already confirmed) or unsubscribed.
• Leaving a list is not a suppression. Whoever unsubscribes from the newsletter keeps receiving your account’s transactional email.
• Whoever left on their own only comes back on their own. They left through the unsubscribe link or the preference center, marked an email as spam, or their address bounced: the API does not subscribe them again — 409 unsubscribed_by_contact, 409 complained or 409 bounced.
• Properties (attributes): names in the form ^[a-z][a-zA-Z0-9_]{0,63}$, never email, firstName or lastName; the type is registered by the first value (or by POST /v1/contacts/properties). Limits: 100 names per account (422 too_many_properties), 8 KB per contact (422 attributes_too_large) and 1 KB per value (400 invalid_property_value).
• Deleting takes the contact off every list at once; 30 days later their data is erased for good (purgeAfter). Only a hash of the address stays, so a re-import does not put back on the list someone who had left. Re-creating the same address later starts from zero (201): nothing of the previous contact comes back — name, properties, tags and subscriptions —, and the unsubscribes the person made still hold.
• Closed body: an unknown field is 400 bad_request with field (the name only comes back when it looks like a field name: no spaces and no at sign). A contact, list or tag of another account answers the same as a nonexistent one (404).
• Concurrent writes: when concurrent writes — from any source, not only this account — hold the contact (or the same new tag) for a few seconds, the write gives up instead of waiting longer — 503 contact_busy with Retry-After (5 s, also in retryAfter). Retrying is safe.
• The request log of these routes keeps the field names, the ids and the error; the values (email address, name, properties, consent IP) only show as { "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 }

Campaigns

A campaign is one edition for one list: the brand, the sender, the footer and the language come from the list. The footer of every campaign message carries the list’s postal address (US commercial email law requires it), the unsubscribe link and the preference center; without the address nothing goes out — the check reports list_missing_postal_address, and a campaign that is already sending waits with the same reason in pauseReason and resumes on its own once it is back. The platform composes the final message: the footer goes in as the last element of the body, with its own inline style, and the result is parsed again and checked; layout or template HTML that does not let it in (a frameset, or nesting far beyond what an email uses) is reported by the check as footer_not_guaranteed and nothing goes out. The composed email, with its links tracked, is capped at 100 KB measured as it is sent — the HTML part encoded in quoted-printable or base64, which is longer than the HTML (accents and emoji weigh up to about 2.4 times their bytes): Gmail clips a message at about 102 KB, and what disappears is the end — the footer. Above it the check reports the same footer_not_guaranteed with the reason in problemReasons ({"footer_not_guaranteed": "html_too_large"}; not_ready carries the same field), and nothing goes out — reduce the HTML. Layout or template CSS that would hide the footer does not pass either: on <html> and <body> only color, background, font, text, margin, border and width are allowed; on any element, no position: absolute, fixed or sticky, offset, positive z-index, negative margin, transform or wide outline; and an external stylesheet (@import, <link rel="stylesheet">) cannot be checked. The check reports footer_not_guaranteed with the reason in problemReasons — css_on_html_body, css_positioning, css_negative_margin, css_transform, css_outline, css_external_stylesheet, css_unsupported_rule, css_outlook_hide — and the screen says what to remove. Scopes read:campaigns (read, check and the report), write:campaigns (create, edit, rehearse, the preview and pause) and send:campaigns (approve, schedule, resume, cancel and delete). With the human-approval lock on the key, write:campaigns and send:campaigns do not work: a campaign goes to the whole list without a draft.

• The states: draft → approved (approving never sends) → scheduled (scheduling is the gesture that sends) → running → done; running ⇄ paused; any of them → cancelled. Editing an approved or scheduled campaign takes it back to draft (returnedToDraft): an approval is for what was checked.
• Approving freezes what the campaign inherits: the version of the template (or of the list layout) that was checked is the one that goes out, even if a newer one is published later — also in a send spread over days. And the list’s sender, reply-to, postal address, language and layout are recorded: if the list changes any of them after the approval, scheduling (or the scheduled campaign, when its time comes) takes the campaign back to draft and the owner is notified — 409 changed with returnedToDraft: true.
• Check first: the check returns problems (empty = ready), the audience and the brand readiness (readiness), item by item, with who fixes each one: account (you), staff (our support team) or automatic. Approving or scheduling with a problem → 422 not_ready with the same problems. The audience is checked within the limit of 30 counts per account per minute and a time limit: without an answer, the problem is audience_check_inconclusive (with audienceError rate_limited, filter_too_slow or busy, when too many audience checks of the account run at the same time) — never «empty», never «ready»: check again in a minute. In daily_capacity, capacity and limitedBy count only the brand’s daily limit and your account’s own caps (domain warmup, quotas, rate), and estimatedDays comes from them alone: the headroom of the platform’s shared marketing sending capacity is not disclosed (a campaign waiting for it pauses with ip_capacity and resumes on its own).
• The cost of the content: converting and compiling a campaign that changed — and creating or editing one — spends one unit per 256 KB of content, up to 60 per account per minute; above that, 429 rate_limited with Retry-After. A campaign that did not change is checked from a cache and spends nothing.
• The brand warms up over days: in the first weeks an edition is spread over days, from the most recent subscribers to the oldest (estimatedDays). A pause by the bounce or complaint thresholds holds the whole brand, and only our support resumes it: 409 paused_for_review. The same thresholds apply to the brand’s campaigns added up over the last 24 hours: the brand is held even if no single campaign goes over them (splitting the audience into small campaigns does not escape it). An edition also respects today’s marketing sending capacity: when it runs out, the campaign waits with pauseReason ip_capacity and resumes by itself when there is room.
• The audience filter is TEXT: audienceFilter is the JSON of the filter inside a string, up to 64 KB — the size is checked before it is read (400 filter_too_large). The whole body is capped at 320 KB (413 payload_too_large).
• The preview only goes to the verified email of an active user of the account (400 preview_recipient_not_allowed; with reason: address_not_ascii when the address has a character outside ASCII), up to 20 a day and 60 attempts a day — the refused ones and the ones that do not go out count too (429 preview_limit).
• The weekly send: a campaign of kind model is the template of a recurring send — it does not send and is never approved or scheduled. With its recurrence (weekday from 1 to 7, Monday = 1; time HH:MM; leadDays from 1 to 6), in the model’s timezone, activate turns the recurrence on (running): each week the edition is created as a draft (kind edition, with parentId and editionDate), leadDays before its time. Nothing goes out without the approval of that edition, and approving the edition already schedules it for its time. One that was not approved by its time becomes skipped and the owner is notified; it only goes out with sendNow, until the next edition (409 edition_superseded after that). The previous edition is never sent again: if it is still going out when the next one starts, the rest of it is ended (errorCode superseded in the report). pause and resume turn the recurrence off and on; cancel ends the model and its draft editions. A pasted AWeber variable ({!firstname_fix}) leaves the campaign not ready (aweber_merge_tag): use the {{firstName}} syntax with a default instead.
• HTML body: a campaign takes contentHtml instead of contentMd. The HTML goes through a whitelist (p, h1 to h4, strong, em, code, pre, a, img, ul, ol, li, blockquote, hr, br) and goes inside the list layout, with the usual footer. A link with class="ovy-botao" goes out as a button. Scripts, CSS, tables and forms are removed, and the answer says what was removed in contentRemoved. The HTML is stored already clean, and that is what reading returns. One source only: send null on the other (400 invalid_content).
• The HTML comes back normalized: reading returns the whitelisted contentHtml, not what was sent. b becomes strong, i becomes em, div becomes p, h5 and h6 become h4; repeated whitespace becomes one space, and the whitespace at the edge of a link, bold or italic moves outside it (bold inside bold becomes one); {, } and ' come out as entities ({, }, '), like &, < and >. In a variable tag, the default comes back with &, < and > as entities: {{firstName|"Tom & Jerry"}} comes back as {{firstName|"Tom & Jerry"}}, and the email shows “Tom & Jerry”. Sending the value back as it came gives the same result.
• Concurrent writes: when concurrent writes — from any source, not only this account — hold the campaign for a few seconds, the change gives up instead of waiting longer — 503 campaign_busy with Retry-After (5 s, also in retryAfter). Nothing changed; retrying is safe.
• A campaign of another account answers the same as a nonexistent one (404 campaign_not_found). The request log of these routes keeps the ids, the states and the schedule; the subject, the content, the name, the filter and the preview to only show as { "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
}

Sequences

A sequence is a series of emails for one list: someone enters the list (or gets a tag) and receives email → wait → email… up to the exit. The sender, the footer (with the list’s postal address), the language and the brand are the list’s, as in campaigns, and each email is Markdown inside the list layout. Each email is rechecked at the moment it goes out: whoever left the list meanwhile, was deleted or is suppressed does not get the next one and leaves the sequence. Scopes read:sequences (read and the funnel) and write:sequences (create, edit, start, pause, stop and delete). With the human-approval lock on the key, write:sequences does not work: starting a sequence sends to every new subscriber, without a draft.

• The graph: the Loops format — rootId, nodeDataById and, on each node, typeName, nextNodeIds and payload. The first version is linear: the root is the trigger (ListTrigger: someone subscribed to the list or confirmed the subscription; TagTrigger: someone subscribed to the list got the tag), then SendEmailAction and TimerAction in any order, and ExitAction at the end — always right after an email. Up to 50 nodes. BranchNode, AudienceFilter and ExperimentBranchNode do not exist yet: 400 unsupported_node. A wrong graph is 400 invalid_graph with the field (the path of the node) and the reason. The rootId does not change after the sequence is created: a graph with another root is 400 invalid_graph with the reason root_changed, and the message says the stored root.
• The waits: amount of unit m, h or d, up to a year; with at (HH:MM, days only) the wait ends at that time in the sequence’s timezone — «3 days at 09:00» is the 3rd calendar day at 09:00 there, also across daylight saving changes.
• An import never triggers it: not the AWeber import, not a subscription with the import method, not a tag the import applies. Paused: whoever enters waits. Stopped: nobody else enters. Whoever subscribes while the sequence is paused enters and waits at the start: when it is started again they go on — and the waits only start counting then. reEligible lets someone who finished enter again on the next trigger — never while still in it.
• The states: draft → active (start checks everything and turns it on: it is the gesture that sends) ⇄ paused; any of them → stopped (whoever was waiting leaves). Starting freezes the list layout it checked and the sender: if the list sender or reply-to changes later, the sequence pauses (sender_changed) and the owner is notified. Sending that refuses the account or the content also pauses the sequence (pauseReason).
• Editing needs the revision you read (another one → 409 changed with the current one) and the sequence off (draft or paused; while active only the name changes). Whoever waits at a step the edit removed leaves the sequence (revision) when it runs again.
• Email body: the payload of a SendEmailAction takes contentMd or contentHtml, never both, with the whitelist of campaigns, and comes back normalized like theirs. In HTML, contentRemoved in the answer says what was removed. An email written in Markdown has no contentHtml field.
• Concurrent writes: when concurrent writes — from any source, not only this account — hold the sequence for a few seconds, the change gives up instead of waiting longer — 503 sequence_busy with Retry-After (5 s, also in retryAfter). Nothing changed; retrying is safe.
• Up to 100 live sequences per account and 50 created per day (UTC): 422 sequence_limit. A sequence of another account answers the same as a nonexistent one (404 sequence_not_found). The request log of these routes keeps the ids, the states and the revision; the name and the graph only show as { "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 }
}

Errors & limits

Errors are JSON with a stable error field (and, when useful, a message and context). Handle them by HTTP status and by error, not by the message.

# same call, same error, different countries
# (Cloudflare injects CF-IPCountry; you do not send anything)

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` is identical in all four. Only `message` changes.

ASCII-only addresses

The platform only accepts email addresses without accents: the local part and the domain in ASCII, with no control character. An internationalized domain (IDN) enters only in its punycode form — xn--…, and a valid xn--; written in Unicode, it is refused. Nothing is converted for you: swapping the accented letter for the plain one would send to another mailbox.

• On the API, every address input refuses with 400, reason: "address_not_ascii" and the field it came in. The error is the family of the field: bad_recipient on the recipients of POST /v1/send, invalid_email on contacts and bad_request on the others (the from, the address headers, suppressions, surveys, outbound allow/block lists and sending policies). The message does not repeat the address. Branch on the reason.
• When replying to a received message (POST /v1/inbound/:uid/reply), a receiving mailbox or an original sender outside ASCII become 409 no_mailbox or 422 no_reply_address, with the same reason.
• On SMTP submission, a MAIL FROM or RCPT TO outside ASCII gets 553 5.6.7; the From and the address headers of the DATA (Reply-To, Sender, To, Cc…) outside ASCII get 550 5.6.7 — the message is neither signed nor queued.
• On imports from the Migration Center, a row with an address outside ASCII is skipped and counted in the report — a suppression with its own reason, an AWeber contact among the invalid addresses; the rest of the batch comes in. The exception is an exit (unsubscribe, complaint or bounce) whose part before the @ is ASCII and whose international domain is written with accents: it comes in as the xn-- form of the same domain, so it keeps applying, and the report counts it separately.
• Unambiguous addresses. In the address fields of POST /v1/send — to, cc, bcc, from and the address headers in headers — the address must be written in full: "a@b.com" or "Name <a@b.com>", one per item (a list, or comma-separated). What a mail reader could read two ways is 400: two addresses separated by a space, a name without <…>, a comment after a bare address (a@b.com (Name)), a group (Name: …;) in to/cc/bcc, an item with no address in a list, and an @ (or the full-width ＠) in the display name. A Unicode space next to the address (NBSP, U+3000…) is reason: "address_not_ascii". The error is bad_recipient on the recipients and bad_request on the from and the headers. Nothing is rewritten for you: the ambiguous form is refused whole.
• What does not change: the display name may have accents ("Zoë" <zoe@example.com>); inbound keeps accepting senders with accents, and the inbound allow/block list keeps accepting an accented pattern to block them.

What is refused before the route

Some responses are produced before the route runs, and they apply to every operation — which is why the OpenAPI spec declares them on all of them:

• 400 invalid_json — with Content-Type: application/json, the body must be valid JSON and cannot be empty. If there is no body, don't send the header.
• 400 request_too_complex — the structure of the body exceeded a limit (with limit): a list with more than 10,000 items, more than 60,000 values in total (list items and object fields), more than 64 levels of nesting or a single number or literal longer than 32 characters. Text does not count — a large attachment is a single value. Split the work into more than one call.
• 413 payload_too_large — the body exceeded that route's limit, reported in limit (in bytes): 25 MB in general, 256 KB on the policy routes. The key is validated before the body is read: without a valid key the answer is 401 (or 403) and the body is not read.
• 415 unsupported_media_type — send the body as application/json (form and plain-text bodies are not accepted).
• 500 internal_error — a failure on our side. The detail stays in our logs, never in the body. Retry reads; retry a write only if it is idempotent or carries an idempotency key.
• 503 ip_rules_unavailable — the key has IP ranges bound to it and the check could not be performed right now. This is caution, not a denial: retry after Retry-After.
• 404 not_found — also for a route or method that does not exist; without a key, the response is 401.

Rate limit, quota and warm-up ramp

• Per key — with a valid credential, the general limit belongs to the key (or to the MCP OAuth connection): 600 req/min by default, whatever IP the call comes from. Exceeded → 429 rate_limited with the Retry-After: 60 header. Wait and retry.
• Per IP — without a valid credential (no Authorization, or an unknown, disabled or revoked key), the limit belongs to the IP: 600 req/min by default. Credential failures — only an unknown or malformed key or token — have their own limit of 20/min per IP (per /48 in IPv6): 429 too_many_auth_failures. A call without Authorization, an expired or revoked OAuth token and a disabled key do not count as failures. A valid key coming from an IP over the limit still gets through: an IP over the limit has 120 credential checks per minute, and only above them the answer is 429 too_many_auth_failures, until the minute turns, for every credential not validated in the last 5 minutes (one that was keeps getting through). Anything without the shape of one of our keys (ov_ + 48 lowercase hexadecimal characters) counts as a failure without being checked. Exceeded → 429 with the Retry-After: 60 header. Wait and retry.
• Tenant quota — 429 quota_exceeded with window (diária|mensal — Portuguese for daily|monthly, returned as is), used/limit and retryAfter in the body. Without window, quota_exceeded is the account's per-minute limit: slow down and retry. Per-service quota (plans) — service_quota_exceeded, with used/quota/effectiveCap in the body.
• Blocked account — 403 account_suspended (suspended account) and 403 account_unknown (account not found). These are not limits and do not clear on their own: they are 403, not 429, precisely so that your backoff does not retry — no amount of waiting fixes them. Contact support.
• Warm-up ramp — a daily cap per domain while its reputation warms up: warmup_cap_reached. Retry later.
• Backpressure — system saturated: queue_full. Back off exponentially and retry.

Golden rule for 429 and 503: exponential backoff with jitter, then retry. Validation 4xx errors (400/422) should not be retried without fixing the request.

API changes

What may change the response of a call that already worked — newest entry first.

• 2026-11-03 — SPF records over 4096 bytes are no longer evaluated. On POST /v1/domains/:id/verify, a record in the SPF chain (the domain’s own, or an include or redirect target) over 4096 bytes is no longer read: the SPF does not count as verified, spfProblem.code is record_too_large and detail.spf says which record to shorten (see the route). Before, it was evaluated in full and could pass.
• 2026-11-03 — this_outside_loop and loop_never_repeats in the campaign and sequence checks. In POST /v1/campaigns/:id/check, problems gained two codes. this_outside_loop: the content uses {{this}} or {{this.nome}} outside a {{#each}} — there is no item there: without a default, the send skipped whoever reached that part; with one, every contact got the default. Use {{nome}} (the engine does not read {{this.nome}} even inside a loop: there it is {{nome}} too). loop_never_repeats: the content (or the template) has a {{#each}} — contact fields are never lists, and the send skipped every contact that had the field (a contact without it got that part empty): remove the loop. Approving or scheduling with either of them gives 422 not_ready, and the same codes keep a sequence from starting (POST /v1/sequences/:id/start).
• 2026-11-03 — a per-account limit on domain checks. POST /v1/domains/:id/verify now answers 429 rate_limited above 60 checks per minute on the account, counted together with the dashboard’s (see the route). Before, only the key’s general limit applied. With the 429 nothing is checked: wait for Retry-After (also in retryAfter) and call again.
• 2026-11-03 — the subject of the campaign test email is now prefixed “[Test]”. On POST /v1/campaigns/:id/preview, the subject prefix was [Preview] (English list) and [Prévia] (Portuguese); it is now [Test] and [Teste] (see the route). The route, the body, the response and the codes (preview_limit…) do not change: only the subject text does. If you filter the test email by the old prefix, update the filter.
• 2026-11-02 — the domain’s SPF with optional: true on POST /v1/domains. In the default mode, the domain’s SPF record now comes with optional: true, like the tracking CNAME: mail sent through us passes SPF through our return address (see Add a domain). With the sender itself as the Return-Path (paid plan), it still comes without optional. The dashboard shows the same: «Recommended» in one mode, «Required» in the other.
• 2026-10-20 — Sequences in the API (marketing, experimental). New routes under /v1/sequences and two new scopes: read:sequences and write:sequences (see Sequences). No existing key gets these scopes — not even one with legacy scopes. With the human-approval lock on the key, write:sequences answers 403 scope_blocked_by_approval_lock, like the other scopes that would undo it.
• 2026-10-19 — Campaigns in the API (marketing, experimental). New routes under /v1/campaigns and three new scopes: read:campaigns, write:campaigns and send:campaigns (see Campaigns). No existing key gets these scopes — not even one with legacy scopes. With the human-approval lock on the key, write:campaigns and send:campaigns answer 403 scope_blocked_by_approval_lock, like the other scopes that would undo it.
• 2026-10-19 — an ambiguous address on POST /v1/send is now 400. What the address reader used to rewrite silently is now refused (see Unambiguous addresses): in to/cc/bcc, in the from and in the address headers of headers, two addresses separated by a space (before, one became the name and only the other received), a name without <…> and a comment after the address, a group in to/cc/bcc (before, its members vanished from the envelope), an item with no address in a list (before, dropped), an @ in the display name, and a Unicode space next to the address (before, an NBSP inside the local part sent to another mailbox). A Unicode space at the ends of to/cc/bcc is no longer trimmed: it is address_not_ascii, as on /v1/suppressions. A value in headers must be text or a list of texts: an object is 400. Also: imports store an exit with an international domain written in Unicode in its xn-- form, and SMTP submission refuses a From or an address header of the DATA outside ASCII with 550 5.6.7. Addresses written as "a@b.com" or "Name <a@b.com>" do not change.
• 2026-10-18 — ASCII-only addresses. Every address input now refuses characters outside ASCII with 400 and reason: "address_not_ascii" (see ASCII-only addresses). What changes for existing callers: a recipient with accents on POST /v1/send, accepted before, is now 400 bad_recipient; the internationalized domain of a contact (POST /v1/contacts), converted to punycode before, now has to arrive already as xn-- — and finding, tagging, unsubscribing or deleting it by the Unicode spelling (GET /v1/contacts/find and the other lookups by email), which used to find the converted contact, is now 400 invalid_email with the same reason; and SMTP submission refuses an accented MAIL FROM/RCPT TO with 553 5.6.7. ASCII addresses do not change.
• 2026-10-15 — detectedType and typeMismatch in the attachment manifest. Each item of attachments — in GET /v1/inbound/:uid and in the inbound.received webhook payload — gained detectedType (the type read from the first bytes of the file; null = no recognized signature) and typeMismatch (true when the sender's label and the content belong to different families). If you check the response against a closed schema, accept the new fields. Messages received before this date come with null and false. See Attachments.
• 2026-10-14 — mcpCallId in the API logs. Each item of GET /v1/logs and GET /v1/logs/:id gained the field mcpCallId (null outside the MCP server), and there are two new routes: GET /v1/logs/mcp and GET /v1/logs/mcp/:id (MCP log). If you check the response against a closed schema, accept the new field. In the stored bodies, attachment file names and the detail of safety signals now show only by their size.
• 2026-10-13 — return_path on POST /v1/send. The field now exists and only accepts "sender" and "platform" (see Return-Path). It used to be ignored, like any field the route does not know; now any other value answers 400 bad_request and nothing is sent — an email address included. Coming from SparkPost, where return_path is the envelope address: drop the field (the platform return address is the default) or, if the address was the sender itself, use "sender" (paid plans, with the include in the domain's SPF).