Email FinderⓘA tool that allows users to look up an email address by using either a name, an email domain, or a combination of both data points. API (V2)

The ZeroBounce Email FinderⓘA tool that allows users to look up an email address by using either a name, an email domain, or a combination of both data points. API allows you to identify the correct email format when you provide a name and email domain.

We then validate the email address and provide the corresponding status and sub-status. You can use the API to connect with potential leads or business connections as long as you can provide the required data points.

Getting started

The Email Finder uses a person’s first and last name and a domain name to test a variety of patterns and combinations in real time until it identifies a valid business email. It does not use or process customer data at any point to aid in this search.

In addition, it will also return a list of possible email formats found for that domain. Each pattern will receive a corresponding confidence score indicating its potential accuracy.

Each Email Finder API call will consume 20 credits if a valid email format is returned.

If you are a monthly subscriber, the API call will consume 1 Email Finder query if a valid format is returned.

If the format returned is “Unknown” with the reasoning “Cannot identify email format” no credits will be deducted.

1 credit will be deducted in the following cases:

  • the domain is identified as a spamtrap
  • the domain is identified in the global suppression list
  • the domain contains a possible typo
  • the name parts provided are role based
  • the domain does not have DNS entries
  • the domain contains an unroutable IP address
  • the domain is disposable

To use the Email Finder API, use the following URL, method, and parameters. Be sure to review the successful response example below and response details to ensure your API configuration works correctly.

API DEFAULT URL: https://api.zerobounce.net/v2/guessformat
API U.S.A. URL*: https://api-us.zerobounce.net/v2/guessformat

Method: GET

*This endpoint uses servers located within the United States. By utilizing this endpoint, you acknowledge and consent to your data being processed on servers in the United States.

  • Parameter
    Required
    Description
  • api_key
    Yes
    Your API Key, found in your account.
  • domain
    Yes
    The email domain for which to find the email format.
  • first_name
    No
    The first name of the person whose email format is being searched. [optional]
  • middle_name
    No
    The middle name of the person whose email format is being searched. [optional]
  • last_name
    No
    The last name of the person whose email format is being searched. [optional]

Successful Response


    {
      "email": "john.doe@example.com",
      "domain": "example.com",
      "format": "first.last",
      "status": "valid",
      "sub_status": "",
      "confidence": "HIGH",
      "did_you_mean": "",
      "failure_reason": "",
      "other_domain_formats": [
        {
            "format": "first_last",
            "confidence": "HIGH",
        },
        {
            "format": "first",
            "confidence": "MEDIUM",
        }
      ]
    }

Response Details

  • Properties
    Description
  • email
    The resulting email address identified by the API.
  • domain
    The provided domain name.
  • format
    The format of the resulting email address.
  • status
    The email address validation status. Possible values can be found at https://www.zerobounce.net/docs/email-validation-api-quickstart#status_codes__v2__
  • sub_status
    The email address validation sub-status. Possible values can be found at https://www.zerobounce.net/docs/email-validation-api-quickstart#status_codes__v2__
  • confidence
    The level of confidence we have in the provided format based on our engine and database. Possible values: LOW, MEDIUM, HIGH, UNKNOWN.
  • did_you_mean
    e.g. a suggestion in case case a firstname is used in the lastname field
  • failure_reason
    A reason for the unknown result. Possible values can be found in the "Possible reasons for unknown status" section below.
  • other_domain_formats
    A list of domain formats we have for the specified domain. This list contains other formats (e.g. first_name, first, first.last, etc.) and the level of confidence we have in the respective format.

Code Samples

Possible failure reasons for unknown status

  • Reason
    Description
  • FREE_DOMAIN_ERROR
    The email domain is not accepted by the free account.
  • ROLE_BASED_ERROR
    The email is role-based, and the role-based filtering is active in your account.
  • CANNOT_IDENTIFY_EMAIL_FORMAT
    The format could not be found in the database or the engine could not identify it.
  • UNEXPECTED_ERROR_OCCURRED_DURING_VALIDATION
    unexpected error
  • DOMAIN_DOES_NOT_ACCEPT_MAIL
    The domain is not accepting emails

Other potential error messages

Insufficient ZeroBounce credits will also produce an error when calling the Email Finder API. See the example below:

“Invalid API key or your account ran out of credits.”

You can resolve this error by ensuring there are at least 20 ZeroBounce credits within your account balance before making your next API call.

Email Finder API confidence levels

For each email address format that the Email Finder API generates, we assign a corresponding confidence level to indicate the probability that the address is actively in use on the respective email domain.

The confidence levels are listed below:

  • LOW - unlikely to be in use; high-risk
  • MEDIUM - medium level of confidence; it is possible the format is used
  • HIGH - highest level of confidence, format likely in use based on validation results
  • UNKNOWN - see above section for possible unknown errors
  • UNDETERMINED - cannot determine email, so format is unknown. Confidence for an empty email cannot be determined.

The Email Finder API lets you reliably identify business email addresses for your potential leads or business contacts.

We can identify potential patterns as long as you can provide the person’s first, middle or last name together with a possible domain. For example, company names are commonly used for private email domains. We then validate the email format to help keep your email list clean.

Every Email Finder search is conducted in real time and does not use or process customer data. Your privacy and security will forever remain a priority at ZeroBounce.

If you need further assistance configuring the Email Finder API or need help to understand your results, the ZeroBounce customer support team is available 24/7.