Litmus Legacy Previews API

openapi: 3.1.0
info:
  title: Litmus Legacy Previews API
  description: >-
    The Litmus Legacy Previews API provides REST endpoints for running email
    preview tests, spam filter tests, link-check tests, and code analysis
    against submitted email HTML. Tests are initiated by POSTing email content
    to the API and results are polled until rendering is complete. Authentication
    uses HTTP Basic Auth with Litmus account credentials.
  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 Legacy Previews API Documentation
  url: https://docs.litmus.com/legacy-previews
servers:
  - url: https://previews-api.litmus.com/api/v1
    description: Litmus Legacy Previews API Production Server
tags:
  - name: Clients
    description: Available email client configurations
  - name: Results
    description: Test result retrieval
  - name: Tests
    description: Email test creation and management
security:
  - basicAuth: []
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'
  /tests/{testId}/previews:
    get:
      operationId: listTestPreviews
      summary: Litmus List email client previews for a test
      description: >-
        Returns the list of email client rendering results for a preview test.
        Each result includes the client identifier, rendering status, and
        screenshot URLs when the render is complete.
      tags:
        - Results
      parameters:
        - $ref: '#/components/parameters/testIdParam'
      responses:
        '200':
          description: List of client preview results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PreviewResult'
        '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'
  /tests/{testId}/spam:
    get:
      operationId: getSpamTestResults
      summary: Litmus Get spam filter test results
      description: >-
        Returns spam filter test results for the specified test, including the
        result from each tested spam filter service. Each result shows whether
        the email was flagged as spam and the spam score where available.
      tags:
        - Results
      parameters:
        - $ref: '#/components/parameters/testIdParam'
      responses:
        '200':
          description: Spam filter test results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpamResult'
        '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'
  /tests/{testId}/links:
    get:
      operationId: getLinkCheckResults
      summary: Litmus Get link check results
      description: >-
        Returns the link-check results for all URLs found in the tested email
        HTML. Each entry indicates the URL, its HTTP status code, and whether
        the link was reachable at the time of testing.
      tags:
        - Results
      parameters:
        - $ref: '#/components/parameters/testIdParam'
      responses:
        '200':
          description: Link check results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LinkResult'
        '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'
  /clients:
    get:
      operationId: listLegacyClients
      summary: Litmus List available email clients
      description: >-
        Returns the full list of email clients available for legacy preview
        testing, including desktop, mobile, and webmail clients. Each entry
        includes the client slug used when creating a test.
      tags:
        - Clients
      responses:
        '200':
          description: List of available email clients
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LegacyClient'
        '401':
          description: Invalid credentials
          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:
    testIdParam:
      name: testId
      in: path
      description: Numeric identifier of the email test
      required: true
      schema:
        type: integer
        example: 12345678
    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:
    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: [email protected]
        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
    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
    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: [email protected]
        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
    PreviewResult:
      type: object
      description: Email client rendering result within a test
      properties:
        client:
          type: string
          description: Email client slug identifier
          example: GMAIL
        client_name:
          type: string
          description: Human-readable name of the email client
          example: Gmail
        status:
          type: string
          description: Rendering status for this client
          enum:
            - pending
            - processing
            - complete
            - failed
            - unavailable
          example: complete
        full_image_url:
          type: string
          format: uri
          description: URL to the full-size rendered screenshot
        thumb_image_url:
          type: string
          format: uri
          description: URL to the thumbnail rendered screenshot
        orientation:
          type: string
          description: Display orientation of the rendering
          enum:
            - desktop
            - mobile
          example: desktop
    SpamResult:
      type: object
      description: Spam filter check result for a single spam filter service
      properties:
        filter:
          type: string
          description: Name of the spam filter service checked
          example: SpamAssassin
        is_spam:
          type: boolean
          description: Whether the email was flagged as spam by this filter
          example: false
        score:
          type: number
          description: Spam score returned by the filter (scale varies by provider)
          example: 0.5
        threshold:
          type: number
          description: Spam score threshold above which the filter flags as spam
          example: 5.0
        status:
          type: string
          description: Status of the spam check
          enum:
            - pending
            - complete
            - failed
          example: complete
    LinkResult:
      type: object
      description: Link reachability check result for a single URL found in the email
      properties:
        url:
          type: string
          format: uri
          description: The URL that was checked
          example: https://www.example.com/landing-page
        status_code:
          type: integer
          description: HTTP status code returned when the URL was fetched
          example: 200
        reachable:
          type: boolean
          description: Whether the URL was successfully reachable
          example: true
        redirect_url:
          type: string
          format: uri
          description: Final URL after any HTTP redirects, if applicable
    LegacyClient:
      type: object
      description: An email client available for legacy preview testing
      properties:
        slug:
          type: string
          description: Identifier used when specifying this client in test requests
          example: GMAIL
        name:
          type: string
          description: Human-readable display name of the email client
          example: Gmail
        platform:
          type: string
          description: Platform category of the email client
          enum:
            - desktop
            - mobile
            - webmail
          example: webmail
        available:
          type: boolean
          description: Whether this client is currently available for rendering
          example: true
    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