# Create a batch of email address lookups

`POST /v1/lookup/email/batch`

Assesses up to 1,000 email addresses synchronously and returns one result per
input in submission order. Malformed addresses receive individual assessments.
Duplicate addresses remain separate entries and each answered entry is billed
at the email lookup rate. Use [Create an email address lookup](/docs/api/reference/create-email-lookup)
for a single address. A batch consumes one request allowance under the shared
lookup rate limit, regardless of its number of addresses.

Requests must fit within 128 KiB. Split larger lists into separate requests.
Reuse an `Idempotency-Key` for retries of the same batch. Successful responses
up to 256 KiB can be retained for replay; larger responses are returned but
are not retained, so retrying can perform and charge for another batch.
An unavailable lookup returns `503` without charging for the batch.

## Code samples

**TypeScript**

```ts
const answer = await bird.lookup.emailBatch({
  emails: ["aisha.khan@example.com", "not-an-email"],
});
for (const item of answer.data) console.log(item.email, item.result);
```

Examples: [TypeScript](/docs/api/reference/create-email-lookup-batch.ts.md) · [Python](/docs/api/reference/create-email-lookup-batch.py.md) · [Go](/docs/api/reference/create-email-lookup-batch.go.md) · [PHP](/docs/api/reference/create-email-lookup-batch.php.md) · [CLI](/docs/api/reference/create-email-lookup-batch.cli.md) · [MCP](/docs/api/reference/create-email-lookup-batch.mcp.md) · [cURL](/docs/api/reference/create-email-lookup-batch.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "email": "aisha.khan@example.com",
      "valid": true,
      "result": "risky",
      "delivery_confidence": 42,
      "flags": [
        "role",
        "free_provider"
      ]
    }
  ]
}
```

## Request body

- `emails` (array of string, required): 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.

## Response body

- `data` (array of object, required): One assessment per submitted address, in submission order, including duplicates.
- `data.email` (string, required): The submitted value after trimming surrounding whitespace. May be empty or malformed.
- `data.valid` (boolean, required): The provider's validity assessment for the address. Read it with `result` and `delivery_confidence` when deciding whether to send; it does not guarantee delivery.
- `data.result` (string, required)
- `data.delivery_confidence` (integer, required): How likely mail to this address is to be delivered, from 0 (certain not to be) to 100 (certain to be). Read it alongside `result` rather than instead of it, because the same score can sit under `neutral` or `risky` for different reasons.
- `data.flags` (array of string, required): Notable characteristics of the address. Empty when none apply.
- `data.reason` (string): An explanation for the assessment. Can accompany an undeliverable, risky, or typo result; omitted when no recognized reason is available.
- `data.did_you_mean` (string): The address this one looks like a misspelling of. Absent unless a correction was found, which in practice means `result` is `typo`. Offer it to whoever typed the original rather than sending to it unasked, because it is a guess and the address they meant may be neither one.

## 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)