Email Analytics API

TIP

Access to our APIs is evaluated on a case-by-case basis. To find out if your use case is one that we support feel free to get in touch with the details of your project. partners@litmus.com

Litmus Email Analytics provides detailed metrics to better understand how your emails are performing. You will find data on who read your email, who deleted it, if they were on a mobile device, what email client they used, where were they located, and if they printed or forwarded.

Using the Email Analytics API you'll primarily be performing 2 functions: creating new campaigns and retrieving analytics data on those campaigns.

Authentication

As an API user youʼll have an API key which, combined with your API passphrase, allows you to log into the Litmus API over basic HTTP authentication. Note: this is different from any email address and password combination you might have used to access Litmus.

Reference Documentation

In additon to this documentation you can view all available functions at https://analytics-api.litmus.com/#!/Campaigns. This site also allows you to run API calls directly in your browser!

Creating a campaign

POST https://analytics-api.litmus.com/api/v1/Campaigns

The only parameter in the create request is the UserGuid. This is a pass-through field that should tie to a unique user ID in your system. You can use this to track all the campaigns by a user. This field is optional and can be left empty.

The response is the campaign serialized to JSON.

The two important fields to examine in the response are the Guid and the BugHtml. You will need the Guid for all future requests regarding this campaign. This is unique to this one campaign. The BugHtml is the snippet of HTML you will need to insert into your outgoing email. You will need to insert this inside the <body></body> tags.

A note about the BugHtml: You should try to keep this exactly as it is. Altering this snippet can have unexpected consquences. There is one exception. You'll notice a few points where we include the url a parameter d=[UNIQUE]. You will want to swap [UNIQUE] with a merge code from your system that will allow you to identify the recipients later.

Body parameters	Description
`UserGuid`	string

Examples

cURL

curl -X POST\
-d '{ UserGuid: "some-user-guid" }'\
-u apikey:password\
-H "Content-type: application/json"\
https://analytics-api.litmus.com/api/v1/Campaigns

Result Format

200 OK

json

{
  "Id": 1,
  "BugHtml": "<style>@media print{ #_t { background-image: url('https:\/\/xyz123.emltrk.com\/xyz123?p&d=[UNIQUE]');}} div.OutlookMessageHeader {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')} table.moz-email-headers-table {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')} blockquote #_t {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')} #MailContainerBody #_t {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')}<\/style><div id=\"_t\"><\/div>\r\n<img src=\"https:\/\/xyz123.emltrk.com\/xyz123?d=[UNIQUE]\" width=\"1\" height=\"1\" border=\"0\" \/>",
  "Guid": "xyz123",
  "ReportGuid": "11111111-1111-1111-1111-abcdabcdabcd",
  "UserGuid": "some-user-guid",
  "CreatedAt": "2015-03-27T18:56:10Z",
  "SentAt": null,
  "OpenCount": 0,
  "ExpiresAt": null,
  "NeverExpires": false
}

Get campaign meta data

POST https://analytics-api.litmus.com/api/v1/Campaigns/Get

You can fetch "meta data" on campaigns, including when the campaign expires and the user associated with it. You can fetch this for 1 or many campaigns at one time.

The response is a collection of campaigns requested in JSON format.

Body parameters	Description
`Guids`	REQUIRED array of strings

Examples

cURL

curl -X POST\
-d '{ "Guids": [ "xyz123" ] }'\
-u apikey:password\
-H "Content-type: application/json"\
https://analytics-api.litmus.com/api/v1/Campaigns/Get

Result Format

200 OK

json

[
  {
    "Id": 1,
    "BugHtml": "<style>@media print{ #_t { background-image: url('https:\/\/xyz123.emltrk.com\/xyz123?p&d=[UNIQUE]');}} div.OutlookMessageHeader {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')} table.moz-email-headers-table {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')} blockquote #_t {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')} #MailContainerBody #_t {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')}<\/style><div id=\"_t\"><\/div>\r\n<img src=\"https:\/\/xyz123.emltrk.com\/xyz123?d=[UNIQUE]\" width=\"1\" height=\"1\" border=\"0\" \/>",
    "Guid": "xyz123",
    "ReportGuid": "11111111-1111-1111-1111-abcdabcdabcd",
    "UserGuid": "some-user-guid",
    "CreatedAt": "2015-03-27T18:56:10Z",
    "SentAt": null,
    "OpenCount": 0,
    "ExpiresAt": null,
    "NeverExpires": false
  }
]

Update a campaign

PUT https://analytics-api.litmus.com/api/v1/Campaigns/:Guid

You can only update 3 fields on a campaign once it's been created:

UserGuid - A pass-through field that should tie to a unique user ID in your system.
ExpiresAt - The date we will stop recording data on a campaign, note this time is UTC and must be between 1970-01-01T00:00:01 and 2038-01-19T03:14:07.
NeverExpires - If this is set to true, Litmus will never stop recording data and will ignore ExpiresAt.

The response is the campaign in JSON format with the updated values.

Path parameters	Description
`Guid`	REQUIRED string

Body parameters	Description
`UserGuid`	string
`ExpiresAt`	timestamp
`NeverExpires`	boolean

Examples

cURL

curl -X PUT\
-d '{ "UserGuid": "some-guid", "ExpiresAt": "2015-12-31T23:59:59Z", "NeverExpires": false }'\
-u apikey:password\
-H "Content-type: application/json"\
https://analytics-api.litmus.com/api/v1/Campaigns/xyz123

