lookup

Get an email address lookup by URL

Performs the same deliverability lookup as Create an email address lookup, with the address in the URL. The response includes a result, confidence score, address characteristics, assessment reason, and suggested correction when available. Treat unknown result and reason values as valid additions.

Because the address is in the URL, it can appear in proxies, access logs, and browser history. This form does not accept an Idempotency-Key; each retry performs and charges for another lookup.

get/v1/lookup/email/{address}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/lookup/email/{address}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

addressstring required

The email address to look up. Percent-encode it, because a local part may legally contain characters a URL path reads as structure. The @ itself is safe either way.

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

Available deliverability information about the address.

emailstring required

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

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

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

flagsEmailLookupFlag[] required

Notable characteristics of the address. Empty when none apply.

reasonstring

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_meanstring

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.

Example response

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

Changes

No recorded changes to this operation across all 2 revisions of this API.