> ## Documentation Index
> Fetch the complete documentation index at: https://orbisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Email by Name and Domain (Unlimited Plans)

> Find a person's deliverable email address from their name and company domain on an unlimited plan. Counts against your plan's monthly cap instead of credits.

This is the unlimited-plan variant of [POST /v1/email-lookup](/docs/api-reference/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](/docs/guides/unlimited-plans). 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](/docs/api-reference/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](/docs/api-reference/errors) for handling.


## OpenAPI

````yaml POST /v1/unlimited/email-lookup
openapi: 3.1.0
info:
  title: OrbiSearch Public API
  version: 1.0.0
  description: >-
    Email verification API for developers and agents. [Get your API key
    →](https://orbisearch.com/dashboard/api-keys)


    **Rate limiting:** requests are limited per API key (20 requests per second
    by default). Every response includes `X-RateLimit-Limit`,
    `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers describing the
    current per-key window so clients can self-throttle; `429` responses also
    include a `Retry-After` header with the suggested backoff in seconds.
  contact:
    name: Get API Key
    url: https://orbisearch.com/dashboard/api-keys
servers:
  - url: https://api.orbisearch.com
    description: OrbiSearch Public API
security:
  - ApiKeyAuth: []
paths:
  /v1/unlimited/email-lookup:
    post:
      tags:
        - Unlimited Plans
      summary: Find Email by Name and Domain (Unlimited Plans)
      description: |-
        Identical lookup engine and response shape as `/v1/email-lookup`, for
        unlimited-plan subscription keys. Counts 1 request against your plan's
        monthly cap per returned response; no credits are consumed. Rate
        limited to your plan's requests-per-second, per account.

        `credits_consumed` is retained for wire compatibility and reads 0 —
        no credits move on unlimited plans.
      operationId: unlimited_lookup_email_v1_unlimited_email_lookup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailLookupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailLookupResponse'
              example:
                email: jane.doe@acme.com
                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: 0
                first_name: Jane
                last_name: Doe
                domain: acme.com
                confidence: 99
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              example:
                detail: API key required in X-API-Key header
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '402':
          description: No active subscription for this key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                detail: >-
                  No active subscription. This key resumes working when the
                  subscription is reinstated.
                code: subscription_inactive
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '403':
          description: Key plan does not match this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                detail: >-
                  This endpoint requires an unlimited API key. Pay-as-you-go
                  keys use the credit-metered /v1 endpoints.
                code: wrong_key_plan
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                detail: >-
                  Invalid request body field '0': Input should be a valid
                  string.
                errors:
                  - loc: body.0
                    msg: >-
                      Invalid request body field '0': Input should be a valid
                      string.
                    type: string_type
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: >-
                Seconds the client should wait before retrying. Computed from
                the remaining rate-limit window (typically 1 for the per-second
                limit, longer when the limit is exceeded by 3x or more); for
                endpoints with a daily quota, seconds until the quota resets.
              schema:
                type: integer
                examples:
                  - 1
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 20
            X-RateLimit-Remaining:
              description: Requests remaining in the current per-API-key window.
              schema:
                type: integer
                examples:
                  - 13
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                type: integer
                examples:
                  - 1751700000
          content:
            application/json:
              example:
                detail: >-
                  Rate limit exceeded. Maximum 20 requests per second per API
                  key. Contact us to discuss higher limits.
                code: rate_limited
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    EmailLookupRequest:
      properties:
        first_name:
          type: string
          maxLength: 255
          title: First Name
          description: >-
            Person's first name. Optional individually — provide at least one of
            first or last name.
          default: ''
          examples:
            - Jane
        last_name:
          type: string
          maxLength: 255
          title: Last Name
          description: >-
            Person's last name. Optional individually — provide at least one of
            first or last name.
          default: ''
          examples:
            - Doe
        domain:
          type: string
          maxLength: 255
          minLength: 3
          title: Domain
          description: Company domain to search within.
          examples:
            - acme.com
        timeout:
          type: integer
          maximum: 97
          minimum: 30
          title: Timeout
          description: Lookup timeout in seconds (30–97).
          default: 97
          examples:
            - 97
      type: object
      required:
        - domain
      title: EmailLookupRequest
      description: Find a deliverable email from a name and company domain.
      example:
        domain: acme.com
        first_name: Jane
        last_name: Doe
        timeout: 97
    EmailLookupResponse:
      properties:
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: >-
            The deliverable email address discovered for this person at this
            domain. Null when no deliverable address could be confirmed.
          examples:
            - jane.doe@acme.com
        status:
          type: string
          enum:
            - safe
            - unknown
          pattern: ^(safe|unknown)$
          title: Status
          description: >-
            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).
          examples:
            - safe
        substatus:
          anyOf:
            - type: string
              pattern: ^(deliverable|no_address_found|timeout)$
            - type: 'null'
          enum:
            - deliverable
            - no_address_found
            - timeout
          title: Substatus
          description: >-
            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.
          examples:
            - deliverable
        explanation:
          type: string
          title: Explanation
          description: Plain-English explanation of the lookup result.
          examples:
            - Safe to email. The mailbox exists and is deliverable.
        email_provider:
          type: string
          title: Email Provider
          description: >-
            Email service provider of the returned address (Google Workspace,
            Microsoft Outlook, etc.).
          examples:
            - Google Workspace
        mx_record:
          anyOf:
            - type: string
            - type: 'null'
          title: Mx Record
          description: >-
            The main mail server the domain uses to receive email. Null if the
            domain has no mail server configured.
          examples:
            - aspmx.l.google.com
        is_domain_catch_all:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Domain Catch All
          description: >-
            True if the domain accepts mail for any username (catch-all). Null
            if we could not determine whether the domain is catch-all.
          examples:
            - false
        is_secure_email_gateway:
          type: boolean
          title: Is Secure Email Gateway
          description: >-
            True if the domain is protected by a secure email gateway —
            Proofpoint, Mimecast, Barracuda, or Trend Micro.
          default: false
          examples:
            - false
        is_disposable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Disposable
          description: >-
            True if this is a temporary/disposable email service, false if not,
            null if unknown.
          examples:
            - false
        is_role_account:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Role Account
          description: >-
            True if this is a generic role-based email (info@, support@, etc.),
            false if not, null if unknown.
          examples:
            - false
        is_free:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Free
          description: >-
            True if this is from a free email provider (gmail.com, yahoo.com,
            etc.), false if not, null if unknown.
          examples:
            - false
        credits_consumed:
          type: integer
          title: Credits Consumed
          description: >-
            Credits charged for this lookup: 1 on pay-as-you-go keys, 0 on
            unlimited plans (no credits move).
          examples:
            - 1
        first_name:
          type: string
          title: First Name
          description: The first name supplied in the request.
          examples:
            - Jane
        last_name:
          type: string
          title: Last Name
          description: The last name supplied in the request.
          examples:
            - Doe
        domain:
          type: string
          title: Domain
          description: The domain supplied in the request.
          examples:
            - acme.com
        confidence:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Confidence
          description: >-
            How certain we are in the verdict on a 0–100 scale. See
            EmailVerificationResponse.confidence for the full scale.
          examples:
            - 99
      type: object
      required:
        - status
        - explanation
        - email_provider
        - credits_consumed
        - first_name
        - last_name
        - domain
      title: EmailLookupResponse
      description: >-
        Lookup result — best deliverable email found for a (first_name,
        last_name, domain).
      example:
        confidence: 99
        credits_consumed: 1
        domain: acme.com
        email: jane.doe@acme.com
        email_provider: Google Workspace
        explanation: Safe to email. The mailbox exists and is deliverable.
        first_name: Jane
        is_disposable: false
        is_domain_catch_all: false
        is_free: false
        is_role_account: false
        is_secure_email_gateway: false
        last_name: Doe
        mx_record: aspmx.l.google.com
        status: safe
        substatus: deliverable
    ApiErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable description of what went wrong.
          examples:
            - API key required in X-API-Key header
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Stable machine-readable error code, present on conditions a client
            may want to branch on (for example `rate_limited` for the per-second
            limit versus `daily_quota_exceeded` for the daily cap). Absent on
            errors that need no further disambiguation.
          examples:
            - daily_quota_exceeded
        errors:
          anyOf:
            - items:
                $ref: '#/components/schemas/ValidationErrorDetail'
              type: array
            - type: 'null'
          title: Errors
          description: >-
            Individual validation failures, one entry per invalid parameter or
            field. Present only on 422 responses; when the request has a single
            problem, `detail` carries the same message. Absent on all other
            error codes.
      type: object
      required:
        - detail
      title: ApiErrorResponse
      description: Error response body.
    ValidationErrorDetail:
      properties:
        loc:
          type: string
          title: Loc
          description: >-
            Where in the request the problem is, as a dot-separated path (e.g.
            `query.email`, `body.0`).
          examples:
            - query.email
        msg:
          type: string
          title: Msg
          description: Human-readable description of this validation error.
          examples:
            - 'Missing required query parameter: email.'
        type:
          type: string
          title: Type
          description: >-
            Machine-readable error category (e.g. `missing`, `less_than_equal`,
            `string_too_long`).
          examples:
            - missing
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationErrorDetail
      description: One request-validation failure.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: API key for authentication
      in: header
      name: X-API-Key

````