VerifyEntry

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mailprobe-dev/json-schema/mailprobe-dev-verify-entry-schema.json",
  "title": "VerifyEntry",
  "description": "A verification result, or — when the submitted entry was not a JSON string — an `InvalidEntry` placeholder that keeps the array aligned with the input.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mailprobe-dev-openapi.yml#/components/schemas/VerifyEntry",
  "oneOf": [
    {
      "$ref": "#/$defs/VerifyResult"
    },
    {
      "$ref": "#/$defs/InvalidEntry"
    }
  ],
  "$defs": {
    "InvalidEntry": {
      "type": "object",
      "description": "Returned in place of a result when the submitted entry was not a JSON string. It has no `result` field, and the credit for that slot is still consumed.",
      "required": [
        "error"
      ],
      "properties": {
        "email": {
          "description": "The offending entry, echoed back as submitted — any JSON value, since only strings are verifiable."
        },
        "error": {
          "type": "string",
          "enum": [
            "invalid"
          ]
        }
      }
    },
    "VerifyResult": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "description": "The submitted address, lower-cased and trimmed."
        },
        "result": {
          "type": "string",
          "description": "Raw verdict from the verification pipeline.",
          "enum": [
            "deliverable",
            "undeliverable",
            "catch-all",
            "unknown"
          ]
        },
        "status": {
          "type": "string",
          "description": "Actionable rollup above `result` — the field most integrations filter on. `valid` = deliverable and clean; `invalid` = bad syntax, no MX, or rejected; `risky` = accepted but uncertain (catch-all, role-based, disposable, or a provider that blocks probing such as Microsoft consumer domains); `unknown` = could not be determined by our probe: transient (network-level failure, unresolved MX, greylisting) or a sender-policy rejection that will recur. Filtering out `risky` discards deliverable Microsoft mailboxes — score them instead.",
          "enum": [
            "valid",
            "risky",
            "invalid",
            "unknown"
          ]
        },
        "score": {
          "type": "integer",
          "description": "Deterministic 0-100 confidence value derived only from the signals in this response — no model, no stored data. Rough bands: 90+ deliverable and clean, ~65 probe-blocking provider (well-formed address on a live major-provider MX), ~55 catch-all, ~50 greylisted, <=15 disposable, 0 invalid. Role-based and suspected-typo addresses are penalised.",
          "minimum": 0,
          "maximum": 100
        },
        "catch_all": {
          "type": "boolean",
          "description": "The domain accepts every address, so the mailbox cannot be confirmed individually."
        },
        "reason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why the verdict is not a plain `deliverable`, `null` otherwise. `accept_all` = catch-all domain; `greylisting` is a temporary (4xx) deferral at RCPT TO: the server evaluated the recipient and asked us to come back, so the mailbox likely exists. `deferred` is a temporary (4xx) refusal earlier in the conversation (banner, EHLO or MAIL FROM) — the server turned us away before we could ask about the mailbox, so it tells you nothing about the address and scores lower. Both are worth retrying and both carry `retry_after`. `provider_blocks_probe` is a server where probing is structurally impossible, so the address could not be judged: either a provider known in advance to block probes, or any server answering `530 Authentication required` — it accepts no unauthenticated transaction from anyone, which says nothing about our sender and nothing about the mailbox. `no_banner`, `ehlo_rejected` and `mail_from_rejected` mean the server refused our probe permanently (5xx) at that step and will refuse it again; `unexpected_code` is a permanent (5xx) refusal that named no cause, or a reply outside every known class (neither 250/251, nor 4xx, nor 5xx), and is worth reporting to us; `mailbox_full` = the server confirmed the mailbox but it is over quota (4.2.2), so nothing can be delivered today; `policy_rejected` = the receiving server refused the sender (our IP, HELO or MAIL FROM) with a 5.7.x status — it says nothing about the mailbox. The enhanced status decides, not the reply code: a `571` or a non-standard 5xx carrying 5.7.x is the same refusal as a `554 5.7.1`; `mx_unresolved` = the MX host could not be resolved: transient when `result` is `unknown` (our resolver got no answer, retry later), permanent when `result` is `undeliverable` (DNS says the host does not exist or has no address).",
          "enum": [
            "accept_all",
            "connection_error",
            "deferred",
            "ehlo_rejected",
            "greylisting",
            "invalid_syntax",
            "mail_from_rejected",
            "mailbox_full",
            "mx_private_ip",
            "mx_unresolved",
            "no_banner",
            "no_mx",
            "policy_rejected",
            "protocol_error",
            "provider_blocks_probe",
            "timeout",
            "unexpected_code",
            null
          ]
        },
        "retry_after": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Suggested wait, in seconds, whenever the server answered with a temporary (4xx) deferral at any step — greylisting, busy server, temporary sender block. `null` when no retry is advised."
        },
        "smtp_code": {
          "type": [
            "integer",
            "null"
          ],
          "description": "SMTP reply code observed on the RCPT probe, `null` when no handshake took place."
        },
        "smtp_enhanced_code": {
          "type": [
            "string",
            "null"
          ],
          "description": "Enhanced status code (RFC 3463) the server sent alongside the reply, exactly as written — `null` when it sent none. It is what disambiguates `smtp_code`, which cannot: a bare `550` is `5.1.1` when the mailbox does not exist and `5.7.x` when the server refused the sender (our IP, HELO or MAIL FROM) and said nothing about the mailbox. Class `4` values are temporary — `4.2.2` is the over-quota mailbox reported as `mailbox_full`."
        },
        "syntax": {
          "type": "boolean",
          "description": "The address is RFC-valid."
        },
        "mx_found": {
          "type": "boolean",
          "description": "The domain publishes usable MX records."
        },
        "smtp_check": {
          "type": "boolean",
          "description": "An SMTP conversation actually took place (false when the server was unreachable)."
        },
        "disposable": {
          "type": "boolean",
          "description": "Domain listed as disposable / throwaway."
        },
        "role_based": {
          "type": "boolean",
          "description": "Local part is a role alias (info, support, contact…) rather than a person."
        },
        "free_provider": {
          "type": "boolean",
          "description": "Domain belongs to a free consumer mailbox provider."
        },
        "did_you_mean": {
          "type": [
            "string",
            "null"
          ],
          "description": "Suggested correction for a likely typo (e.g. `gmial.com` -> `gmail.com`), `null` when the domain looks intentional."
        },
        "mx_records": {
          "type": "array",
          "description": "MX hostnames found for the domain, in priority order, capped at the first 10. Empty when none.",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}