Email Finder API (V2)

The ZeroBounce Email Finder 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

Email Finder makes use of the person's first, middle or last name together with the domain name in order to test multiple combinations and identify the correct email.

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 1 Email Finder Query from your Tools subscription. Once the available queries from the subscription have been exhausted, each Email Finder API call will consume 20 credits if a format is returned. If the format is returned is Unknown with the “Cannot identify email format.” failure reason, 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.

URL: https://api.zerobounce.net/v2/guessformat
Method: GET

  • 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

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
  • HIGH - highest level of confidence; email 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 allows you to reliably identify email addresses for your potential leads or business contacts.

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

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