lookup

Create an email address lookup

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.

post/v1/lookup/email

Request

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

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

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.

Request body

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

Example request

{
  "email": "aisha.khan@example.com"
}

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.