components:
  schemas:
    AIStatusResponse:
      additionalProperties: false
      properties:
        aiError:
          type: string
        aiInsight:
          type:
            - string
            - "null"
        aiRetryCount:
          format: int64
          type: integer
        aiStatus:
          type: string
        mailId:
          type: string
      required:
        - mailId
        - aiStatus
        - aiInsight
        - aiRetryCount
      type: object
    AttachmentSummaryResponse:
      additionalProperties: false
      properties:
        contentType:
          type: string
        filename:
          type: string
        id:
          type: string
        sizeBytes:
          format: int64
          type: integer
      required:
        - id
        - filename
        - contentType
        - sizeBytes
      type: object
    AuditEventResponse:
      additionalProperties: false
      properties:
        action:
          examples:
            - VIEW_MAIL
          type: string
        actorSubject:
          examples:
            - jota
          type: string
        id:
          examples:
            - a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
        mailId:
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        tenantId:
          examples:
            - c7aab4e8-1234-5678-9abc-def012345678
          type: string
        timestamp:
          examples:
            - "2026-03-28T10:35:00Z"
          type: string
        userId:
          examples:
            - d4e5f6a7-b8c9-0123-4567-890abcdef012
          type: string
      required:
        - id
        - tenantId
        - action
        - timestamp
      type: object
    AuditListResponse:
      additionalProperties: false
      properties:
        hasMore:
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/AuditEventResponse"
          type: array
        nextCursor:
          type:
            - string
            - "null"
      required:
        - items
        - nextCursor
        - hasMore
      type: object
    CategoryStatResponse:
      additionalProperties: false
      properties:
        category:
          type: string
        timeline:
          items:
            $ref: "#/components/schemas/TimelinePointResponse"
          type: array
        total:
          format: int64
          type: integer
      required:
        - category
        - total
        - timeline
      type: object
    CountMailsResponse:
      additionalProperties: false
      properties:
        computedAt:
          type: string
        count:
          format: int64
          type: integer
      required:
        - count
        - computedAt
      type: object
    CreateSettingsRequestBody:
      additionalProperties: true
      properties:
        aiApiKey:
          description: AI provider API key (encrypted at rest). At most 500 characters.
          maxLength: 500
          type: string
        aiEndpoint:
          description: AI API endpoint URL, at most 500 characters. Must be HTTPS and must not resolve to a private or loopback address; "" clears it. Those two rules need DNS, so the service applies them and answers 400 BCC-0001.
          maxLength: 500
          type: string
        aiModel:
          description: AI model identifier. At most 100 characters.
          examples:
            - gpt-4o-mini
          maxLength: 100
          type: string
        aiProvider:
          description: AI provider. One of openai, anthropic, gemini, or "" to clear it (AI not configured). Brand names such as ChatGPT are refused.
          enum:
            - openai
            - anthropic
            - gemini
            - ""
          examples:
            - openai
          type: string
        aiSystemPrompt:
          description: Per-tenant AI system prompt. At most 2000 characters.
          maxLength: 2000
          type: string
        bcbPassword:
          description: BCB Sisbacen password (encrypted at rest). At most 255 characters.
          maxLength: 255
          type: string
        bcbUsername:
          description: BCB Sisbacen username (encrypted at rest). At most 255 characters.
          maxLength: 255
          type: string
        defaultDestination:
          description: Default BCB destination code. At most 50 characters.
          examples:
            - DEINF
          maxLength: 50
          type: string
        pollingIntervalMinutes:
          description: BCB polling interval in minutes.
          enum:
            - 5
            - 15
            - 30
            - 60
          examples:
            - 15
          format: int64
          type: integer
        retentionDays:
          description: Mail retention in days (min 1825 = 5y, max 36500 = 100y).
          examples:
            - 1825
          format: int64
          maximum: 36500
          minimum: 1825
          type: integer
      type: object
    DashboardCategoriesResponse:
      additionalProperties: false
      properties:
        categories:
          items:
            $ref: "#/components/schemas/CategoryStatResponse"
          type: array
        period:
          $ref: "#/components/schemas/DateRangeResponse"
        tenantId:
          type: string
      required:
        - tenantId
        - categories
        - period
      type: object
    DashboardSummaryResponse:
      additionalProperties: false
      properties:
        avgTimeToReadMinutes:
          format: double
          type:
            - number
            - "null"
        bySender:
          items:
            $ref: "#/components/schemas/SenderCountResponse"
          type: array
        period:
          $ref: "#/components/schemas/DateRangeResponse"
        tenantId:
          type: string
        totalReceived:
          format: int64
          type: integer
        totalUnread:
          format: int64
          type: integer
        unreadOlderThan15Days:
          format: int64
          type: integer
        unreadOlderThan3Days:
          format: int64
          type: integer
        unreadOlderThan7Days:
          format: int64
          type: integer
      required:
        - tenantId
        - totalReceived
        - totalUnread
        - avgTimeToReadMinutes
        - unreadOlderThan3Days
        - unreadOlderThan7Days
        - unreadOlderThan15Days
        - bySender
        - period
      type: object
    DateRangeResponse:
      additionalProperties: false
      properties:
        end:
          type: string
        start:
          type: string
      required:
        - start
        - end
      type: object
    Detail:
      additionalProperties: false
      properties:
        code:
          description: "Stable, machine-readable domain error code scoped to the emitting service (format: <SERVICE>-NNNN)."
          type: string
        correlationId:
          description: Request-scoped correlation identifier echoing X-Request-ID.
          examples:
            - req-7a3f9c2e
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: "#/components/schemas/ErrorDetail"
          type:
            - array
            - "null"
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
        upstream:
          $ref: "#/components/schemas/Upstream"
          description: "RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one."
      required:
        - correlationId
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    MailDetailResponse:
      additionalProperties: false
      properties:
        aiError:
          type: string
        aiInsight:
          examples:
            - Resolução altera normas de câmbio para exportações acima de USD 50k.
          type:
            - string
            - "null"
        attachments:
          items:
            $ref: "#/components/schemas/AttachmentSummaryResponse"
          type: array
        bcbConfirmationId:
          examples:
            - "20260404123456789"
          type:
            - string
            - "null"
        bcbMessageId:
          examples:
            - BCB-MSG-2026-003456
          type: string
        body:
          examples:
            - <p>Prezados, informamos que...</p>
          type: string
        contentType:
          examples:
            - text/html
          type: string
        createdAt:
          examples:
            - "2026-03-28T10:31:05Z"
          type: string
        destination:
          examples:
            - DEINF
          type:
            - string
            - "null"
        folder:
          examples:
            - INBOX
          type: string
        id:
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        isRead:
          examples:
            - true
          type: boolean
        metadata:
          additionalProperties: {}
          type: object
        readAt:
          examples:
            - "2026-03-28T11:00:00Z"
          type:
            - string
            - "null"
        receivedAt:
          examples:
            - "2026-03-28T10:30:00Z"
          type: string
        sendStatus:
          examples:
            - CONFIRMED
          type:
            - string
            - "null"
        sender:
          examples:
            - BACEN/DENOR
          type: string
        sentAt:
          examples:
            - "2026-03-28T10:31:05Z"
          type:
            - string
            - "null"
        subject:
          examples:
            - Resolução BCB nº 400 - Alteração de normas cambiais
          type: string
        tenantId:
          examples:
            - c7aab4e8-1234-5678-9abc-def012345678
          type: string
        type:
          examples:
            - RESOLUTION
          type: string
        updatedAt:
          examples:
            - "2026-03-28T14:22:00Z"
          type: string
      required:
        - id
        - tenantId
        - bcbMessageId
        - folder
        - type
        - subject
        - body
        - contentType
        - aiInsight
        - sender
        - receivedAt
        - createdAt
        - updatedAt
        - attachments
        - isRead
        - readAt
        - sendStatus
        - bcbConfirmationId
        - sentAt
        - destination
      type: object
    MailListResponse:
      additionalProperties: false
      properties:
        hasMore:
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/MailSummaryResponse"
          type: array
        nextCursor:
          type:
            - string
            - "null"
      required:
        - items
        - nextCursor
        - hasMore
      type: object
    MailSummaryResponse:
      additionalProperties: false
      properties:
        destination:
          examples:
            - DEINF
          type:
            - string
            - "null"
        folder:
          examples:
            - INBOX
          type: string
        hasAttachments:
          examples:
            - true
          type: boolean
        id:
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        isRead:
          examples:
            - false
          type: boolean
        receivedAt:
          examples:
            - "2026-03-28T10:30:00Z"
          type: string
        sendStatus:
          examples:
            - CONFIRMED
          type:
            - string
            - "null"
        sender:
          examples:
            - BACEN/DENOR
          type: string
        subject:
          examples:
            - Comunicado BACEN - Resolução 4.966
          type: string
        type:
          examples:
            - COMMUNICATION
          type: string
      required:
        - id
        - subject
        - sender
        - receivedAt
        - folder
        - type
        - hasAttachments
        - isRead
        - sendStatus
        - destination
      type: object
    MarkAsReadResponse:
      additionalProperties: false
      properties:
        isRead:
          type: boolean
        mailId:
          type: string
        readAt:
          type:
            - string
            - "null"
      required:
        - mailId
        - isRead
        - readAt
      type: object
    ReanalyzeAIResponse:
      additionalProperties: false
      properties:
        aiInsight:
          type: string
        aiStatus:
          type: string
        mailId:
          type: string
        message:
          type: string
      required:
        - mailId
        - aiStatus
        - message
      type: object
    RetentionPolicyResponse:
      additionalProperties: false
      properties:
        effectiveDate:
          type: string
        retentionDays:
          format: int64
          type: integer
        tenantId:
          type: string
        updatedAt:
          type: string
        updatedBy:
          type: string
      required:
        - tenantId
        - retentionDays
        - effectiveDate
        - updatedBy
        - updatedAt
      type: object
    SendMessageRequestBody:
      additionalProperties: true
      properties:
        body:
          description: Message body. Non-blank, at most 102400 bytes.
          examples:
            - Prezados, gostaríamos de esclarecer...
          maxLength: 102400
          minLength: 1
          type: string
        destination:
          description: BCB destination code override (e.g. DEINF). At most 50 characters.
          examples:
            - DEINF
          maxLength: 50
          type: string
        inReplyToMailId:
          description: "Optional UUID of a received mail being replied to. Omit the key when not replying: an empty string is not a UUID and is refused."
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        keywords:
          description: "Optional PalavrasChave list: at most 10 entries, each at most 100 characters."
          examples:
            -   - regulacao
                - cambio
          items:
            maxLength: 100
            type: string
          maxItems: 10
          type:
            - array
            - "null"
        subject:
          description: Message subject. Non-blank, at most 500 bytes.
          examples:
            - Consulta sobre Resolução 4.966
          maxLength: 500
          minLength: 1
          type: string
      type: object
    SendMessageResponse:
      additionalProperties: false
      properties:
        bcbConfirmationId:
          examples:
            - BCB-2026-0311-001234
          type:
            - string
            - "null"
        idempotencyKey:
          examples:
            - send-msg-2026-03-30-001
          type: string
        messageId:
          examples:
            - a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
        sentAt:
          examples:
            - "2026-03-30T14:00:00Z"
          type: string
        status:
          examples:
            - CONFIRMED
          type: string
      required:
        - messageId
        - bcbConfirmationId
        - sentAt
        - status
        - idempotencyKey
      type: object
    SenderCountResponse:
      additionalProperties: false
      properties:
        count:
          format: int64
          type: integer
        sender:
          type: string
      required:
        - sender
        - count
      type: object
    TenantSettingsResponse:
      additionalProperties: false
      properties:
        aiEndpoint:
          type: string
        aiModel:
          type: string
        aiProvider:
          type: string
        aiSystemPrompt:
          type: string
        defaultDestination:
          examples:
            - DEINF
          type: string
        hasAiApiKey:
          type: boolean
        hasBcbCredentials:
          type: boolean
        pollingIntervalMinutes:
          examples:
            - 15
          format: int64
          type: integer
        retentionDays:
          examples:
            - 1825
          format: int64
          type: integer
        tenantId:
          examples:
            - c7aab4e8-1234-5678-9abc-def012345678
          type: string
        updatedAt:
          type: string
      required:
        - tenantId
        - pollingIntervalMinutes
        - retentionDays
        - hasBcbCredentials
        - hasAiApiKey
        - updatedAt
      type: object
    TestAIConnectionResponse:
      additionalProperties: false
      properties:
        latencyMs:
          examples:
            - 423
          format: int64
          type: integer
        message:
          examples:
            - "AI provider rejected the probe: 401 Unauthorized"
          type: string
        model:
          examples:
            - gpt-4o-mini
          type: string
        provider:
          examples:
            - openai
          type: string
        status:
          examples:
            - ok
          type: string
        testedAt:
          type: string
      required:
        - status
        - latencyMs
        - testedAt
      type: object
    TestConnectionResponse:
      additionalProperties: false
      properties:
        authorizedFolders:
          items:
            type: string
          type:
            - array
            - "null"
        isConnected:
          type: boolean
        message:
          type: string
        testedAt:
          type: string
      required:
        - isConnected
        - message
        - testedAt
      type: object
    TimelinePointResponse:
      additionalProperties: false
      properties:
        count:
          format: int64
          type: integer
        date:
          type: string
      required:
        - date
        - count
      type: object
    UpdateRetentionRequestBody:
      additionalProperties: true
      properties:
        retentionDays:
          description: New retention period in days (min 1825 = 5y, max 36500 = 100y).
          examples:
            - 1825
          format: int64
          maximum: 36500
          minimum: 1825
          type: integer
      type: object
    UpdateSettingsRequestBody:
      additionalProperties: true
      properties:
        aiApiKey:
          description: AI provider API key, at most 500 characters (send "" to clear).
          maxLength: 500
          type: string
        aiEndpoint:
          description: AI API endpoint URL, at most 500 characters. Must be HTTPS and must not resolve to a private or loopback address; "" clears it. Those two rules need DNS, so the service applies them and answers 400 BCC-0001.
          maxLength: 500
          type: string
        aiModel:
          description: AI model identifier. At most 100 characters.
          examples:
            - gpt-4o-mini
          maxLength: 100
          type: string
        aiProvider:
          description: AI provider. One of openai, anthropic, gemini, or "" to clear it (AI not configured). Brand names such as ChatGPT are refused.
          enum:
            - openai
            - anthropic
            - gemini
            - ""
          examples:
            - openai
          type: string
        aiSystemPrompt:
          description: Per-tenant AI system prompt. At most 2000 characters.
          maxLength: 2000
          type: string
        bcbPassword:
          description: BCB Sisbacen password, at most 255 characters (send "" to clear).
          maxLength: 255
          type: string
        bcbUsername:
          description: BCB Sisbacen username, at most 255 characters (send "" to clear).
          maxLength: 255
          type: string
        defaultDestination:
          description: Default BCB destination code. At most 50 characters.
          examples:
            - DEINF
          maxLength: 50
          type: string
        pollingIntervalMinutes:
          description: BCB polling interval in minutes.
          enum:
            - 5
            - 15
            - 30
            - 60
          examples:
            - 15
          format: int64
          type: integer
        retentionDays:
          description: Mail retention in days (min 1825 = 5y, max 36500 = 100y).
          examples:
            - 1825
          format: int64
          maximum: 36500
          minimum: 1825
          type: integer
      type: object
    Upstream:
      additionalProperties: false
      properties:
        code:
          description: The upstream provider's own error code, verbatim.
          examples:
            - E4001
          type: string
        message:
          description: The upstream provider's own error message, verbatim (bounded, never its raw response body).
          examples:
            - account not found at provider
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: JWT bearer token issued by the identity provider.
      scheme: bearer
      type: http
