Skip to main content
POST
/
v1
/
email-lookup
Find Email by Name and Domain
curl --request POST \
  --url https://api.orbisearch.com/v1/email-lookup \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "first_name": "Jane",
  "last_name": "Doe",
  "domain": "acme.com"
}
'
{
  "email": "[email protected]",
  "status": "safe",
  "substatus": "deliverable",
  "explanation": "Safe to email. The mailbox exists and is deliverable.",
  "email_provider": "Google Workspace",
  "mx_record": "aspmx.l.google.com",
  "is_domain_catch_all": false,
  "is_secure_email_gateway": false,
  "is_disposable": false,
  "is_role_account": false,
  "is_free": false,
  "credits_consumed": 1,
  "first_name": "Jane",
  "last_name": "Doe",
  "domain": "acme.com"
}
Use this endpoint when you have a person’s name and their company’s domain but not their email address. OrbiSearch returns the deliverable address if one exists at that domain, together with the same enrichment fields as /v1/verify. The response returns status: safe when a deliverable address is found (substatus: deliverable, email set), or status: unknown otherwise — with substatus: no_address_found if we couldn’t find one, or substatus: timeout if the lookup did not complete within the time budget.

​
Caching

Results are cached for 24 hours. If you look up the same person (matched by first name, last name, and domain, ignoring casing and whitespace) within that window, the cached result is returned immediately at no credit cost.

​
Pricing and refund behaviour

  • Each lookup costs 1 credit.
  • You are charged when we return a deliverable email (status: safe), when no deliverable address exists for this person at this domain (status: unknown, substatus: no_address_found), and when a lookup hits the per-request time budget (status: unknown, substatus: timeout).
  • You are not charged, and the credit is refunded automatically, when our lookup service is temporarily unavailable (502). Retry the request.

​
Rate limits

This endpoint shares the 20 requests per second per API key limit with /v1/verify and /v1/bulk. Exceeding it returns a 429 Too Many Requests response. See errors for how to handle rate limit responses.

Authorizations

​
X-API-Key
string
header
required

API key for authentication

Body

application/json

Request object containing all parameters for an email lookup.

​
first_name
string
required
Required string length: 1 - 255
Example:

"Jane"

​
last_name
string
required
Required string length: 1 - 255
Example:

"Doe"

​
domain
string
required
Required string length: 3 - 255
Example:

"acme.com"

​
timeout
integer
default:90
Required range: 3 <= x <= 120
Example:

90

Response

Successful Response

Lookup result — best deliverable email found for a (first_name, last_name, domain).

​
status
enum<string>
required

Lookup status: safe (a deliverable address was found and is in the email field) or unknown (no deliverable address was found, or the lookup timed out; the email field is null).

Available options:
safe,
unknown
Pattern: ^(safe|unknown)$
Example:

"safe"

​
explanation
string
required

Plain-English explanation of the lookup result.

Example:

"Safe to email. The mailbox exists and is deliverable."

​
email_provider
string
required

Email service provider of the returned address (Google Workspace, Microsoft Outlook, etc.).

Example:

"Google Workspace"

​
credits_consumed
integer
required

Credits charged for this lookup.

Example:

1

​
first_name
string
required

The first name supplied in the request.

Example:

"Jane"

​
last_name
string
required

The last name supplied in the request.

Example:

"Doe"

​
domain
string
required

The domain supplied in the request.

Example:

"acme.com"

​
email
string | null

The deliverable email address discovered for this person at this domain. Null when no deliverable address could be confirmed.

Example:

"[email protected]"

​
substatus
enum<string> | null

Specific reason for the status: deliverable (a deliverable address was found — only returned with status=safe), no_address_found (no deliverable address was found for this person at this domain — only returned with status=unknown), timeout (the lookup did not complete within the time budget — only returned with status=unknown).

Available options:
deliverable,
no_address_found,
timeout
Pattern: ^(deliverable|no_address_found|timeout)$
Example:

"deliverable"

​
mx_record
string | null

The main mail server the domain uses to receive email. Null if the domain has no mail server configured.

Example:

"aspmx.l.google.com"

​
is_domain_catch_all
boolean | null

True if the domain accepts mail for any username (catch-all). Null if we could not determine whether the domain is catch-all.

Example:

false

​
is_secure_email_gateway
boolean
default:false

True if the domain is protected by a secure email gateway — Proofpoint, Mimecast, Barracuda, or Trend Micro.

Example:

false

​
is_disposable
boolean | null

True if this is a temporary/disposable email service, false if not, null if unknown.

Example:

false

​
is_role_account
boolean | null

True if this is a generic role-based email (info@, support@, etc.), false if not, null if unknown.

Example:

false

​
is_free
boolean | null

True if this is from a free email provider (gmail.com, yahoo.com, etc.), false if not, null if unknown.

Example:

false