Anymail finder

API Documentation

Gain access to the the millions of emails in our database—and our core validator through an easy to use 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 includes almost everything you'll find in our app. There are two minor differences:

  • Pricing: Because we log requests from the API differently, you will be charged for the same search twice. You are encouraged to keep a local cache of the results. Additionally, you will be charged for unverified and generic emails, but you will have the option to turn them off for each request, and to know in advance what kind of info we have on each domain.
  • 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. Most requests are completed in less than 1 second.

Authentication & status

Check the status of the API

To check the status of the API, make a GET request to the following endpoint.

https://api.anymailfinder.com/v3.1/health.json

This will return a JSON response that looks like this:

{
  "healthy": true,
  "status": "success"
}

Authentication

All requests except the previous require authentication. To authenticate, you'll need to set an X-Api-Key header with the API key you find in your settings as value.

A failed authentication will return this error:

{
  "error": "key_not_found",
  "status": "unauthorized"
}

If you run out of credits and make a request where you might have to use one, this error will be returned:

{
  "error": "too_many_requests",
  "status": "unauthorized"
}

Rate limits

To make sure the API works well for everyone, we apply three rate limits.

By organization

You will hit the rate limit if you perform more than 15,000 requests in any 60 minute period, or more than 10 per second, with the same API key.

By IP address

You will hit the rate limit if you perform more than 50,000 requests in any 60 minute period, or more than 50 per second, from the same IP address.

By domain

To ensure we don't overload any website, you will only be able to find emails on the same domain up to 60 times per hour, and no more than 2 times per second.

This rate limit applies to all endpoints that accept a domain parameter, as well as our verification endpoint based on the domain of the email you provide.

Specifications

  • The rate limit applies to all requests, whether successful or not.
  • We never charge credits for requests that hit the rate limit.
  • The rate limit is calculated on the number of requests in the previous 60 minutes. Therefore, you won't be able to perform 15,000 requests in the last few minutes of an hour, and 15,000 more in the first few minutes of the following one.
  • Requests blocked by the rate limit will prolong the limit. Therefore you should wait the number of seconds contained in retry_in before making another request.
  • If you hit our domain rate limit, other rate limits will not be affected. You only need to wait for retry_in to perform other requests with the same domain.

If you hit the rate limit, the response will look like this:

{
  "error": "rate_limit_exceeded",
  "status": "unauthorized",
  "scope": "account", // Either 'account', 'ip', or 'domain'
  "retry_in": 3600
}

Our enterprise customers have the option of requesting a dedicated server without rate limiting for an extra fee.

Checking how many searches you have left

To check how many searches you have left on your account, make a GET request to the following endpoint.

https://api.anymailfinder.com/v3.1/account/hits_left.json

This will return a JSON response that looks like this:

{
  "credits_left": 5000,
  "status": "success"
}

Usage of the API

Differently from our website, all searches made through the API are performed immediately. This means that requests to the following endpoints might take a few seconds to complete.

Performing an email search (Personal email)

To perform an email search of a specific person, make a POST request to the following endpoint

https://api.anymailfinder.com/v3.1/search/person.json

with the following parameters.

Field Type Description
name String The name of the person to search
domain String The domain to search the email at.
company_name String The name of the company to search the email at.
include_pattern Boolean (true or false) Whether you will accept an email guessed from the most common pattern at that domain (defaults to true).

name, and domain or company_name are required parameters. Providing a domain will yield better results than a company_name.

There is no need to provide both a domain and a company_name. If they are both present, the company_name will be ignored.

The request will return one of the following responses.

Successful search

{
  "alternatives": [
    "john@acme.com",
    "smithj@acme.com"
  ],
  "best_guess": "jsmith@acme.com",
  "email_class": "validated",
  "status": "success"
}

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

Field Description
alternatives A list of other emails that could belong to the person (it can be empty).
best_guess Our best guess.
email_class One of: validated (with the server), (guessed from the) pattern, or crawled (somewhere on the web).

Errors

{
  "error": "not_found",
  "error_explained": "The email has not been found on the server",
  "status": "error"
}

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

