openapi: 3.1.0
info:
  title: Litmus Email Analytics Tests 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: Tests
  description: Email test creation and management
paths:
  /tests:
    get:
      operationId: listTests
      summary: Litmus List tests
      description: Returns a paginated list of all email tests run under the authenticated account. Each test entry includes the test type, creation timestamp, current status, and a link to the full test results.
      tags:
      - Tests
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam'
      responses:
        '200':
          description: Paginated list of tests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestList'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createTest
      summary: Litmus Create a test
      description: Creates a new email test by submitting email HTML, subject, and optional sender details. The test type (preview, spam, links) determines which checks are run. Returns the newly created test object with an ID for polling results.
      tags:
      - Tests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTestRequest'
      responses:
        '201':
          description: Test created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Test'
        '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'
  /tests/{testId}:
    get:
      operationId: getTest
      summary: Litmus Get a test
      description: Retrieves a specific email test by its numeric ID. Returns the test status and all available results. Poll this endpoint until the test status transitions to complete for all requested test types.
      tags:
      - Tests
      parameters:
      - $ref: '#/components/parameters/testIdParam'
      responses:
        '200':
          description: Test retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Test'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Test not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteTest
      summary: Litmus Delete a test
      description: Permanently deletes an email test and all associated results from the Litmus account. This action cannot be undone.
      tags:
      - Tests
      parameters:
      - $ref: '#/components/parameters/testIdParam'
      responses:
        '204':
          description: Test deleted successfully
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Test not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    perPageParam:
      name: per_page
      in: query
      description: Number of results per page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    pageParam:
      name: page
      in: query
      description: Page number for paginated results (1-based)
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    testIdParam:
      name: testId
      in: path
      description: Numeric identifier of the email test
      required: true
      schema:
        type: integer
        example: 12345678
  schemas:
    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
    TestList:
      type: object
      description: Paginated list of email tests
      properties:
        tests:
          type: array
          description: Array of test summaries
          items:
            $ref: '#/components/schemas/Test'
        total:
          type: integer
          description: Total number of tests in the account
          example: 128
        page:
          type: integer
          description: Current page number
          example: 1
        per_page:
          type: integer
          description: Number of tests per page
          example: 25
    CreateTestRequest:
      type: object
      description: Request body for creating an email test
      required:
      - html
      properties:
        html:
          type: string
          description: Full HTML source of the email to be tested
        plain_text:
          type: string
          description: Optional plain text alternative of the email
        subject:
          type: string
          description: Email subject line
          maxLength: 998
        from_address:
          type: string
          format: email
          description: Sender email address used for spam filter testing
          example: sender@example.com
        from_name:
          type: string
          description: Sender display name used in spam filter context
          example: My Company
        clients:
          type: array
          description: Email client slugs to include in preview rendering
          items:
            type: string
          example:
          - GMAIL
          - OL2019
        run_spam_filter_tests:
          type: boolean
          description: Whether to run spam filter tests on the submitted email
          default: false
        run_link_check_tests:
          type: boolean
          description: Whether to run link reachability checks on URLs in the email HTML
          default: false
    Test:
      type: object
      description: An email test with status and result references
      properties:
        id:
          type: integer
          description: Unique numeric identifier for the test
          example: 12345678
        status:
          type: string
          description: Overall status of the test
          enum:
          - pending
          - processing
          - complete
          - failed
          example: complete
        created_at:
          type: string
          format: date-time
          description: Timestamp when the test was created
        completed_at:
          type: string
          format: date-time
          description: Timestamp when the test completed
        subject:
          type: string
          description: Email subject that was tested
          example: Welcome to Our Newsletter
        from_address:
          type: string
          format: email
          description: Sender address used in the test
          example: sender@example.com
        previews_requested:
          type: boolean
          description: Whether email client preview rendering was requested
        spam_requested:
          type: boolean
          description: Whether spam filter testing was requested
        links_requested:
          type: boolean
          description: Whether link checking was requested
  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