Result Format

200 OK

json

{
    "Id": 1,
    "BugHtml": "<style>@media print{ #_t { background-image: url('https:\/\/xyz123.emltrk.com\/xyz123?p&d=[UNIQUE]');}} div.OutlookMessageHeader {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')} table.moz-email-headers-table {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')} blockquote #_t {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')} #MailContainerBody #_t {background-image:url('https:\/\/xyz123.emltrk.com\/xyz123?f&d=[UNIQUE]')}<\/style><div id=\"_t\"><\/div>\r\n<img src=\"https:\/\/xyz123.emltrk.com\/xyz123?d=[UNIQUE]\" width=\"1\" height=\"1\" border=\"0\" \/>",
    "Guid": "xyz123",
    "ReportGuid": "11111111-1111-1111-1111-abcdabcdabcd",
    "UserGuid": "some-user-guid",
    "CreatedAt": "2015-03-27T18:56:10Z",
    "SentAt": null,
    "OpenCount": 0,
    "ExpiresAt": "2015-12-31T23:59:59Z",
    "NeverExpires": false
}

Activate a campaign

PUT https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/Start

Activating or starting a campaign will primarily do two things: timestamp the SentAt on the campaign, and set the ExpiresAt to 30 days from now if the ExpiresAt is null or less then 30 days from now.

You do not have to activate a campaign. If you do not Litmus will automatically activate it after it receives 500 opens.

Path parameters	Description
`Guid`	REQUIRED string

Examples

cURL

curl -X PUT\
-u apikey:password\
-H "Content-type: application/json"\
https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/Start

Summary reports

Summary reports will get high-level data on a campaign and total opens. All of these reports can be run for a single or multiple campaigns in a single call.

Open counts reports (guid)

POST https://analytics-api.litmus.com/api/v1/Campaigns/OpenCounts

Use the Open Counts report to display the total opens a campaign has received. You can use different requests to filter the opens to a specific date range, but note that the return object for all 3 possible calls is the same.

Body parameters	Description
`Guids`	REQUIRED array of strings

Examples

cURL

curl -X POST\
-d '{ "Guids": [ "xyz123" ] }'\
-u apikey:password\
-H "Content-type: application/json"\
https://analytics-api.litmus.com/api/v1/Campaigns/OpenCounts

Result Format

200 OK

json

[
  {
    "CampaignGuid": "xyz123",
    "TotalOpens": 116245
  }
]

Open count reports (month)

POST https://analytics-api.litmus.com/api/v1/Campaigns/OpenCounts/:year/:month

Summary reports will get high-level data on a campaign and total opens. All of these reports can be run for a single or multiple campaigns in a single call.

Path parameters	Description
`year`	string
`month`	string

Body parameters	Description
`Guids`	REQUIRED array of strings

Examples

cURL

# fetches all opens for given 4 digit year and 2 digit month - ie /OpenCounts/2015/03
curl -X POST\
-d '{ "Guids": [ "xyz123" ] }'\
-u apikey:password\
-H "Content-type: application/json"\
https://analytics-api.litmus.com/api/v1/Campaigns/OpenCounts/{year}/{month}

Result Format

200 OK

json

[
  {
    "CampaignGuid": "xyz123",
    "TotalOpens": 116245
  }
]

Open count reports (range)

POST https://analytics-api.litmus.com/api/v1/Campaigns/OpenCounts/:fromDate/:untilDate

Path parameters	Description
`fromDate`	string
`untilDate`	string

Body parameters	Description
`Guids`	REQUIRED array of strings

Examples

cURL

# fetches all opens for given date range
# to fetch all from 3/1/2015 to 3/15/2015 the call would be: /OpenCounts/20150301/20150315
curl -X POST\
-d '{ "Guids": [ "xyz123" ] }'\
-u apikey:password\
-H "Content-type: application/json"\
https://analytics-api.litmus.com/api/v1/Campaigns/OpenCounts/{fromDate}/{untilDate}

Result Format

200 OK

json

[
  {
    "CampaignGuid": "xyz123",
    "TotalOpens": 116245
  }
]

Advanced open counts report

POST https://analytics-api.litmus.com/api/v1/Campaigns/AdvancedOpenCounts

Use the Advanced Open Counts report to display the total opens a campaign has received, how long it's been running, and when it will expire.

Body parameters	Description
`Guids`	REQUIRED array of strings

Examples

cURL

curl -X POST\
-d '{ "Guids": [ "xyz123" ] }'\
-u apikey:password\
-H "Content-type: application/json"\
https://analytics-api.litmus.com/api/v1/Campaigns/AdvancedOpenCounts

Result Format

200 OK

json

[
  {
    "CampaignGuid": "xyz123",
    "TotalOpens": 116026,
    "CreatedAt": "2015-03-27T18:56:10Z",
    "SentAt": "2015-03-28T10:43:32Z",
    "ExpiresAt": "2015-12-31T23:59:59Z"
  }
]

Engagement reports

Use Engagement Reports to see how much time users spent viewing an email. For more information on our engagement metrics see: How are engagement metrics defined?

We use the term "no-engagement opens" to describe opens for which we are unable to measure engagement. Conversely, "engagement opens" are opens for which we are able to measure engagement. For more information on why we're unable to measure engagement for certain types of opens see this help article.

Engagement report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/EngagementReport

