pricklymails-com Verification API

openapi: 3.2.0
info:
  title: Pricklymails Com Verification API
  version: 0.9.0
  contact:
    email: support@pricklymails.com
  license:
    name: Proprietary
  description: 'Operations tagged verification across 2 of this provider''s published API definitions: pricklymails-com-openapi.json, pricklymails-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Verification
  description: Verify one address and read its result.
paths:
  /api/verify:
    post:
      tags:
      - Verification
      summary: Submits a single-email verification job
      description: 'Authenticated with a `pm_live_` or `pm_test_` API key, a dashboard session, or a scoped agent session token; the `email:verify:single` scope is required (a dashboard session always has it). A key-authed submit runs the checks enabled on the key and bills the key''s account. A `pm_test_` key takes the sandbox path: the response contract is the same, but no tokens are reserved and the result is a deterministic canned one chosen by the email''s local-part prefix, with no real probe. A session submit has no key: it always runs for real, bills the caller''s own account, and runs the default checks of the caller''s plan. An optional `checks` list runs those checks instead, each allowed on the caller''s plan (`403` otherwise), with their dependencies added (`smtp` brings `mx`, `catchall` brings both). Tokens are reserved when the job is accepted; a request that fails validation reserves nothing. Send an `Idempotency-Key` header to make retries safe: a replay of the same key and email returns `200` with an `Idempotent-Replayed: true` header instead of creating a second job. Send `Prefer: wait=N` to hold the response up to `N` seconds (at most 12) while the job runs: if it finishes in time, the response is `200` with the result in `verification`; otherwise it is the usual `202`, and the job keeps running. The job is processed the same way either way.'
      operationId: submit_verification
      parameters:
      - name: Prefer
        in: header
        description: '`wait=N`: hold the response up to `N` seconds (at most 12) for the result. Answered with `Preference-Applied: wait=N`.'
        required: false
        schema:
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitVerificationRequest'
        required: true
      responses:
        '200':
          description: 'Idempotent replay of a prior submission, or a job that finished within the `Prefer: wait` window, its result in `verification`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitVerificationResponse'
        '202':
          description: Job accepted and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitVerificationResponse'
        '400':
          description: An unknown check name in `checks`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '402':
          description: Wallet balance too low to reserve the job's cost.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: Caller is missing the `email:verify:single` scope, or a requested check is not allowed for the plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
  /api/verify/{uuid}:
    get:
      tags:
      - Verification
      summary: Returns a verification job and its per-email results
      description: Authenticated like `POST /api/verify` and limited to the caller's own jobs; a uuid that belongs to another account returns the same 404 as an unknown uuid. While the job has not reached a final status, the response carries a `Retry-After` header suggesting a poll delay.
      operationId: get_verification
      parameters:
      - name: uuid
        in: path
        description: Public UUID of the verification job.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The job and its per-email verification results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVerificationResponse'
        '400':
          description: Malformed job `uuid`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: Caller is missing the `results:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: No job with that uuid belongs to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
components:
  schemas:
    ApiErrorBody:
      type: object
      description: 'Error envelope returned with every non-success status: `{ "error": { "code", "message" } }`.'
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
          description: Error detail.
    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.

              `false` even when `records` is non-empty for an RFC 7505 null MX, exchangers that resolve to no address, or

              a 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.


        Renders as `{ "status": "skipped" }` when the MX check did not run (excluded from the caller''s check set), the same

        shape the `smtp` check uses for its own skipped state, so an unrun check never reads as a negative `valid: false`

        result. When the check did run, it renders as `{ "valid": bool, "records": [...] }`.'
    GetVerificationResponse:
      type: object
      description: '`GET /api/verify/{uuid}` response body.'
      required:
      - job_uuid
      - status
      - verifications
      properties:
        job_uuid:
          type: string
          description: Public UUID of the job.
        status:
          type: string
          description: Current status of the job.
        verifications:
          type: array
          items:
            $ref: '#/components/schemas/VerificationResultDto'
          description: 'Per-email verification rows.

            Empty while the job is still pending or queued; populated once results are available.'
    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.

            Only 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

            raw email is available in-request.

            Always absent on `GET /api/verify/{uuid}`, because the submitted address is never stored (zero-retention

            policy); `suggested_domain` is that path''s equivalent.'
    CheckDurationsDto:
      type: object
      description: 'Per-check elapsed time in milliseconds.


        Field names mirror the per-check result object one-to-one so a client can pair a check''s outcome with its timing.

        `null` means the check did not run (disabled, or short-circuited by an earlier step), never that it took zero

        milliseconds.'
      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
    SmtpCheckDto:
      type: object
      description: SMTP deliverability probe result.
      required:
      - status
      properties:
        status:
          $ref: '#/components/schemas/SmtpStatusDto'
          description: 'SMTP probe outcome: `deliverable` (the server accepted the `RCPT TO` command), `undeliverable` (the server

            permanently rejected the recipient, 5xx), `unknown` (no definitive answer: a temporary refusal, a timeout, a

            connection failure, or a server that refused the probe itself), or `skipped` (not requested, or not

            needed because the answer was already known).'
    ApiErrorDetail:
      type: object
      description: Detail of an error response.
      required:
      - code
      properties:
        code:
          type: string
          description: Stable key identifying the error (for example `"verify.invalid_uuid"`). Clients localize by this key.
        message:
          type:
          - string
          - 'null'
          description: 'Present on most error kinds and equal to `code`; the API returns no localized text.

            Absent for error kinds that carry no extra detail.'
    SubmitVerificationRequest:
      type: object
      description: '`POST /api/verify` request body.'
      required:
      - email
      properties:
        checks:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'Optional explicit check names, each allowed on the caller''s plan; defaults to the key''s enabled checks, or to

            the plan''s default checks for a dashboard session.'
        email:
          type: string
          description: Email address to verify.
    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`).


        Renders as a bare `true`/`false` when the check ran, or as `{ "status": "skipped" }` when it did not run (excluded

        from the caller''s check set), the same skipped shape the `mx` and `smtp` checks use, so an unrun check never reads

        as a definitive negative result.'
    ChecksDto:
      type: object
      description: Individual check results for a verified email address.
      required:
      - syntax
      - mx
      - disposable
      - role
      - free
      - typo
      - smtp
      - catchall
      properties:
        catchall:
          $ref: '#/components/schemas/ProviderFlagDto'
          description: Whether the domain is a catch-all server (accepts any address).
        disposable:
          $ref: '#/components/schemas/ProviderFlagDto'
          description: Whether the domain is from a known disposable provider.
        free:
          $ref: '#/components/schemas/ProviderFlagDto'
          description: 'Whether the domain is a known free webmail provider (gmail, yahoo, etc.). Free providers are informational and

            do not change the quality score.'
        mx:
          $ref: '#/components/schemas/MxCheckDto'
          description: MX record check result.
        role:
          $ref: '#/components/schemas/ProviderFlagDto'
          description: 'Whether the local-part is a known role-based address (info@, support@, etc.). Role addresses are a risk factor

            and reduce the quality score.'
        smtp:
          $ref: '#/components/schemas/SmtpCheckDto'
          description: SMTP deliverability probe result.
        syntax:
          type: boolean
          description: Whether the email syntax is valid.
        typo:
          $ref: '#/components/schemas/TypoCheckDto'
          description: Typo detection result.
    VerificationResultDto:
      type: object
      description: 'Per-email verification projection.


        Email addresses are never stored (zero-retention policy); only keyed hashes are kept and returned here. The `checks`

        object carries the per-step breakdown.

        `checks.typo.suggestion` (the full corrected address) is always absent on this path;

        `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: '#/components/schemas/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: '#/components/schemas/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"`,

            `"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
    SubmitVerificationResponse:
      type: object
      description: '`POST /api/verify` response body.'
      required:
      - job_uuid
      - status
      - estimated_cost
      - idempotency_key
      - replayed
      - email
      properties:
        email:
          type: string
          description: 'Echo of the submitted email address.

            The address is never stored; this echo comes from the request itself so the caller can correlate the response to

            its input.'
        estimated_cost:
          type: integer
          format: int32
          description: 'Total tokens reserved for the job.

            Tokens for checks that did not complete are refunded when the job finishes.'
          minimum: 0
        idempotency_key:
          type: string
          description: 'Resolved idempotency key.

            Either 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

            synchronously at submit time.

            Absent when no likely typo is detected.

            Transient like `email`: never stored, so `GET /api/verify/{uuid}` never carries it.'
        verification:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/VerificationResultDto'
            description: 'The result, present when a `Prefer: wait` header held the response until the job finished.'
  securitySchemes:
    bearer_api_key:
      type: http
      scheme: bearer
      description: A `pm_live_*` or `pm_test_*` API key.
    jwt:
      type: http
      scheme: bearer
      description: A short-lived token from `/api/auth/login`, or `/oauth/token` for an agent.
x-refined-from:
- pricklymails-com-openapi.json
- pricklymails-com-openapi.yaml