Create an email address lookup · API reference — Bird

Create an email address lookup

Endpoint

POST

/v1/lookup/email

SDK Examples

TypeScript

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

Python

answer = client.lookup.email(email="aisha.khan@example.com")
# result is an open vocabulary; delivery_confidence is always comparable.
print(answer.result, answer.delivery_confidence)

Go

answer, err := client.Lookup.Email(context.Background(), bird.LookupEmailParams{
    Email: "aisha.khan@example.com",
})
if err != nil {
    log.Fatal(err)
}// result is an open vocabulary; delivery_confidence is always comparable.
fmt.Println(*answer.Result, *answer.DeliveryConfidence)

PHP

$answer = $bird->lookup->email(
    (new EmailLookupRequest())->setEmail('aisha.khan@example.com'),
);
// result is an open vocabulary; delivery_confidence is always comparable.
echo $answer->getResult(), ' ', $answer->getDeliveryConfidence();

CLI

bird lookup email --email aisha.khan@example.com

cURL

curl -X POST "https://us1.platform.bird.com/v1/lookup/email" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "aisha.khan@example.com"
  }'

Response200

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

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 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.

Request Payload

email

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 Payload

email

The address that was looked up, exactly as you sent it.

valid

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

The verdict on the address, and the one field to decide on.

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.

Possible values (may grow over time): valid, neutral, risky, undeliverable, typo

delivery_confidence

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

Notable characteristics of the address. Empty when none apply.

reason

An explanation for the assessment. Can accompany an undeliverable, risky, or typo result; omitted when no recognized reason is available.

Possible values (may grow over time): invalid_syntax, invalid_domain, invalid_recipient, disposable_domain

did_you_mean

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.