Documentation

Getting Started

Welcome to our iLead REST API docs section. iLead is the SaaS tool that gives you the access to email database you can use for your business needs. With our REST API you can search for an email in our database and check its validity. To work with REST API you need to have the knowledge of client-server work and to be able to understand JSON data format. The current REST API version allows you to work with all functionality that iLead has. You will need a secret key to use the API, in order to recieve a secret key, please login and go to API section. Here are the iLead API methods available:

  • The Email Finder searches for the match of an email with the data in our database by first, last and/or domain name.
  • The Email Verifier checks if the requested email is stored in our database and if the message can be delivered to this email address.
  • The Account Information returns the information regarding your iLead account.

Please note that free account gives you only 3000 requests per month. To verify more emails contact us

Api Endpoint

http://app.ilead.io/api/

Request Body

iLead REST API is designed to be as simple as possible for the usage. The basic structure of the request is always the same:

  • data - contains the data you requested.
  • meta - provides information regarding your request.
  • errors - shows the errors with insights regarding what made the request fail.

Learn more about the HTTP Status Codes.

Successful Response

{
    "data" : {
      ...
    },
    "meta" : {
      ...
    }
}

Error Response

{
    "errors" : {
      ...
    }
}

Authentication

To authenticate with iLead REST API you need to use the API secret key that can be found on API page from your account. This is the mandatory parameter, an error will be returned in case of missing it.

API secret key should be hidden from other persons, it is unique only to your iLead account. It is your obligation to keep it in safety. If you notice or guess that your API secret key could be used by third persons you can always generate the new one on API page.

An example of API secret key

1234c567-89sd0-12e3-b4cf-5df6d7b89cc12345
				

HTTP Status Codes

We use general HTTP response codes for our iLead REST API to point to the success or failure of the requested REST API method.

In a case of an error, the server returns an errors array containing information regarding what happened.

HTTP Status Codes

200 - OK The request was successful.
201 - Created The request was successful and the resource was created.
204 - No content The request was successful and no additional content was sent.
400 - Bad request Your request was not valid.
401 - Unauthorized No valid API key was provided.
404 - Not found The requested resource does not exist.
422 - Unprocessable entity Your request is valid but the creation of the resource failed. Check the errors.
429 - Too many requests You have reached your usage limit. Upgrade your plan if necessary.
5XX - Server Errors Something went wrong on iLead's end.

Error example

{
   "errors" : [
     {
       "id" : "wrong_params",
       "code" : 400,
       "details" : "You are missing the domain parameter"
     }
   ]
}

Account Information

With this REST API you can get the information regarding your iLead account and amount of requests left at any time. This API request is free.

apiKey Required* API secret key associated with your iLead account.

HTTP request example

GET http://app.ilead.io/api/account?apiKey=1234c567-89a0-12e3-b4cf-5df6rb78ecc12345

Response: 200 OK

{
    data: {
        "firstName": "John",
        "lastName": "Smith",
        "email": "john.smith@gmail.com",
      	"freeRequests": 3000
    }
}

Email Finder

With this REST API you can verify if the message can be delivered to this email address.

email Required* The email address that should be verified. Case insensitive.
api_secret Required* Your secret API key. You can generate it on API page.

Email validity indicators definition:

catchall - if this indicator is true than there the email domain returns the same answer for any email. No way to determine the status of the email. If this is true you can ignore all other indicators.

is_confirmed - true if the email address is confirmed.

is_format - true if the email addresses passed by our regular expression.

is_mail_exists - is true if the email address doesn't bounce.

is_public_webmail - true if the email address is the public one.

is_smtp - true if the connection to the SMTP server was successful.

result.status_code - the integer number from the range [1..10], an assessment of the email validity.

result.status_txt - the interpretation of the result status.

HTTP request example

GET http://app.ilead.io/api/account?apiKey=1234c567-89a0-12e3-b4cf-5df6rb78ecc12345

Response 200: OK

{
    data: {
        firstName: "John",
        lastName: "Smith",
        email: "john.smith@gmail.com",
        requestLimit: 9153,
        requestUsed: 21357
    }
}

Single Email Verifier

Using this route you can verify single emails.

In order to verify a single email you have to send a GET request to "emailVerfication" route. Parameters of the route:

API secret key This string is required, you can get an API secret key if you login
Email This string is required, input the email you want to verify

HTTP request example

GET ~/api/emailVerification?apiKey=[API KEY]&email=[EMAIL]

Response 200: OK

{
	"data": {
		"is_confirmed": null,
		"is_format": true,
		"is_mail_exists": true,
		"is_mx_records": true,
		"is_public_webmail": true,
		"is_smtp": true,
		"result": {
			"rcpt_code": null,
			"rcpt_message": null,
			"status_code": 90,
			"status_txt": "It's almost perfect address. Keep calm and send emails"
		}
	},
	"error": null,
	"metadata": {
		"datetime": "2018-08-14 14:10:31.679243",
		"domain": "gmail.com",
		"email": "superverifiedemail@gmail.com"
	}
}