Error code Error string Description
400 input.{FIELD} The {FIELD} you provided is not correct / you haven't provided one.
404 not_found We could not find an email.
404 company_name_not_found We could not find a domain for company_name.
516 blacklist This happens when the owner of the domain you are searching has asked us to blacklist their website.

Performing an email search (All emails)

To retrieve a list of emails at a particular domain, make a POST request to the following endpoint

https://api.anymailfinder.com/v3.1/search/domain.json

with the following parameters.

Field Type Description
domain String The domain to search the emails at.
include_generic Boolean (true or false) Whether you'd like us to include generic emails (e.g. info@acme.com).

The request will return one of the following responses.

Successful search

{
  "emails": [
    {
      "email": "john@acme.net",
      "email_class": "validated"
    },
    {
      "email": "comments@acme.net",
      "email_class": "generic"
    },
    {
      "email": "support@acme.net",
      "email_class": "generic"
    }
  ],
  "status": "success"
}

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

Field Description
emails A list of emails found on the website.

Each email is an object that looks like this:

Field Description
email The email
email_class One of: validated (with the server), crawled (but not verified), or generic (like info@).

NB: It's unlikely you will find validated and crawled emails together. If we can perform validation, we'll only include valid ones and take out the ones that do not exist.

Errors

{
  "error": "not_found",
  "error_explained": "The email has not been found on the server",
  "status": "error"
}

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

Error code Error string Description
400 input.{FIELD} The {FIELD} you provided is not correct / you haven't provided one.
404 not_found No emails were found.
516 blacklist This happens when the owner of the domain you are searching has asked us to blacklist their website.

Validating an email

The API will also give you access to our validator.

To validate an email address, make a POST request to the following endpoint

https://api.anymailfinder.com/v3.1/validate.json

with the following parameters:

Field Type Description
email String The email to validate

Response

The request will return a response that looks like this,

{
  "email_verified": true,
  "status": "success"
}

with email_verified true or false if the email could be verified. This means that if email_verified is false, it is safe to assume the email is wrong.

If the status code is 200 you will be charged 1 credit, regardless of the email being correct or not.

Errors

An error like the following will be returned if the email could not be validated.

{
  "error": "catch_all",
  "error_explained": "The domain accepts all emails",
  "status": "error"
}

A full list of possible errors follows.

Error code Error string Description
400 input.{FIELD} The {FIELD} you provided is not correct / you haven't provided one.
513 catch_all This error happens when the server is set up to accept emails at all address.
514 server_not_responding This error happens when the server is ignoring our requests.
516 blacklist This happens when the owner of the domain you are searching has asked us to blacklist their website.

Check domain status

To check what kind of info we have on a particular domain, make a get request to the following endpoint

https://api.anymailfinder.com/v3.1/domains/check.json

with the following fields:

Field Type Description
domain String The domain to check

Response

A successful response will look like this:

{
  "status": "success",
  "can_validate": true,
  "is_blacklisted": false,
  "crawled_emails": {
    "personal_count": 5,
    "generic_count": 2
  },
  "has_pattern": true
}
Field Description
can_validate Whether we can perform server validation on this domain.
is_blacklisted Whether this domain is blacklisted.
crawled_emails.personal_count The number of personal emails we have collected for this domain.
crawled_emails.generic_count The number of generic emails we have collected for this domain.
has_pattern Whether we have information on the most common pattern for this domain.

Finding the domain for a company name

To find the domain name for a company name, make a POST request to the following endpoint

https://api.anymailfinder.com/v3.1/search/company_name.json

with the following parameters.

Field Type Description
company_name String The name of the company to find the domain for.

The request will return one of the following responses.

Successful search

{
  "domain": "acme.com",
  "status": "success"
}

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

Field Description
domain The domain.

Errors

{
  "error": "not_found",
  "error_explained": "The email has not been found on the server",
  "status": "error"
}

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

Error code Error string Description
400 input.{FIELD} The {FIELD} you provided is not correct / you haven't provided one.
404 company_name_not_found We could not find a domain for company_name.
516 blacklist This happens when the owner of the domain you are searching has asked us to blacklist their website.