What is an API

An API, or Application Programming Interface, is used to programatically access the data available on the Email Format web site. Interactive queries from visitors using web browsers present information in a way easy to identify with the eye.

For customers who need bulk access and who want programs to efficiently interpret the data we have an API available. Use your favorite programming language such as C#, Java, Javascript, PHP, Python, Ruby, or others.

Accessing the API

All Email Format subscribers can have access to the API. When logged in click on the "Account" tab and generate a set of access keys.

Get up to 10,000 API hits daily - contact us if your usage will exceed this. We bill based on actual API usage at $10USD per 1,000 API requests.

Signing API Requests

All API calls must be signed with your public key and must include the current timestamp, your public key, and any call-specific required parameters.

When you sign up for API access Email Format assigns an API key and secret to your account. Your API key and secret is only known by you and Email Format. It is important to keep both confidential to protect your account. Only the public API key should be included in the request.

Note: Do not share your API key or secret with anyone not even on the Email Format support forum. No one who legitimately represents Email Format will ever ask you for your API key or secret!

To prove that you are the owner of the account making the request, you must include a signature. For all requests, you calculate the signature with your API secret. Email Format uses the API key in the request to look up your API secret and then calculates a signature with the secret. If the calculated signature matches the signature you sent, the request is considered authentic. Otherwise, the request fails authentication and is not processed.

To protect against someone replaying your request, the signature also contains a timestamp.

The steps involved in signing a request is as follows:

  1. Sort request parameters alphabetically (e.g. foo=1, bar=2, baz=3 sorts to bar=2, baz=3, foo=1)
  2. Concatenate in order your API private key and request name-value pairs (e.g. SECRETbar2baz3foo1)
  3. Calculate the signature as the MD5 hash of this string
  4. Include the signature parameter in the request encoded as lowercase HEX
    (e.g. hash=7431d31140cf412ab5caa73586d6324a)

API Call: get_formats

Returns a JSON-encoded object with the known formats for the given domain.

GET Request Parameters

URL: www.email-format.com/api/get_formats/?key=$1&ts=$2&hash=$3&domain=$4

  • key - Your public API key
  • ts - The current timestamp used in your signature hash
  • hash - Hash of the following strings concatenated together (without spaces): Private Key, Timestamp, domain (literal), domain (variable)
  • domain - The domain to query

Example request parameters

  • private key - fads89u432njk
  • key - sdfjkl398ekns
  • ts - 1392672392
  • hash - md5(fads89u432njk 1392672392 citrix.com)
    (calculate md5 WITHOUT the spaces - they are added here for clarity)
    md5('fads89u432njk1392672392domaincitrix.com') == b72a8a7725a3d2bf037f016c06439dc7
  • domain - citrix.com

GET /api/get_formats/?hash=b72a8a7725a3d2bf037f016c06439dc7&ts=1392672392&key=sdfjkl398ekns&domain=citrix.com

GET Response

{
  "results": 8,
  "formats": [
    {
      "format": "first_name . last_name ",
      "example": "John.Smith@citrix.com",
      "score": 56
    },
    {
      "format": "first_name - last_name ",
      "example": "John-Smith@citrix.com",
      "score": 1
    },
    {
      "format": "last_name ",
      "example": "Smith@citrix.com",
      "score": 4
    },
    {
      "format": "first_initial last_name ",
      "example": "JSmith@citrix.com",
      "score": 4
    },
    {
      "format": "last_name first_initial ",
      "example": "SmithJ@citrix.com",
      "score": 4
    },
    {
      "format": "first_name last_name ",
      "example": "JohnSmith@citrix.com",
      "score": 11
    },
    {
      "format": "first_name last_initial ",
      "example": "JohnS@citrix.com",
      "score": 4
    },
    {
      "format": "first_name ",
      "example": "John@citrix.com",
      "score": 4
    }
  ]
}

API Call: get_best_format

Returns a JSON-encoded object with the best known formats for the given domain.

GET Request Parameters

URL: www.email-format.com/api/get_best_formats/?key=$1&ts=$2&hash=$3&domain=$4

  • key - Your public API key
  • ts - The current timestamp used in your signature hash
  • hash - Hash of the following strings concatenated together (without spaces): Private Key, Timestamp, domain (literal), domain (variable)
  • domain - The domain to query

Example request parameters

  • private key - fads89u432njk
  • key - sdfjkl398ekns
  • ts - 1392672392
  • hash - md5(fads89u432njk 1392672392 domain citrix.com)
    (calculate md5 WITHOUT the spaces - they are added here for clarity)
    md5('fads89u432njk1392672392domaincitrix.com') == b72a8a7725a3d2bf037f016c06439dc7
  • domain - citrix.com

GET /api/get_best_format/?hash=b72a8a7725a3d2bf037f016c06439dc7&ts=1392672392&key=sdfjkl398ekns&domain=citrix.com

GET Response

{
  "results": 1,
  "format": {
    "format": "first_name . last_name ",
    "example": "John.Smith@citrix.com",
    "score": 56
  }
}