---
title: "Submits a list of emails for bulk verification."
method: POST
path: "/api/batches"
tags: ["batches"]
---

# Submits a list of emails for bulk verification.

`POST /api/batches`

## Request

- Base URL: `https://api.pricklymails.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pricklymails.com/api/batches`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Request body

- SubmitBatchRequest: `POST /api/batches` request body.
  - `checks` string[], nullable: Optional explicit check names; defaults to every check the caller's plan allows.
  - `custom_ids` string[]: Optional per-email client references, index-aligned 1:1 with `emails`; empty means none.
  - `emails` string[], required: Email addresses to verify.
  - `final` boolean: Whether this is the batch's only (or final) chunk. Defaults to `true`, the single-shot behavior.
  - `name` string, nullable: Optional display name for the batch.

## Response `202`

Batch accepted and queued.

- SubmitBatchResponse: `POST /api/batches` response body.
  - `batch_uuid` string, required: Public UUID of the batch. Use it with `GET /api/batches/{uuid}` to poll status.
  - `duplicates` integer, required: Number of submitted addresses that were exact duplicates of an already-accepted one.
  - `estimated_cost` integer, required: Total tokens reserved for the batch.
  - `status` string, required: Status of the batch right after submit (always `"processing"`).
  - `syntax_errors` integer, required: Number of submitted addresses that failed syntax validation.
  - `total_jobs` integer, required: Number of unique valid emails queued as jobs.

## Other responses

- `400`: Empty or oversized email list, or every address rejected.
- `401`: Missing or invalid API key, session token, or agent token.
- `402`: Wallet balance too low to reserve the batch's cost.
- `403`: 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.

---

[API](https://skmtc.dev/pricklymails/apis/pricklymails-api.md) · [All operations](https://skmtc.dev/pricklymails/apis/pricklymails-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pricklymails/apis/pricklymails-api/revisions/b4225a92d8fb?raw)