pricklymails-com Jobs API

openapi: 3.2.0
info:
  title: Pricklymails Com Jobs API
  version: 0.9.0
  contact:
    email: support@pricklymails.com
  license:
    name: Proprietary
  description: 'Operations tagged jobs 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: Jobs
  description: Your verification jobs and their details.
paths:
  /api/jobs:
    get:
      tags:
      - Jobs
      summary: Returns a paginated list of the caller's standalone verification jobs, newest…
      description: Jobs that belong to a batch are excluded; read those through `GET /api/batches/{uuid}/results`. Accepts optional `limit` (default 20, cap 96) and `offset` (default 0) query params, plus optional filters (`status`, `from`/`to` on `created_at`, `search` as a uuid prefix, `verdict` as the sole verification's deliverability verdict), combined with AND and applied before pagination. Both `status` and `verdict` accept a comma-separated list of values (e.g. `status=completed,failed`), OR'd together within the filter. Also accepts an optional sort (`sort` = `created_at` | `score` | `status` | `verdict` | `uuid`, `order` = `desc` | `asc`); an unknown `sort`, `order`, `status`, or `verdict` value is a `400`. Authenticated with a dashboard session, or an API key or agent token holding the `results:read` scope.
      operationId: list_jobs
      parameters:
      - name: limit
        in: query
        description: Number of jobs to return (default 20, cap 96).
        required: false
        schema:
          type: integer
          format: int64
      - name: offset
        in: query
        description: Number of jobs to skip (default 0).
        required: false
        schema:
          type: integer
          format: int64
      - name: status
        in: query
        description: Comma-separated list of lifecycle statuses to match, OR'd together (e.g. `completed,failed`).
        required: false
        schema:
          type: string
      - name: from
        in: query
        description: Inclusive lower bound on `created_at` (RFC 3339).
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: Inclusive upper bound on `created_at` (RFC 3339).
        required: false
        schema:
          type: string
          format: date-time
      - name: search
        in: query
        description: Case-insensitive prefix match on the job's public uuid.
        required: false
        schema:
          type: string
      - name: verdict
        in: query
        description: Comma-separated list of deliverability verdicts to match, OR'd together (e.g. `valid,risky`).
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: 'Column to order by: `created_at` (default), `score`, `status`, `verdict`, or `uuid`.'
        required: false
        schema:
          type: string
      - name: order
        in: query
        description: 'Order direction: `desc` (default) or `asc`.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Paginated standalone-job list, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListJobsResponse'
        '400':
          description: Unknown `sort`, `order`, `status`, or `verdict` value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid API key, session token, or agent token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: The key or agent token lacks the `results:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
  /api/jobs/{uuid}:
    get:
      tags:
      - Jobs
      summary: Returns one of the caller's jobs together with its per-check verification detail
      description: Returns the same body as `GET /api/verify/{uuid}`, and accepts the same credentials (`results:read` scope). A uuid that belongs to another account returns the same 404 as an unknown uuid.
      operationId: get_job
      parameters:
      - name: uuid
        in: path
        description: Public uuid of the job.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The job and its per-check verification detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVerificationResponse'
        '400':
          description: Malformed `uuid`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid API key, session token, or agent token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: The key or agent token lacks 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'
      security:
      - bearer_api_key: []
      - jwt: []
components:
  schemas:
    JobItem:
      type: object
      description: A single job summary item in the response list.
      required:
      - uuid
      - status
      - email_count
      - created_at
      properties:
        created_at:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp.
        email_count:
          type: integer
          format: int32
          description: 'Number of email addresses associated with this job.

            Raw email addresses are never stored (zero-retention policy); only the count is surfaced.'
          minimum: 0
        error:
          type:
          - string
          - 'null'
          description: 'The job''s failure reason, populated only when the job''s lifecycle status is `"failed"`.

            `null` for every other job.'
        score:
          type:
          - integer
          - 'null'
          format: int32
          description: 'Quality score (0-100) of the job''s sole verification.

            Populated only for a single-email job (`email_count == 1`) whose email already has a result; `null` for

            multi-email jobs (no single representative verdict) and for results still pending.'
          minimum: 0
        status:
          type: string
          description: Current lifecycle status (e.g. `"pending"`, `"completed"`).
        uuid:
          type: string
          description: Public UUID of the job.
        verdict:
          type:
          - string
          - 'null'
          description: 'Deliverability verdict of the job''s sole verification (e.g. `"valid"`, `"risky"`), the same stable strings

            `POST /api/verify` returns. `null` under the same condition as `score`.'
    ListJobsResponse:
      type: object
      description: JSON response body for `GET /api/jobs`.
      required:
      - jobs
      - limit
      - offset
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/JobItem'
          description: List of jobs, newest first.
        limit:
          type: integer
          format: int64
          description: Pagination limit used for this page (effective after clamping).
        offset:
          type: integer
          format: int64
          description: Pagination offset used for this page.
    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
    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.'
    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).'
    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
  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