Anymail finder API

Anymail finder is built with reliability in mind. In over two years of operation it suffered only minor downtime, none of which affected the API, which is completely separate.

The API provides access to the complete Anymail finder database, our validator, and our email guesser.

You can find your API key in your account settings.

Differences from the website

The current version of our API will provide the same results you will get in our web app.

  • Pricing: On Anymail finder, you never pay for the same query twice, regardless of your billing period. The only exception to this are:
    • email verifications, which are charged every time you perform them, regardless of the result;
    • employee name lookups, which are charged every time you perform them, if we find at least one employee.
  • Speed: The API performs all requests in real time, so while the load time might be a bit slow, you won’t have to check back for a result. It can take several seconds for the server to respond, so you should set a high timeout within your application (at least 60 seconds).

API Status

You can make a request to our GET status endpoint to check the status of the API.

In your logic, any 503 response should be treated the same way & retried after a few seconds.

To check the status of the API, make a request to:

GET
https://api.anymailfinder.com/status

If the API is healthy, the following response will be returned.

200 - OK
{
"healthy": true
}

If the API is currently experiencing issues, the following error will be returned. Any response with a status code other than 200 - OK should be interpreted as the API having downtime.

503 - SERVICE UNAVAILABLE
{
"healthy": false
}

Authentication

All requests except the GET /status endpoint require authentication. To authenticate, you’ll need to set an Authorization header with the API key you find in your settings as value.

For example, if your API key is secret_key_123 you will want to add a Authorization header with value Bearer secret_key_123

A failed authentication will return this error:

401 - UNAUTHORIZED
{
"error": "not_authorized",
"error_explained": "Please make sure you are authenticating this request correctly.",
"success": false
}

If you run out of credits, this error will be returned:

402 - PAYMENT NEEDED
{
"error": "upgrade_needed",
"status": "You will need to upgrade your account at https://app.anymailfinder.com/purchase",
"success": false
}

Rate limits

Our API has been reworked from the ground up to remove rate limits. We now aim to process queries as fast as possible and will scale up our back-end resources when more request come in.

To accomplish this we have implemented an internal queue system that makes sure requests are served fast and that priority is given to smaller accounts. Your request can be in this queue for up to 1 minute. Do not terminate / restart the request, as this will put you at the back of the queue.

When a large number of requests comes in and we are unable to meet the demand quickly enough, we’ll be returning a 503 response. Whenever you encounter this, you are encouraged to retry the request after a few seconds.

When we are unable to serve your request quickly enough, the following error will be returned:

503 - SERVER BUSY
{
"error": "server_busy",
"error_explained": "Our server is currently under heavy load, please slow down."
}

Checking how many searches you have left

If you’d like to know how many credits you have left, you can make a request to our GET /v5.0/meta/account.json endpoint.

To check how many searches you have left on your account, make a request to:

GET
https://api.anymailfinder.com/v5.0/meta/account.json

Response

FieldTypeDescription
credits_leftIntegerHow many credits are left
credits_totalIntegerTotal number of credits initially available to you
credits_used_not_verifiedIntegerNumber of requests that would have used a credit but were free because not verified
credits_used_verifiedIntegerNumber of credits used for verified emails

This will return a JSON response that looks like this:

200 - OK
{
"credits_left": 1000,
"credits_total": 5000,
"credits_used_not_verified": 1000,
"credits_used_verified": 3000,
"success": true
}

Find someone’s email

Use our POST /v5.0/search/person.json endpoint to find an individual’s email.

Parameters

FieldTypeDescription
full_nameStringThe full name of the person to search
first_nameStringThe first name of the person to search
last_nameStringThe last name of the person to search
domainStringThe domain to search the email at
company_nameStringThe name of the company to search the email at
country_codeStringThe country code (e.g. US) to target the company name conversion in.

You must provide either a domain or a company_name. Providing a domain will yield better results than a company_name.

You must provide either a full_name, or both a first_name and a last_name.

The request will return one of the following responses.

To perform an email search of a specific person, make the following request:

POST
https://api.anymailfinder.com/v5.0/search/person.json
{
"domain": "hundo.io",
"full_name": "Joe d'Elia"
}

Successful search

Successful searches will cost one credit, taken from your Anymail finder balance.

FieldDescription
inputYour original input
results.emailThe most likely email for the person
results.validationEither valid or unknown depending on whether we could confirm with the server.
results.alternativesAn array of other possible emails.

A successful response will look like this:

200 - OK
{
"input": {
"company_name": null,
"country_code": null,
"domain": "hundo.io",
"first_name": null,
"full_name": "Joe d'Elia",
"last_name": null
},
"results": {
"alternatives": [
"joedelia@hundo.io"
],
"email": "joed@hundo.io",
"validation": "valid"
},
"success": true
}

Errors

One of the following errors might be returned by the server. You will not be charged any credits if you incur an error.

Error codeError stringDescription
400bad_requestThe field specified in field is not correct / you haven’t provided one
404no_resultWe could not find an email
404domain_not_foundWe could not find a domain from the company name provided
404domain_records_not_foundThe domain does not have valid email hosting
451blacklistedWe are not allowed to return this email because its owner has asked us to remove it from our database.

