---
title: "POST /v1/emails/batch"
method: POST
path: "/v1/emails/batch"
---

# POST /v1/emails/batch

`POST /v1/emails/batch`

## Headers

- `Idempotency-Key` string — Pass the optional Idempotency-Key header to make the request safe to retry. The key can be up to 256 characters. The server stores the canonical request body and behaves as follows: - Same key + same request body → returns the original emailId with 200 OK without re-sending. - Same key + different request body → returns 409 Conflict with code: NOT_UNIQUE so you can detect the mismatch. - Same key while another request is still being processed → returns 409 Conflict; retry after a short delay or once the first request completes. Entries expire after 24 hours. Use a unique key per logical send (for example, an order or signup ID).

## Request body

- object[]
  - `to` union, required
    - string
    - string[]
  - `from` string, required
  - `subject` string — Optional when templateId is provided
  - `templateId` string — ID of a template from the dashboard
  - `variables` object
  - `replyTo` union
    - string
    - string[]
  - `cc` union
    - string
    - string[]
  - `bcc` union
    - string
    - string[]
  - `text` string, nullable
  - `html` string, nullable
  - `headers` object — Custom headers to included with the emails
  - `attachments` object[]
    - `filename` string, required
    - `content` string, required
  - `scheduledAt` string, date-time
  - `inReplyToId` string, nullable

## Response `200`

List of successfully created email IDs

- object
  - `data` object[], required
    - `emailId` string, required

## Changes

> 27 revisions in range; 1 could not be searched.

- **2025-11-17** `d5dbb8522d58` — 1 info
  - added the new optional `header` request parameter `Idempotency-Key`
- **2025-09-28** `b78e8de12151` — 1 info
  - added the new optional request property `items/headers`
- **2025-09-26** `f3f4be68abf8` — 3 breaking, 3 info
  - removed `subschema #1, subschema #2` from the `items/bcc` request property `anyOf` list
  - removed `subschema #1, subschema #2` from the `items/cc` request property `anyOf` list
  - removed `subschema #1, subschema #2` from the `items/replyTo` request property `anyOf` list
  - added `subschema #1, subschema #2` to the `items/bcc` request property `anyOf` list
  - …2 more
- **2025-06-01** `80d7f1c84475` — 1 breaking, 2 info
  - removed `subschema #1, subschema #2` from the `items/to` request property `anyOf` list
  - added `subschema #1, subschema #2` to the `items/to` request property `anyOf` list
  - the `items/from` request property type/format was generalized from `string`/`email` to `string`/``
- **2025-05-25** `df13b10684f7` — 1 info
  - added the new optional request property `items/inReplyToId`

[Full history](https://skmtc.dev/usesend/apis/usesend-api/changes/v1/emails/batch/post.md)

---

[API](https://skmtc.dev/usesend/apis/usesend-api.md) · [All operations](https://skmtc.dev/usesend/apis/usesend-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/usesend/usesend-api/revisions/ee7832fe66a6/schema)