openapi: 3.2.0
info:
  title: LDM v3 Email Accounts 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: Email Accounts
paths:
  /api/email-accounts/lookup:
    get:
      operationId: EmailAccountsController_lookupProvider
      parameters:
      - name: email
        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: Look up provider SMTP/IMAP settings for an email address
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:read
  /api/email-accounts/test-unsaved:
    post:
      operationId: EmailAccountsController_testUnsaved
      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: Test SMTP/IMAP credentials without saving the account
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:write
  /api/email-accounts:
    get:
      operationId: EmailAccountsController_findAll
      parameters:
      - name: page
        required: true
        in: query
        schema:
          type: string
      - name: pageSize
        required: true
        in: query
        schema:
          type: string
      - name: listId
        required: true
        in: query
        schema:
          type: string
      - name: status
        required: true
        in: query
        schema:
          type: string
      - name: service
        required: true
        in: query
        schema:
          type: string
      - name: type
        required: true
        in: query
        schema:
          type: string
      - name: sendMethod
        required: true
        in: query
        schema:
          type: string
      - name: imapMode
        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 email accounts with filters and pagination
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:read
    post:
      operationId: EmailAccountsController_create
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailAccountDto'
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Create a new email account.
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:write
  /api/email-accounts/stats:
    get:
      operationId: EmailAccountsController_getStats
      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 aggregated stats across all email accounts
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:read
  /api/email-accounts/check-duplicate:
    get:
      operationId: EmailAccountsController_checkDuplicate
      parameters:
      - name: email
        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: Check if an email address is already registered
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:read
  /api/email-accounts/relay-health-summary:
    get:
      operationId: EmailAccountsController_relayHealthSummary
      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: 'Relay health across the whole tenant (#337): how many relays are sending right…'
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:read
  /api/email-accounts/relay-health/attention:
    get:
      operationId: EmailAccountsController_relayAttention
      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: 'Relays that automation can no longer recover (#356): status=ERROR relays where…'
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:read
  /api/email-accounts/relay-health/probe:
    post:
      operationId: EmailAccountsController_relayProbe
      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: Re-probe ERROR relays of this tenant right now (#356) instead of waiting for…
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:write
  /api/email-accounts/{id}/stats:
    get:
      operationId: EmailAccountsController_getAccountStats
      parameters:
      - name: id
        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-account email statistics
      tags:
      - Email Accounts
  /api/email-accounts/{id}:
    get:
      operationId: EmailAccountsController_findById
      parameters:
      - name: id
        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 an email account by id
      tags:
      - Email Accounts
    patch:
      operationId: EmailAccountsController_update
      parameters:
      - name: id
        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 an email account.
      tags:
      - Email Accounts
    delete:
      operationId: EmailAccountsController_remove
      parameters:
      - name: id
        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 an email account
      tags:
      - Email Accounts
  /api/email-accounts/import-oauth:
    post:
      operationId: EmailAccountsController_importOauth
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportOauthDto'
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Import an Outlook/Hotmail account from an OAuth combo…
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:write
  /api/email-accounts/import-oauth/bulk:
    post:
      operationId: EmailAccountsController_importOauthBulk
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportOauthBulkDto'
      responses:
        '201':
          description: ''
      security:
      - jwt: []
      summary: Bulk-import Outlook/Hotmail accounts from OAuth combo strings (one per array…
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:write
  /api/email-accounts/{id}/fetch-imap:
    post:
      operationId: EmailAccountsController_fetchImap
      parameters:
      - name: id
        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: Trigger an IMAP fetch for an account (queue or fast-lane)
      tags:
      - Email Accounts
  /api/email-accounts/{id}/test:
    post:
      operationId: EmailAccountsController_testConnection
      parameters:
      - name: id
        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: Test SMTP and/or IMAP connectivity for an account
      tags:
      - Email Accounts
  /api/email-accounts/{id}/test-receive:
    post:
      operationId: EmailAccountsController_testReceive
      parameters:
      - name: id
        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: Universal Receive Test (#4).
      tags:
      - Email Accounts
  /api/email-accounts/{id}/test-send:
    post:
      operationId: EmailAccountsController_testSend
      parameters:
      - name: id
        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: Universal Send Test (#5).
      tags:
      - Email Accounts
  /api/email-accounts/{id}/dns-check:
    get:
      operationId: EmailAccountsController_checkDns
      parameters:
      - name: id
        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: Run DNS health check for the account domain
      tags:
      - Email Accounts
  /api/email-accounts/{id}/reset-counters:
    post:
      operationId: EmailAccountsController_resetCounters
      parameters:
      - name: id
        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 daily send counters for an account
      tags:
      - Email Accounts
  /api/email-accounts/{id}/warmup/start:
    post:
      operationId: EmailAccountsController_warmupStart
      parameters:
      - name: id
        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 mailbox warm-up for an account
      tags:
      - Email Accounts
  /api/email-accounts/{id}/warmup/stop:
    post:
      operationId: EmailAccountsController_warmupStop
      parameters:
      - name: id
        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: Stop mailbox warm-up for an account
      tags:
      - Email Accounts
  /api/email-accounts/{id}/warmup:
    get:
      operationId: EmailAccountsController_warmupStats
      parameters:
      - name: id
        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 mailbox warm-up stats for an account
      tags:
      - Email Accounts
    patch:
      operationId: EmailAccountsController_warmupConfigure
      parameters:
      - name: id
        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: Configure mailbox warm-up parameters
      tags:
      - Email Accounts
  /api/email-accounts/{id}/suspend:
    post:
      operationId: EmailAccountsController_suspend
      parameters:
      - name: id
        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: Suspend an email account
      tags:
      - Email Accounts
  /api/email-accounts/{id}/unsuspend:
    post:
      operationId: EmailAccountsController_unsuspend
      parameters:
      - name: id
        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: Unsuspend an email account
      tags:
      - Email Accounts
  /api/email-accounts/{id}/work-status:
    patch:
      operationId: EmailAccountsController_updateWorkStatus
      parameters:
      - name: id
        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 work status (IDLE / IN_PROGRESS) of an account
      tags:
      - Email Accounts
  /api/email-accounts/{id}/gas/setup:
    post:
      operationId: EmailAccountsController_gasSetup
      parameters:
      - name: id
        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: Generate GAS setup instructions for the account
      tags:
      - Email Accounts
  /api/email-accounts/{id}/gas/verify:
    post:
      operationId: EmailAccountsController_gasVerify
      parameters:
      - name: id
        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: Verify a deployed GAS web app URL for the account
      tags:
      - Email Accounts
  /api/email-accounts/{id}/gas/ping:
    post:
      operationId: EmailAccountsController_gasPing
      parameters:
      - name: id
        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: Ping the GAS web app to verify connectivity
      tags:
      - Email Accounts
  /api/email-accounts/{id}/gas/test-send:
    post:
      operationId: EmailAccountsController_gasTestSend
      parameters:
      - name: id
        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: Send a test email via GAS
      tags:
      - Email Accounts
  /api/email-accounts/{id}/gas/test-fetch:
    post:
      operationId: EmailAccountsController_gasTestFetch
      parameters:
      - name: id
        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: Run a test fetch via GAS
      tags:
      - Email Accounts
  /api/email-accounts/{id}/gas/disable:
    patch:
      operationId: EmailAccountsController_gasDisable
      parameters:
      - name: id
        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: Disable GAS integration for an account
      tags:
      - Email Accounts
  /api/email-accounts/{id}/gas/labels:
    get:
      operationId: EmailAccountsController_gasLabels
      parameters:
      - name: id
        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 Gmail labels available via GAS
      tags:
      - Email Accounts
  /api/email-account-lists:
    get:
      operationId: EmailAccountsController_findAllLists
      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 email account lists
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:read
    post:
      operationId: EmailAccountsController_createList
      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: Create an email account list
      tags:
      - Email Accounts
      x-required-scope:
      - accounts:write
  /api/email-account-lists/{id}:
    patch:
      operationId: EmailAccountsController_updateList
      parameters:
      - name: id
        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 an email account list
      tags:
      - Email Accounts
    delete:
      operationId: EmailAccountsController_removeList
      parameters:
      - name: id
        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 an email account list
      tags:
      - Email Accounts
  /api/email-account-lists/{id}/relay-health:
    get:
      operationId: EmailAccountsController_relayHealth
      parameters:
      - name: id
        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: Relay pool health (#40) for an email-account-list / relay-pool id (not an…
      tags:
      - Email Accounts
components:
  schemas:
    ImportOauthDto:
      type: object
      properties:
        combo:
          type: string
        email:
          type: string
        password:
          type: string
        refreshToken:
          type: string
        clientId:
          type: string
        listId:
          type: string
    ImportOauthBulkDto:
      type: object
      properties:
        combos:
          type: array
          items:
            type: string
        listId:
          type: string
      required:
      - combos
    CreateEmailAccountDto:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        displayName:
          type: string
        signature:
          type: string
        notes:
          type: string
        smtpHost:
          type: string
        smtpPort:
          type: number
          minimum: 1
        smtpLogin:
          type: string
        smtpPassword:
          type: string
        smtpSsl:
          type: boolean
        imapHost:
          type: string
        imapPort:
          type: number
          minimum: 1
        imapLogin:
          type: string
        imapPassword:
          type: string
        imapSsl:
          type: boolean
        imapMode:
          type: string
        type:
          type: object
        service:
          type: object
        provider:
          type: string
          description: 'Lower-case provider key (`gmail`, `yandex`, `mailru`, `outlook`, ...).

            Not stored on EmailAccount — service normalizes it to {@link service}

            when `service` is not explicitly set.'
        status:
          type: string
        dailySendLimit:
          type: number
          minimum: 0
        hourlySendLimit:
          type: number
          minimum: 0
        minSendIntervalSeconds:
          type: number
          minimum: 0
        sendMethod:
          type: string
        fetchPriority:
          type: string
        webPassword:
          type: string
        isRelay:
          type: boolean
        oauthClientAlias:
          type: string
        folderId:
          type: string
        profileId:
          type: string
        profilePlatform:
          type: string
        listId:
          type: string
        _confirmDuplicate:
          type: boolean
      required:
      - email
  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.