---
title: "Create a batch of email address lookups"
method: POST
path: "/v1/lookup/email/batch"
tags: ["lookup"]
---

# Create a batch of email address lookups

`POST /v1/lookup/email/batch`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/lookup/email/batch`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

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.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- EmailLookupBatchRequest
  - `emails` 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 `200`

Completed assessments in submission order.

- EmailLookupBatchResponse
  - `data` EmailLookupBatchItem[], required: One assessment per submitted address, in submission order, including duplicates.
    - `email` string, required: The submitted value after trimming surrounding whitespace. May be empty or malformed.
    - `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.
    - `result` string, required: The verdict on the address, and the one field to decide on. - `valid`: the address exists and accepts mail. - `neutral`: it could not be confirmed either way, usually because the receiving domain answers every recipient the same. - `risky`: it probably accepts mail but is likelier than most to bounce or complain. Examples include role, disposable, and low-reputation addresses. - `undeliverable`: it does not accept mail, and `reason` says why. - `typo`: the address looks misspelled, and `did_you_mean` contains the correction. Open enum: further verdicts may be added over time, so treat an unrecognized value as a future one rather than an error. Branch on the values you know and fall back on `delivery_confidence`, which is always present and always comparable.
    - `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.
    - `flags` EmailLookupFlag[], required: Notable characteristics of the address. Empty when none apply.
    - `reason` string: An explanation for the assessment, when available. - `invalid_syntax`: the address is malformed. - `invalid_domain`: the domain does not accept mail. - `invalid_recipient`: the domain accepts mail but this mailbox does not exist. - `disposable_domain`: the domain belongs to a disposable-address provider. Open enum: further reasons may be added over time, so treat an unrecognized value as a future one rather than an error. `result` is what to branch on; this field explains it.
    - `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.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `402`: Insufficient balance
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `413`: Request body or message size exceeds the allowed limit
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)