NAV
shell

Introduction

Welcome to the SimplyEmail API! You can use our API to access SimplyEmail API endpoints, which can get and search for emails on the web that have been scrapped.

We have language bindings in Shell and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

SimplyEmail Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: meowmeowmeow"

Make sure to replace meowmeowmeow with your API key.

Kittn uses API keys to allow access to the API. You can register a new Kittn API key at our developer portal.

Kittn expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: meowmeowmeow

Config

Version

curl "http://example.com/api/version?token=447xadjtxla1elkbw9e6ojb5rd2ueaufm8r59kp7"

The above command returns JSON structured like this:

{
  "version": "v1.4.2"
}

This API call gets the current version of the SimplyEmail endpoint. Authetication is required for even a version request.

HTTP Request

GET http://example.com/api/version?token=447xadjtxla1elkbw9e6ojb5rd2ueaufm8r59kp7

Query Parameters

Parameter Default Required Description
Token True Required for auth

Reporting

All Reporting

curl "curl https://0.0.0.0:1337/api/reporting?
token=447xadjtxla1elkbw9e6ojb5rd2ueaufm8r59kp7"

The above command returns JSON structured like this:

{
  "reports": [
    {
      "domain": "example.com", 
      "emails_domain": 5, 
      "emails_found": 9, 
      "emails_unique": 5, 
      "end_time": "02/07/2016 11:34:33", 
      "modules_enabled_key": 0, 
      "search_id": 2072016113418, 
      "start_time": "02/07/2016 11:34:18"
    }, 
    {
      "domain": "example1.com", 
      "emails_domain": 44, 
      "emails_found": 59, 
      "emails_unique": 44, 
      "end_time": "02/07/2016 11:35:11", 
      "modules_enabled_key": 0, 
      "search_id": 2072016113454, 
      "start_time": "02/07/2016 11:34:54"
    }
  ]
}

This API call returns all the search reports conducted in the DB. This will allow corelation to emails obtained during a search via search_id.

HTTP Request

GET https://0.0.0.0:1337/api/reporting

URL Parameters

Parameter Default Required Description
Token True Required for auth
curl "curl https://0.0.0.0:1337/api/reporting/domain/
example.com?token=447xadjtxla1elkbw9e6ojb5rd2ueaufm8r59kp7"

The above command returns JSON structured like this:

{
  "reports": [
    {
      "domain": "example.com", 
      "emails_domain": 5, 
      "emails_found": 9, 
      "emails_unique": 5, 
      "end_time": "02/07/2016 11:34:33", 
      "modules_enabled_key": 0, 
      "search_id": 2072016113418, 
      "start_time": "02/07/2016 11:34:18"
    }, 
    {
      "domain": "example.com", 
      "emails_domain": 44, 
      "emails_found": 59, 
      "emails_unique": 44, 
      "end_time": "02/07/2016 11:35:11", 
      "modules_enabled_key": 0, 
      "search_id": 2072016113454, 
      "start_time": "02/07/2016 11:34:54"
    }
  ]
}

This API call returns all the search reports conducted in the DB related to the supplied domain.

HTTP Request

GET https://0.0.0.0:1337/api/reporting/domain/<DOMAIN>

URL Parameters

Parameter Default Required Description
Token True Required for auth
Domain True Domain name to search reports for.

Domains

All Domains

curl "curl https://0.0.0.0:1337/api/domain?
token=447xadjtxla1elkbw9e6ojb5rd2ueaufm8r59kp7"

The above command returns JSON structured like this:

{
  "domains": [
    {
      "allows_verification": 0, 
      "domain": "example1.com", 
      "email_count": 6, 
      "instances_scraped": 0, 
      "last_scrapped": "02/07/2016 11:34:18", 
      "pattern": "{first}", 
      "webmail": 0
    }, 
    {
      "allows_verification": 0, 
      "domain": "example2.com", 
      "email_count": 44, 
      "instances_scraped": 0, 
      "last_scrapped": "02/07/2016 11:34:54", 
      "pattern": "{first}{last}", 
      "webmail": 0
    }, 
    {
      "allows_verification": 0, 
      "domain": "example3.com", 
      "email_count": 0, 
      "instances_scraped": 0, 
      "last_scrapped": "03/07/2016 00:48:26", 
      "pattern": "", 
      "webmail": 0
    }
  ]
}

This API call returns all the search domains that have been searched. This supports building a domain list.

HTTP Request

GET https://0.0.0.0:1337/api/domain

URL Parameters

Parameter Default Required Description
Token True Required for auth

Target Domain

curl "curl https://0.0.0.0:1337/api/domain/example3.com
?token=447xadjtxla1elkbw9e6ojb5rd2ueaufm8r59kp7"

The above command returns JSON structured like this:

{
  "domain": {
    "allows_verification": 0, 
    "domain": "example3.com", 
    "email_count": 6, 
    "instances_scraped": 0, 
    "last_scrapped": "02/07/2016 11:34:18", 
    "pattern": "{first}", 
    "webmail": 0
  }
}

This API call returns a specfic domain supplied by user. This returns a JSON object with all the required doman info

HTTP Request

GET https://0.0.0.0:1337/api/domain/example3.com

URL Parameters

Parameter Default Required Description
Token True Required for auth
Domain True The target domain requested

Emails

All Emails

curl "curl https://0.0.0.0:1337/api/email?
token=447xadjtxla1elkbw9e6ojb5rd2ueaufm8r59kp7"

The above command returns JSON structured like this:

{
  "emails": [
    {
      "domain": "example.com", 
      "email_address": "info@example.com", 
      "email_verified": 0, 
      "first_name": "", 
      "first_seen": "02/07/2016 11:34:33", 
      "instances_seen": 3, 
      "last_name": "", 
      "last_seen": "02/07/2016 20:41:40", 
      "name_generated_email": 0, 
      "score": 0
    }, 
    {
      "domain": "example.com", 
      "email_address": "fef@example.com", 
      "email_verified": 0, 
      "first_name": "", 
      "first_seen": "02/07/2016 11:34:33", 
      "instances_seen": 3, 
      "last_name": "", 
      "last_seen": "02/07/2016 20:41:40", 
      "name_generated_email": 0, 
      "score": 0
    }, 
    {
      "domain": "example.com", 
      "email_address": "dall@example.com", 
      "email_verified": 0, 
      "first_name": "", 
      "first_seen": "02/07/2016 11:34:33", 
      "instances_seen": 1, 
      "last_name": "", 
      "last_seen": "02/07/2016 20:41:40", 
      "name_generated_email": 0, 
      "score": 0
    }
  ]
}

This API call returns all the emails in the db. This call is offten not public due to mlarge backends.

HTTP Request

GET https://0.0.0.0:1337/api/email

URL Parameters

Parameter Default Required Description
Token True Required for auth

Target Email

curl "curl https://0.0.0.0:1337/api/email/info@example.com?
token=447xadjtxla1elkbw9e6ojb5rd2ueaufm8r59kp7"

The above command returns JSON structured like this:

{
  "email": {
    "domain": "example.com", 
    "email_address": "info@example.com", 
    "email_verified": 0, 
    "first_name": "", 
    "first_seen": "02/07/2016 11:34:33", 
    "instances_seen": 3, 
    "last_name": "", 
    "last_seen": "02/07/2016 20:41:40", 
    "name_generated_email": 0, 
    "score": 0
  }
}

This API call returns all the emails in the db. This call is offten not public due to mlarge backends.

HTTP Request

GET https://0.0.0.0:1337/api/email/<EMAIL@ADDR.COM>

URL Parameters

Parameter Default Required Description
Token True Required for auth
Email Address True User supplied email to inspect

Search

curl "curl https://0.0.0.0:1337/api/search/example.com?
token=447xadjtxla1elkbw9e6ojb5rd2ueaufm8r59kp7"

The above command returns JSON structured like this:

{
  "allows_verification": 0, 
  "domain": "test.com", 
  "email_count": 6, 
  "emails": [
    {
      "domain": "test.com", 
      "email_address": "info@test.com", 
      "email_verified": 0, 
      "first_name": "", 
      "first_seen": "02/07/2016 11:34:33", 
      "instances_seen": 3, 
      "last_name": "", 
      "last_seen": "02/07/2016 20:41:40", 
      "name_generated_email": 0, 
      "score": 0
    }, 
    {
      "domain": "test.com", 
      "email_address": "fed@test.com", 
      "email_verified": 0, 
      "first_name": "", 
      "first_seen": "02/07/2016 11:34:33", 
      "instances_seen": 3, 
      "last_name": "", 
      "last_seen": "02/07/2016 20:41:40", 
      "name_generated_email": 0, 
      "score": 0
    }
  ], 
  "instances_scraped": 0, 
  "last_scrapped": "02/07/2016 11:34:18", 
  "pattern": "", 
  "webmail": 0
}

This API call is the core functionality of SimplyEmail CLI and what other paid services offer. This will allow API users to quickly obtain the domain and email info for a supplied search.

HTTP Request

GET https://0.0.0.0:1337/api/search/<DOMAIN>

URL Parameters

Parameter Default Required Description
Token True Required for auth
Domain True Domain supplied for meta search

Errors

The SimplyEmail API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request may be messed up?
401 Unauthorized – Your API key is wrong
403 Forbidden – The API call requested is hidden for administrator / su tokens only
404 Not Found – The specified call could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 No data to return – The call did not return any data
418 I’m a teapot
490 Too Many Requests – You’re requesting too many kittens! Slow down!
491 Gone – The API call is not active on this endpoint.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.