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.
V1 of the API is hosted at https://www.emailfinder.io/api/v1
. All calls use this URL as the base.
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.
Here are the most common HTTP status codes you may receive from our API and what they mean.
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.
This is the endpoint for doing one-off email finding.
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 |
GET https://www.emailfinder.io/api/v1/email-finder?key=<<log in to see your key>>&first_name=james&last_name=brown&company=motown
{ "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" } }
This is the endpoint for doing one-off mailserver email testing. EmailFinder will communicate with the MX server and attempt to validate the address.
key | Your API key | required |
address | The email address you want to test. | required |
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. |
GET https://www.emailfinder.io/api/v1/email-tester?key=<<log in to see your key>>&address=james@motown.com
{ "status": "SUCCESS", "message": "Tested email.", "data": { "score": 0, "result": "invalid", "error": "NoServerError", "address": "james@motown.com", "client_valid": "true" } }
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.
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 |
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. |
GET https://www.emailfinder.io/api/v1/email-handshaker?key=<<log in to see your key>>&address=james@motown.com
{ "status": "SUCCESS", "message": "Queued email handshake job.", "data": { "address": "james@motown.com", "mailserver": "catchall", "catchall": true, "friendly_pattern": "first", "client_valid": "true" } }
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.
GET https://www.emailfinder.io/api/v1/batches?key=<<log in to see your key>>
{ "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 }
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.
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.
The email address you want to verify. | required | |
meta | JSON formatted metadata, which could include an internal ID. | optional |
POST https://www.emailfinder.io/api/v1/batches
{ "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" } }
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
.
GET https://www.emailfinder.io/api/v1/batches/<batch_id>/export?key=<<log in to see your key>>
{ "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" } } ] }
{ "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" } } ] }
This is call to remove the compiled export from a batch.
POST https://www.emailfinder.io/api/v1/batches/<batch_id>/purge?key=<<log in to see your key>>
{ "status": "SUCCESS", "message": "Batch data purge queued." }
© 2023 Live Data Technologies. All rights reserved.