An error from the endpoint will generally look like this:

404 - NOT FOUND
{
"error": "no_result",
"error_explained": "We could not find an email for this person. Sorry.",
"input": {
"company_name": null,
"country_code": null,
"domain": "hundo.io",
"first_name": null,
"full_name": "Mark d'Elia",
"last_name": null
},
"success": false
}

Finding all emails at a company

You can pull up the most popular emails at a particular company with our POST /v5.0/search/company.json endpoint.

Parameters

A domain or a company_name is required.

FieldTypeDescription
domainStringThe domain to search the emails at
company_nameStringThe company name to search the emails at

The request will return one of the following responses.

To retrieve a list of emails at a company, use the following endpoint:

POST
https://api.anymailfinder.com/v5.0/search/company.json
{
"domain": "hundo.io"
}

Successful search

Successful searches will cost one credit, taken from your Anymail finder balance.

FieldDescription
inputYour original input
results.emailsAn array of emails at the company
results.validationEither valid or unknown depending on whether we could confirm with the server.
results.totalCountThe total number of emails in our database at the searched company. Refining the search by adding a person name will show these results.

A successful response looks like this:

200 - OK
{
"input": {
"company_name": null,
"country_code": null,
"domain": "hundo.io"
},
"results": {
"emails": [
"joedelia@hundo.io",
"cameronjames@hundo.io"
],
"totalCount": 4,
"validation": "valid"
},
"success": true
}

Errors

One of the following errors might be returned by the server. You will not be charged any credits if you incur an error.

Error codeError stringDescription
400bad_requestThe field specified in field is not correct / you haven’t provided one
404no_resultWe could not find any emails
404domain_not_foundWe could not find a domain from the company name provided
404domain_records_not_foundThe domain does not have valid email hosting
451blacklistedWe are not allowed to return this email because its owner has asked us to remove it from our database.

An error response will generally look like this:

404 - NOT FOUND
{
"input": {
"company_name": null,
"country_code": null,
"domain": "hundo.io"
},
"results": {
"emails": [
"joedelia@hundo.io",
"cameronjames@hundo.io"
],
"validation": "valid"
},
"success": true
}

Listing a company’s employees

If you want to find a list of employees at a company you can use our POST /v5.0/search/employees.json endpoint. A credit will be charged each time there is at least one result.

Parameters

A domain or a company_name is required, as well as a preferred_title

FieldTypeDescription
domainStringThe domain to search the employees
company_nameStringThe company name to search the employees
preferred_titleStringThe target job title to look for
country_codeStringThe country code (e.g. US) to target the search in

The request will return one of the following responses.

To retrieve a list of employees at a company, use the following endpoint:

POST
https://api.anymailfinder.com/v5.0/search/employees.json
{
"company_name": "Upscope",
"domain": "upscope.io",
"preferred_title": "CTO"
}

Successful search

Successful searches will cost one credit, taken from your Anymail finder balance.

FieldDescription
inputYour original input
company_name_usedThe company name used to search for employees (in case it was converted from a domain)
employees[].companyThe name of the company for the employee (can vary slightly from the search name)
employees[].linkedin_urlIf available, the URL of the employee’s linkedin account
employees[].nameThe name of the employee
employees[].titleThe job title of the employee

A successful response looks like this:

200 - OK
{
"company_name_used": "upscope",
"employees": [
{
"company": "Upscope",
"linkedin_url": "https://uk.linkedin.com/in/thejoedelia",
"name": "Joe d'Elia",
"title": "Co-Founder"
}
],
"input": {
"company_name": "upscope",
"country_code": null,
"domain": "upscope.io",
"preferred_title": "CTO"
},
"success": true
}

Errors

One of the following errors might be returned by the server. You will not be charged any credits if you incur an error.

Error codeError stringDescription
400bad_requestThe field specified in field is not correct / you haven’t provided one
404no_resultWe could not find any employees
404company_name_not_foundWe could not convert the domain into a valid company name
451blacklistedWe are not allowed to return this employee because they have removed themselves from our database.

An error response will generally look like this:

404 - NOT FOUND
{
"error": "company_name_not_found",
"error_explained": "We could not find the correct company name",
"success": false
}

Validating an email

You can use our POST /v5.0/validate.json

Parameters

FieldTypeDescription
emailStringThe email to validate

To validate an email, make the following request

POST
https://api.anymailfinder.com/v5.0/validate.json
{
"email": "jo@hundo.io"
}

Response

A successful response will contain a validation field with either valid, invalid or unknown if the validation was inconclusive.

A credit will be charged regardless of the outcome.

A successful response will look like this:

200 - OK
{
"input": {
"email": "jo@hundo.io"
},
"success": true,
"validation": "invalid"
}

Errors

A full list of possible errors follows.

Error codeError stringDescription
400
bad_requestThe email to validate is missing.

An error response looks like this:

400 - BAD REQUEST
{
"error": "bad_request",
"error_explained": "Please enter a valid email",
"field": "email",
"input": {
"email": null
},
"success": false
}