Emails

Send batch emails

Validate and process up to 100 independent one-recipient transactional emails.

POST/api/v1/emails/batch

On this page

Authentication

Send a RouteKite API key as a Bearer token. This endpoint requires the email:send scope.

Required headers
Name	Type	Requirement	Description
`Authorization`	string	Required	Bearer API key with the required workspace scope.Example: `Bearer rk_your_key`
`Content-Type`	string	Required	Must be application/json.Example: `application/json`

Request body

Request fields
Name	Type	Requirement	Description
`emails`	email[]	Required	Between 1 and 100 one-recipient email items.
`emails[].idempotency_key`	string	Required	A unique key between 8 and 200 characters for this item.
`from`	email	Required	A verified RouteKite Sending Address. Maximum 320 characters.Example: `updates@example.com`
`to`	email	Required	Exactly one recipient. Maximum 320 characters.Example: `customer@example.net`
`reply_to`	email	Optional	Override where replies are delivered for this message.Example: `support@example.com`
`subject`	string	Direct content	The message subject when template_id is not used. Between 1 and 998 characters.Example: `Your order is confirmed`
`preview_text`	string	Optional	Inbox preview shown beside the subject in supported inboxes. Maximum 240 characters. Requires HTML or template_id and may use declared variables with a template.Example: `Your receipt and delivery details are inside.`
`html`	string	Direct content	HTML body when template_id is not used. Provide html, text, or both. Maximum 500,000 characters. RouteKite removes scripts, event handlers, embedded documents, forms, and unsafe URLs before the message is stored.Example: `<h1>Thank you</h1>`
`text`	string	Direct content	Plain-text body when template_id is not used. Provide html, text, or both. Maximum 200,000 characters.Example: `Thank you. Your order is confirmed.`
`template_id`	uuid	Template content	A published transactional template in this workspace.
`template_version_id`	uuid	Optional	Pin an immutable published version. Omit it to use the current published version.
`variables`	object	Optional	Values used to render template variables and lists. Each dynamic image accepts one complete HTTPS URL variable and uses its saved fallback image when that value is omitted. Maximum encoded size is 100,000 characters.Example: `{ "product": { "image_url": "https://images.example.com/product.jpg" } }`
`metadata`	object	Optional	Small correlation values. Keys are limited to 80 characters and string values to 500 characters.Example: `{ "order_id": "ord_123" }`
`emails[].attachments`	uuid[]	Optional	Up to 10 unique ready uploaded attachment IDs. Direct attachments are not supported in batches.

Response

Response fields
Name	Type	Requirement	Description
`object`	string	Always	Always list.
`data`	batch_result[]	Always	Results in the same order as the request.
`data[].index`	integer	Always	Zero-based input position.
`data[].idempotency_key`	string \| null	Always	The submitted item key when available.
`data[].id`	uuid	Accepted item	The accepted email identifier.
`data[].error`	error	Failed item	The stable per-item code, message, status, retryable flag, and optional details.
`accepted`	integer	Always	Accepted item count.
`failed`	integer	Always	Failed item count.

Independent results

Each item has its own idempotency key and result. A fully accepted batch returns 202. Any item failure returns 207 with accepted and failed counts.

Errors