The Engagement Report returns high-level engagement statistics for a campaign.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

JSON response body attributes	Description
`Total`	The total number of opens
`GlancedOrUnreadCount`	The number of opens where engagement was less than 2 seconds. Does not include "no-engagement" opens
`SkimmedCount`	The number of opens where engagement was 2-8 seconds
`ReadCount`	The number of opens where engagement was more than 8 seconds
`GlancedOrUnreadPercentage`	The percent of engagement opens where engagement was between 2-8 seconds, in relation to the total number of engagement opens
`SkimmedPercentage`	The percent of engagement opens where engagement was between 2-8 seconds, in relation to the total number of engagement opens
`ReadPercentage`	The percent of engagement opens where engagement was more than 8 seconds, in relation to the total number of engagement opens
`GlancedOrUnreadAvgPercentage`	The average percentage of glanced or unread opens that Litmus sees across all campaigns, for comparison purposes
`SkimmedAvgPercentage`	The average percentage of skimmed opens that Litmus sees across all campaigns, for comparison purposes
`ReadAvgPercentage`	The average percentage of read opens that Litmus sees across all campaigns, for comparison purposes

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/EngagementReport

Result Format

200 OK

json

{
  "Total": 116049,
  "GlancedOrUnreadCount": 15720,
  "SkimmedCount": 12540,
  "ReadCount": 44148,
  "GlancedOrUnreadPercentage": 22,
  "SkimmedPercentage": 17,
  "ReadPercentage": 61,
  "GlancedOrUnreadAvgPercentage": 30,
  "SkimmedAvgPercentage": 21,
  "ReadAvgPercentage": 49
}

Detailed engagement report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/DetailedEngagementReport

The Detailed Engagement Report returns high-level engagement statistics for a campaign broken down into 2-second buckets.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

JSON response body attributes	Description
`LessThan[#]SecCount`	The number of opens where engagement was within this 2-second bucket
`Over18SecCount`	The number of opens where engagement was over 18 seconds
`LessThan[#]SecPercentage`	The percent of engagement opens where engagement was within this 2-second bucket, in relation to the total number of engagement opens
`Over18SecPercentage`	The percent of engagement opens where engagement was more than 18 seconds, in relation to the total number of engagement opens
`LessThan[#]SecAvgCount`	The `LessThan[#]SecCount` multiplied by the `LessThan[#]SecAvgPercentage`
`Over18SecAvgCount`	The `Over18SecCount` multiplied by the `Over18SecAvgPercentage`
`LessThan[#]SecAvgPercentage`	The average percentage of `LessThan[#]Sec` opens that Litmus sees across all campaigns, for comparison purposes
`Over18SecAvgPercentage`	The average percentage of `Over18Sec` opens that Litmus sees across all campaigns, for comparison purposes

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/DetailedEngagementReport

Result Format

200 OK

json

{
  "Less2SecCount": 15765,
  "Less4SecCount": 6343,
  "Less6SecCount": 3672,
  "Less8SecCount": 2542,
  "Less10SecCount": 1916,
  "Less12SecCount": 1423,
  "Less14SecCount": 1200,
  "Less16SecCount": 1134,
  "Less18SecCount": 832,
  "Over18SecCount": 37725,
  "Less2SecPercentage": 22,
  "Less4SecPercentage": 9,
  "Less6SecPercentage": 5,
  "Less8SecPercentage": 4,
  "Less10SecPercentage": 3,
  "Less12SecPercentage": 2,
  "Less14SecPercentage": 2,
  "Less16SecPercentage": 2,
  "Less18SecPercentage": 1,
  "Over18SecPercentage": 50,
  "Less2SecAvgCount": 5820,
  "Less4SecAvgCount": 1151,
  "Less6SecAvgCount": 752,
  "Less8SecAvgCount": 579,
  "Less10SecAvgCount": 527,
  "Less12SecAvgCount": 409,
  "Less14SecAvgCount": 516,
  "Less16SecAvgCount": 299,
  "Less18SecAvgCount": 232,
  "Over18SecAvgCount": 5445,
  "Less2SecAvgPercentage": 37,
  "Less4SecAvgPercentage": 7,
  "Less6SecAvgPercentage": 5,
  "Less8SecAvgPercentage": 4,
  "Less10SecAvgPercentage": 3,
  "Less12SecAvgPercentage": 3,
  "Less14SecAvgPercentage": 3,
  "Less16SecAvgPercentage": 2,
  "Less18SecAvgPercentage": 1,
  "Over18SecAvgPercentage": 35
}

Group engagement report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/GroupEngagementReport

The Group Engagement Report breaks the engagement data down by platform: "Mobile", "Webmail", "Desktop", "Other", "Image Cache". For more information on how we define these platforms see this help article.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

JSON response body attributes	Description
`Name`	The name of the platform
`Total`	The total number of opens across all platforms
`Count`	The total number of opens for this platform
`GlancedOrUnreadCount`	The number of opens where engagement was less than 2 seconds. Does not include "no-engagement" opens
`SkimmedCount`	The number of opens where engagement was 2-8 seconds
`ReadCount`	The number of opens where engagement was more than 8 seconds
`GlancedOrUnreadPercentage`	The percent of engagement opens where engagement was between 2-8 seconds, in relation to the number of engagement opens across all platforms
`SkimmedPercentage`	The percent of engagement opens where engagement was between 2-8 seconds, in relation to the number of engagement opens across all platforms
`ReadPercentage`	The percent of engagement opens where engagement was more than 8 seconds, in relation to the number of engagement opens across all platforms

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/GroupEngagementReport

