Send one address and get one verdict: valid, neutral, risky, undeliverable, or typo. Alongside it, a confidence score from 0 to 100, the flags that say what kind of address it is, and the address a misspelling looks like it was meant to be. One request, no list to upload and no job to poll.
const answer = await bird.lookup.email({
email: "aisha.khan@exampel.com",
});
console.log(answer.result, answer.delivery_confidence);
// → "typo" 31
console.log(answer.did_you_mean);
// → "aisha.khan@example.com"
console.log(answer.valid, answer.flags);
// → true []
A verdict you can branch on.
Not a percentage you have to pick a threshold for.
Email address lookup is one of the two operations in the Bird Lookup API. The field to write your logic against is result, because it already reduces syntax, domain, mailbox, and reputation checks to five outcomes. delivery_confidence is there for the cases where you want to grade rather than gate, for example holding a risky signup for review instead of refusing it. The address you send is the address that comes back: the local part is case-sensitive and is not lowercased, and the display-name form is rejected rather than parsed.
Six fields, and what each is for.
Every one of them arrives with the same single request.
- 01
result, the verdict.
valid is safe to send to. neutral is deliverable with nothing to recommend it. risky will probably accept mail and carries a reason to hesitate. undeliverable cannot receive mail. typo reads like a misspelling of a real address.
- 02
reason, only where it applies.
invalid_syntax, invalid_domain, or invalid_recipient, naming which of the three checks the address failed. It is present on the undeliverable verdict and on no other, so its absence is information too.
- 03
did_you_mean, the correction.
The address a typo looks like a misspelling of, ready to put in front of the person who typed it. A signup form that offers the correction recovers the account instead of losing it to a bounce nobody sees.
- 04
delivery_confidence, 0 to 100.
A grade rather than a decision, which is what makes it different from result. Two addresses can share a verdict and sit far apart on this number, and that gap is where a review queue belongs.
- 05
flags, the kind of address.
role for a shared mailbox such as info or support, disposable for a throwaway provider, and free_provider for a consumer mailbox. All three are well-formed addresses that accept mail, which is why they are flags and not verdicts.
- 06
valid, the narrow boolean.
Whether the address is well formed and its domain can receive mail at all. It says nothing about the mailbox, so it is true for plenty of addresses whose verdict is risky. When you mean the verdict, read result.
Five outcomes, four things to do.
Refuse the undeliverable ones, offer the correction on a typo, hold a risky address for review, and accept the rest. That is the whole integration, and it fits in the submit handler of the form that collects the address.
const answer = await bird.lookup.email({
email: "info@example.com",
});
if (answer.result === "undeliverable") {
// reason is present on this verdict and no other.
reject(answer.reason);
} else if (answer.result === "typo") {
suggest(answer.did_you_mean);
} else if (answer.result === "risky") {
// A role or disposable address is well formed and still a poor signup.
review(answer.flags);
} else {
accept(answer.delivery_confidence);
}
What it costs, and what it is not.
One address per request, and every verdict bills, undeliverable included, because reaching that verdict is the work. There is no batch form and no list upload. A retry carrying the same Idempotency-Key replays the verdict you already paid for. Lookup is also not a suppression list: it tells you what an address looks like before you send, while suppression records what happened after you did, and a healthy sending setup uses both.
Go deeper in the docs.
Look up an email address walks the request and every field in the response. The Lookup overview covers both operations in one page, rate limits documents the lookup group, and idempotency explains what a replayed verdict costs.
Email address questions, answered.
The verdicts, the flags, the confidence score, and where suppression fits.
What does an email address lookup answer?
What are the five verdicts?
Why is an address undeliverable?
What should I do with a typo verdict?
How does delivery_confidence differ from result?
There is also a valid field. Is that the valid verdict?
What do the flags mean?
How should I write the address?
Do I need Lookup to stop sending to addresses that already bounced?
The rest of Lookup
One API key, one error envelope. Explore the other capability.
Check an address before it reaches your list.
One call in your signup handler keeps the bounces, the throwaway accounts, and the misspellings out of the database.