Email Metric API

Follow

Overview

In order to facilitate the automated retrieval of Email Marketing metrics, a restful Email Metric API has been established. To take advantage of the API, you will need to have a web services contract. Please visit with your Account Manager if you are interested in web services.

Location

Interactive documentation can be found

Authentication tokens can be retrieved from the endpoint at http://{yoursite}.imodules.com/apiservices/authenticate.

U.S. production calls are made against the endpoint https://emapi.imodules.com.

Canadian production calls are made against the endpoint https://emapi-ca.imodules.com

Access and Authentication

In order to authenticate against the API, you will need your secret key (web services password). If you do not have your secret key, please contact your Account Manager. 

To get your JSON Web Token (JWT), you need to make an application/x-www-form-urlencoded POST call to API services (Endpoint: http://{yoursite}.imodules.com/apiservices/authenticate) with the following keys:

Key Value Notes
client_id site_id Replace this with your site id
client_secret api_guid Replace this with your api key
grant_type "email_api_auth_key" Use the value "email_api_auth_key"


The JSON response will be similar to the following:

{
  "access_token": "eyJ0esefJhbGciOiJIUzI1NiJ9.eyJzaXRlSWQiOiItMTAwNTUiLCJyb2xlIjoiQXBpVXNlciIsImVuY0F1dGhUeXBlIjoiRW5jb21wYXNzQXBpU2Vzsef32wrw4bsImV4cCI6MTUzNTA5NDExOSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdCIsImF1ZCI6IkVtYWlsQXBpIiwibmJmIjoxNDcxOTc4MDE5fQ.Ph885s7W-Ca4svc1e61feHQL4xSJasfe_Gs",
  "token_type": "bearer",
  "expires_in": 63115199
}

With this response, you can add an Authentication header to your API calls with the access_token value. Since it is of type bearer, you will need to prepend "Bearer" (case-sensitive) to the token in the header. As an Authentication header example:

Authentication: Bearer eyJ0esefJhbGciOiJIUzI1NiJ9.eyJzaXRlSWQiOiItMTAwNTUiLCJyb2xlIjoiQXBpVXNlciIsImVuY0F1dGhUeXBlIjoiRW5jb21wYXNzQXBpU2Vzsef32wrw4bsImV4cCI6MTUzNTA5NDExOSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdCIsImF1ZCI6IkVtYWlsQXBpIiwibmJmIjoxNDcxOTc4MDE5fQ.Ph885s7W-Ca4svc1e61feHQL4xSJasfe_Gs

With this header, you will be able to authenticate and make calls against the API. Note that the header is required on every call and expires 24 hours after generation. So, you will need to refresh it periodically.

Using Interactive Documentation

Swagger offers interactive documentation that allows you to make real calls against the API before you build your script. http://docs.emapi.imodules.com or http://docs-ca.emapi.imodules.com lists each call available.  Clicking the button to the left of the path expands the window so you can see the schema.  Enter the word Bearer followed by your authentication key into the authorization field (under Parameters subhead) to apply your authentication.  Next, when you modify other parameters and and click "Try it out!" you receive responses from the API. Swagger offers interactive documentation that allows you to make real calls against the API before you build your script.

Time Parameters

For both queries and returned values, all time stamps are Epoch formatted coordinated universal time (UTC) expressed in milliseconds. The API will never have access to data from messages sent prior to January 1, 2016. 

IMPORTANT: In order to ensure the ongoing performance of the API, we intend to initiate an automated archiving of action data older than 90 days. API users will have until April 2017 to retrieve "historical" data points.

Getting Help

All questions or issues should be directed toward ws-support@imodules.com. If you are an Australian client interested in accessing the API, please reach out via the web service support address above.

Metrics Available

  1. Bounce: A non-unique record of every bounce response generated from a recipient's mail server which includes the unique recipient id, type, reason, time stamp of bounce action, date added (times tamp of database write), and a unique id for the action.
  2. Click: A non-unique record of every click which includes the unique recipient id, time stamp of click action, date added (time stamp of database write), unique link id, ip address, user agent string, and unique click id.
  3. Deliver: A non-unique record of every acceptance response generated from a recipients email server which includes a unique deliver id, date added (time stamp of database write), time stamp of deliver action, and unique recipient id.
  4. Link: A unique record of every hyperlink included within an email sent via Encompass which includes a unique id, name, and url. 
  5. Message: A record of an email sent through Encompass which includes subscription category, email name, from address, from name, pre-header, sent count, subject line, sub community id, scheduled date, actual send time, date added (time stamp of database write), and a unique message id. Recurring emails have unique message records for each send.
  6. Open: a non-unique record of every open action that includes date added (time stamp of database write), unique open id, ip address, unique recipient id, time stamp of open action and user agent string.
  7. Recipient: A record of a person with a bounce or deliver action for a given message - less any duplicates.
  8. Sent: The count of emails sent available in the message call. It is the count of intended recipients less exceptions.

Definitions

Swagger - Swagger is an open source specification for documenting REST API. It specifies the format (URL, method, and representation) to describe REST web services. It provides also tools to generate/compute the documentation from application code.

What does this mean? As an application developer, you write web services using your favorite framework, Swagger scans your code and exposes the documentation on some URL. Any client can consume this URL (which comes as XML or JSON documents) and learn how to use your REST web services: which HTTP methods to call on which URL, which input documents to send, which status code to expect, etc.

Jason Web Token - JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA.

Let's explain some concepts of this definition further.

    • Compact: Because of its smaller size, JWTs can be sent through an URL, POST parameter, or inside an HTTP header. Additionally, the smaller size means transmission is fast.

    • Self-contained: The payload contains all the required information about the user, avoiding the need to query the database more than once.

Have more questions? Submit a request