EmailFinder 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 or testing 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.

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.

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:

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.

Emails

Find emails

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

Parameters

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

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",
    "client_valid": "true"
  }
}

Test emails

This is the endpoint for doing one-off mailserver email testing. EmailFinder will communicate with the MX server and attempt to validate the address.

Parameters

key Your API key required
address The email address you want to test. required

Parameters

address (required)
The email address you want to test.

Responses

address The email address tested
result: valid The email address is valid on the host.
result: invalid The email address could not be validated on the host.
result: catchall The email address is on a server that responds positively to all requests.

Example

GET https://www.emailfinder.io/api/v1/email-tester?key=<<log in to see your key>>&address=james@motown.com

Result

{
  "status": "SUCCESS",
  "message": "Tested email.",
  "data": {
    "score": 0,
    "result": "invalid",
    "error": "NoServerError",
    "address": "james@motown.com",
    "client_valid": "true"
  }
}

Handshake emails

This is the endpoint for doing one-off mailserver handshakes specifically. EmailFinder will communicate with the MX server and attempt to validate the address regardless of past attempts or other testing logic that may bypass the handshake. By default this endpoint queues a handshake job so we can use more resilient infrastructure.

Parameters

key Your API key required
address The email address you want to test. required
now Perform the test in the same request (instead of queuing a job). optional

Parameters

address (required)
The email address you want to test.

Responses

address The email address tested
result: valid The email address is valid on the host.
result: invalid The email address could not be validated on the host.
result: catchall The email address is on a server that responds positively to all requests.

Example

GET https://www.emailfinder.io/api/v1/email-handshaker?key=<<log in to see your key>>&address=james@motown.com

Result

{
  "status": "SUCCESS",
  "message": "Queued email handshake job.",
  "data": {
    "address": "james@motown.com",
    "mailserver": "catchall",
    "catchall": true,
    "friendly_pattern": "first",
    "client_valid": "true"
  }
}

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 Your API key required
name A name to identify or describe your batch. required
data JSON formatted employee or email payload. required
tier Must be one of regular, verified, or handshake. Regular batches may default to the top pattern for an email if available. It's the fastest option. Verified batches require an email send. Handshake batches require a mailserver test. required
webhook_url Fully-formed URL to accept a POST request containing the batch attributes when the batch status changes to finished. optional

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 First name of the employee. required
last_name Last name of the employee. required
company Name of company (can be string or website or domain). required
meta JSON formatted metadata, which could include an internal ID. optional

The data JSON payload must have these keys for email records.

email The email address you want to verify. required
meta JSON formatted metadata, which could include an internal ID. optional

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",
      "client_valid": "true",
      "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",
      "client_valid": "true",
      "meta": {
        "other_key": "def456",
        "internal_id": "abc123"
      }
    }
  ]
}

Purge batch

This is call to remove the compiled export from a batch.

Example

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

Result of purged batch

{
  "status": "SUCCESS",
  "message": "Batch data purge queued."
}

© 2023 Live Data Technologies. All rights reserved.