---
title: "Appends one chunk of emails to a batch whose intake is still open (submitted with `final: false`)."
method: POST
path: "/api/batches/{uuid}/emails"
tags: ["batches"]
---

# Appends one chunk of emails to a batch whose intake is still open (submitted with \`final: false\`).

`POST /api/batches/{uuid}/emails`

## 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/{uuid}/emails`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Path parameters

- `uuid` string, required

## Request body

- AppendEmailsRequest: `POST /api/batches/{uuid}/emails` 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 in this chunk. May be empty (a pure "close intake now" call).
  - `final` boolean: 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`.

## Response `202`

Chunk accepted and queued.

- AppendEmailsResponse: `POST /api/batches/{uuid}/emails` response body.
  - `batch_uuid` string, required: Public UUID of the batch.
  - `duplicates` integer, required: Number of addresses in this chunk that were duplicates within the same chunk.
  - `estimated_cost` integer, required: Tokens reserved for this chunk.
  - `status` string, required: Status of the batch right after this chunk.
  - `syntax_errors` integer, required: Number of addresses in this chunk that failed syntax validation.
  - `total_jobs` integer, required: Cumulative number of unique valid emails queued as jobs across every chunk so far.

## Other responses

- `400`: Chunk exceeds the per-request email cap.
- `401`: Missing or invalid API key, session token, or agent token.
- `402`: Wallet balance too low to reserve this chunk's cost.
- `403`: 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.
- `404`: No batch with that uuid belongs to the caller.
- `409`: The batch's intake is already closed, or it is terminal.

---

[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)