> ## Documentation Index
> Fetch the complete documentation index at: https://dugble.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch sending

> Queue up to 50 independent emails in one atomic API request

Use `POST /emails/batch` when your application needs to submit multiple independent emails in one HTTP request. A batch can contain between 1 and 50 messages.

## Send a batch

The preferred request shape is a top-level JSON array:

```bash theme={null}
curl --request POST \
  --url https://api.dugble.com/emails/batch \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: weekly-report-2026-08-10" \
  --data '[
    {
      "to": "ada@example.com",
      "subject": "Hello Ada",
      "html": "<p>Your report is ready.</p>",
      "tags": [{ "name": "batch", "value": "weekly_30" }]
    },
    {
      "to": "grace@example.com",
      "subject": "Hello Grace",
      "text": "Your report is ready.",
      "tags": [{ "name": "batch", "value": "weekly_30" }]
    }
  ]'
```

For compatibility, Dugble also accepts an object containing `messages`:

```json theme={null}
{
  "messages": [
    {
      "to": "ada@example.com",
      "subject": "Hello Ada",
      "text": "Your report is ready."
    }
  ]
}
```

## Response ordering

A successful request returns `202 Accepted`. Each item in `data` corresponds to the message at the same zero-based index in the request.

```json theme={null}
{
  "success": true,
  "data": [
    {
      "object": "email",
      "id": "ae2014de-c168-4c61-8267-70d2662a1ce1"
    },
    {
      "object": "email",
      "id": "faccb7a5-8a28-4e9a-ac64-8da1cc3bc1cb"
    }
  ]
}
```

Store the returned IDs in the same order as the request items so each application record remains associated with the correct Dugble message.

## Atomic acceptance

Dugble validates every message before committing the batch. The messages and their durable delivery jobs are then written in one transaction. If validation fails or the transaction cannot complete, none of the messages in the batch are committed.

<Note>
  Atomic acceptance does not mean atomic delivery. After the batch is accepted, each email has its own delivery lifecycle and can be delivered, delayed, bounced, rejected, or failed independently.
</Note>

## Limitations

* A batch can contain between 1 and 50 emails.
* Attachments are not supported in batch email requests.
* Each email must independently satisfy the normal send validation rules.
* Each email may be immediate or have its own `scheduled_at` value.
* The `Idempotency-Key` applies to the complete batch request.
* The combined validated batch payload is limited to 10 MiB.

For emails with attachments, use `POST /emails` for each message instead.