---
title: "Create an email address lookup"
canonical: "https://bird.com/docs/api/reference/create-email-lookup"
---

# Create an email address lookup

`POST /v1/lookup/email`

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.

## Code samples

**TypeScript**

```ts
const answer = await bird.lookup.email({ email: "aisha.khan@example.com" });
// result is an open vocabulary; delivery_confidence is always comparable.
console.log(answer.result, answer.delivery_confidence);
```

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

## Example response `200`

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

## Request body

- `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 body

- `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)
- `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` (array of string, required): Notable characteristics of the address. Empty when none apply.
- `reason` (string): An explanation for the assessment. Can accompany an undeliverable, risky, or typo result; omitted when no recognized reason is available.
- `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

- [Email lookup: will that address actually accept mail](/learn/lookup/email-lookup-will-that-address-actually-accept-mail) (video)
- [Email lookup](/lookup-api) (product)
- [Look up an email address](/docs/guides/lookup/email-addresses) (docs)

[Get an implementation brief](/learn/workspace?topic=lookup-email)