openapi: 3.2.0
info:
  title: Paubox Marketing Drip Campaigns API
  description: "Public documentation Paubox Marketing API. \n\nAll Paubox Marketing customers have access to the Paubox Marketing API to automate various tasks.\n\n## Authentication\nUse the authorization header in requests with the format: `authorization: Token token=<API_KEY>`\n\nReplace `<API_KEY>` with your API key. Find your API key in the address bar from the email builder (note: each API Key is displayed only once upon creation).\n\n## Base URL\n`https://api.paubox.com/v1/marketing`\n"
  contact:
    name: Paubox Support
    url: https://www.paubox.com
  version: 1.0.0
servers:
- url: https://api.paubox.com/v1/marketing
  description: Production server
security:
- TokenAuth: []
tags:
- name: drip_campaigns
  description: Drip campaign management and automation operations
paths:
  /drip_campaigns:
    get:
      tags:
      - drip_campaigns
      summary: Fetch drip campaigns
      description: Return json data about Drip Campaigns
      operationId: getDripCampaigns
      parameters:
      - name: search
        in: query
        description: Regex string to search on. Compares against drip campaign name
        required: false
        schema:
          type: string
      - name: order_by
        in: query
        description: Attribute to sort on. Default value is created_at
        required: false
        schema:
          type: string
          default: created_at
      - name: order
        in: query
        description: Direction to sort. Default value is descending
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: Drip campaigns data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DripCampaignsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /drip_campaigns/{id}:
    get:
      tags:
      - drip_campaigns
      summary: Fetch drip campaign
      description: Returns json data about a drip campaign
      operationId: getDripCampaign
      parameters:
      - name: id
        in: path
        description: The ID of the drip campaign to fetch
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Drip campaign data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DripCampaignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - drip_campaigns
      summary: Update drip campaign
      description: Updates drip campaign attributes
      operationId: updateDripCampaign
      parameters:
      - name: id
        in: path
        description: The ID of the drip campaign to update
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDripCampaignRequest'
            example:
              drip_campaign:
                name: Welcome Series
                subscription_list_id: 123e4567-e89b-12d3-a456-426614174000
                start_trigger: subscription
                drip_campaign_nodes: '{"nodes": [], "edges": []}'
        required: true
      responses:
        '200':
          description: Drip campaign updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DripCampaignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /drip_campaigns/{id}/start:
    post:
      tags:
      - drip_campaigns
      summary: Start a drip campaign
      description: Starts a drip campaign
      operationId: startDripCampaign
      parameters:
      - name: id
        in: path
        description: The ID of the drip campaign to start
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Drip campaign started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartDripCampaignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /drip_campaigns/{id}/pause:
    post:
      tags:
      - drip_campaigns
      summary: Pause a drip campaign
      description: Pauses a drip campaign
      operationId: pauseDripCampaign
      parameters:
      - name: id
        in: path
        description: The ID of the drip campaign to pause
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Drip campaign paused successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PauseDripCampaignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    UpdateDripCampaignRequest:
      type: object
      properties:
        drip_campaign:
          $ref: '#/components/schemas/UpdateDripCampaignRequest_drip_campaign'
    StartDripCampaignResponse_data:
      type: object
      properties:
        jids:
          type: array
          description: Array of job IDs for the started drip campaign
          items:
            type: string
    DripCampaignsResponse_data:
      type: object
      properties:
        id:
          type: string
          description: Drip campaign ID
        type:
          type: string
          description: Resource type
          enum:
          - drip_campaign
        attributes:
          $ref: '#/components/schemas/DripCampaignsResponse_attributes'
    DripCampaignsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DripCampaignsResponse_data'
    DripCampaignsResponse_attributes:
      type: object
      properties:
        name:
          type: string
          description: Name of the drip campaign
        subscription_list_id:
          type: string
          description: Subscription list ID
        subscription_list_name:
          type: string
          description: Name of the subscription list
        state:
          type: string
          description: Current state of the drip campaign
        updated_at:
          type: string
          description: Last update timestamp
          format: date-time
        start_trigger:
          type: string
          description: Trigger condition to start the drip campaign
        subscriber_count:
          type: integer
          description: Number of subscribers in the campaign
        subscriber_completed_count:
          type: integer
          description: Number of subscribers who completed the campaign
    StartDripCampaignResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/StartDripCampaignResponse_data'
    PauseDripCampaignResponse_data:
      type: object
      properties:
        drip_campaign_id:
          type: string
          description: ID of the paused drip campaign
        status:
          type: string
          description: Status of the drip campaign after pausing
    DripCampaignResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DripCampaignResponse_data'
    UpdateDripCampaignRequest_drip_campaign:
      type: object
      properties:
        name:
          type: string
          description: Name of the drip campaign
        subscription_list_id:
          type: string
          description: Subscription list ID
          format: uuid
        start_trigger:
          type: string
          description: Trigger condition to start the drip campaign
        drip_campaign_nodes:
          type: string
          description: JSON string containing drip campaign node configuration
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
        details:
          type: object
          description: Additional error details
    DripCampaignResponse_data:
      type: object
      properties:
        id:
          type: string
          description: Drip campaign ID
        type:
          type: string
          description: Resource type
          enum:
          - drip_campaign
        attributes:
          $ref: '#/components/schemas/DripCampaignResponse_data_attributes'
    DripCampaignResponse_data_attributes:
      type: object
      properties:
        name:
          type: string
          description: Name of the drip campaign
        subscription_list_id:
          type: string
          description: Subscription list ID
        subscription_list_name:
          type: string
          description: Name of the subscription list
        state:
          type: string
          description: Current state of the drip campaign
        updated_at:
          type: string
          description: Last update timestamp
          format: date-time
        start_trigger:
          type: string
          description: Trigger condition to start the drip campaign
        subscriber_count:
          type: integer
          description: Number of subscribers in the campaign
        subscriber_completed_count:
          type: integer
          description: Number of subscribers who completed the campaign
        drip_campaign_nodes:
          type: string
          description: JSON string containing drip campaign node configuration
        drip_campaign_tree_blob:
          type: string
          description: JSON string containing drip campaign tree structure
    PauseDripCampaignResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PauseDripCampaignResponse_data'
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Unprocessable entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    TokenAuth:
      type: apiKey
      description: 'Token-based authentication. Use format: "Token token=<API_KEY>" where <API_KEY> is your API key'
      name: authorization
      in: header