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/
externalDocs:
  description: Litmus Email Analytics API Documentation
  url: https://docs.litmus.com/email-analytics
servers:
  - url: https://analytics-api.litmus.com/api/v1
    description: Litmus Email Analytics API Production Server
tags:
  - name: Analytics
    description: Campaign engagement metrics and breakdowns
  - name: Campaigns
    description: Email campaign tracking and management
security:
  - basicAuth: []
paths:
  /campaigns:
    get:
      operationId: listCampaigns
      summary: Litmus List campaigns
      description: >-
        Returns a paginated list of tracked email campaigns associated with the
        authenticated account. Each campaign entry includes its GUID, name,
        creation date, and a summary of total opens tracked so far.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam'
      responses:
        '200':
          description: Paginated list of campaigns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignList'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createCampaign
      summary: Litmus Create a campaign
      description: >-
        Creates a new campaign tracking entry and returns a tracking GUID and
        pixel URL to embed in the email HTML. The tracking pixel collects
        engagement data when recipients open the email.
      tags:
        - Campaigns
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCampaignRequest'
      responses:
        '201':
          description: Campaign created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /campaigns/{campaignGuid}:
    get:
      operationId: getCampaign
      summary: Litmus Get a campaign
      description: >-
        Retrieves a specific campaign by its GUID including basic metadata and
        aggregate open count. Use the analytics sub-resources to retrieve
        detailed engagement breakdowns.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/campaignGuidParam'
      responses:
        '200':
          description: Campaign retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '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'
    delete:
      operationId: deleteCampaign
      summary: Litmus Delete a campaign
      description: >-
        Permanently deletes a campaign and all associated tracking data from the
        account. This action cannot be undone and will stop collection of new
        engagement events for the campaign.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/campaignGuidParam'
      responses:
        '204':
          description: Campaign deleted successfully
        '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}/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:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth using Litmus account username and password
  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
    pageParam:
      name: page
      in: query
      description: Page number for paginated results (1-based)
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    perPageParam:
      name: per_page
      in: query
      description: Number of results per page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  schemas:
    CreateCampaignRequest:
      type: object
      description: Request body for creating a new campaign tracking entry
      required:
        - name
      properties:
        name:
          type: string
          description: Human-readable name for the campaign
          example: March Newsletter 2026
          maxLength: 255
        tags:
          type: array
          description: Optional tags for organizing campaigns
          items:
            type: string
          example:
            - newsletter
            - Q1-2026
    CampaignList:
      type: object
      description: Paginated list of campaigns
      properties:
        campaigns:
          type: array
          description: Array of campaign summaries
          items:
            $ref: '#/components/schemas/Campaign'
        total:
          type: integer
          description: Total number of campaigns in the account
          example: 54
        page:
          type: integer
          description: Current page number
          example: 1
        per_page:
          type: integer
          description: Number of campaigns per page
          example: 25
    Campaign:
      type: object
      description: An email campaign tracking entry
      properties:
        guid:
          type: string
          format: uuid
          description: Unique identifier for the campaign
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Human-readable name of the campaign
          example: March Newsletter 2026
        tracking_pixel_url:
          type: string
          format: uri
          description: URL of the tracking pixel to embed in the email HTML
          example: https://analytics.litmus.com/t/550e8400-e29b-41d4-a716-446655440000.gif
        created_at:
          type: string
          format: date-time
          description: Timestamp when the campaign was created
        total_opens:
          type: integer
          description: Total number of opens tracked for this campaign
          example: 4832
        tags:
          type: array
          description: Tags assigned to the campaign
          items:
            type: string
    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
    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
    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
    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
    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'
    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
    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