asyncapi: 3.1.0
info:
  title: Mail Service Async Generic Command Contract
  version: 1.0.0
  description: |
    Stable contract for generic asynchronous delivery commands published by
    Notification Service to Mail Service through Redis Streams.
channels:
  deliveryCommands:
    address: mail:delivery_commands
    messages:
      renderedDeliveryCommand:
        $ref: '#/components/messages/RenderedDeliveryCommand'
      templateDeliveryCommand:
        $ref: '#/components/messages/TemplateDeliveryCommand'
operations:
  publishDeliveryCommand:
    action: send
    channel:
      $ref: '#/channels/deliveryCommands'
    messages:
      - $ref: '#/channels/deliveryCommands/messages/renderedDeliveryCommand'
      - $ref: '#/channels/deliveryCommands/messages/templateDeliveryCommand'
components:
  messages:
    RenderedDeliveryCommand:
      name: RenderedDeliveryCommand
      title: Rendered delivery command
      summary: Generic asynchronous delivery command with final rendered content.
      payload:
        $ref: '#/components/schemas/RenderedDeliveryCommandEnvelope'
      examples:
        - name: rendered
          summary: Rendered delivery command example.
          payload:
            delivery_id: mail-123
            source: notification
            payload_mode: rendered
            idempotency_key: notification:mail-123
            requested_at_ms: "1775121700000"
            request_id: req-123
            trace_id: trace-123
            payload_json: '{"to":["pilot@example.com"],"cc":[],"bcc":[],"reply_to":["noreply@example.com"],"subject":"Turn ready","text_body":"Turn 54 is ready.","html_body":"<p>Turn 54 is ready.</p>","attachments":[{"filename":"report.txt","content_type":"text/plain","content_base64":"cmVwb3J0"}]}'
    TemplateDeliveryCommand:
      name: TemplateDeliveryCommand
      title: Template delivery command
      summary: Generic asynchronous delivery command with template rendering data.
      payload:
        $ref: '#/components/schemas/TemplateDeliveryCommandEnvelope'
      examples:
        - name: template
          summary: Template delivery command example.
          payload:
            delivery_id: mail-124
            source: notification
            payload_mode: template
            idempotency_key: notification:mail-124
            requested_at_ms: "1775121700001"
            payload_json: '{"to":["pilot@example.com"],"cc":[],"bcc":[],"reply_to":[],"template_id":"game.turn_ready","locale":"fr-FR","variables":{"turn_number":54},"attachments":[]}'
  schemas:
    RenderedDeliveryCommandEnvelope:
      type: object
      additionalProperties: false
      required:
        - delivery_id
        - source
        - payload_mode
        - idempotency_key
        - requested_at_ms
        - payload_json
      properties:
        delivery_id:
          type: string
        source:
          type: string
          const: notification
        payload_mode:
          type: string
          const: rendered
        idempotency_key:
          type: string
        requested_at_ms:
          type: string
          pattern: '^[0-9]+$'
        request_id:
          type: string
        trace_id:
          type: string
        payload_json:
          type: string
          contentMediaType: application/json
          contentSchema:
            $ref: '#/components/schemas/RenderedPayloadJSON'
    TemplateDeliveryCommandEnvelope:
      type: object
      additionalProperties: false
      required:
        - delivery_id
        - source
        - payload_mode
        - idempotency_key
        - requested_at_ms
        - payload_json
      properties:
        delivery_id:
          type: string
        source:
          type: string
          const: notification
        payload_mode:
          type: string
          const: template
        idempotency_key:
          type: string
        requested_at_ms:
          type: string
          pattern: '^[0-9]+$'
        request_id:
          type: string
        trace_id:
          type: string
        payload_json:
          type: string
          contentMediaType: application/json
          contentSchema:
            $ref: '#/components/schemas/TemplatePayloadJSON'
    RenderedPayloadJSON:
      type: object
      additionalProperties: false
      required:
        - to
        - cc
        - bcc
        - reply_to
        - subject
        - text_body
        - attachments
      properties:
        to:
          $ref: '#/components/schemas/EmailList'
        cc:
          $ref: '#/components/schemas/EmailList'
        bcc:
          $ref: '#/components/schemas/EmailList'
        reply_to:
          $ref: '#/components/schemas/EmailList'
        subject:
          type: string
          minLength: 1
        text_body:
          type: string
          minLength: 1
        html_body:
          type: string
        attachments:
          $ref: '#/components/schemas/AttachmentList'
    TemplatePayloadJSON:
      type: object
      additionalProperties: false
      required:
        - to
        - cc
        - bcc
        - reply_to
        - template_id
        - locale
        - variables
        - attachments
      properties:
        to:
          $ref: '#/components/schemas/EmailList'
        cc:
          $ref: '#/components/schemas/EmailList'
        bcc:
          $ref: '#/components/schemas/EmailList'
        reply_to:
          $ref: '#/components/schemas/EmailList'
        template_id:
          type: string
          minLength: 1
        locale:
          type: string
          minLength: 1
        variables:
          type: object
          additionalProperties: true
        attachments:
          $ref: '#/components/schemas/AttachmentList'
    EmailList:
      type: array
      items:
        type: string
        format: email
    AttachmentList:
      type: array
      maxItems: 5
      items:
        $ref: '#/components/schemas/Attachment'
    Attachment:
      type: object
      additionalProperties: false
      required:
        - filename
        - content_type
        - content_base64
      properties:
        filename:
          type: string
          minLength: 1
        content_type:
          type: string
          minLength: 1
        content_base64:
          type: string
          description: Inline base64 payload. The sum of all attachment `content_base64` lengths must not exceed 2097152 bytes.