openapi: 3.2.0
info:
  title: PersistIQ API V1 Replies API
  version: v1
  description: Public REST API for PersistIQ. Authenticate with your API key in the `x-api-key` header.
servers:
- url: https://api.persistiq.com
  description: Production
security:
- api_key: []
tags:
- name: Replies
paths:
  /v1/campaigns/{campaign_id}/replies:
    get:
      summary: List replies for a campaign
      tags:
      - Replies
      parameters:
      - name: campaign_id
        in: path
        required: true
        description: Campaign hashed ID
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
      - name: lead_id
        in: query
        required: false
        description: Filter by lead hashed ID
        schema:
          type: string
      - name: start_at
        in: query
        required: false
        description: Filter replies sent on or after this date (ISO 8601)
        schema:
          type: string
      - name: end_at
        in: query
        required: false
        description: Filter replies sent on or before this date (ISO 8601)
        schema:
          type: string
      responses:
        '200':
          description: replies listed
          content:
            application/json:
              schema:
                type: object
                properties:
                  has_more:
                    type: boolean
                  next_page:
                    type:
                    - string
                    - 'null'
                  status:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
                  replies:
                    type: array
                    items:
                      $ref: '#/components/schemas/reply_type'
        '404':
          description: campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
    post:
      summary: Reply to an inbox message in a campaign
      tags:
      - Replies
      parameters:
      - name: campaign_id
        in: path
        required: true
        description: Campaign hashed ID
        schema:
          type: string
      responses:
        '201':
          description: reply queued for sending
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: queued
                  message:
                    type: string
        '400':
          description: bad request (missing params or message not in campaign)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '404':
          description: campaign or inbox message not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '422':
          description: mailbox disconnected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - inbox_message_id
              - body
              properties:
                inbox_message_id:
                  type: string
                  description: Hashed ID of the inbox message to reply to
                body:
                  type: string
                  description: HTML body of the reply
components:
  schemas:
    error_response:
      type: object
      properties:
        status:
          type: string
          example: error
        error:
          type: object
          properties:
            reason:
              type: string
            message:
              type: string
    reply_type:
      type: object
      properties:
        id:
          type: string
        from_email:
          type:
          - string
          - 'null'
        to_emails:
          type: array
          items:
            type: string
        cc_emails:
          type: array
          items:
            type: string
        subject:
          type:
          - string
          - 'null'
        body:
          type:
          - string
          - 'null'
        preview:
          type:
          - string
          - 'null'
        sent_at:
          type:
          - string
          - 'null'
        sentiment:
          type:
          - string
          - 'null'
        kind:
          type: string
        lead_id:
          type:
          - string
          - 'null'
        campaign_id:
          type:
          - string
          - 'null'
        step_message_id:
          type:
          - string
          - 'null'
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
      description: API key found in Settings > Integrations > API Key