openapi: 3.1.0
info:
  title: Litmus Email Analytics Previews 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: Previews
  description: Email preview generation and management
paths:
  /emails:
    post:
      operationId: createEmailPreview
      summary: Litmus Create an email preview
      description: Submits email HTML to generate previews across one or more email clients. The request body includes the HTML source and a list of email client identifiers. Returns a preview object with a unique ID that can be used to retrieve individual client screenshots once rendering is complete.
      tags:
      - Previews
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailPreviewRequest'
      responses:
        '201':
          description: Email preview created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailPreview'
        '400':
          description: Invalid request body or HTML content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /emails/{emailGuid}:
    get:
      operationId: getEmailPreview
      summary: Litmus Get email preview
      description: Retrieves the status and results of an email preview by its GUID. Returns the overall preview state and the rendering status for each requested email client. Poll this endpoint until all client results show a completed status.
      tags:
      - Previews
      parameters:
      - $ref: '#/components/parameters/emailGuidParam'
      responses:
        '200':
          description: Email preview details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailPreview'
        '401':
          description: Missing or invalid authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Email preview not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /emails/{emailGuid}/previews/{clientId}:
    get:
      operationId: getClientPreview
      summary: Litmus Get client preview screenshot
      description: Retrieves the rendered screenshot and metadata for a specific email client within an email preview. Returns URLs for the full-size and thumbnail image captures once the client rendering status is complete.
      tags:
      - Previews
      parameters:
      - $ref: '#/components/parameters/emailGuidParam'
      - $ref: '#/components/parameters/clientIdParam'
      responses:
        '200':
          description: Client preview screenshot retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientPreview'
        '401':
          description: Missing or invalid authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Email preview or client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    clientIdParam:
      name: clientId
      in: path
      description: Email client identifier string
      required: true
      schema:
        type: string
        example: gmail_chrome
    emailGuidParam:
      name: emailGuid
      in: path
      description: Unique identifier (GUID) for the email preview
      required: true
      schema:
        type: string
        format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    Error:
      type: object
      description: An API error response
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Invalid or expired access token
        code:
          type: string
          description: Machine-readable error code
          example: unauthorized
    ClientPreview:
      type: object
      description: Rendered preview result for a single email client
      properties:
        client_id:
          type: string
          description: Email client identifier for this preview
          example: gmail_chrome
        status:
          type: string
          description: Rendering status for this client
          enum:
          - pending
          - processing
          - complete
          - failed
          - unavailable
          example: complete
        full_url:
          type: string
          format: uri
          description: URL to the full-size rendered screenshot image
          example: https://litmus-screenshots.s3.amazonaws.com/full/abc123.png
        thumb_url:
          type: string
          format: uri
          description: URL to the thumbnail rendered screenshot image
          example: https://litmus-screenshots.s3.amazonaws.com/thumb/abc123.png
        orientation:
          type: string
          description: Rendering orientation of the screenshot
          enum:
          - desktop
          - mobile
          example: desktop
    CreateEmailPreviewRequest:
      type: object
      description: Request body for creating an email preview
      required:
      - html
      - clients
      properties:
        html:
          type: string
          description: Full HTML source of the email to be previewed
          example: <html><body><h1>Hello World</h1></body></html>
        plain_text:
          type: string
          description: Optional plain text version of the email
        subject:
          type: string
          description: Email subject line shown in clients that render subject previews
          maxLength: 998
        from_address:
          type: string
          format: email
          description: Sender email address used for spam filter context
          example: sender@example.com
        clients:
          type: array
          description: List of email client identifiers to generate previews for. Use the /clients endpoint to retrieve valid identifiers.
          items:
            type: string
          minItems: 1
          example:
          - gmail_chrome
          - outlook_2019
          - apple_mail_14
    EmailPreview:
      type: object
      description: An email preview with rendering results across email clients
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the email preview
          example: 550e8400-e29b-41d4-a716-446655440000
        status:
          type: string
          description: Overall status of the preview rendering job
          enum:
          - pending
          - processing
          - complete
          - failed
          example: complete
        created_at:
          type: string
          format: date-time
          description: Timestamp when the preview was created
        completed_at:
          type: string
          format: date-time
          description: Timestamp when all client renders completed
        previews:
          type: array
          description: List of per-client preview results
          items:
            $ref: '#/components/schemas/ClientPreview'
  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