Result Format

200 OK

json

[
  {
    "Name": "Mobile",
    "Total": 116049,
    "Count": 10318,
    "GlancedOrUnreadCount": 1253,
    "SkimmedCount": 1790,
    "ReadCount": 7275,
    "GlancedOrUnreadPercentage": 2,
    "SkimmedPercentage": 2,
    "ReadPercentage": 10
  },
  {
    "Name": "Webmail",
    "Total": 116049,
    "Count": 32730,
    "GlancedOrUnreadCount": 0,
    "SkimmedCount": 0,
    "ReadCount": 0,
    "GlancedOrUnreadPercentage": 0,
    "SkimmedPercentage": 0,
    "ReadPercentage": 0
  },
  {
    "Name": "Desktop",
    "Total": 116049,
    "Count": 58658,
    "GlancedOrUnreadCount": 13779,
    "SkimmedCount": 10206,
    "ReadCount": 34672,
    "GlancedOrUnreadPercentage": 19,
    "SkimmedPercentage": 14,
    "ReadPercentage": 48
  },
  {
    "Name": "Other",
    "Total": 116049,
    "Count": 3433,
    "GlancedOrUnreadCount": 688,
    "SkimmedCount": 544,
    "ReadCount": 2201,
    "GlancedOrUnreadPercentage": 1,
    "SkimmedPercentage": 1,
    "ReadPercentage": 3
  },
  {
    "Name": "Image Cache",
    "Total": 116049,
    "Count": 10910,
    "GlancedOrUnreadCount": 0,
    "SkimmedCount": 0,
    "ReadCount": 0,
    "GlancedOrUnreadPercentage": 0,
    "SkimmedPercentage": 0,
    "ReadPercentage": 0
  }
]

Mail client engagement report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/MailClientEngagementReport

The Mail Client Engagement Report breaks down the engagement data by mail client version.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

JSON response body attributes	Description
`Name`	The name of the mail client
`ClientDetail`	The name of the mail client version
`PlatformDescription`	The name of the platform
`Total`	The total number of opens across all mail client versions
`Count`	The total number of opens for this mail client version
`GlancedOrUnreadCount`	The number of opens where engagement was less than 2 seconds. Does not include "no-engagement" opens
`SkimmedCount`	The number of opens where engagement was 2-8 seconds
`ReadCount`	The number of opens where engagement was more than 8 seconds
`GlancedOrUnreadPercentage`	The percent of engagement opens where engagement was between 2-8 seconds, in relation to the number of engagement opens across all mail client versions
`SkimmedPercentage`	The percent of engagement opens where engagement was between 2-8 seconds, in relation to the number of engagement opens across all mail client versions
`ReadPercentage`	The percent of engagement opens where engagement was more than 8 seconds, in relation to the number of engagement opens across all mail client versions

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/MailClientEngagementReport

Result Format

200 OK

json

[
    {
        "Name": "Apple iPhone",
        "ClientDetail": "iOS 13 Dark Mode",
        "PlatformDescription": "Mobile",
        "Count": 496,
        "Total": 1674,
        "GlancedOrUnreadCount": 0,
        "SkimmedCount": 0,
        "ReadCount": 496,
        "GlancedOrUnreadPercentage": 0,
        "SkimmedPercentage": 0,
        "ReadPercentage": 30
    },
    {
        "Name": "Apple iPhone",
        "ClientDetail": "iOS 13 Light Mode",
        "PlatformDescription": "Mobile",
        "Count": 310,
        "Total": 1674,
        "GlancedOrUnreadCount": 0,
        "SkimmedCount": 0,
        "ReadCount": 310,
        "GlancedOrUnreadPercentage": 0,
        "SkimmedPercentage": 0,
        "ReadPercentage": 19
    },
    {
        "Name": "Outlook",
        "ClientDetail": "on iOS",
        "PlatformDescription": "Mobile",
        "Count": 868,
        "Total": 1674,
        "GlancedOrUnreadCount": 248,
        "SkimmedCount": 62,
        "ReadCount": 558,
        "GlancedOrUnreadPercentage": 15,
        "SkimmedPercentage": 4,
        "ReadPercentage": 33
    },
    {
        "Name": "Apple Mail Privacy",
        "ClientDetail": "Via Apple's Image Cache Light Mode",
        "PlatformDescription": "Image Cache",
        "Count": 843,
        "Total": 1674,
        "GlancedOrUnreadCount": 0,
        "SkimmedCount": 0,
        "ReadCount": 0,
        "GlancedOrUnreadPercentage": 0,
        "SkimmedPercentage": 0,
        "ReadPercentage": 0
    }
]

Detailed mail client engagement report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/DetailedMailClientEngagementReport

The Detailed Mail Client Engagement Report breaks down engagement data by mail client. Engagement is divided into 2-second buckets.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

