> ## 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 SMS messages in one atomic API request

Use `POST /sms/batch` to submit multiple independent SMS messages 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/sms/batch \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: reminder-batch-2026-08-10" \
  --data '[
    {
      "to": "+233201234567",
      "from": "Dugble",
      "body": "Hello Ada!",
      "metadata": {
        "customer_id": "cust_42"
      }
    },
    {
      "to": "+233241234567",
      "from": "Dugble",
      "body": "Hello Grace!",
      "scheduled_at": "in 10 min",
      "metadata": {
        "customer_id": "cust_84"
      }
    }
  ]'
```

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

```json theme={null}
{
  "messages": [
    {
      "to": "+233201234567",
      "from": "Dugble",
      "body": "Hello Ada!"
    }
  ]
}
```

## Response ordering

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

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

## Atomic acceptance

Before committing a batch, Dugble validates every destination, sender ID, body, metadata value, and schedule. It also resolves each destination country and calculates the SMS segment count.

The messages and their durable delivery jobs are then created in one transaction. If any item is invalid or the transaction fails, none of the messages are committed.

<Note>
  Atomic acceptance does not guarantee atomic delivery. Once accepted, each SMS has its own provider and carrier delivery lifecycle.
</Note>

## Best practices

* Use one idempotency key for the complete batch request.
* Preserve request ordering when storing returned IDs.
* Split workloads larger than 50 messages into independent requests with independent keys.
* Group messages by business operation rather than combining unrelated sends.
* Retrieve individual messages when you need delivery details.