# `bird email send-batch`

## Usage

```bash
bird email send-batch [flags]
```

## Description

Send a batch of email messages in one call.

The body is a JSON array of send requests (up to 100). Every message is
validated before any is queued — if one fails, the whole batch is rejected.
Sending is outbound and irreversible: each result reports "accepted", not
"delivered" — read a message back with "bird email get" to confirm delivery.

Build the request from flags, a JSON EmailMessageBatchRequest body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.

## Examples

```bash
# print the body shape (no credentials needed)
bird email send-batch --example

# the body it prints:
[
  {
    "from": {
      "email": "hello@bird.com",
      "name": "Bird Support"
    },
    "subject": "Your receipt for order #1234",
    "text": "Thanks for your purchase! Your receipt is attached.",
    "to": [
      {
        "email": "jane@example.com",
        "name": "Jane Doe"
      }
    ]
  },
  {
    "from": {
      "email": "hello@bird.com",
      "name": "Bird Support"
    },
    "subject": "Your receipt for order #1235",
    "text": "Thanks for your purchase! Your receipt is attached.",
    "to": [
      {
        "email": "john@example.com",
        "name": "John Roe"
      }
    ]
  }
]

# send a batch from a JSON array of messages
bird email send-batch --body-file batch.json

# preview the resolved batch without sending
bird email send-batch --body-file batch.json --dry-run

# pipe the batch in on stdin
cat batch.json | bird email send-batch --body-file -
```

## Options

#### Request

| Name                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--body-file`       | Read the JSON request body from this file; "-" reads stdin   |
| `--example`         | Print a complete example request body, then exit             |
| `--dry-run`         | Print the resolved request without sending it, then exit     |
| `--idempotency-key` | Deduplication key; a retry with the same key won't act twice |

#### Options

| Name                | Description                                      |
| ------------------- | ------------------------------------------------ |
| `--response-schema` | Print the fields this command returns, then exit |

## Related

| Name                                                            | Description                  |
| --------------------------------------------------------------- | ---------------------------- |
| [`bird email cancel`](/docs/cli/reference/email-cancel)         | Cancel a scheduled message   |
| [`bird email content`](/docs/cli/reference/email-content)       | Get stored message content   |
| [`bird email get`](/docs/cli/reference/email-get)               | Get a message                |
| [`bird email list`](/docs/cli/reference/email-list)             | List messages                |
| [`bird email recipients`](/docs/cli/reference/email-recipients) | List recipients of a message |
| [`bird email send`](/docs/cli/reference/email-send)             | Send an email message.       |