JSON response body attributes	Description
`Name`	The name of the mail client
`Count`	The total number of opens for this mail client
`LessThan[#]SecCount`	The number of opens where engagement was within this 2-second bucket
`Over18SecCount`	The number of opens where engagement was over 18 seconds
`ReadCount`	The number of opens where engagement was more than 8 seconds
`LessThan[#]SecPercentage`	The percent of engagement opens where engagement was within this 2-second bucket, in relation to the number of engagement opens across all mail clients
`Over18SecPercentage`	The percent of engagement opens where engagement was more than 18 seconds, in relation to the number of engagement opens across all mail clients
`ReadPercentage`	The percent of engagement opens where engagement was more than 8 seconds, in relation to the number of engagement opens across all mail clients

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/DetailedMailClientEngagementReport

Result Format

200 OK

json

[
    {
        "Name": "Apple iPhone",
        "Count": 436,
        "ReadCount": 310,
        "Less2SecCount": 0,
        "Less4SecCount": 64,
        "Less6SecCount": 62,
        "Less8SecCount": 0,
        "Less10SecCount": 0,
        "Less12SecCount": 0,
        "Less14SecCount": 0,
        "Less16SecCount": 0,
        "Less18SecCount": 0,
        "Over18SecCount": 310,
        "ReadPercentage": 71,
        "Less2SecPercentage": 0,
        "Less4SecPercentage": 15,
        "Less6SecPercentage": 14,
        "Less8SecPercentage": 0,
        "Less10SecPercentage": 0,
        "Less12SecPercentage": 0,
        "Less14SecPercentage": 0,
        "Less16SecPercentage": 0,
        "Less18SecPercentage": 0,
        "Over18SecPercentage": 71
    },
    {
        "Name": "Gmail",
        "Count": 62,
        "ReadCount": 0,
        "Less2SecCount": 0,
        "Less4SecCount": 0,
        "Less6SecCount": 0,
        "Less8SecCount": 0,
        "Less10SecCount": 0,
        "Less12SecCount": 0,
        "Less14SecCount": 0,
        "Less16SecCount": 0,
        "Less18SecCount": 0,
        "Over18SecCount": 0,
        "ReadPercentage": 0,
        "Less2SecPercentage": 0,
        "Less4SecPercentage": 0,
        "Less6SecPercentage": 0,
        "Less8SecPercentage": 0,
        "Less10SecPercentage": 0,
        "Less12SecPercentage": 0,
        "Less14SecPercentage": 0,
        "Less16SecPercentage": 0,
        "Less18SecPercentage": 0,
        "Over18SecPercentage": 0
    }
]

Platform reports

Use Platform Reports to learn more about the environment an email is being viewed in.

Mail client usage report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/MailClientUsage

The Mail Client Usage report provides a complete breakdown of the different email clients used to view an email. The report breaks down email clients by different versions, provides a percentage of each client share across the whole campaign, and an average percentage against all Litmus' data for comparison.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/MailClientUsage

Result Format

200 OK

json

