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):

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.

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": "{{firstName}}, your order has arrived",
    "html": "<p>Hello {{firstName}}, use coupon {{ coupon | \"SAVE10\" }}.</p>",
    "text": "Hello {{firstName}}, 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": "{{firstName}}, your order has arrived",
    "html": "<p>Hello {{firstName}}, use coupon {{ coupon | \"SAVE10\" }}.</p>",
    "text": "Hello {{firstName}}, 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": { "firstName": "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 90 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 (html, text, content…) become their size, and each template variable (data) keeps its name and loses its value. For the inbound content routes and the two log routes the response is not stored: only its size.
• 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. 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
    }
  ],
  "next_cursor": "bDoxNzU5OTMyMjA3NDgxLjQ4MjEz"
}

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

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 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. 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, recipient, subject, hour and day of the week in the account's time zone. Operators equals, contains, starts_with, ends_with, matches (a glob with * — never a regex), 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.

  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) returns the same id instead of replying twice. 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). 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[].

  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 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 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 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).
  "attachments": [
    { "ord": 1, "filename": "quote.pdf", "contentType": "application/pdf",
      "sizeBytes": 14233, "sha256": "9f2c…",
      "url": "/v1/inbound/b71e0c34-…/attachments/1" },
    { "ord": 2, "filename": "logo.png", "contentType": "image/png",
      "sizeBytes": 3180, "sha256": "0ab7…",
      "url": "/v1/inbound/b71e0c34-…/attachments/2" }
  ],

  // 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 per-IP cap, these routes have a 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,
    "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`.
  "attachments": [
    { "ord": 1, "filename": "quote.pdf", "contentType": "application/pdf",
      "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",
    "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(payload) {
  // 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(payload.eventId);
  if (!isNew) return;              // already processed — answer 2xx and move on

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

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 payload = JSON.parse(raw.toString('utf8'));
  enqueueForProcessing(payload);    // 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; }

$payload = json_decode($raw, true);
enqueueForProcessing($payload);    // 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.

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": "invalid@example.com", "reason": "hard_bounce",
      "source": "bounce", "createdAt": "2026-07-20T09:11:00.000Z" }
  ],
  "total": 1, "limit": 100, "offset": 0
}

curl -X POST https://api.oveyon.com/v1/suppressions \
  -H "Authorization: Bearer $OVEYON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "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. Since it returns no error at all, the way to see it through the API is 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 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 per-IP 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). 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 per-IP 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)" },
    { "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" }
}

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.

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.
• 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 body is read up to the limit before the key is validated.
• 415 unsupported_media_type — send the body as application/json.
• 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 IP — a limit on requests/min and on auth failures/min. 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.