pricklymails-com Batches API

openapi: 3.2.0
info:
  title: Pricklymails Com Batches API
  version: 0.9.0
  contact:
    email: support@pricklymails.com
  license:
    name: Proprietary
  description: 'Operations tagged batches 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: Batches
  description: 'Verify a list of addresses: submit, append, list, and read the results.'
paths:
  /api/batches:
    get:
      tags:
      - Batches
      summary: Lists the caller's bulk-verification batches, newest first, paginated
      description: Authenticated with a dashboard session, or an API key or agent token holding the `results:read` scope.
      operationId: list_batches
      parameters:
      - name: limit
        in: query
        description: Number of batches to return (default 20, cap 96).
        required: false
        schema:
          type: integer
          format: int64
      - name: offset
        in: query
        description: Number of batches to skip (default 0).
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Paginated batch list, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBatchesResponse'
        '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: []
    post:
      tags:
      - Batches
      summary: Submits a list of emails for bulk verification
      description: 'The email list is normalized and deduplicated; a syntax-invalid or duplicate address never becomes a job. The caller''s plan governs which checks may be requested; when `checks` is omitted the batch defaults to every check the plan allows (SMTP included). Deselecting a check narrows the batch via an explicit `checks` list (still subject to plan gating). `final` (default `true`) closes the batch''s intake immediately, the single-shot behavior; set it `false` to open the batch for further chunks via `POST /api/batches/{uuid}/emails`, letting a batch grow past the single-request cap of 4,096 emails, up to a ceiling of 1,000,000 emails per batch. A batch holds at least 20 distinct valid addresses: a `final` submit under that is a `400`, and fewer addresses go through `POST /api/verify`. Authenticated with a dashboard session, or an API key or agent token holding the `email:verify:bulk` scope. Tokens are reserved when the batch is accepted; a request that fails validation reserves nothing.'
      operationId: submit_batch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitBatchRequest'
        required: true
      responses:
        '202':
          description: Batch accepted and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitBatchResponse'
        '400':
          description: Empty or oversized email list, every address rejected, or a final submit under 20 distinct valid addresses.
          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'
        '402':
          description: Wallet balance too low to reserve the batch's cost.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: A requested check is not allowed for the plan, the unique-valid email count exceeds the plan's max_batch_size, or the key or agent token lacks the `email:verify:bulk` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
  /api/batches/{uuid}:
    get:
      tags:
      - Batches
      summary: Returns one batch's status, progress, and aggregated results
      description: A uuid that belongs to another account returns the same 404 as an unknown uuid.
      operationId: get_batch
      parameters:
      - name: uuid
        in: path
        description: Public UUID of the batch.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '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 batch with that uuid belongs to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
  /api/batches/{uuid}/emails:
    post:
      tags:
      - Batches
      summary: Appends one chunk of emails to a batch whose intake is still open (submitted…
      description: 'Reserves tokens and queues this chunk''s jobs the same way as the first chunk, then grows the batch''s `progress.total`. Authenticated like `POST /api/batches` (`email:verify:bulk` scope). Accepts the same optional `checks` as `POST /api/batches` (defaulting to every plan-allowed check); a streamed caller passes the same selection on every chunk. Set `final: true` (the default) on the last chunk to close intake; the batch then completes immediately if every job (old and new) is already processed, or as soon as the last of them finishes. A final chunk that would close the batch under 20 distinct valid addresses is refused with a `400`, and the batch stays open.'
      operationId: append_batch_emails
      parameters:
      - name: uuid
        in: path
        description: Public UUID of the batch.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppendEmailsRequest'
        required: true
      responses:
        '202':
          description: Chunk accepted and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppendEmailsResponse'
        '400':
          description: Chunk exceeds the per-request email cap, or a final chunk would close the batch under 20 distinct valid addresses.
          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'
        '402':
          description: Wallet balance too low to reserve this chunk's cost.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: A requested check is not allowed for the plan, the batch's cumulative unique-valid count would exceed the plan's max_batch_size, or the key or agent token lacks the `email:verify:bulk` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: No batch with that uuid belongs to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '409':
          description: The batch's intake is already closed, or it is terminal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
  /api/batches/{uuid}/results:
    get:
      tags:
      - Batches
      summary: Returns the per-email results of a batch
      description: Returns the per-email results for a batch (job status plus verdict/score once available), submission order first, paginated. Limited to the caller's own batches.
      operationId: get_batch_results
      parameters:
      - name: uuid
        in: path
        description: Public UUID of the batch.
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return (default 20, cap 96).
        required: false
        schema:
          type: integer
          format: int64
      - name: offset
        in: query
        description: Number of results to skip (default 0).
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Paginated per-email results for the batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBatchResultsResponse'
        '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 batch with that uuid belongs to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
components:
  schemas:
    BatchResultItem:
      type: object
      description: One per-email row in a batch's results listing.
      required:
      - uuid
      - status
      properties:
        custom_id:
          type:
          - string
          - 'null'
          description: The client reference supplied at submit for this email, if any.
        reason:
          type:
          - string
          - 'null'
          description: 'Stable verdict reason string (e.g. `"accept_all_provider"`), populated once available.

            Lets a caller distinguish a mainstream accept-all provider''s capped-but-`"valid"` verdict from a genuinely

            confirmed one without parsing the score.'
        recommendation:
          type:
          - string
          - 'null'
          description: 'Deterministic list-cleaning action (`"remove"`, `"send"`, or `"review"`), derived from the verdict, reason, and

            typo flag. Populated under the same condition as `verdict`.'
        score:
          type:
          - integer
          - 'null'
          format: int32
          description: Quality score (0-100), populated once the job's result is available.
          minimum: 0
        status:
          type: string
          description: Current lifecycle status (e.g. `"queued"`, `"completed"`).
        uuid:
          type: string
          description: Public UUID of the job.
        verdict:
          type:
          - string
          - 'null'
          description: Deliverability verdict (e.g. `"valid"`, `"risky"`), populated once available.
    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.
    RecommendationCountsDto:
      type: object
      description: 'Recommendation-bucket counts (`remove`, `review`, `send`) for a batch''s completed jobs.

        A job with no completed verification, or a failed job, is counted in none of the three.'
      required:
      - remove
      - review
      - send
      properties:
        remove:
          type: integer
          format: int32
          minimum: 0
        review:
          type: integer
          format: int32
          minimum: 0
        send:
          type: integer
          format: int32
          minimum: 0
    BatchResultsDto:
      type: object
      description: Aggregated verdict counts of a batch.
      required:
      - valid
      - invalid
      - risky
      - unknown
      - duplicates
      - syntax_errors
      properties:
        duplicates:
          type: integer
          format: int64
          minimum: 0
        invalid:
          type: integer
          format: int64
          minimum: 0
        risky:
          type: integer
          format: int64
          minimum: 0
        syntax_errors:
          type: integer
          format: int64
          minimum: 0
        unknown:
          type: integer
          format: int64
          minimum: 0
        valid:
          type: integer
          format: int64
          minimum: 0
    SubmitBatchRequest:
      type: object
      description: '`POST /api/batches` request body.'
      required:
      - emails
      properties:
        checks:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Optional explicit check names; defaults to every check the caller's plan allows.
        custom_ids:
          type: array
          items:
            type:
            - string
            - 'null'
          description: 'Optional per-email client references, index-aligned 1:1 with `emails`; empty means none.

            Echoed back verbatim in `GET /api/batches/{uuid}/results` so a caller can map each result to its input row

            without trusting submission order.'
        emails:
          type: array
          items:
            type: string
          description: Email addresses to verify.
        final:
          type: boolean
          description: 'Whether this is the batch''s only (or final) chunk. Defaults to `true`, the single-shot behavior.

            Set `false` to open the batch for further chunks via `POST /api/batches/{uuid}/emails`.'
        name:
          type:
          - string
          - 'null'
          description: Optional display name for the batch.
    BatchResponse:
      type: object
      description: A batch with its status, progress, aggregated results, and recommendation counts.
      required:
      - uuid
      - status
      - progress
      - results
      - recommendations
      - created_at
      - updated_at
      properties:
        created_at:
          type: string
        error:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        progress:
          $ref: '#/components/schemas/BatchProgressDto'
        recommendations:
          $ref: '#/components/schemas/RecommendationCountsDto'
        results:
          $ref: '#/components/schemas/BatchResultsDto'
        status:
          type: string
        updated_at:
          type: string
        uuid:
          type: string
    SubmitBatchResponse:
      type: object
      description: '`POST /api/batches` response body.'
      required:
      - batch_uuid
      - status
      - total_jobs
      - syntax_errors
      - duplicates
      - estimated_cost
      properties:
        batch_uuid:
          type: string
          description: Public UUID of the batch. Use it with `GET /api/batches/{uuid}` to poll status.
        duplicates:
          type: integer
          format: int64
          description: Number of submitted addresses that were exact duplicates of an already-accepted one.
          minimum: 0
        estimated_cost:
          type: integer
          format: int32
          description: Total tokens reserved for the batch.
          minimum: 0
        status:
          type: string
          description: Status of the batch right after submit (always `"processing"`).
        syntax_errors:
          type: integer
          format: int64
          description: Number of submitted addresses that failed syntax validation.
          minimum: 0
        total_jobs:
          type: integer
          format: int64
          description: Number of unique valid emails queued as jobs.
          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.'
    ListBatchesResponse:
      type: object
      description: '`GET /api/batches` response body.'
      required:
      - batches
      - limit
      - offset
      properties:
        batches:
          type: array
          items:
            $ref: '#/components/schemas/BatchResponse'
          description: The caller's batches, 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.
    BatchProgressDto:
      type: object
      description: Progress counters of a batch.
      required:
      - total
      - processed
      - succeeded
      - failed
      - skipped
      - percent_complete
      properties:
        failed:
          type: integer
          format: int64
          minimum: 0
        percent_complete:
          type: integer
          format: int32
          minimum: 0
        processed:
          type: integer
          format: int64
          minimum: 0
        skipped:
          type: integer
          format: int64
          minimum: 0
        succeeded:
          type: integer
          format: int64
          minimum: 0
        total:
          type: integer
          format: int64
          minimum: 0
    AppendEmailsRequest:
      type: object
      description: '`POST /api/batches/{uuid}/emails` request body.'
      required:
      - emails
      properties:
        checks:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'Optional explicit check names; defaults to every check the caller''s plan allows.

            A streamed caller passes the same selection on every chunk so the whole batch runs one check set.'
        custom_ids:
          type: array
          items:
            type:
            - string
            - 'null'
          description: 'Optional per-email client references, index-aligned 1:1 with `emails`; empty means none.

            Echoed back verbatim in `GET /api/batches/{uuid}/results`.'
        emails:
          type: array
          items:
            type: string
          description: Email addresses to verify in this chunk. May be empty (a pure "close intake now" call).
        final:
          type: boolean
          description: 'Whether this is the batch''s final chunk; closes intake and completes the batch when every job (old and new) is

            already processed. Defaults to `true`.'
    AppendEmailsResponse:
      type: object
      description: '`POST /api/batches/{uuid}/emails` response body.'
      required:
      - batch_uuid
      - status
      - total_jobs
      - syntax_errors
      - duplicates
      - estimated_cost
      properties:
        batch_uuid:
          type: string
          description: Public UUID of the batch.
        duplicates:
          type: integer
          format: int64
          description: Number of addresses in this chunk that were duplicates within the same chunk.
          minimum: 0
        estimated_cost:
          type: integer
          format: int32
          description: Tokens reserved for this chunk.
          minimum: 0
        status:
          type: string
          description: Status of the batch right after this chunk.
        syntax_errors:
          type: integer
          format: int64
          description: Number of addresses in this chunk that failed syntax validation.
          minimum: 0
        total_jobs:
          type: integer
          format: int64
          description: Cumulative number of unique valid emails queued as jobs across every chunk so far.
          minimum: 0
    ListBatchResultsResponse:
      type: object
      description: '`GET /api/batches/{uuid}/results` response body.'
      required:
      - results
      - limit
      - offset
      properties:
        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.
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchResultItem'
          description: Per-email results for the batch, submission order first.
  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