[
  {
    "Name": "Apple Mail",
    "Count": 36640,
    "Percentage": 31.5,
    "AvgPercentage": 7.305,
    "Versions": [
      {
        "Name": "Apple Mail 3",
        "Count": 41,
        "Percentage": 0,
        "AvgPercentage": 2.024
      },
      {
        "Name": "Apple Mail 2",
        "Count": 17,
        "Percentage": 0,
        "AvgPercentage": 0.456
      },
      {
        "Name": "Apple Mail 8",
        "Count": 23750,
        "Percentage": 20.4,
        "AvgPercentage": 0
      },
      {
        "Name": "Apple Mail 7",
        "Count": 8465,
        "Percentage": 7.3,
        "AvgPercentage": 0
      },
      {
        "Name": "Apple Mail 6",
        "Count": 2398,
        "Percentage": 2.1,
        "AvgPercentage": 0
      },
      {
        "Name": "Apple Mail 5",
        "Count": 1094,
        "Percentage": 0.9,
        "AvgPercentage": 0.039
      },
      {
        "Name": "Apple Mail 4",
        "Count": 875,
        "Percentage": 0.8,
        "AvgPercentage": 4.786
      }
    ]
  },
  {
    "Name": "Gmail",
    "Count": 35909,
    "Percentage": 30.9,
    "AvgPercentage": 0,
    "Versions": [
      {
        "Name": "Via Gmail's Image Cache",
        "Count": 35909,
        "Percentage": 30.9,
        "AvgPercentage": 0
      }
    ]
  },
  {
    "Name": "Outlook",
    "Count": 21491,
    "Percentage": 18.5,
    "AvgPercentage": 38.294,
    "Versions": [
      {
        "Name": "Outlook Web Access (Firefox)",
        "Count": 1,
        "Percentage": 0,
        "AvgPercentage": 0.006
      },
      {
        "Name": "Outlook 2007",
        "Count": 3198,
        "Percentage": 2.8,
        "AvgPercentage": 5.86
      },
      {
        "Name": "Outlook Web Access (Explorer)",
        "Count": 1,
        "Percentage": 0,
        "AvgPercentage": 0.076
      },
      {
        "Name": "Outlook 2013",
        "Count": 7146,
        "Percentage": 6.1,
        "AvgPercentage": 0
      },
      {
        "Name": "Outlook 2010",
        "Count": 9527,
        "Percentage": 8.2,
        "AvgPercentage": 1.324
      },
      {
        "Name": "Outlook 2000-2003",
        "Count": 1618,
        "Percentage": 1.4,
        "AvgPercentage": 31.028
      }
    ]
  },
  {
    "Name": "Apple iPhone",
    "Count": 7714,
    "Percentage": 6.6,
    "AvgPercentage": 0,
    "Versions": [
      {
        "Name": "iOS 6",
        "Count": 94,
        "Percentage": 0.1,
        "AvgPercentage": 0
      },
      {
        "Name": "iOS 5",
        "Count": 9,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "iOS 4",
        "Count": 3,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "iOS 8",
        "Count": 6669,
        "Percentage": 5.7,
        "AvgPercentage": 0
      },
      {
        "Name": "iOS 7",
        "Count": 939,
        "Percentage": 0.8,
        "AvgPercentage": 0
      }
    ]
  },
  {
    "Name": "Web version",
    "Count": 6130,
    "Percentage": 5.3,
    "AvgPercentage": 7.617,
    "Versions": [
      {
        "Name": "Using Explorer",
        "Count": 98,
        "Percentage": 0.1,
        "AvgPercentage": 5.148
      },
      {
        "Name": "Using iPad",
        "Count": 24,
        "Percentage": 0,
        "AvgPercentage": 0.022
      },
      {
        "Name": "Using iPhone",
        "Count": 91,
        "Percentage": 0.1,
        "AvgPercentage": 0.024
      },
      {
        "Name": "Using Android",
        "Count": 93,
        "Percentage": 0.1,
        "AvgPercentage": 0.032
      },
      {
        "Name": "Using Chrome",
        "Count": 4083,
        "Percentage": 3.5,
        "AvgPercentage": 0
      },
      {
        "Name": "Using Firefox",
        "Count": 1257,
        "Percentage": 1.1,
        "AvgPercentage": 1.756
      },
      {
        "Name": "Using Safari",
        "Count": 362,
        "Percentage": 0.3,
        "AvgPercentage": 0.391
      },
      {
        "Name": "Other",
        "Count": 122,
        "Percentage": 0.1,
        "AvgPercentage": 0.051
      }
    ]
  },
  {
    "Name": "Other",
    "Count": 3469,
    "Percentage": 3,
    "AvgPercentage": 2.433,
    "Versions": [
      {
        "Name": "Other",
        "Count": 3469,
        "Percentage": 3,
        "AvgPercentage": 2.433
      }
    ]
  },
  {
    "Name": "Google Android",
    "Count": 1343,
    "Percentage": 1.2,
    "AvgPercentage": 0,
    "Versions": [
      {
        "Name": "5.x",
        "Count": 305,
        "Percentage": 0.3,
        "AvgPercentage": 0
      },
      {
        "Name": "4.x",
        "Count": 1019,
        "Percentage": 0.9,
        "AvgPercentage": 0
      },
      {
        "Name": "2.x",
        "Count": 19,
        "Percentage": 0,
        "AvgPercentage": 0
      }
    ]
  },
  {
    "Name": "Apple iPad",
    "Count": 1206,
    "Percentage": 1,
    "AvgPercentage": 0,
    "Versions": [
      {
        "Name": "iOS 7",
        "Count": 207,
        "Percentage": 0.2,
        "AvgPercentage": 0
      },
      {
        "Name": "iOS 6",
        "Count": 5,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "iOS 5",
        "Count": 32,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "iOS 8",
        "Count": 962,
        "Percentage": 0.8,
        "AvgPercentage": 0
      }
    ]
  },
  {
    "Name": "Outlook.com",
    "Count": 817,
    "Percentage": 0.6,
    "AvgPercentage": 0,
    "Versions": [
      {
        "Name": "Using iPhone",
        "Count": 2,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Using Android",
        "Count": 2,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Using Firefox",
        "Count": 214,
        "Percentage": 0.2,
        "AvgPercentage": 0
      },
      {
        "Name": "Using Explorer",
        "Count": 11,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Using iPad",
        "Count": 2,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Using Chrome",
        "Count": 498,
        "Percentage": 0.4,
        "AvgPercentage": 0
      },
      {
        "Name": "Using Safari",
        "Count": 52,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Other",
        "Count": 36,
        "Percentage": 0,
        "AvgPercentage": 0
      }
    ]
  },
  {
    "Name": "Yahoo! Mail",
    "Count": 791,
    "Percentage": 0.6,
    "AvgPercentage": 7.825,
    "Versions": [
      {
        "Name": "Using Firefox",
        "Count": 276,
        "Percentage": 0.2,
        "AvgPercentage": 2.1
      },
      {
        "Name": "Using Explorer",
        "Count": 10,
        "Percentage": 0,
        "AvgPercentage": 4.983
      },
      {
        "Name": "Using Chrome",
        "Count": 436,
        "Percentage": 0.4,
        "AvgPercentage": 0.299
      },
      {
        "Name": "Using Safari",
        "Count": 55,
        "Percentage": 0,
        "AvgPercentage": 0.427
      },
      {
        "Name": "Other",
        "Count": 14,
        "Percentage": 0,
        "AvgPercentage": 0.016
      }
    ]
  },
  {
    "Name": "Windows Live Mail",
    "Count": 323,
    "Percentage": 0.3,
    "AvgPercentage": 0.864,
    "Versions": [
      {
        "Name": "Live Mail 2008",
        "Count": 323,
        "Percentage": 0.3,
        "AvgPercentage": 0.864
      }
    ]
  },
  {
    "Name": "Postbox",
    "Count": 179,
    "Percentage": 0.2,
    "AvgPercentage": 0.006,
    "Versions": [
      {
        "Name": "Postbox",
        "Count": 179,
        "Percentage": 0.2,
        "AvgPercentage": 0.006
      }
    ]
  },
  {
    "Name": "Thunderbird",
    "Count": 121,
    "Percentage": 0,
    "AvgPercentage": 1.098,
    "Versions": [
      {
        "Name": "Thunderbird 14",
        "Count": 3,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Thunderbird 11",
        "Count": 3,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Thunderbird 24",
        "Count": 58,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Thunderbird 17",
        "Count": 43,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Thunderbird 10",
        "Count": 1,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Thunderbird 16",
        "Count": 1,
        "Percentage": 0,
        "AvgPercentage": 0
      },
      {
        "Name": "Thunderbird 3",
        "Count": 9,
        "Percentage": 0,
        "AvgPercentage": 1.022
      },
      {
        "Name": "Thunderbird 2",
        "Count": 3,
        "Percentage": 0,
        "AvgPercentage": 0.076
      }
    ]
  },
  {
    "Name": "BlackBerry",
    "Count": 66,
    "Percentage": 0.1,
    "AvgPercentage": 0.026,
    "Versions": [
      {
        "Name": "BlackBerry Z10",
        "Count": 64,
        "Percentage": 0.1,
        "AvgPercentage": 0
      },
      {
        "Name": "Other BlackBerry",
        "Count": 2,
        "Percentage": 0,
        "AvgPercentage": 0.026
      }
    ]
  },
  {
    "Name": "AOL Mail",
    "Count": 44,
    "Percentage": 0,
    "AvgPercentage": 0.671,
    "Versions": [
      {
        "Name": "Using Android",
        "Count": 2,
        "Percentage": 0,
        "AvgPercentage": 0.006
      },
      {
        "Name": "Using Explorer",
        "Count": 7,
        "Percentage": 0,
        "AvgPercentage": 0.644
      },
      {
        "Name": "Using Firefox",
        "Count": 2,
        "Percentage": 0,
        "AvgPercentage": 0.016
      },
      {
        "Name": "Using Chrome",
        "Count": 28,
        "Percentage": 0,
        "AvgPercentage": 0.004
      },
      {
        "Name": "Other",
        "Count": 5,
        "Percentage": 0,
        "AvgPercentage": 0.001
      }
    ]
  },
  {
    "Name": "Entourage",
    "Count": 1,
    "Percentage": 0,
    "AvgPercentage": 0.326,
    "Versions": [
      {
        "Name": "Entourage",
        "Count": 1,
        "Percentage": 0,
        "AvgPercentage": 0.326
      }
    ]
  }
]

