Look up an email address
POST
/v1/lookup/email
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);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)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)$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();bird lookup email --email aisha.khan@example.comcurl -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"
}'Returns whether an email address is worth sending to:
- Whether it will accept mail.
- How confident that is.
- Why not, when it will not.
- Whether it is a role, disposable, or free-provider address.
- What it looks like it was meant to be, when it looks misspelled.
One address per call, and one answer: result is the field to decide on. Every answer costs the same, including undeliverable, which is usually the most valuable one you can get.
result and reason are open vocabularies: the values below are the ones in use today, and further ones may be added. Branch on the values you know and treat anything else as a future value rather than an error. delivery_confidence is always present and always comparable, so it is the safe fallback.
Send the address in the body rather than the URL when you would rather it did not appear in request logs or browser history. Look up an email address by URL is the same lookup with the address in the path.
Send an Idempotency-Key and a retried request returns the stored answer instead of validating the address and charging again. Without one, every attempt is a new lookup and is billed.
Request Payload
email
string
required
The email address to look up. Send it exactly as you hold it: the part before the @ is case-sensitive, so nothing is lowercased for you, and a display-name form such as Aisha <aisha@example.com> is rejected rather than unwrapped.
Response Payload
email
string
required
The address that was looked up, exactly as you sent it.
valid
boolean
required
Whether the address is well-formed and its domain is set up to receive mail at all. It says nothing about the mailbox itself, so a valid domain with no such mailbox is true here and undeliverable in result.
result
object
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
object
Why the address cannot receive mail. Absent unless result is undeliverable.
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.