openapi: "3.0.3"
info:
  title: NEXARCH Mail API
  version: "1.0.0"
  description: >
    Mail-spezifische v1-Endpunkte für lesenden Zugriff auf archivierte
    Mails/Postfächer (INT-01). IAM-nahe Funktionen (Login,
    Tenant-Verwaltung) sind bewusst NICHT Teil dieser API — der
    Tenant-Kontext wird als bereits validierter Query-Parameter vom
    Aufrufer/Gateway mitgegeben.
servers:
  - url: /api/v1/mail
paths:
  /messages:
    get:
      summary: Mail-Liste
      operationId: listMessages
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - name: q
          in: query
          required: false
          description: Optionaler Volltext-Suchbegriff.
          schema:
            type: string
      responses:
        "200":
          description: Liste der Treffer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "502":
          $ref: "#/components/responses/UpstreamError"
  /messages/{messageID}:
    get:
      summary: Mail-Detail
      operationId: getMessage
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/MessageID"
      responses:
        "200":
          description: Vollständige Nachricht.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageDetail"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          $ref: "#/components/responses/UpstreamError"
  /messages/{messageID}/attachments/{index}:
    get:
      summary: Anhang-Download
      operationId: getAttachment
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/MessageID"
        - name: index
          in: path
          required: true
          description: Anhang-Index innerhalb der Nachricht (0-basiert).
          schema:
            type: integer
            minimum: 0
      responses:
        "200":
          description: Anhangsinhalt.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          $ref: "#/components/responses/UpstreamError"
components:
  parameters:
    Tenant:
      name: tenant
      in: query
      required: true
      description: >
        Mandanten-Kennung (bereits validiert vom Aufrufer/Gateway —
        keine Anmeldung/Sitzungsprüfung Bestandteil dieser API).
      schema:
        type: string
        minLength: 1
    MessageID:
      name: messageID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
  schemas:
    MessageListItem:
      type: object
      required: [messageId, subject, sentAt]
      properties:
        messageId:
          type: string
        subject:
          type: string
        sentAt:
          type: integer
          format: int64
    MessageListResponse:
      type: object
      required: [messages]
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/MessageListItem"
    MessageDetail:
      type: object
      required: [messageId, subject, body, sender, mailbox, sentAt]
      properties:
        messageId:
          type: string
        subject:
          type: string
        body:
          type: string
        sender:
          type: string
        mailbox:
          type: string
        sentAt:
          type: integer
          format: int64
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
  responses:
    BadRequest:
      description: Ungültige oder fehlende Anfrageparameter (u. a. fehlender Tenant-Kontext).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Nachricht oder Anhang für diesen Mandanten nicht gefunden.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UpstreamError:
      description: Ein nachgelagerter Dienst (Suchindex/Objektspeicher) hat einen Fehler geliefert.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"