Group usage report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/GroupUsageReport

The Group Usage Report breaks down the open data by platform: Mobile, Webmail, Desktop, Other / Unknown. For more information on how we determine these platforms see: How are mobile, desktop and webmail categories defined?

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/GroupUsageReport

Result Format

200 OK

json

[
  {
    "ClientType": "Mobile",
    "Total": 10329,
    "Percentage": 9
  },
  {
    "ClientType": "Webmail",
    "Total": 43691,
    "Percentage": 39
  },
  {
    "ClientType": "Desktop",
    "Total": 58755,
    "Percentage": 52
  }
]

Browser usage report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/BrowserUsageReport

The Browser Usage Report breaks down the open data by the web browser that was used. However, this only applies to web based email clients.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/BrowserUsageReport

Result Format

200 OK

json

[
  {
    "ClientType": "Using Firefox",
    "Total": 1749,
    "Percentage": 4
  },
  {
    "ClientType": "Using Explorer",
    "Total": 126,
    "Percentage": 0
  },
  {
    "ClientType": "Via Gmail's Image Cache",
    "Total": 35909,
    "Percentage": 83
  },
  {
    "ClientType": "Using Chrome",
    "Total": 5045,
    "Percentage": 12
  },
  {
    "ClientType": "Using Safari",
    "Total": 469,
    "Percentage": 1
  }
]

Rendering category report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/RenderingCategoryReport

The Rendering Category Report breaks down the open data by the core rendering engine that was used.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/RenderingCategoryReport

Result Format

200 OK

json

[
  {
    "RenderingType": "Other",
    "Total": 42387,
    "Percentage": 36
  },
  {
    "RenderingType": "Webkit",
    "Total": 49868,
    "Percentage": 43
  },
  {
    "RenderingType": "Firefox",
    "Total": 2050,
    "Percentage": 2
  },
  {
    "RenderingType": "MSWord",
    "Total": 19871,
    "Percentage": 17
  },
  {
    "RenderingType": "Explorer",
    "Total": 2068,
    "Percentage": 2
  }
]

Geolocation Report

GET https://analytics-api.litmus.com/api/v1/Campaigns/{guid}/GeolocationReport

Making a GET request to the GeolocationReport endpoint will provide a response containing the geolocation data for your hits.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

Examples

cURL

curl -X GET\
-u apikey:password\
-H "Content-type: application/json"\
https://analytics-api.litmus.com/api/v1/Campaigns/{guid}/GeolocationReport

Result Format

200 OK

json

[
    {
        "Region": "Unknown",
        "Country": "United States",
        "CountryCode": "US",
        "DesktopCount": 0,
        "MobileCount": 0,
        "WebmailCount": 1,
        "RegionCode": null
    }
]

Activity reports

Activity Reports provide information on print and forward activity we've detected on a campaign.

Activity summary report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/ActivitySummaryReport

