EmailFinder | Find emails with our API

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.

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

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."
}

EmailFinder API Documentation (v1)

Calling the API

Authentication

Status and Error Codes

Confidence Scores

Emails

Find emails

Parameters

Example

Result

Test emails

Parameters

Parameters

Responses

Example

Result

Handshake emails

Parameters

Parameters

Responses

Example

Result

Batches

List batches

Example

Result

Create a batch

Parameters

Example

Result

Export batch

Example

Result of unverified batch

Result of verified batch

Purge batch

Example

Result of purged batch