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 Customer Success Manager if you are interested in web services.

Update: Version 1 has been sunset on March 30, 2018

Current Version: 2

Version 2 introduces the new parameters to only the messages, bounces, clicks, delivers, opens, links and recipients calls.

• Query results are now indexed 0 to n. startAt references the index value.
• maxResults sets a ceiling for the number of records returned
  • By default, maxResults is set to 1000.
  • If no maxResult value is passed, the application will return 1000 records per page.
  • The value of maxResults cannot exceed 1000.
  • If a negative number or number less than one is passed, the application will set maxResults to one
• You will achieve custom pagination when you increment startAt by maxResults
• Results now end with a summary
  
  • maxResults: #
  • startAt: #
  • total #
• The total in the results will help you know how many pages are needed to contain all query results
• startAt and maxResults are passed via the URL
  Example: https://emapi.imodules.com/v2/messages/#/recipients?startAt=11&maxResults=10

Location

Interactive documentation can be found

• http://docs.emapi.imodules.com for the U.S. environment.  
• http://docs.emapi-ca.imodules.com for the Canadian environment.

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 GUID). If you do not have your secret key, please contact your Customer Success Manager. 

To get your JSON Web Token (JWT), you need to make an application/x-www-form-urlencoded POST call to API services. The authentication endpoint for retrieving the access token is: {yoursite}/apiservices/authenticate where {yoursite} is one of the URLs for your iModules site. The POST call requires 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:

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 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 (and a space) followed by your authentication key into the authorization field (under the Parameters subhead) to apply your authentication.  
• Next, when you modify other parameters and and click "Try it out!" you receive responses from the API.

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 have initiated an automated archiving of action data older than 180 days.

Getting Help

All questions or issues should be directed toward ws-support@imodules.com.

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.

JSON 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.