Use the Activity Summary report to display how many natural prints or forwards have been recorded.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/ActivitySummaryReport

Result Format

200 OK

json

{
  "PrintCount": 44,
  "ForwardCount": 320,
  "PrintAvgCount": 12,
  "ForwardAvgCount": 88
}

Activity report

GET https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/ActivityReport

Use the Activity Report to fetch the last 25 print / forward activities on a campaign.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

Examples

cURL

curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/ActivityReport

Result Format

200 OK

json

[
  {
    "Type": "Forwarded",
    "Detail": "hello@litmus.com",
    "RegionCode": "CaliforniaUnited States",
    "RegionName": "California",
    "City": "Mountain View",
    "Country": "United States",
    "Latitude": 37.4192047,
    "Longitude": -122.0574,
    "MailClient": "Other",
    "CreatedAt": "2015-03-26T17:24:40"
  },
  {
    "Type": "Printed",
    "Detail": "resellers@litmus.com",
    "RegionCode": "CaliforniaUnited States",
    "RegionName": "California",
    "City": "Mountain View",
    "Country": "United States",
    "Latitude": 37.4192047,
    "Longitude": -122.0574,
    "MailClient": "Other",
    "CreatedAt": "2015-03-26T17:24:39"
  },
  {
    "Type": "Printed",
    "Detail": "hello@litmus.com",
    "RegionCode": "CaliforniaUnited States",
    "RegionName": "California",
    "City": "Mountain View",
    "Country": "United States",
    "Latitude": 37.4192047,
    "Longitude": -122.0574,
    "MailClient": "Web version",
    "CreatedAt": "2015-03-26T14:43:44"
  }
]

Getting raw data

If you want to access the underlying raw data behind Email Analytics, first check out the data fields available via Email Analytics.

There are three methods for retrieving the raw data for an Email Analytics campaign.

Request the data via email

PUT https://analytics-api.litmus.com/api/v1/Campaigns/:Guid/EmailExportLink

You can use the API to submit a request for a full export to be delivered via email.

Path parameters	Description
`Guid`	REQUIRED string The unique identifier for the campaign

Body parameters	Description
`Email`	REQUIRED string

Examples

cURL

curl -X PUT\
-d '{ "Email" : "hello@litmus.com" }'\
-u apikey:password\
-H "Content-type: application/json"\
https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/EmailExportLink

FTP / SFTP

Litmus can deliver data from your campaigns to a FTP or SFTP site you provide. You can learn more about our FTP data feeds.

All FTP / SFTP sites need to be first vetted by Litmus to prevent incorrect transmissions or man-in-the-middle attacks. If you are interested in using this feature please contact us at resellers@litmus.com.

For FTP related API methods—including Create, Update, and Get calls—see the reference documentation: https://analytics-api.litmus.com/#!/FtpSites.

Email Analytics API ​

Authentication ​

Reference Documentation ​

Creating a campaign ​

Examples ​

cURL ​

Result Format ​

Get campaign meta data ​

Examples ​

cURL ​

Result Format ​

Update a campaign ​

Examples ​

cURL ​

Result Format ​

Activate a campaign ​

Examples ​

cURL ​

Summary reports ​

Open counts reports (guid) ​

Examples ​

cURL ​

Result Format ​

Open count reports (month) ​

Examples ​

cURL ​

Result Format ​

Open count reports (range) ​

Examples ​

cURL ​

Result Format ​

Advanced open counts report ​

Examples ​

cURL ​

Result Format ​

Engagement reports ​

Engagement report ​

Examples ​

cURL ​

Result Format ​

Detailed engagement report ​

Examples ​

cURL ​

Result Format ​

Group engagement report ​

Examples ​

cURL ​

Result Format ​

Mail client engagement report ​

Examples ​

cURL ​

Result Format ​

Detailed mail client engagement report ​

Examples ​

cURL ​

Result Format ​

Platform reports ​

Mail client usage report ​

Examples ​

cURL ​

Result Format ​

Group usage report ​

Examples ​

cURL ​

Result Format ​

Browser usage report ​

Examples ​

cURL ​

Result Format ​

Rendering category report ​

Examples ​

cURL ​

Result Format ​

Geolocation Report ​

Examples ​

cURL ​

Result Format ​

Activity reports ​

Activity summary report ​

Examples ​

Email Analytics API

Authentication

Reference Documentation

Creating a campaign

Examples

cURL

Result Format

Get campaign meta data

Examples

cURL

Result Format

Update a campaign

Examples

cURL

Result Format

Activate a campaign

Examples

cURL

Summary reports

Open counts reports (guid)

Examples

cURL

Result Format

Open count reports (month)

Examples

cURL

Result Format

Open count reports (range)

Examples

cURL

Result Format

Advanced open counts report

Examples

cURL

Result Format

Engagement reports

Engagement report

Examples

cURL

Result Format

Detailed engagement report

Examples

cURL

Result Format

Group engagement report

Examples

cURL

Result Format

Mail client engagement report

Examples

cURL

Result Format

Detailed mail client engagement report

Examples

cURL

Result Format

Platform reports

Mail client usage report

Examples

cURL

Result Format

Group usage report

Examples

cURL

Result Format

Browser usage report

Examples

cURL

Result Format

Rendering category report

Examples

cURL

Result Format

Geolocation Report

Examples

cURL

Result Format

Activity reports

Activity summary report

Examples