Authentication
Introduction
curl "https://api.emailable.com/v1/{api_endpoint}?api_key={your_api_key}"
Emailable.api_key = 'your_api_key'
var emailable = require("emailable")("your_api_key");
client = emailable.Client('your_api_key')
Make sure to replace
your_api_key
with your API key.
Emailable uses API keys to allow access to our API. To get started, sign up for an account here.
Emailable expects the API key to be included in all API requests to the server as a URL parameter, or as POST data for POST endpoints.
Security
Emailable has two types of API Keys. Please use the proper API key for your application.
Public API Keys
This type of key is meant to be used anywhere that the key will be exposed publicly. One example would be using the API in the Javascript of a website to verify that user entered email addresses are valid.
To prevent abuse of your account, we require that you set up a list of trusted domains when you create a public API key. All requests that are made using a public API key will only work if they originate from a trusted domain. They will also be rate limited to 10 requests per day per user.
Also note that only the /verify
endpoint can be used with public API keys.
Private API Keys
This type of key is meant to be used on the server-side of your application. These keys should never be exposed because they are not protected.
Should a private API key be compromised, you should immediately generate a new one by using the "roll key" function in the dashboard.
Client Libraries
gem install emailable
npm install emailable --save
# or
yarn add emailable
pip install emailable
Below is a list of client libraries.
Emails
Verify an email
curl "https://api.emailable.com/v1/verify?email=john@smith.com&api_key=your_api_key"
Emailable.verify('john@smith.com')
emailable.verify('john@smith.com')
.then(function (response) {
// asynchronously called
});
client.verify('john@smith.com')
The above command returns JSON structured like this:
{
"accept_all": null,
"did_you_mean": null,
"disposable": false,
"domain": "gmail.com",
"duration": 0.493,
"email": "john.smith@gmail.com",
"first_name": "John",
"free": true,
"full_name": "John Smith",
"gender": "male",
"last_name": "Smith",
"mx_record": "aspmx.l.google.com",
"reason": "accepted_email",
"role": false,
"score": 100,
"smtp_provider": "google",
"state": "deliverable",
"tag": null,
"user": "john.smith"
}
If a verification is taking too long, a 249 status code will be returned:
{
"message": "Your request is taking longer than normal. Please send your request again."
}
Verify a single email. If a verification request takes longer than the timeout, you may retry this request for up to 5 minutes. After 5 minutes, further requests will count against your usage. The verification result will be returned when it is available.
When a test key is used, a random sample response will be returned.
HTTP Request
GET https://api.emailable.com/v1/verify
Parameters
Parameter | Required | Description |
---|---|---|
true | The email you want verified. | |
smtp | false | "true" or "false". The SMTP step takes up a majority of the API's response time. If you would like to speed up your response times, you can disable this step. Default: true |
accept_all | false | "true" or "false". Whether or not an accept-all check is performed. Heavily impacts API's response time. Default: false |
timeout | false | Optional timeout to wait for response (in seconds). Min: 5, Max: 30. Default: 5 |
api_key | true | Your API key. |
Response
Attribute | Type | Description |
---|---|---|
accept_all | Boolean | Whether the mail server used to verify indicates that all addresses are deliverable regardless of whether or not the email is valid. |
did_you_mean | String | A suggested correction for a common misspelling. |
disposable | Boolean | Whether this email is hosted on a disposable or temporary email service. |
domain | String | The domain of the email. (e.g. The domain for john.smith@gmail.com would be gmail.com ) |
duration | Float | The length of time (in seconds) spent verifying this email. |
String | The email that was verified. | |
first_name | String | The possible first name of the user. |
free | Boolean | Whether the email is hosted by a free email provider. |
full_name | String | The possible full name of the user. |
gender | String | The possible gender of the user. |
last_name | String | The possible last name of the user. |
mx_record | String | The address of the mail server used to verify the email. |
reason | String | The reason for the associated state . |
role | Boolean | Whether the email is considered a role address. (e.g. support , info , etc.) |
score | Integer | The score of the verified email. |
smtp_provider | String | The SMTP provider of the verified email's domain. |
state | String | The state of the verified email. (e.g. deliverable , undeliverable , risky , unknown ) |
tag | String | The tag part of the verified email. (e.g. The tag for john.smith+example@gmail.com would be example ) |
user | String | The user part of the verified email. (e.g. The user for john.smith@gmail.com would be john.smith ) |
Verify a batch of emails
curl -X POST "https://api.emailable.com/v1/batch" -d "emails=tim@smith.com,john@smith.com" -d "url=http://example.com/callback" -d "api_key=your_api_key"
emails = ['tim@smith.com', 'john@smith.com']
callback = 'http://example.com/callback'
batch = Emailable::Batch.new(emails, callback: callback)
batch.verify
var emails = ['tim@smith.com', 'john@smith.com'];
var callback = 'http://example.com/callback';
emailable.batches.verify(emails, callback)
.then(function (response) {
// asynchronously called
});
emails = ['tim@smith.com', 'john@smith.com']
callback = 'http://example.com/callback'
client.batch(emails, callback_url=callback)
The above command returns JSON structured like this:
{
"message": "Batch successfully created.",
"id": "5cf6dd30093f96d2ac34bb0a"
}
Verify a batch of emails. The emails should be sent as a parameter emails
and
should be separated by commas. Up to 1,000 emails can be sent per batch.
If a URL is specified, the results will be sent to it via HTTP POST upon batch
completion. The body will be JSON data, identical to the output from the batch
status (GET /v1/batch
) endpoint below.
When a test key is used, a successful batch creation response will be returned along with an example batch id.
HTTP Request
POST https://api.emailable.com/v1/batch
Parameters
Parameter | Required | Description |
---|---|---|
emails | true | A comma separated list of emails. |
url | false | A URL that will receive the batch results via HTTP POST. |
api_key | true | Your API key. |
retries | false | Defaults to true. Retries increase accuracy by automatically retrying verification when our system receives certain responses from mail servers. To speed up verification, you can disable this by setting retries to false; however, doing so may increase the number of unknown responses. |
Response
Attribute | Type | Description |
---|---|---|
message | String | A message about your batch. |
id | String | The unique ID of the batch. |
Get the status of a batch
curl "https://api.emailable.com/v1/batch?api_key=your_api_key&id=5cf6dd30093f96d2ac34bb0a"
batch = Emailable::Batch.new('5cf6dd30093f96d2ac34bb0a')
batch.status
var id = '5cf6dd30093f96d2ac34bb0a';
emailable.batches.status(id)
.then(function (response) {
// asynchronously called
});
client.batch_status('5cf6dd30093f96d2ac34bb0a')
If your batch is incomplete, a message will be returned, as well as the batch's progress if it is processing:
{
"message": "Your batch is being processed.",
"processed": 1,
"total": 2
}
If you choose to include partial results, you will get emails and counts in your response, even if the batch is still processing (keep an eye on total_counts.processed and total_counts.total for progress):
{
"message": "Your batch is being processed.",
"emails": [
{
"accept_all": false,
"did_you_mean": null,
"disposable": false,
"domain": "gmail.com",
"email": "john.smith@gmail.com",
"first_name": "John",
"free": true,
"full_name": "John Smith",
"gender": "male",
"last_name": "Smith",
"mx_record": "aspmx.l.google.com",
"reason": "accepted_email",
"role": false,
"score": 95,
"smtp_provider": "google",
"state": "deliverable",
"tag": null,
"user": "john.smith"
}
],
"id": "5cf6dd30093f96d2ac34bb0a",
"reason_counts": {
"accepted_email": 1,
"invalid_domain": 0,
"invalid_email": 0,
"invalid_smtp": 0,
"low_deliverability": 0,
"low_quality": 0,
"no_connect": 0,
"rejected_email": 0,
"timeout": 0,
"unavailable_smtp": 0,
"unexpected_error": 0
},
"total_counts": {
"deliverable": 1,
"processed": 1,
"risky": 0,
"total": 2,
"undeliverable": 0,
"unknown": 0
}
When the batch completes, it will be indicated in the message field, and the results will be returned:
{
"emails": [
{
"accept_all": false,
"did_you_mean": null,
"disposable": false,
"domain": "gmail.com",
"email": "john.smith@gmail.com",
"first_name": "John",
"free": true,
"full_name": "John Smith",
"gender": "male",
"last_name": "Smith",
"mx_record": "aspmx.l.google.com",
"reason": "accepted_email",
"role": false,
"score": 95,
"smtp_provider": "google",
"state": "deliverable",
"tag": null,
"user": "john.smith"
},
{
"accept_all": false,
"did_you_mean": null,
"disposable": false,
"domain": "smith.com",
"email": "tim@smith.com",
"first_name": "Tim",
"free": false,
"full_name": "Tim",
"gender": "male",
"last_name": null,
"mx_record": "mx1.smith.com",
"reason": "accepted_email",
"role": false,
"score": 100,
"smtp_provider": null,
"state": "deliverable",
"tag": null,
"user": "tim"
}
],
"id": "5cf6dd30093f96d2ac34bb0a",
"message": "Batch verification completed.",
"reason_counts": {
"accepted_email": 2,
"invalid_domain": 0,
"invalid_email": 0,
"invalid_smtp": 0,
"low_deliverability": 0,
"low_quality": 0,
"no_connect": 0,
"rejected_email": 0,
"timeout": 0,
"unavailable_smtp": 0,
"unexpected_error": 0
},
"total_counts": {
"deliverable": 2,
"processed": 2,
"risky": 0,
"total": 2,
"undeliverable": 0,
"unknown": 0
}
}
GET requests to the batch endpoint will get the current status of the batch verification job specified in the "id" parameter.
When a credit card transaction is necessary to obtain enough credits to verify a batch, billing related messages will be returned if there is an error. These will be sent with a 402 response code.
When a test key is used, a random sample response will be returned.
After 30 days, the batch status endpoint will no longer return the emails and their individual verification results. Only the aggregate counts for the batch will be returned.
HTTP Request
GET https://api.emailable.com/v1/batch
Parameters
Parameter | Required | Description |
---|---|---|
id | true | The id of the batch. |
api_key | true | Your API key. |
partial | false | Defaults to false. A boolean value indicating whether to include partial results when a batch is still verifying. |
Response
Attribute | Type | Description |
---|---|---|
message | String | A message about your batch. |
processed | Integer | The number of emails that have been verified in the batch. |
total | Integer | The total number of emails in your batch. |
emails | Array | An array containing responses for each email in the batch. (See single email verification for more information on the response object.) |
id | String | The unique ID of the batch. |
reason_counts | Hash | A hash with one key per possible reason attribute. The values are integers representing the number of emails with that reason. |
total_counts | Hash | A hash with one key per possible state attribute. The values are integers representing the number of emails with that state. In addition to the state keys, total_counts also contains keys processed and total , with values indicating the number of emails in the batch. |
Test email addresses
There are several email addresses that can be used to return specific attributes when using a test API key. These will only work with the verify endpoint, not the batch endpoint.
Response | |
---|---|
deliverable@example.com | state will be deliverable |
undeliverable@example.com | state will be undeliverable |
risky@example.com | state will be risky |
unknown@example.com | state will be unknown |
role@example.com | role will be true |
free@example.com | free will be true |
accept-all@example.com | accept_all will be true |
disposable@example.com | disposable will be true |
slow@example.com | returns a 249 status code |
Account
Get account info
curl "https://api.emailable.com/v1/account?api_key=your_api_key"
Emailable.account
emailable.account()
.then(function (response) {
// asynchronously called
});
client.account()
The above command returns JSON structured like this:
{
"owner_email": "john@smith.com",
"available_credits": 1337
}
Get general account information like the email of the account owner and available credits.
HTTP Request
GET https://api.emailable.com/v1/account
Parameters
Parameter | Required | Description |
---|---|---|
api_key | true | Your API key. |
Response
Attribute | Type | Description |
---|---|---|
owner_email | String | The email of the account owner. |
available_credits | Integer | The amount of credits remaining on the account. |
Widget
Using our widget is the easiest way to get email verification integrated into your existing website. Just install our embed code and we'll do the rest.
Install the embed code
Click here to go to the API page. Click "New Key" and create a Public API key. After you select Public, you will see an input for Trusted Domains. Be sure to enter the domain(s) that you will be installing the embed code on.
Once you have an API key, install the code and we'll begin verifying any input with the type email.
<script>
(function (w, d, ns) {
w['EmailableObject'] = ns;
w[ns] = w[ns] || function () { (w[ns].q = w[ns].q || []).push(arguments) },
s = d.createElement('script'), fs = d.getElementsByTagName('script')[0];
s.async = 1; s.src = 'https://js.emailable.com/v2/';
fs.parentNode.insertBefore(s, fs)
})(window, document, 'emailable');
emailable('apiKey', 'your_api_key');
</script>
Configuration Options
Using our configuration options, you can customize the email attributes you'd like to allow, which inputs we'll monitor, and more. The default configuration options are below.
<script>
// types of emails that are allowed
emailable('allow', {
states: ['deliverable', 'risky', 'unknown'],
free: true,
role: true,
disposable: false
});
// maximum time to wait for the verification to respond. some mail servers
// are slow and we don't want to hold the user up for too long.
emailable('verificationTimeout', 5);
// how long to wait after a user stops typing to verify the email
emailable('verifyAfterDelay', 1000);
// enable HTML5 validation messages
emailable('html5Validation', true);
// this is the selector for the inputs we will monitor
emailable('inputSelector', 'input[type=email]');
// array of form names to ignore
emailable('ignoredForms', []);
// array of input names to ignore
emailable('ignoredInputs', []);
// users who enter 10+ emails will be rate-limited by our servers.
// when set to true the user will get the rateLimited message.
emailable('blockOnRateLimit', false)
// styles
emailable('style', {
loadingIconColor: 'rgba(0, 0, 0, 0.3)'
});
// messages
emailable('messages', {
verifying: "Please wait a moment while we verify your email address.",
invalid: "It looks like you've entered an invalid email address.",
role: "It looks like you've entered a role or group email address.",
free: "It looks like you've entered a free email address.",
disposable: "It looks like you've entered a disposable email.",
didYouMean: "It looks like you've entered an invalid email address. Did you mean [EMAIL]?",
rateLimited: "It looks like you've attempted to enter too many emails."
});
</script>
Event Listener
Our event listeners will give you the ability to take specific actions once the verification has completed.
Verified Event
<script>
// example event listener
$('input').on('verified', function(event) {
console.log(event.detail);
/*
{
accepted: false,
message: "It looks like you've entered an invalid email address.",
verificationData: {
body: "{"accept_all":false,"did_you_mean":null,"disposable":false,"domain":"gmail.com",...",
status: 200
}
}
*/
});
</script>
Error Event
<script>
// example event listener
$('input').on('error', function(event) {
console.log(event.detail);
/*
{
status: 429,
message: 'Rate limit reached'
}
*/
});
</script>
Rate Limits
{
"message": "Rate Limit Exceeded"
}
When rate limits are exceeded, the 429 status code will be returned.
There are different rate limits for different API endpoints. These rate limits are shown below.
Endpoint | Method | Rate Limit |
---|---|---|
/v1/account | GET/POST | 5 per second |
/v1/batch | POST | 5 per second |
/v1/batch | GET | 5 per second |
/v1/verify | GET/POST | 25 per second |
Errors
{
"message": "API key is required"
}
The Emailable API uses the following error codes:
Code | Error | Meaning |
---|---|---|
400 | Bad Request | Your request is structured incorrectly. |
401 | Unauthorized | You did not send an API key. |
402 | Payment Required | You don't have enough credits to complete this request. |
403 | Forbidden | Your API key is invalid. |
404 | Not Found | The specified resource does not exist. |
429 | Too Many Requests | You're requesting an endpoint too often. |
500 | Internal Server Error | A server error occurred. Please try again later, or contact support if you're having trouble. |
503 | Service Unavailable | We're temporarily offline for maintenance. Please try again later. |