openapi: 3.2.0
info:
  title: LDM v3 Mailing API
  description: 'Multi-tenant B2B outreach automation platform. Auth: JWT Bearer (15-min) or tenant API key (ldm_*) managed in CRM Settings → API Keys. All tenant-scoped endpoints require the X-Tenant-Id header.'
  version: 1.0.0
  contact: {}
servers:
- url: https://api.live-direct-marketing.online
  description: Production
- url: https://api.dev.live-direct-marketing.online
  description: Development
- url: http://127.0.0.1:3000
  description: Local
tags:
- name: Mailing
paths:
  /api/mailing/overview:
    get:
      operationId: MailingController_getOverview
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get a global overview of all mailing campaigns (admin dashboard) — merges…
      tags:
      - Mailing
      x-required-scope:
      - mailing:read
  /api/mailing/bounce-overview:
    get:
      operationId: MailingController_getBounceOverview
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: 'Get global bounce statistics: legacy mailing tasks (per-task + per-domain) AND…'
      tags:
      - Mailing
      x-required-scope:
      - mailing:read
  /api/mailing/warmup-overview:
    get:
      operationId: MailingController_getWarmupOverview
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get an overview of all email accounts currently in warmup mode
      tags:
      - Mailing
      x-required-scope:
      - mailing:read
  /api/mailing/pending-approvals:
    get:
      operationId: MailingController_getPendingApprovals
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: List campaigns awaiting admin approval (cross-tenant for SUPER)
      tags:
      - Mailing
      x-required-scope:
      - mailing:read
  /api/mailing/{taskId}/approve:
    post:
      operationId: MailingController_approveCampaign
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Approve a pending mailing campaign (admin)
      tags:
      - Mailing
  /api/mailing/{taskId}/reject:
    post:
      operationId: MailingController_rejectCampaign
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Reject a pending mailing campaign (admin)
      tags:
      - Mailing
  /api/mailing/creative-preview/{creativeId}:
    get:
      operationId: MailingController_getCreativePreview
      parameters:
      - name: creativeId
        required: true
        in: path
        schema:
          type: string
      - name: dbName
        required: true
        in: query
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Preview a creative for approval (cross-tenant for SUPER)
      tags:
      - Mailing
  /api/mailing/{taskId}/config:
    get:
      operationId: MailingController_getConfig
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get the mailing configuration for a campaign
      tags:
      - Mailing
    patch:
      operationId: MailingController_updateConfig
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Update the mailing configuration for a campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/start:
    post:
      operationId: MailingController_startCampaign
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Start a mailing campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/start-sending:
    post:
      operationId: MailingController_startSending
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: 'Issue #180: start sending an APPROVED campaign (status=APPROVED).'
      tags:
      - Mailing
  /api/mailing/batch-stats:
    post:
      operationId: MailingController_getBatchStats
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Get stats for a batch of mailing tasks in one call
      tags:
      - Mailing
      x-required-scope:
      - mailing:write
  /api/mailing/{taskId}/start-list-stats:
    get:
      operationId: MailingController_getStartListStats
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get start-list statistics for a mailing campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/stats:
    get:
      operationId: MailingController_getStats
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get aggregate stats for a mailing campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/timeline:
    get:
      operationId: MailingController_getTimeline
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get the activity timeline for a mailing campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/speed:
    get:
      operationId: MailingController_getSpeed
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get sending speed metrics for a mailing campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/streams:
    get:
      operationId: MailingController_getStreams
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: List sending streams for a mailing campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/streams/{streamId}/logs:
    get:
      operationId: MailingController_getStreamLogs
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: streamId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get logs for a specific mailing stream
      tags:
      - Mailing
  /api/mailing/{taskId}/streams/{streamId}/detail:
    get:
      operationId: MailingController_getStreamDetail
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: streamId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get detailed information for a specific mailing stream
      tags:
      - Mailing
  /api/mailing/{taskId}/streams/{streamId}/logs-filtered:
    get:
      operationId: MailingController_getStreamLogsFiltered
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: streamId
        required: true
        in: path
        schema:
          type: string
      - name: stage
        required: true
        in: query
        schema:
          type: string
      - name: status
        required: true
        in: query
        schema:
          type: string
      - name: page
        required: true
        in: query
        schema:
          type: string
      - name: pageSize
        required: true
        in: query
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get filtered and paginated logs for a mailing stream
      tags:
      - Mailing
  /api/mailing/{taskId}/logs:
    delete:
      operationId: MailingController_deleteTaskLogs
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Delete all logs for a mailing campaign (SUPER only)
      tags:
      - Mailing
  /api/mailing/{taskId}/items:
    get:
      operationId: MailingController_getItems
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: page
        required: true
        in: query
        schema:
          type: string
      - name: pageSize
        required: true
        in: query
        schema:
          type: string
      - name: status
        required: true
        in: query
        schema:
          type: string
      - name: search
        required: true
        in: query
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: List mailing items (recipients) for a campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/items/{itemId}:
    get:
      operationId: MailingController_getItem
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: itemId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get a single mailing item by id
      tags:
      - Mailing
    patch:
      operationId: MailingController_updateItem
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: itemId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Update fields of a single mailing item
      tags:
      - Mailing
  /api/mailing/{taskId}/items/{itemId}/status:
    patch:
      operationId: MailingController_updateItemStatus
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: itemId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Update the status of a single mailing item
      tags:
      - Mailing
  /api/mailing/{taskId}/reset-errors:
    post:
      operationId: MailingController_resetErrors
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Reset all failed mailing items in a campaign back to pending
      tags:
      - Mailing
  /api/mailing/{taskId}/reset-status/{status}:
    post:
      operationId: MailingController_resetByStatus
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: status
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Reset all items with a given status back to pending (admin recovery only)
      tags:
      - Mailing
  /api/mailing/{taskId}/stats/today:
    get:
      operationId: MailingController_getStatsToday
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get today's stats for a mailing campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/ab-test:
    get:
      operationId: MailingController_getAbTest
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get A/B test statistics for a mailing campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/analytics:
    get:
      operationId: MailingController_getAnalytics
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get per-domain analytics for a mailing campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/control-email-stats:
    get:
      operationId: MailingController_getControlEmailStats
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get control-email tracking stats for a mailing campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/control-email-autopause/evaluate:
    post:
      operationId: MailingController_evaluateControlEmailAutoPause
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Manually evaluate control-email auto-pause rules for a campaign
      tags:
      - Mailing
  /api/mailing/{taskId}/export.csv:
    get:
      operationId: MailingController_exportCsv
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Export a mailing campaign as CSV
      tags:
      - Mailing
  /api/mailing/{taskId}/report.pdf:
    get:
      operationId: MailingController_exportReportPdf
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Export a client-ready PDF report for a mailing campaign
      tags:
      - Mailing
  /api/mailing/block-guard/dashboard:
    get:
      operationId: MailingController_blockGuardDashboard
      parameters:
      - name: taskId
        required: true
        in: query
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get the BlockGuard dashboard (blocks, barked templates, paused accounts)
      tags:
      - Mailing
      x-required-scope:
      - mailing:read
  /api/mailing/block-guard/template/{templateId}:
    get:
      operationId: MailingController_blockGuardTemplate
      parameters:
      - name: templateId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get block-event history for a template
      tags:
      - Mailing
  /api/mailing/block-guard/template/{templateId}/unblock:
    post:
      operationId: MailingController_blockGuardUnblock
      parameters:
      - name: templateId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Manually unblock a previously barked template
      tags:
      - Mailing
  /api/mailing/block-guard/account/{accountId}/reset-limits:
    post:
      operationId: MailingController_blockGuardResetAccount
      parameters:
      - name: accountId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: 'Reset limit counters for one account: clear auto-pause + zero working counters…'
      tags:
      - Mailing
  /api/mailing/{taskId}/reset-limits:
    post:
      operationId: MailingController_resetLimits
      parameters:
      - name: taskId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: 'Reset limit counters for a whole mailing: un-pause blocked accounts, KEEP…'
      tags:
      - Mailing
  /api/mailing/block-guard/account/{accountId}:
    get:
      operationId: MailingController_blockGuardAccount
      parameters:
      - name: accountId
        required: true
        in: path
        schema:
          type: string
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get block-event history for an email account
      tags:
      - Mailing
  /api/mailing/block-guard/providers:
    get:
      operationId: MailingController_blockGuardProviders
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - jwt: []
      summary: Get block statistics aggregated per email provider
      tags:
      - Mailing
      x-required-scope:
      - mailing:read
components:
  securitySchemes:
    jwt:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: JWT access token from /auth/login (Bearer <token>)
    tenant-api-key:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Tenant API key (Bearer ldm_*) for MCP/A2A clients. Issued via CRM Settings → API Keys.
    rpa-service:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Dedicated RPA service key. No tenant API-key or query-key authentication.