Implementing API v2

Below you'll find details on how to implement calls into the version 2 API.

Authentication

All API requests must include an Authentication header. The header should refer to your private key.

When you sign up for API access, Email Format assigns an API private key to your account. Your private API key is only known by you and Email Format. It is important to keep both confidential to protect your account. Your API key is accessible from the Account link.

Note: Do not share your API private key 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!

API Call: ping

  GET https://www.email-format.com/api/v2/ping

The ping call is used to validate connectivity to the Email Format API server and to confirm that your Authentication header and API private key are functioning as expected. Calls to this API are not metered and you will not be billed for their use.

GET Request Parameters

none

Example Request Parameters

none

GET Response

{"message":"success"}

curl Request Example

> curl -vk \
       -H "Content-Type: application/json" \
       -H "Authorization: api_private_key" \
       -X GET "https://www.email-format.com/api/v2/ping"

API Call: get_formats

  GET https://www.email-format.com/api/v2/get_formats

Returns a JSON-encoded object with the known formats for the given domain. Calls to the API are metered and billed if there are any formats returned with the result. If there are no formats available you will not be billed.

GET Request Parameters

• domain - The domain to query (required)
• first_name - Email results will return using the specified name. If not specified "John Smith" will be used as a placeholder (optional)
• last_name - Email results will return using the specified name. If not specified "John Smith" will be used as a placeholder (optional)

Example Request Parameters

• domain - citrix.com
• first_name - Jane
• last_name - Doe

GET Response

{
  "results": 3,
  "formats": [
    {
      "format": "first_name . last_name ",
      "example": "jane.doe@citrix.com",
      "score": 56
    },
    {
      "format": "last_name ",
      "example": "doe@citrix.com",
      "score": 4
    },
    {
      "format": "first_initial last_name ",
      "example": "jdoe@citrix.com",
      "score": 4
    }
  ]
}

curl Request Example

> curl -vk \
       -H "Content-Type: application/json" \
       -H "Authorization: api_private_key" \
       -X GET "https://www.email-format.com/api/v2/get_formats?domain=example.com"

API Call: get_best_format

  GET https://www.email-format.com/api/v2/get_best_format

Returns a JSON-encoded object with the best known formats for the given domain. Calls to the API are metered and billed if there are any formats returned with the result. If there are no formats available you will not be billed.

GET Request Parameters

• domain - The domain to query (required)
• first_name - Email results will return using the specified name. If not specified "John Smith" will be used as a placeholder (optional)
• last_name - Email results will return using the specified name. If not specified "John Smith" will be used as a placeholder (optional)

Example Request Parameters

• domain - citrix.com
• first_name - Jane
• last_name - Doe

GET Response

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

curl Request Example

> curl -vk \
       -H "Content-Type: application/json" \
       -H "Authorization: api_private_key" \
       -X GET "https://www.email-format.com/api/v2/get_best_format?domain=example.com"