AntispamResultDto

inspectionIdstringrequired

Unique id for this inspection — correlate it with the webhook delivery and your logs.

Example: 26bc4f0d-ac21-407b-bf21-bb452cd17319

verdictstringrequired

The authoritative classification to act on. It is NOT a plain score threshold, so key your logic off this field, not off score.

Possible values: [clean, spam, phishing]

Example: phishing

scorenumberrequired

Severity / confidence, 0–100 (higher = more dangerous). A strength indicator, NOT the decision: use verdict to act, score for how strong the signal is. Rough guide: <25 low, 25–59 elevated, ≥60 high.

Possible values: >= 0 and <= 100

Example: 46

modelAvailablebooleanrequired

True when the full AI analysis was applied; false = a reduced analysis was used.

Example: true

rationalestring

Plain-language, customer-safe explanation of the verdict — safe to surface to end users.

Example: Dangerous: this message uses a shortened link and pushes you to “verify” a delivery, a common scam. Do not click it; go to the delivery company’s official app instead.

layers object[]required

Per-layer evidence behind the verdict. Each entry has a layer id, a 0–100 contribution, and human-readable signal strings.

Array [

layerstringrequired

Evidence layer identifier.

Example: L2

scorenumberrequired

This layer's risk contribution, 0–100.

Example: 20

signalsstring[]required

Human-readable evidence signals produced by this layer.

Example: ["lang:en","url-shortener"]

labelstring

This layer's own classification (AI layers only).

Possible values: [clean, spam, phishing]

Example: phishing

rationalestring

AI rationale for this layer (L4).

modelAvailableboolean

False when the AI model was unreachable (the check degrades to heuristics + threat-intel).

Example: true

latencyMsnumber

Wall-clock latency of this layer's model/provider call, in ms.

Example: 1969

usage object

Token usage for AI layers.

modelstring

ROUNDBOX AI model that produced this layer (Henrietta classifier).

Example: henrietta-classify

inputTokensnumber

Example: 165

outputTokensnumber

Example: 59

reasoningTokensnumber

Example: 0

cachedInputTokensnumber

Example: 0

]

urlsstring[]

URLs/hosts detected in the message (including any decoded from QR codes). Each is checked against ROUNDBOX threat intelligence.

Example: ["http://bit.ly/verify-now"]

langstring

Detected message language (ISO-639-1).

Example: en

attachments object[]

Per-attachment reputation summary. NOTE: the antispam API inspects the message body + URLs; full malware scanning of files (including password-protected archives) is the dedicated POST /api/v1/files endpoint.

Array [

filenamestringrequired

Example: invoice.pdf

sha256stringrequired

SHA-256 of the attachment.

Example: e3b0c44298fc1c14…

dispositionstringrequired

Hash-reputation disposition of the attachment (see note on the top-level field).

Possible values: [malicious, suspicious, clean, unknown]

Example: clean

]

elapsedMsnumber

Total time the whole inspection took, end to end, in milliseconds.

Example: 6884

filescan object[]

Per-attachment deep file-scan results (nested file-scan jobs). Present on the async poll result/webhook; pending in the sync response.

Array [

filenamestringrequired

Example: invoice.pdf

sha256string

SHA-256 of the attachment.

jobIdstring

Child file-scan job id — poll GET /api/v1/files/:jobId.

statusstringrequired

Possible values: [pending, done, failed]

Example: done

verdictobject

Customer-safe file verdict, present when status=done (no cost fields).

]

filescan_job_idsstring[]

Ids of the nested file-scan jobs spawned for attachments — poll each via GET /api/v1/files/:jobId.

Example: ["9f1c2e00-0000-0000-0000-000000000001"]

blockedboolean

True when the message was blocked by an orthogonal policy (e.g. offensive language). Key drop/allow logic off this AND verdict.

Example: true

blockReasonstring

Why the message was blocked. Only present when blocked is true.

Possible values: [offensive-language]

Example: offensive-language

offensive object

Offensive-language check result — present only when the check ran (opt-in).

severitystringrequired

Possible values: [none, low, medium, high]

Example: high

categoriesstring[]required

Offensive-content categories found (masked evidence only).

Example: ["profanity","insult"]

matchedCountnumberrequired

How many offending items were found (count only).

Example: 2

maskedRationalestring

Masked, customer-safe explanation — never reprints the offending words.

Example: Message blocked for offensive language (profanity, insult).

AntispamResultDto

{
  "inspectionId": "26bc4f0d-ac21-407b-bf21-bb452cd17319",
  "verdict": "phishing",
  "score": 46,
  "modelAvailable": true,
  "rationale": "Dangerous: this message uses a shortened link and pushes you to “verify” a delivery, a common scam. Do not click it; go to the delivery company’s official app instead.",
  "layers": [
    {
      "layer": "L2",
      "score": 20,
      "signals": [
        "lang:en",
        "url-shortener"
      ],
      "label": "phishing",
      "rationale": "string",
      "modelAvailable": true,
      "latencyMs": 1969,
      "usage": {
        "model": "henrietta-classify",
        "inputTokens": 165,
        "outputTokens": 59,
        "reasoningTokens": 0,
        "cachedInputTokens": 0
      }
    }
  ],
  "urls": [
    "http://bit.ly/verify-now"
  ],
  "lang": "en",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "sha256": "e3b0c44298fc1c14…",
      "disposition": "clean"
    }
  ],
  "elapsedMs": 6884,
  "filescan": [
    {
      "filename": "invoice.pdf",
      "sha256": "string",
      "jobId": "string",
      "status": "done",
      "verdict": {}
    }
  ],
  "filescan_job_ids": [
    "9f1c2e00-0000-0000-0000-000000000001"
  ],
  "blocked": true,
  "blockReason": "offensive-language",
  "offensive": {
    "severity": "high",
    "categories": [
      "profanity",
      "insult"
    ],
    "matchedCount": 2,
    "maskedRationale": "Message blocked for offensive language (profanity, insult)."
  }
}