info:
  description: API for Lerian BC Correios, which connects the institution to BC Correio, Banco Central do Brasil's electronic correspondence system. It retrieves and stores the institution's BC Correio mail, sends messages to BACEN departments, and keeps an audit trail.
  title: Lerian BC Correios API
  version: 1.0.0
openapi: 3.1.0
paths:
  /api/v1/correios/audit:
    get:
      description: Returns paginated audit events for the tenant. Audit queries are not themselves logged.
      operationId: QueryAuditTrail
      parameters:
        - description: Filter by mail ID (UUID v4)
          explode: false
          in: query
          name: mailId
          schema:
            description: Filter by mail ID (UUID v4)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            type: string
        - description: Filter by user ID (UUID v4)
          explode: false
          in: query
          name: userId
          schema:
            description: Filter by user ID (UUID v4)
            type: string
        - description: Filter by action type (VIEW_MAIL, DOWNLOAD_ATTACHMENT, SEND_MESSAGE, MAIL_ARCHIVED, MAIL_RESTORED, MAIL_READ, SETTINGS_UPDATED, RETENTION_POLICY_APPLIED)
          explode: false
          in: query
          name: action
          schema:
            description: Filter by action type (VIEW_MAIL, DOWNLOAD_ATTACHMENT, SEND_MESSAGE, MAIL_ARCHIVED, MAIL_RESTORED, MAIL_READ, SETTINGS_UPDATED, RETENTION_POLICY_APPLIED)
            examples:
              - VIEW_MAIL
            type: string
        - description: Events from this date (ISO 8601 / RFC 3339)
          explode: false
          in: query
          name: startDate
          schema:
            description: Events from this date (ISO 8601 / RFC 3339)
            type: string
        - description: Events up to this date (ISO 8601 / RFC 3339)
          explode: false
          in: query
          name: endDate
          schema:
            description: Events up to this date (ISO 8601 / RFC 3339)
            type: string
        - description: Pagination cursor (opaque)
          explode: false
          in: query
          name: cursor
          schema:
            description: Pagination cursor (opaque)
            type: string
        - description: Results per page (default 20, max 100)
          explode: false
          in: query
          name: limit
          schema:
            description: Results per page (default 20, max 100)
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditListResponse"
          description: OK
          headers:
            Cache-Control:
              schema:
                description: Always no-store — the trail carries operator identities
                type: string
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Query audit trail
      tags:
        - Audit
      x-mint:
        href: /pt/reference/rails/bc-correios/query-audit-trail
  /api/v1/correios/audit/export:
    get:
      description: Generates an audit-trail report file for the given date range. The response is a file download (text/csv by default, or application/pdf when the Accept header requests it), not JSON.
      operationId: ExportAuditTrail
      parameters:
        - description: Export start date (ISO 8601 / RFC 3339, required — enforced by the handler)
          explode: false
          in: query
          name: startDate
          schema:
            description: Export start date (ISO 8601 / RFC 3339, required — enforced by the handler)
            type: string
          required: true
        - description: Export end date (ISO 8601 / RFC 3339, required — enforced by the handler)
          explode: false
          in: query
          name: endDate
          schema:
            description: Export end date (ISO 8601 / RFC 3339, required — enforced by the handler)
            type: string
          required: true
      responses:
        "200":
          content:
            application/pdf:
              schema:
                contentMediaType: application/octet-stream
                format: binary
                type: string
            text/csv:
              schema:
                contentMediaType: application/octet-stream
                format: binary
                type: string
          description: "Audit-trail export file: text/csv (default) or application/pdf, selected by the Accept header."
          headers:
            Cache-Control:
              schema:
                description: Always no-store — the export file carries operator identities
                type: string
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Export audit trail
      tags:
        - Audit
      x-mint:
        href: /pt/reference/rails/bc-correios/export-audit-trail
  /api/v1/correios/dashboard/categories:
    get:
      description: Returns per-category mail counts with a day or month timeline for the tenant.
      operationId: GetDashboardCategories
      parameters:
        - description: Period start (ISO 8601 / RFC 3339). Defaults to 30 days ago.
          explode: false
          in: query
          name: startDate
          schema:
            description: Period start (ISO 8601 / RFC 3339). Defaults to 30 days ago.
            type: string
        - description: Period end (ISO 8601 / RFC 3339). Defaults to now.
          explode: false
          in: query
          name: endDate
          schema:
            description: Period end (ISO 8601 / RFC 3339). Defaults to now.
            type: string
        - description: "Timeline granularity: 'day' (default) or 'month'."
          explode: false
          in: query
          name: granularity
          schema:
            description: "Timeline granularity: 'day' (default) or 'month'."
            examples:
              - day
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DashboardCategoriesResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Dashboard category breakdown
      tags:
        - Dashboard
      x-mint:
        href: /pt/reference/rails/bc-correios/dashboard-category-breakdown
  /api/v1/correios/dashboard/summary:
    get:
      description: "Returns aggregate metrics for the tenant: total received, unread, avg time to read, unread >3/7/15 days, and breakdown by sender. All counts are scoped to the given period (defaults to the last 30 days)."
      operationId: GetDashboardSummary
      parameters:
        - description: Period start (ISO 8601 / RFC 3339, e.g. 2026-01-01T00:00:00Z). Defaults to 30 days ago.
          explode: false
          in: query
          name: startDate
          schema:
            description: Period start (ISO 8601 / RFC 3339, e.g. 2026-01-01T00:00:00Z). Defaults to 30 days ago.
            examples:
              - "2026-01-01T00:00:00Z"
            type: string
        - description: Period end (ISO 8601 / RFC 3339, e.g. 2026-03-31T23:59:59Z). Defaults to now.
          explode: false
          in: query
          name: endDate
          schema:
            description: Period end (ISO 8601 / RFC 3339, e.g. 2026-03-31T23:59:59Z). Defaults to now.
            examples:
              - "2026-03-31T23:59:59Z"
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DashboardSummaryResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Dashboard summary
      tags:
        - Dashboard
      x-mint:
        href: /pt/reference/rails/bc-correios/dashboard-summary
  /api/v1/correios/mails:
    get:
      description: Returns mails for a tenant. Pass 'folder' to browse a folder or 'query' to full-text search.
      operationId: ListOrSearchMails
      parameters:
        - description: Folder filter (INBOX, SENT, ARCHIVED, CANCELLED)
          explode: false
          in: query
          name: folder
          schema:
            description: Folder filter (INBOX, SENT, ARCHIVED, CANCELLED)
            examples:
              - INBOX
            type: string
        - description: Full-text search keyword
          explode: false
          in: query
          name: query
          schema:
            description: Full-text search keyword
            type: string
        - description: Mail type filter (RESOLUTION, CIRCULAR, COMMUNICATION, OTHER)
          explode: false
          in: query
          name: type
          schema:
            description: Mail type filter (RESOLUTION, CIRCULAR, COMMUNICATION, OTHER)
            type: string
        - description: Read status filter (true=read, false=unread)
          explode: false
          in: query
          name: isRead
          schema:
            description: Read status filter (true=read, false=unread)
            type: string
        - description: Filter mails received after this date (ISO 8601)
          explode: false
          in: query
          name: receivedAfter
          schema:
            description: Filter mails received after this date (ISO 8601)
            type: string
        - description: Filter mails received before this date (ISO 8601)
          explode: false
          in: query
          name: receivedBefore
          schema:
            description: Filter mails received before this date (ISO 8601)
            type: string
        - description: AI analysis status filter (none, pending, completed, failed)
          explode: false
          in: query
          name: aiStatus
          schema:
            description: AI analysis status filter (none, pending, completed, failed)
            type: string
        - description: Pagination cursor (opaque)
          explode: false
          in: query
          name: cursor
          schema:
            description: Pagination cursor (opaque)
            type: string
        - description: Results per page (default 20, max 100)
          explode: false
          in: query
          name: limit
          schema:
            description: Results per page (default 20, max 100)
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MailListResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: List or search mails
      tags:
        - Mails
      x-mint:
        href: /pt/reference/rails/bc-correios/list-or-search-mails
  /api/v1/correios/mails/count:
    get:
      description: Returns the total count of mails matching the given filters. May be cached for up to 60 seconds.
      operationId: CountMails
      parameters:
        - description: Folder filter
          explode: false
          in: query
          name: folder
          schema:
            description: Folder filter
            type: string
        - description: Mail type filter
          explode: false
          in: query
          name: type
          schema:
            description: Mail type filter
            type: string
        - description: Read status filter (true=read, false=unread)
          explode: false
          in: query
          name: isRead
          schema:
            description: Read status filter (true=read, false=unread)
            type: string
        - description: After date (ISO 8601)
          explode: false
          in: query
          name: receivedAfter
          schema:
            description: After date (ISO 8601)
            type: string
        - description: Before date (ISO 8601)
          explode: false
          in: query
          name: receivedBefore
          schema:
            description: Before date (ISO 8601)
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CountMailsResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Count mails
      tags:
        - Mails
      x-mint:
        href: /pt/reference/rails/bc-correios/count-mails
  /api/v1/correios/mails/send:
    post:
      description: Sends a message to BCB through BC Correio. Requires the X-Idempotency header for safe retries.
      operationId: SendMessage
      parameters:
        - description: Idempotency key for safe retries
          in: header
          name: X-Idempotency
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendMessageRequestBody"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendMessageResponse"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Conflict
        "413":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Request Entity Too Large
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Send message to BCB
      tags:
        - Mails
      x-mint:
        href: /pt/reference/rails/bc-correios/send-message-to-bcb
  /api/v1/correios/mails/{id}:
    get:
      description: Retrieves the full content of a mail including body and attachment list. Emits a VIEW_MAIL audit event.
      operationId: GetMail
      parameters:
        - description: Mail ID (UUID v4)
          in: path
          name: id
          required: true
          schema:
            description: Mail ID (UUID v4)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MailDetailResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Get mail by ID
      tags:
        - Mails
      x-mint:
        href: /pt/reference/rails/bc-correios/get-mail-by-id
  /api/v1/correios/mails/{id}/ai-status:
    get:
      description: Returns the current AI analysis status, insight, and retry count for a mail.
      operationId: GetAIStatus
      parameters:
        - description: Mail ID (UUID v4)
          in: path
          name: id
          required: true
          schema:
            description: Mail ID (UUID v4)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AIStatusResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
      security:
        - BearerAuth: []
      summary: Get AI analysis status
      tags:
        - Mails
      x-mint:
        href: /pt/reference/rails/bc-correios/get-ai-analysis-status
  /api/v1/correios/mails/{id}/archive:
    put:
      description: Moves a mail to the ARCHIVED folder. Local-only action; idempotent (returns 204).
      operationId: ArchiveMail
      parameters:
        - description: Mail ID (UUID v4)
          in: path
          name: id
          required: true
          schema:
            description: Mail ID (UUID v4)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            type: string
        - description: Idempotency key to dedup folder transitions
          in: header
          name: X-Idempotency
          schema:
            description: Idempotency key to dedup folder transitions
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Archive mail
      tags:
        - Mails
      x-mint:
        href: /pt/reference/rails/bc-correios/archive-mail
  /api/v1/correios/mails/{id}/attachments/{attachmentId}:
    get:
      description: Streams an attachment file (application/octet-stream). Emits a DOWNLOAD_ATTACHMENT audit event.
      operationId: GetAttachment
      parameters:
        - description: Mail ID (UUID v4)
          in: path
          name: id
          required: true
          schema:
            description: Mail ID (UUID v4)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            type: string
        - description: Attachment ID (UUID v4)
          in: path
          name: attachmentId
          required: true
          schema:
            description: Attachment ID (UUID v4)
            examples:
              - 660e8400-e29b-41d4-a716-446655440111
            type: string
      responses:
        "200":
          content:
            application/octet-stream:
              schema:
                contentMediaType: application/octet-stream
                format: binary
                type: string
          description: "Attachment bytes, streamed with the stored MIME type and a Content-Disposition: attachment header."
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Download attachment
      tags:
        - Mails
      x-mint:
        href: /pt/reference/rails/bc-correios/download-attachment
  /api/v1/correios/mails/{id}/read:
    put:
      description: Idempotently marks a mail as read. If already read, returns 200 with current state.
      operationId: MarkAsRead
      parameters:
        - description: Mail ID (UUID v4)
          in: path
          name: id
          required: true
          schema:
            description: Mail ID (UUID v4)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarkAsReadResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Mark mail as read
      tags:
        - Mails
      x-mint:
        href: /pt/reference/rails/bc-correios/mark-mail-as-read
  /api/v1/correios/mails/{id}/reanalyze:
    post:
      description: Executes a fresh AI analysis synchronously when the provider responds within 20s (200 with the insight); 202 pending when the provider exceeds the sync window. 422 BCC-3004 when the tenant has no AI configuration, 422 BCC-3005 when the mail has no content. Supports X-Idempotency for safe retries.
      operationId: ReanalyzeAI
      parameters:
        - description: Idempotency key for safe retries
          in: header
          name: X-Idempotency
          required: true
          schema:
            type: string
        - description: Mail ID (UUID v4)
          in: path
          name: id
          required: true
          schema:
            description: Mail ID (UUID v4)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReanalyzeAIResponse"
          description: OK
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReanalyzeAIResponse"
          description: Accepted — AI analysis is pending (provider exceeded the sync window). Poll GET /mails/{id}/ai-status.
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "502":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Gateway
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Trigger AI re-analysis
      tags:
        - Mails
      x-mint:
        href: /pt/reference/rails/bc-correios/trigger-ai-re-analysis
  /api/v1/correios/mails/{id}/restore:
    put:
      description: Moves a mail back to INBOX from ARCHIVED. Local-only; 409 BCC-0014 for CANCELLED or SENT mails.
      operationId: RestoreMail
      parameters:
        - description: Mail ID (UUID v4)
          in: path
          name: id
          required: true
          schema:
            description: Mail ID (UUID v4)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            type: string
        - description: Idempotency key to dedup folder transitions
          in: header
          name: X-Idempotency
          schema:
            description: Idempotency key to dedup folder transitions
            type: string
      responses:
        "204":
          description: No Content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Restore mail
      tags:
        - Mails
      x-mint:
        href: /pt/reference/rails/bc-correios/restore-mail
  /api/v1/correios/settings:
    get:
      description: Returns the current settings for the authenticated tenant. Sensitive credential fields are represented as boolean flags.
      operationId: GetSettings
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantSettingsResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Get tenant settings
      tags:
        - Settings
      x-mint:
        href: /pt/reference/rails/bc-correios/get-tenant-settings
    patch:
      description: Partially updates tenant settings. Only provided fields are updated; send an empty string to clear an encrypted credential field.
      operationId: UpdateSettings
      parameters:
        - description: Idempotency key for safe retries
          in: header
          name: X-Idempotency
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSettingsRequestBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantSettingsResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Update tenant settings
      tags:
        - Settings
      x-mint:
        href: /pt/reference/rails/bc-correios/update-tenant-settings
    post:
      description: Creates initial tenant settings. Returns 409 Conflict (BCC-0006) if settings already exist — use PATCH to update.
      operationId: CreateSettings
      parameters:
        - description: Idempotency key for safe retries
          in: header
          name: X-Idempotency
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSettingsRequestBody"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantSettingsResponse"
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Create tenant settings
      tags:
        - Settings
      x-mint:
        href: /pt/reference/rails/bc-correios/create-tenant-settings
  /api/v1/correios/settings/retention:
    patch:
      description: Updates the mail retention period in days. Minimum 1825 (5 years), maximum 36500 (100 years).
      operationId: UpdateRetentionPolicy
      parameters:
        - description: Idempotency key for safe retries
          in: header
          name: X-Idempotency
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRetentionRequestBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetentionPolicyResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Update retention policy
      tags:
        - Settings
      x-mint:
        href: /pt/reference/rails/bc-correios/update-retention-policy
  /api/v1/correios/settings/test-ai-connection:
    post:
      description: Issues a synchronous probe to the tenant's configured AI provider using the stored API key. 200 with status="ok" + latency on success; 200 with status="failed" + the redacted reason when the probe reaches the provider but is rejected. 400 when the provider is not configured, 404 when settings are absent, 500 on decrypt failure, 503 when AI is disabled.
      operationId: TestAIConnection
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestAIConnectionResponse"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Not Found
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Test AI provider connection
      tags:
        - Settings
      x-mint:
        href: /pt/reference/rails/bc-correios/test-ai-provider-connection
  /api/v1/correios/settings/test-connection:
    post:
      description: Decrypts the stored BCB credentials and asks BC Correio for the authorized folders to verify connectivity. Returns the list of authorized folders on success.
      operationId: TestBCBConnection
      parameters:
        - description: Idempotency key for safe retries
          in: header
          name: X-Idempotency
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestConnectionResponse"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unauthorized
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Unprocessable Entity
        "429":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
          description: Service Unavailable
      security:
        - BearerAuth: []
      summary: Test BCB connection
      tags:
        - Settings
      x-mint:
        href: /pt/reference/rails/bc-correios/test-bcb-connection
security:
  - BearerAuth: []
servers:
  - url: https://api.example.com
    description: Replace the example host with the URL provided during environment onboarding.
tags:
  - description: Mail listing, search, read, send, and lifecycle operations.
    name: Mails
  - description: Immutable audit-trail query and export.
    name: Audit
  - description: "Per-tenant configuration: BCB credentials, polling, AI, retention."
    name: Settings
  - description: Aggregate mail metrics and category breakdowns.
    name: Dashboard