OpenAPI Specification
openapi: 3.1.0
info:
title: Litmus Email Analytics API
description: The Litmus Email Analytics API provides REST endpoints for retrieving email campaign engagement metrics including read rates, deletion rates, device types, email clients, geographic data, and forwarding activity. Campaign data is accessed by GUID and returns detailed activity summary reports. Analytics data is collected via a tracking pixel embedded in sent emails and the API surfaces aggregated engagement breakdowns.
version: 1.0.0
contact:
name: Litmus Support
url: https://www.litmus.com/support/
termsOfService: https://www.litmus.com/terms-of-service/
servers:
- url: https://analytics-api.litmus.com/api/v1
description: Litmus Email Analytics API Production Server
security:
- basicAuth: []
tags:
- name: Analytics
description: Campaign engagement metrics and breakdowns
paths:
/campaigns/{campaignGuid}/summary:
get:
operationId: getCampaignSummary
summary: Litmus Get campaign engagement summary
description: Returns a high-level engagement summary for the campaign including total opens, unique opens, read time distribution, deletion rate, forwarding count, and print count. Provides the core metrics for evaluating campaign performance.
tags:
- Analytics
parameters:
- $ref: '#/components/parameters/campaignGuidParam'
responses:
'200':
description: Campaign engagement summary
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignSummary'
'401':
description: Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/campaigns/{campaignGuid}/clients:
get:
operationId: getCampaignClientBreakdown
summary: Litmus Get campaign email client breakdown
description: Returns a breakdown of campaign opens by email client, showing the count and percentage of opens recorded from each detected email client such as Gmail, Apple Mail, Outlook, and others.
tags:
- Analytics
parameters:
- $ref: '#/components/parameters/campaignGuidParam'
responses:
'200':
description: Email client breakdown for the campaign
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ClientBreakdownEntry'
'401':
description: Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/campaigns/{campaignGuid}/geo:
get:
operationId: getCampaignGeoBreakdown
summary: Litmus Get campaign geographic breakdown
description: Returns a geographic breakdown of campaign opens by country and region. Each entry includes the country name, ISO country code, open count, and percentage share of total opens.
tags:
- Analytics
parameters:
- $ref: '#/components/parameters/campaignGuidParam'
responses:
'200':
description: Geographic breakdown of campaign opens
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GeoBreakdownEntry'
'401':
description: Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/campaigns/{campaignGuid}/devices:
get:
operationId: getCampaignDeviceBreakdown
summary: Litmus Get campaign device breakdown
description: Returns a breakdown of campaign opens by device type including desktop, mobile, and tablet. Shows the count and percentage of opens for each device category.
tags:
- Analytics
parameters:
- $ref: '#/components/parameters/campaignGuidParam'
responses:
'200':
description: Device type breakdown of campaign opens
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DeviceBreakdownEntry'
'401':
description: Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/campaigns/{campaignGuid}/read-times:
get:
operationId: getCampaignReadTimes
summary: Litmus Get campaign read time distribution
description: Returns the distribution of how long recipients spent reading the email. Categorizes reads into glanced (under 2 seconds), skimmed (2-8 seconds), and read (over 8 seconds) buckets with counts and percentages.
tags:
- Analytics
parameters:
- $ref: '#/components/parameters/campaignGuidParam'
responses:
'200':
description: Read time distribution for the campaign
content:
application/json:
schema:
$ref: '#/components/schemas/ReadTimeDistribution'
'401':
description: Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
GeoBreakdownEntry:
type: object
description: Campaign opens attributed to a single country
properties:
country:
type: string
description: Country name
example: United States
country_code:
type: string
description: ISO 3166-1 alpha-2 country code
pattern: ^[A-Z]{2}$
example: US
opens:
type: integer
description: Number of opens from this country
example: 2841
percentage:
type: number
format: float
description: Percentage of total opens from this country
minimum: 0
maximum: 100
example: 58.8
CampaignSummary:
type: object
description: High-level engagement metrics for an email campaign
properties:
total_opens:
type: integer
description: Total number of opens recorded
example: 4832
unique_opens:
type: integer
description: Number of unique recipients who opened the email
example: 3201
forwards:
type: integer
description: Number of times the email was forwarded
example: 47
prints:
type: integer
description: Number of times the email was printed
example: 12
read_rate:
type: number
format: float
description: Percentage of opens where recipients read the email for over 8 seconds
minimum: 0
maximum: 100
example: 42.5
skim_rate:
type: number
format: float
description: Percentage of opens where recipients skimmed (2-8 seconds)
minimum: 0
maximum: 100
example: 31.2
glance_rate:
type: number
format: float
description: Percentage of opens where recipients glanced (under 2 seconds)
minimum: 0
maximum: 100
example: 26.3
delete_rate:
type: number
format: float
description: Percentage of opens followed by deletion
minimum: 0
maximum: 100
example: 18.7
ReadTimeDistribution:
type: object
description: Distribution of recipient read times for a campaign
properties:
glanced:
$ref: '#/components/schemas/ReadTimeBucket'
skimmed:
$ref: '#/components/schemas/ReadTimeBucket'
read:
$ref: '#/components/schemas/ReadTimeBucket'
Error:
type: object
description: An API error response
required:
- message
properties:
message:
type: string
description: Human-readable error message
example: Authentication required
code:
type: string
description: Machine-readable error code
example: unauthorized
ReadTimeBucket:
type: object
description: A read time engagement bucket with count and percentage
properties:
label:
type: string
description: Human-readable label for the bucket
example: Read
seconds_range:
type: string
description: Description of the time range this bucket covers
example: '>8 seconds'
count:
type: integer
description: Number of opens falling in this bucket
example: 2054
percentage:
type: number
format: float
description: Percentage of total opens falling in this bucket
minimum: 0
maximum: 100
example: 42.5
ClientBreakdownEntry:
type: object
description: Campaign opens attributed to a single email client
properties:
client:
type: string
description: Name of the email client
example: Gmail
opens:
type: integer
description: Number of opens from this email client
example: 1842
percentage:
type: number
format: float
description: Percentage of total opens from this email client
minimum: 0
maximum: 100
example: 38.1
DeviceBreakdownEntry:
type: object
description: Campaign opens attributed to a device category
properties:
device_type:
type: string
description: Device category
enum:
- desktop
- mobile
- tablet
- unknown
example: mobile
opens:
type: integer
description: Number of opens from this device type
example: 2156
percentage:
type: number
format: float
description: Percentage of total opens from this device type
minimum: 0
maximum: 100
example: 44.6
parameters:
campaignGuidParam:
name: campaignGuid
in: path
description: Unique identifier (GUID) for the email campaign
required: true
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic Auth using Litmus account username and password
externalDocs:
description: Litmus Email Analytics API Documentation
url: https://docs.litmus.com/email-analytics