Email Finder API

This endpoint allows you to uncover professional emails by providing a first and last name or a full name, along with a company (domain, website, or company name). The system leverages multiple patterns and advanced technology to discover and verify emails while staying fully GDPR compliant.

ℹ️

You will be charged only if we find a VALID email. If the email is CATCH_ALL (risky), we provide it for free.
You won't be charged if no results are found (NO_RESULT error code).
You won't be charged for duplicate email found.

Endpoint

POST https://api.prospeo.io/email-finder

curl -X POST \
 -H "Content-Type: application/json" \
 -H "X-KEY: your_api_key" \
 -d '{
   "first_name": "John",
   "last_name": "Doe",
   "company": "intercom.com"
   }' \
 "https://api.prospeo.io/email-finder"

Parameters

Parameter	Example value	Description
`first_name` ^optional	`John`	The person's first name.
`last_name` ^optional	`Doe`	The person's last name.
`full_name` ^optional	`John Doe`	The person's full name. We advise you to submit the first and last name for higher accuracy.
`company` ^required	`intercom.com`, `https://intercom.com`, `Intercom`	The company domain, website, or name. Using a domain or website is recommended for better accuracy. If submitting a company name, it needs to be between 3 to 75 characters.

⚠️

We strongly encourage you to submit the company domain/website instead of the company name for faster and better processing. To find the correct domain from your company name, our system leverages AI. While this allows us to find almost any company website, it is not as accurate as using the domain name. It also means that response times are longer when submitting a company name.

Response

The response will contain a JSON object. Check if the error property is false. If it is true, refer to the section below to handle the error message.

{
    "error": false,
    "response": {
        "free": false,
        "email": "[email protected]",
        "email_anon_id": "24Z97EARRT",
        "email_status": "VALID",
        "first_name": "Ewa",
        "last_name": "Kadlool",
        "domain": "intercom.com",
        "total_emails": 194
    }
}

Property	Type	Description
`error`	boolean	Indicates if an error has occurred. If `false`, the request was successful. If `true`, an error has occurred.
`free`	boolean	Indicates whether you were charged. This is always `true` if you found the email before or if the `email_status` is not `VALID`.
`email`	string	The email that was verified.
`email_status`	string	The verification status of the email. Possible values are `VALID`, `CATCH_ALL`.
`first_name`	string	The first name of the email address owner.
`last_name`	string	The last name of the email address owner.
`domain`	string	The domain part of the email.
`total_emails`	integer	The total number of emails that we have linked to that domain in our database.

The email_status can be either VALID or CATCH_ALL. If an email was not found, or if the mail server can't be reach, we will return an error code, see below.

Specific error codes

ℹ️

If you can't find the error message on this list, check our general error message.

Error code	Message	Meaning
`400`	`NO_RESULT`	We couldn't find any valid or risky email linked to the provided details.
`400`	`INVALID_DOMAIN_NAME`	The domain name you submitted is not reachable or does not have valid MX records.
`400`	`INVALID_COMPANY`	The company name you submitted is invalid (3-75 characters).
`400`	`CANT_FIND_DOMAIN`	We can't find which domain name this company use for sure, so instead of returning a false-positive, we return this message.
`400`	`DOMAIN_IS_WEBMAIL`	The company you submitted is a webmail (Gmail, Outlook, and others).
`400`	`NO_VALID_NAME`	The provided name is not valid. Check the required format.

Rate limit

The rate limits are:

150 call per minute
5 call per second (burst allowance)

When the limit is reached, we will return a 429 error code.

ℹ️

If you need your rate limit to be increased, feel free to contact us at [email protected]. The rate limit can easily be increased to 15+ requests per second (1000+ per minute).

Response time

On average, a request take around 4 seconds but can extend up to 10 seconds.

Given that this product performs all of its test in real-time, the response time largely depends on the SMTP server of the targeted domain/company.

We don't just make attempts to validate emails through SMTP; but we also execute much more complex operations to uncover catch-all emails, which are beyond the scope of standard SMTP-pinging approaches.

While a majority of SMTP servers have quick response times, when encountering a catch-all SMTP, we delve deeper and elsewhere on the web to verify the email. This additional investigation can increase the response time.

We recommend not setting a timeout.

ℹ️

In any case, rest assured that we have established hard limits on our response time. There's no need to worry about your system hanging indefinitely while waiting for our response.