# `bird lookup email-batch`

## Usage

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

## Description

Create a batch of email address lookups

Assess up to 1,000 email addresses in one request. Results preserve input order and duplicates; malformed addresses receive individual assessments. Each answered entry is billed. Use a separate idempotency key per batch and reuse it for retries. Requests are limited to 128 KiB; responses over 256 KiB cannot be replayed and a retry can incur another charge.

Build the request from flags, a JSON EmailLookupBatchRequest 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 lookup email-batch --example

# the body it prints:
```

```json
{
  "emails": ["aisha.khan@example.com", "not-an-email"]
}
```

## 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                                                                                                                                                                                                                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--emails <value>…` | Addresses to assess in submission order. Surrounding whitespace is trimmed and case is preserved. Malformed addresses receive individual assessments. Duplicates are assessed and billed at each position. The request must also fit within the 128 KiB request-body limit. (required; or in --body-file) |
| `--response-schema` | Print the fields this command returns, then exit                                                                                                                                                                                                                                                          |

## Related

| Name                                                                  | Description                    |
| --------------------------------------------------------------------- | ------------------------------ |
| [`bird lookup email`](/docs/cli/reference/lookup-email)               | Create an email address lookup |
| [`bird lookup phone-number`](/docs/cli/reference/lookup-phone-number) | Create a phone number lookup   |

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)