---
title: "Create an email address lookup"
method: POST
path: "/v1/lookup/email"
tags: ["lookup"]
---

# Create an email address lookup

`POST /v1/lookup/email`

## Request

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

Returns a deliverability `result`, a `delivery_confidence` score, address characteristics, an assessment `reason`, and a suggested correction when available. `result` and `reason` are open vocabularies. Handle unknown values and use `delivery_confidence` as the stable fallback. Each completed lookup incurs the same charge regardless of its result.

This form keeps the address out of the URL. The [URL form](/docs/api/reference/get-email-lookup) performs the same lookup but cannot use an idempotency key. With this form, reuse an `Idempotency-Key` to return the stored result without another lookup or charge.

## Headers

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

## Request body

- EmailLookupRequest
  - `email` string, required: The email address to look up. Send it exactly as you hold it. The part before the `@` is case-sensitive, so the API does not lowercase it. A display-name form such as `Aisha <aisha@example.com>` is rejected rather than unwrapped.

## Response `200`

Available deliverability information about the address.

- EmailLookup: Assessment of whether an email address accepts mail, the confidence and reason for that assessment, and a suggested correction when the address appears misspelled. `result` is the field to decide on; `delivery_confidence` grades it, and `flags` describes the address itself rather than its deliverability, so a perfectly valid address can still have `role` or `disposable`. Fields without resolved values are omitted rather than sent as null. Every field present in the response was resolved.
  - `email` string, required: The address that was looked up, exactly as you sent it.
  - `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
- `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)