Skip to main content
POST
Find Email by Name and Domain (Unlimited Plans)
This is the unlimited-plan variant of POST /v1/email-lookup. The request and response contracts are identical (same fields, same statuses); what differs is how usage is metered and authenticated. See the counterpart page for lookup semantics and response details. Requests require an Unlimited API key tied to an active unlimited plan. A pay-as-you-go key on this endpoint returns 403 with code: wrong_key_plan; if the plan’s subscription has lapsed, the key returns 402 with code: subscription_inactive until it is reinstated.

Metering

  • Each returned response counts 1 request against your plan’s monthly single-lookup cap (100,000, 200,000, or 400,000 per billing period depending on plan), including status: unknown outcomes.
  • No credits are charged. The credits_consumed field is retained for wire compatibility and reads 0; no credits move on unlimited plans.
  • The consumed unit is released only when OrbiSearch infrastructure cannot complete the request (502). Retry the request.
  • When the cap is reached, the endpoint returns 429 with code: monthly_quota_exceeded and a Retry-After giving the seconds until your billing period ends. Check consumption at any time via GET /v1/unlimited/usage.

Rate limits

Requests are limited to your plan’s per-second rate, per account: 10 requests per second on Starter, 15 on Standard, 20 on Professional. The limit is keyed to your account, not the key, so creating additional keys does not raise it. The X-RateLimit-* response headers describe this window. Exceeding it returns 429 with code: rate_limited; see errors for handling.

Authorizations

X-API-Key
string
header
required

API key for authentication

Body

application/json

Find a deliverable email from a name and company domain.

domain
string
required

Company domain to search within.

Required string length: 3 - 255
Example:

"acme.com"

first_name
string
default:""

Person's first name. Optional individually — provide at least one of first or last name.

Maximum string length: 255
Example:

"Jane"

last_name
string
default:""

Person's last name. Optional individually — provide at least one of first or last name.

Maximum string length: 255
Example:

"Doe"

timeout
integer
default:97

Lookup timeout in seconds (30–97).

Required range: 30 <= x <= 97
Example:

97

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: 1 on pay-as-you-go keys, 0 on unlimited plans (no credits move).

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:

"jane.doe@acme.com"

substatus
enum<string>

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 caller's timeout parameter exhausted before the lookup completed; retry with a larger timeout — only returned from /v1/email-lookup, never from /v1/bulk-lookup, since bulk lookups have no caller-tunable timeout). All substatuses are billable; refunds happen only when OrbiSearch infrastructure cannot complete the request.

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

confidence
integer | null

How certain we are in the verdict on a 0–100 scale. See EmailVerificationResponse.confidence for the full scale.

Required range: 0 <= x <= 100
Example:

99