Email bulk verifier – Sending Bulks

Using this route you can verify emails in bulks.

In order to verify a bulk of email you have to send a POST request to "bulk/emailVerfication" route. Parameters that you need to include in the body of the request:

API secret key This string is required, you can get an API secret key if you login
Emails list This element is required, this should be an array of emails. Emails must be in brackets ("") and separated by (,). The list of emails must be in square brackets ([])
Callback URL This element is optional. After the validation process is finished a POST request will be sent to this URL

HTTP request example

POST ~/api/bulk/emailVerification

Body of the request:

{
"apiKey":"2f891550-e009-11e7-b9c5-4b3fc2c2b8bc7141",
"emailsList":["johndoe@gmail.com","johndoe2@bk.ru", "johndoe3@bk.ru"],
"callbackUrl":"https://callback.url/finishedEmailsBulk"
}

Response 200: OK

{
"_id": "5a8a8b6ddeb5981884752548",
"name": "Emails Bulk(37).csv"
}

Email bulk verifier – Receiving results

Using this routes you can receive results of bulk email verification.

There three ways to get the result of bulk email verification. It is up to your prefererence, which one to use. API secret key is requreid for every request. Here are the three possible routes to use:

Get All Bulks This request will return the result of validation of email bulks that were uploaded by you.
Get Bulk By Name This request allows you to specify the email bulk name so iLead will return a single result JSON for that particular email bulk that.
Get Bulk By ID Similair to the previous one, this route returns the results of a single email bulk, but here you specify the ID of the bulk.

Get ALL Bulks HTTP request example

GET ~/api/bulk/emailVerification?apiKey=[API KEY HERE]

Response 200: OK

[
    {
        "_id": "5a6b34b54e71f91c0cb6a26f",
        "name": "MOCK(15).csv",
        "status": "InProgress",
        "items": [
            "email",
            "johndoe@dion.ne.jp",
            "johndoe1@geocities.jp",
            "johndoe2@sphinn.com",
            "johndoe3@soup.io",
            "johndoe4@sun.com",
            "johndoe5@usda.gov",
            "johndoe6@berkeley.edu",
            "johndoe7@edublogs.org",
            "johndoe8@fastcompany.com",
            "johndoe9@intel.com"
        ]
    },
    {
        "_id": "5a6b31b54e71f92c0cb6a26f",
        "name": "4test.csv",
        "status": "processed",
        "items": [
            [
            "email",
            "Email status",
            "Validity percentage",
            "Confirmed email",
            "Valid format",
            "Existing email",
            "Detected MX records",
            "Is public",
            "SMTP"
            ],
            [
            "johndoe@dion.ne.jp",
            "We don't recomend you to send emails on this address",
            10,
            null,
            true,
            false,
            null,
            null,
            null
            ]
        ]
    },
    ...
]

Get Bulk By Name HTTP request example

GET ~/api/bulk/emailVerification/name=[NAME]?apiKey=[API KEY]

Response 200: OK

{
    "_id": "5a6f1f2a03d3c9523ecee1de",
    "name": "4test.csv",
    "status": "processed",
    "items": [
        [
            "email",
            "Email status",
            "Validity percentage",
            "Confirmed email",
            "Valid format",
            "Existing email",
            "Detected MX records",
            "Is public",
            "SMTP"
        ],
        [
            "johndoe@dion.ne.jp",
            "We don't recomend you to send emails on this address",
            10,
            null,
            true,
            false,
            null,
            null,
            null
        ],
        [
            "johndoe3@soup.io",
            "We almost sure that this email is ok, but there are still minimal risks. It's up to you",
            70,
            null,
            true,
            false,
            true,
            null,
            true
        ],
        [
            "johndoe4@sun.com",
            "It's almost perfect address. Keep calm and send emails",
            90,
            null,
            true,
            true,
            true,
            null,
            true
        ]
    ]
}

Get Bulk By ID HTTP request example

GET ~/api/bulk/emailVerification/[ID]?apiKey=[API KEY]

Response 200: OK

{
    "_id": "5a6f1f2a03d3c9523ecee1de",
    "name": "4test.csv",
    "status": "processed",
    "items": [
        [
            "email",
            "Email status",
            "Validity percentage",
            "Confirmed email",
            "Valid format",
            "Existing email",
            "Detected MX records",
            "Is public",
            "SMTP"
        ],
        [
            "johndoe0@dion.ne.jp",
            "We don't recomend you to send emails on this address",
            10,
            null,
            true,
            false,
            null,
            null,
            null
        ],
        [
            "johndoe3@soup.io",
            "We almost sure that this email is ok, but there are still minimal risks. It's up to you",
            70,
            null,
            true,
            false,
            true,
            null,
            true
        ],
        [
            "johndoe4@sun.com",
            "It's almost perfect address. Keep calm and send emails",
            90,
            null,
            true,
            true,
            true,
            null,
            true
        ]
    ]
}