Send yourself an email reminder

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 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 and regardless of the result.
  • 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, but you should set a very high timeout (e.g. 30 seconds) to make sure you get a result when the email server we are quering is slower than usual.

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/v4.0/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": "no_credits_left",
  "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/v4.0/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/v4.0/search/person.json

with the following parameters.

Field Type Description
full_name String The full name of the person to search
first_name String The first name of the person to search
last_name String The last 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

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.

Successful search

{
  "email": "jsmith@acme.com",
  "email_class": "verified",
  "alternatives": [
    "john@acme.com",
    "smithj@acme.com"
  ],
  "input": {
    "full_name": "John Smith",
    "company_name": "Acme Inc"
  },
  "domain": "acme.com",
  "status": "success"
}

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

Field Description
email The email of the person
alternatives The alternative valid emails that could belong to the person
email_class Either verified or not_verified
domain The domain we found for the company name (only returned if domain was not part of the input)
input A hash containing the input we received in your request

Errors

{
  "error": "not_found",
  "error_explained": "The email has not been found on the server",
  "input": {
    "full_name": "John Smith",
    "company_name": "Acme Inc"
  },
  "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 bad_request The field specified in field 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 the provided company_name
451 blacklisted This happens when the owner of the domain you are searching has asked us to blacklist their website, or when you try to search a personal domain like gmail.com.

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/v4.0/search/company.json

with the following parameters.

Field Type Description
domain String The domain to search the emails at
company_name String The company name to search the emails at

A domain or a company_name is required.

The request will return one of the following responses.

Successful search

{
  "emails": ["john@acme.net", "mark@acme.com", "joe@acme.com"],
  "email_class": "not_verified",
  "input": {
    "domain": "acme.com"
  },
  "domain": null,
  "status": "success"
}

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

Field Description
emails A list of emails
email_class Either verified or not_verified
domain The domain we found for the company name (only returned if domain was not part of the input)
input A hash containing the input we received in your request

Errors

{
  "error": "not_found",
  "error_explained": "The email has not been found on the server",
  "input": {
    "full_name": "John Smith",
    "company_name": "Acme Inc"
  },
  "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 bad_request The field specified in field 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 the provided company_name
451 blacklisted This happens when the owner of the domain you are searching has asked us to blacklist their website, or when you try to search a personal domain like gmail.com.

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/v4.0/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,
  "input": {
    "email": "john@acme.com"
  },
  "status": "success"
}

with email_verified either true or false if the email could have been 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, so we can't check whether yours is correct",
  "input": {
    "email": "john@acme.com"
  },
  "status": "error"
}

A full list of possible errors follows.

Error code Error string Description
400 bad_request The field specified in field is not correct / you haven't provided one
451 blacklisted This happens when the owner of the domain you are searching has asked us to blacklist their website, or when you try to search a personal domain like gmail.com.
513 catch_all The domain accepts all emails, so we can't check whether yours is correct
514 server_not_responding The server is not responding to our requests

Check domain status

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

https://api.anymailfinder.com/v4.0/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",
  "is_blacklisted": false,
  "person_search": true,
  "domain_search": true,
  "domain_count": 3,
  "input": {
    "domain": "acme.com"
  }
}
Field Description
is_blacklisted Whether the domain is blacklisted from Anymail finder
person_search Whether we can find a specific person's email on this domain
domain_search Whether we can return a list of emails for this domain
domain_count The number of emails we are likely to return on a domain search for this domain
input A hash containing the input we received in your request