Implementing API v1

Below you'll find details on how to implement calls into the legacy version 1 API. New implementations should use API v2.

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('fads89u432njk1392672392citrix.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": "[email protected]",
      "score": 56
    },
    {
      "format": "first_name - last_name ",
      "example": "[email protected]",
      "score": 1
    },
    {
      "format": "last_name ",
      "example": "[email protected]",
      "score": 4
    },
    {
      "format": "first_initial last_name ",
      "example": "[email protected]",
      "score": 4
    },
    {
      "format": "last_name first_initial ",
      "example": "[email protected]",
      "score": 4
    },
    {
      "format": "first_name last_name ",
      "example": "[email protected]",
      "score": 11
    },
    {
      "format": "first_name last_initial ",
      "example": "[email protected]",
      "score": 4
    },
    {
      "format": "first_name ",
      "example": "[email protected]",
      "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": "[email protected]",
    "score": 56
  }
}