# `bird email send`

## Usage

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

## Description

Send an email message.

Sending is outbound and irreversible: it reports "accepted", not "delivered" —
read the message back with "bird email get" to confirm delivery. Send inline
content with --subject and --html/--text, or a stored template with --template.

Build the request from flags, a JSON EmailMessageSendRequest 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 --example

# the body it prints:
```

```json
{
  "category": "transactional",
  "cc": ["manager@bird.com"],
  "from": {
    "email": "hello@bird.com",
    "name": "Bird Support"
  },
  "headers": {
    "X-Campaign": "spring-2026"
  },
  "html": "<h1>Hi there 👋</h1>",
  "metadata": {
    "user_id": "usr_12345"
  },
  "reply_to": ["support@bird.com"],
  "subject": "Welcome aboard",
  "tags": [
    {
      "name": "category",
      "value": "welcome"
    }
  ],
  "text": "Hi there",
  "to": [
    {
      "email": "customer@bird.com",
      "name": "Jane Doe"
    }
  ],
  "track_clicks": false
}
```

```bash
# send a stored template with variable values
bird email send --from hello@bird.com --to alice@bird.com --template welcome-email --parameters '{"first_name":"Alice"}'

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

## Options

#### Recipients

| Name                   | Description                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `--from`               | Sender address; must be on a verified domain                                            |
| `--to <v1,v2,…>`       | Recipient address; repeatable. Accepts bare addresses or RFC 5322 "Name &lt;addr>" form |
| `--cc <v1,v2,…>`       | CC address; repeatable. Accepts bare addresses or RFC 5322 "Name &lt;addr>" form        |
| `--bcc <v1,v2,…>`      | BCC address; repeatable. Accepts bare addresses or RFC 5322 "Name &lt;addr>" form       |
| `--reply-to <v1,v2,…>` | Reply-To address; repeatable. Accepts bare addresses or RFC 5322 "Name &lt;addr>" form  |

#### Content

| Name                 | Description                          |
| -------------------- | ------------------------------------ |
| `--subject`          | Subject line                         |
| `--html`             | HTML body                            |
| `--html-file`        | Read the HTML body from a file       |
| `--text`             | Plain-text body                      |
| `--text-file`        | Read the plain-text body from a file |
| `--attach <v1,v2,…>` | Attach a file by path; repeatable    |

#### Template

| Name           | Description                                                                                                                                                     |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--template`   | Send by a stored template: its id (emt_…) or name (mutually exclusive with --subject/--html/--text)                                                             |
| `--parameters` | Substitution values as a JSON object (e.g. {{ first_name }} tokens); applied to the stored template on a template send, or to the inline subject/body otherwise |

#### Labels & metadata

| Name                   | Description                            |
| ---------------------- | -------------------------------------- |
| `--header <key=value>` | Custom header as Key=Value; repeatable |
| `--tag <key=value>`    | Tag as name=value; repeatable          |
| `--metadata`           | Arbitrary JSON metadata object         |

#### Delivery

| Name             | Description                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------- |
| `--category`     | Suppression policy: marketing (default) or transactional                                    |
| `--ip-pool-id`   | IP pool id (ipp_…) to send from                                                             |
| `--track-opens`  | Track open events (default true)                                                            |
| `--track-clicks` | Track click events (default true)                                                           |
| `--scheduled-at` | Schedule the send for a future time (RFC 3339, e.g. 2026-07-10T09:00:00Z); 30s to 30d ahead |

#### 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-batch`](/docs/cli/reference/email-send-batch) | Send a batch of email messages in one call. |