---
title: "Send multiple emails"
method: POST
path: "/emails/batch"
tags: ["Emails"]
---

# Send multiple emails

`POST /emails/batch`

Send up to 100 emails in a single request. Useful for sending
personalized emails to multiple recipients efficiently.

Each email in the batch can have different content and recipients.
Failed emails don't affect other emails in the batch.

**Idempotency:** Supports `Idempotency-Key` header for safe retries.

## Headers

- `Idempotency-Key` string

## Request body

- SendBatchRequest
  - `from` string, required — Sender email for all messages
  - `emails` object[], required
    - `to` string[], required
    - `subject` string, required
    - `html` string, nullable
    - `text` string, nullable
    - `tag` string, nullable — Tag for categorization and filtering
    - `metadata` Metadata, nullable — Custom key-value pairs attached to an email for webhook correlation. When you send an email with metadata, these key-value pairs are: - **Stored** with the message - **Returned** in all webhook event payloads (MessageSent, MessageBounced, etc.) - **Never visible** to email recipients This is useful for correlating webhook events with your internal systems (e.g., user IDs, order IDs, campaign identifiers). **Validation Rules:** - Maximum 10 keys per email - Keys: 1-40 characters, must start with a letter, only alphanumeric and underscores (`^[a-zA-Z][a-zA-Z0-9_]*$`) - Values: 1-500 characters, no control characters (newlines, tabs, etc.) - Total size: 4KB maximum (JSON-encoded)

## Response `200`

Batch accepted

- SendBatchResponse
  - `success` true, required
  - `data` object, required
    - `total` integer, required — Total emails in the batch
    - `accepted` integer, required — Successfully accepted emails
    - `failed` integer, required — Failed emails
    - `messages` object, required — Map of recipient email to message info
    - `sandbox` boolean — Whether this batch was sent in sandbox mode. Only present (and true) for sandbox emails sent from @arkhq.io addresses.
  - `meta` ApiMeta, required
    - `requestId` string, required — Unique request identifier for debugging and support

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `402` — Payment required - insufficient credits or billing not configured. This error occurs when: - Your organization doesn't have billing configured - Your credit balance is too low to complete the request **Error codes:** - `billing_not_configured` - Set up billing at arkhq.io/org/billing - `insufficient_balance` - Add credits to continue sending - `billing_error` - Billing system error, try again
- `409` — A request with this idempotency key is already being processed
- `429` — Too many requests. This can be either: - **Rate limit exceeded** (`rate_limit_exceeded`): Too many API requests per second. Includes `X-RateLimit-*` headers. - **Send limit exceeded** (`send_limit_exceeded`): Hourly email sending quota exceeded. The entire batch is rejected if total recipients across all emails exceed remaining capacity. No emails are sent or billed. Includes `X-SendLimit-*` headers. Check the `error.code` field to distinguish between the two.
- `500` — Internal server error

---

[API](https://skmtc.net/arkhq-io/apis/ark-email-api.md) · [All operations](https://skmtc.net/arkhq-io/apis/ark-email-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arkhq-io/ark-email-api/revisions/98a90852ffca/schema)