SubmitVerificationResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pricklymails-com/json-schema/pricklymails-com-submit-verification-response-schema.json",
  "title": "SubmitVerificationResponse",
  "description": "`POST /api/verify` response body.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pricklymails-com-openapi.json#/components/schemas/SubmitVerificationResponse",
  "type": "object",
  "required": [
    "job_uuid",
    "status",
    "estimated_cost",
    "idempotency_key",
    "replayed",
    "email"
  ],
  "properties": {
    "email": {
      "type": "string",
      "description": "Echo of the submitted email address.\nThe address is never stored; this echo comes from the request itself so the caller can correlate the response to\nits input."
    },
    "estimated_cost": {
      "type": "integer",
      "format": "int32",
      "description": "Total tokens reserved for the job.\nTokens for checks that did not complete are refunded when the job finishes.",
      "minimum": 0
    },
    "idempotency_key": {
      "type": "string",
      "description": "Resolved idempotency key.\nEither the client-supplied `Idempotency-Key` header or a generated UUID v4 when none was provided."
    },
    "job_uuid": {
      "type": "string",
      "description": "Public UUID of the persisted job. Use it with `GET /api/verify/{uuid}` to poll the result."
    },
    "replayed": {
      "type": "boolean",
      "description": "`true` when the response replays a prior submission made with the same idempotency key and the same email."
    },
    "status": {
      "type": "string",
      "description": "Current status of the job (`pending`, `queued`, `processing`, `completed`, `failed`, `canceled`)."
    },
    "suggestion": {
      "type": [
        "string",
        "null"
      ],
      "description": "Typo-corrected suggestion for the submitted email (e.g. `user@gmial.com` -> `user@gmail.com`), computed\nsynchronously at submit time.\nAbsent when no likely typo is detected.\nTransient like `email`: never stored, so `GET /api/verify/{uuid}` never carries it."
    },
    "verification": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/VerificationResultDto",
          "description": "The result, present when a `Prefer: wait` header held the response until the job finished."
        }
      ]
    }
  },
  "$defs": {
    "CheckDurationsDto": {
      "type": "object",
      "description": "Per-check elapsed time in milliseconds.\n\nField names mirror the per-check result object one-to-one so a client can pair a check's outcome with its timing.\n`null` means the check did not run (disabled, or short-circuited by an earlier step), never that it took zero\nmilliseconds.",
      "properties": {
        "catchall": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "minimum": 0
        },
        "disposable": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "minimum": 0
        },
        "free": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "minimum": 0
        },
        "mx": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "minimum": 0
        },
        "role": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "minimum": 0
        },
        "smtp": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "minimum": 0
        },
        "syntax": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "minimum": 0
        },
        "typo": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "minimum": 0
        }
      }
    },
    "ChecksDto": {
      "type": "object",
      "description": "Individual check results for a verified email address.",
      "required": [
        "syntax",
        "mx",
        "disposable",
        "role",
        "free",
        "typo",
        "smtp",
        "catchall"
      ],
      "properties": {
        "catchall": {
          "$ref": "#/$defs/ProviderFlagDto",
          "description": "Whether the domain is a catch-all server (accepts any address)."
        },
        "disposable": {
          "$ref": "#/$defs/ProviderFlagDto",
          "description": "Whether the domain is from a known disposable provider."
        },
        "free": {
          "$ref": "#/$defs/ProviderFlagDto",
          "description": "Whether the domain is a known free webmail provider (gmail, yahoo, etc.). Free providers are informational and\ndo not change the quality score."
        },
        "mx": {
          "$ref": "#/$defs/MxCheckDto",
          "description": "MX record check result."
        },
        "role": {
          "$ref": "#/$defs/ProviderFlagDto",
          "description": "Whether the local-part is a known role-based address (info@, support@, etc.). Role addresses are a risk factor\nand reduce the quality score."
        },
        "smtp": {
          "$ref": "#/$defs/SmtpCheckDto",
          "description": "SMTP deliverability probe result."
        },
        "syntax": {
          "type": "boolean",
          "description": "Whether the email syntax is valid."
        },
        "typo": {
          "$ref": "#/$defs/TypoCheckDto",
          "description": "Typo detection result."
        }
      }
    },
    "MxCheckDto": {
      "oneOf": [
        {
          "type": "object",
          "description": "The check ran.",
          "required": [
            "valid",
            "records"
          ],
          "properties": {
            "records": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "MX record hostnames found for the domain."
            },
            "valid": {
              "type": "boolean",
              "description": "Whether the domain publishes at least one usable mail exchanger.\n`false` even when `records` is non-empty for an RFC 7505 null MX, exchangers that resolve to no address, or\na known parking placeholder; the `reason` names which."
            }
          }
        },
        {
          "type": "object",
          "description": "The check was not run.",
          "required": [
            "status"
          ],
          "properties": {
            "status": {
              "type": "string",
              "description": "Always `\"skipped\"`."
            }
          }
        }
      ],
      "description": "MX record check result.\n\nRenders as `{ \"status\": \"skipped\" }` when the MX check did not run (excluded from the caller's check set), the same\nshape the `smtp` check uses for its own skipped state, so an unrun check never reads as a negative `valid: false`\nresult. When the check did run, it renders as `{ \"valid\": bool, \"records\": [...] }`."
    },
    "ProviderFlagDto": {
      "oneOf": [
        {
          "type": "boolean",
          "description": "The check ran; carries the real boolean result."
        },
        {
          "type": "object",
          "description": "The check was not run.",
          "required": [
            "status"
          ],
          "properties": {
            "status": {
              "type": "string",
              "description": "Always `\"skipped\"`."
            }
          }
        }
      ],
      "description": "A boolean provider or risk-flag check result (`disposable`, `role`, `free`, `catchall`).\n\nRenders as a bare `true`/`false` when the check ran, or as `{ \"status\": \"skipped\" }` when it did not run (excluded\nfrom the caller's check set), the same skipped shape the `mx` and `smtp` checks use, so an unrun check never reads\nas a definitive negative result."
    },
    "SmtpCheckDto": {
      "type": "object",
      "description": "SMTP deliverability probe result.",
      "required": [
        "status"
      ],
      "properties": {
        "status": {
          "$ref": "#/$defs/SmtpStatusDto",
          "description": "SMTP probe outcome: `deliverable` (the server accepted the `RCPT TO` command), `undeliverable` (the server\npermanently rejected the recipient, 5xx), `unknown` (no definitive answer: a temporary refusal, a timeout, a\nconnection failure, or a server that refused the probe itself), or `skipped` (not requested, or not\nneeded because the answer was already known)."
        }
      }
    },
    "SmtpStatusDto": {
      "type": "string",
      "description": "Outcome of the SMTP probe.",
      "enum": [
        "deliverable",
        "undeliverable",
        "unknown",
        "skipped"
      ]
    },
    "TypoCheckDto": {
      "type": "object",
      "description": "Typo detection result.",
      "required": [
        "detected"
      ],
      "properties": {
        "detected": {
          "type": "boolean",
          "description": "Whether a domain typo was detected."
        },
        "suggested_domain": {
          "type": [
            "string",
            "null"
          ],
          "description": "Corrected domain only (e.g. `\"gmail.com\"`), present on `GET /api/verify/{uuid}` when a typo was detected.\nOnly the domain is returned (zero-retention policy); the caller already has the local part to combine it with."
        },
        "suggestion": {
          "type": [
            "string",
            "null"
          ],
          "description": "Full corrected address (e.g. `\"user@gmail.com\"`), only ever present on the synchronous submit response where the\nraw email is available in-request.\nAlways absent on `GET /api/verify/{uuid}`, because the submitted address is never stored (zero-retention\npolicy); `suggested_domain` is that path's equivalent."
        }
      }
    },
    "VerificationResultDto": {
      "type": "object",
      "description": "Per-email verification projection.\n\nEmail addresses are never stored (zero-retention policy); only keyed hashes are kept and returned here. The `checks`\nobject carries the per-step breakdown.\n`checks.typo.suggestion` (the full corrected address) is always absent on this path;\n`checks.typo.suggested_domain` (the corrected domain only) is present instead when a typo was detected.",
      "required": [
        "email_hash",
        "domain_hash",
        "status",
        "reason",
        "score",
        "recommendation",
        "verified_at",
        "checks",
        "durations"
      ],
      "properties": {
        "checks": {
          "$ref": "#/$defs/ChecksDto",
          "description": "Per-check breakdown of the verification result."
        },
        "domain_hash": {
          "type": "string",
          "description": "Keyed hash of the email domain."
        },
        "duration_ms": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "minimum": 0
        },
        "durations": {
          "$ref": "#/$defs/CheckDurationsDto",
          "description": "Per-check elapsed time in milliseconds."
        },
        "email_hash": {
          "type": "string",
          "description": "Keyed hash of the normalized email address."
        },
        "reason": {
          "type": "string"
        },
        "recommendation": {
          "type": "string",
          "description": "Deterministic list-cleaning action derived from `status`, `reason`, and the typo flag: one of `\"remove\"`,\n`\"send\"`, or `\"review\"`. A presentation layer on top of the honest verdict above, not a replacement for it."
        },
        "score": {
          "type": "integer",
          "format": "int32",
          "minimum": 0
        },
        "status": {
          "type": "string"
        },
        "verified_at": {
          "type": "string"
        }
      }
    }
  }
}