EmailFinder.io Bulk Email Finder API Documentation (V1)

The EmailFinder API enables you to find employee emails in batches of up to 1,000 employees. This API also supports single email verifications with our guaranteed delivery scoring technology.

Calling the API

V1 of the API is hosted at https://www.emailfinder.io/api/v1. All calls use this URL as the base.

Authentication

The EmailFinder API uses token-based authentication. If you're logged into your EmailFinder account, you'll see your API key below.

Your API key is <<log in to see your key>>.

Simply include key as a query parameter or a header parameter in your queries, like this: https://www.emailfinder.io/api/v1/batches?key=<<log in to see your key>>.

If you don't include an API key or use the wrong one, EmailFinder will respond with a 401 authorization error.

Status and Error Codes

Here are the most common HTTP status codes you may receive from our API and what they mean.

  • 200: Request and response were successful.
  • 401: The API key you used was not found.
  • 404: The recipient you're looking for wasn't found or is not accessible from your account.
  • 405: The method you attempted was not allowed.
  • 500: There was a server error.

Confidence Scores

The confidence score is a way for us to tell you numerically about the likelihood an email will bounce. Every email that EmailFinder responds with will include a confidence score. The number is a weighted average of serveral tests performed to determine its deliverability. These tests include:

  • Generic domain: Scores lower if the email domain is a generic or free email service provider (like Gmail, Hotmail, etc)
  • Disposable domain: Scores lower if the email domain is a disposable service (like Mailinator, 10minutemail, etc)
  • Catchall domain: Scores lower if the domain is a catchall (and accepts every request)
  • MX records: Scores lower if DNS check shows no MX records
  • Gibberish: Scores lower if gibberish is detected in the email handle
  • Likely list: Scores lower if the email handle is probably a list (like support, help, sales, contact, etc)
  • Has a name: Scores higher if the email handle includes a person's name
  • Email pattern: Scores higher if the top scoring email is also the most common pattern for the domain
  • Mailserver: Scores higher if the mailserver responds to the handle

Given these scores, we can give some examples for how it shakes out. In short, only by passing in verified on the batch can you be certain the email won't bounce. Also, to make it easier for you, we provide a quality parameter with values low, medium, and high, which correspond to the confidence thresholds for likelihood of bouncing.

  • Score 33: Domain has MX records and isn't a catchall. Handle passes all tests, but mailserver response is blank and pattern is not common on the domain. Likely to bounce!
  • Score 60: Domain has MX records and isn't a catchall. Handle passes all tests, but mailserver response is blank. However, the pattern is very common on the domain. Not likely to bounce!
  • Score 94: Domain has MX records and isn't a catchall. Handle passes all tests, mailserver response is positive, and the pattern is very common on the domain. Very unlikely to bounce!
  • Score 100: We confirmed that the email can be delivered. 100% deliverability

Finally, here are the API response codes.

  • 200: Request and response were successful.
  • 401: The API key you used was not found.
  • 404: The recipient you're looking for wasn't found or is not accessible from your account.
  • 405: The method you attempted was not allowed.
  • 500: There was a server error.

Emails

Find emails

This is the endpoint for doing one-off email finding.

Parameters
first_name (required)
First name of the employee.
last_name (required)
Last name of the employee
company (required)
Name of company (can be string or website or domain)
Example

GET https://www.emailfinder.io/api/v1/email-finder?key=<<log in to see your key>>&first_name=james&last_name=brown&company=motown

Result

{
  "status": "SUCCESS",
  "message": "Found email.",
  "data": {
    "first_name": "james",
    "last_name": "brown",
    "address": "james@motown.com",
    "confidence": 60,
    "verified": "unverified",
    "quality": "medium",
    "domain": "motown.com"
  }
}

Batches

List batches

This is the index call for your batches. Batches store the bulk employee data you submit for processing. A status attibute on the batch will tell you whether the batch is still processing or finished.

Example

GET https://www.emailfinder.io/api/v1/batches?key=<<log in to see your key>>

Result

{
  "status": "SUCCESS",
  "message": "Loaded all batches.",
  "data": [
    {
      "id": 24,
      "user_id": 1,
      "name": "Marketing batch A",
      "created_at": "2020-02-04T23:38:06.876Z",
      "updated_at": "2020-02-04T23:38:06.955Z",
      "status": "ready"
    }
  ],
  "last_page": true,
  "total_count": 1
}

Create a batch

Add a batch of employees or emails to process on your account. Note that we will attempt to verify all emails entered in the batch, regardless of the verified parameter.

Parameters
key (required)
Your API key
name (required)
A name to identify or describe your batch
data (required)
JSON formatted employee or email payload
webhook_url (optional)
Fully-formed URL to accept a POST request containing the batch attributes when the batch status changes to finished.
verified (optional)
Put true if you want to test the best email by sending a real email. Omit this param or put false if not desired.
The data JSON payload must have these keys for employee records. Note that the first_name, last_name, and company fields must have at least one character and no non-ASCII characters.
first_name (required)
First name of the employee.
last_name (required)
Last name of the employee
company (required)
Name of company (can be string or website or domain)
meta (optional)
JSON formatted metadata, which could include an internal ID
The data JSON payload must have these keys for email records.
email (required)
The email address you want to verify
Example

POST https://www.emailfinder.io/api/v1/batches

Result

{
  "status": "SUCCESS",
  "message": "Created batch.",
  "data": {
    "id": 24,
    "user_id": 1,
    "name": "Marketing batch A",
    "created_at": "2020-02-04T23:38:06.876Z",
    "updated_at": "2020-02-04T23:38:06.955Z",
    "status": "ready"
  }
}

Export batch

This is the index call for the data in a batch. To export all your data, you must do so on a batch-by-batch basis.

Each employee and email has a confidence attribute with a number between 0 and 100 and a verified attribute with one of these values: unverified, verified_true or verified_false.

Example

GET https://www.emailfinder.io/api/v1/batches/<batch_id>/export?key=<<log in to see your key>>

Result of unverified batch

{
  "status": "SUCCESS",
  "message": "Loaded employees.",
  "data": [
    {
      "first_name": "james",
      "last_name": "brown",
      "address": "james@motown.com",
      "confidence": 60,
      "verified": "unverified",
      "quality": "medium",
      "domain": "motown.com",
      "meta": {
        "other_key": "def456",
        "internal_id": "abc123"
      }
    }
  ]
}

Result of verified batch

{
  "status": "SUCCESS",
  "message": "Loaded employees.",
  "data": [
    {
      "first_name": "james",
      "last_name": "brown",
      "address": "james@motown.com",
      "confidence": 100,
      "verified": "verified_true",
      "quality": "high",
      "domain": "motown.com",
      "meta": {
        "other_key": "def456",
        "internal_id": "abc123"
      }
    }
  ]
}