email-components.yml

openapi: 3.0.4
info:
  title: Email API Components
  version: 0.1.0
  description: Entity schemas, request payloads, and path parameters for the Email API.
paths: {}
components:
  parameters:
    AccountId:
      name: accountId
      in: path
      required: true
      description: Identifies the tenant-scoped account configuration to use. The well-known value `default` selects the tenant's default account.
      schema:
        type: string
        example: default

  schemas:
    EmailAddress:
      type: object
      description: An email participant. A bare address, optionally with a display name.
      required: [address]
      properties:
        address:
          type: string
          format: email
          description: RFC 5322 mailbox address.
          example: alice@example.com
        name:
          type: string
          nullable: true
          description: Optional display name shown alongside the address.
          example: Alice Smith

    EmailStatus:
      type: object
      description: >-
        Configuration and health of the email service for the calling tenant. The endpoint always
        responds `200`; `configured` and `healthy` report whether a usable account is available
        rather than being signalled through the HTTP status.
      required: [configured, healthy]
      properties:
        configured:
          type: boolean
          description: True when the tenant has at least one usable account configuration.
        healthy:
          type: boolean
          description: True when the service can reach its transport. Tracks `configured` for the SMTP transport.
        defaultAccountId:
          type: string
          default: default
          description: The account id used when a request omits `accountId`.
        lastError:
          type: string
          nullable: true
          description: The most recent configuration or connectivity error, when one is known.

    EmailDelivery:
      type: object
      description: >-
        Outcome of an accepted send. Returned with `202`; a send that the transport rejects is
        reported as an error response, not as a `FAILED` body.
      required: [status]
      properties:
        deliveryId:
          type: string
          nullable: true
          description: Service-assigned id for the accepted message. Mirrors the provider message id for the SMTP transport.
        providerMessageId:
          type: string
          nullable: true
          description: The transport-assigned message id, such as the SMTP `Message-ID`.
        transportId:
          type: string
          nullable: true
          description: The id of the transport that delivered the message, for example `smtp`.
        status:
          type: string
          enum: [SENT, FAILED, PENDING]
          default: SENT
          description: Delivery state. Accepted sends report `SENT`.

    SmtpAccountFields:
      type: object
      description: >-
        SMTP transport settings on an account write. `password` is write-only: it is handed to the
        configured secret backend and never returned. The persisted reference is surfaced on reads
        as `passwordSecretRef`.
      required: [host, port]
      properties:
        host:
          type: string
          description: SMTP server hostname.
          example: smtp.example.com
        port:
          type: integer
          description: SMTP server port.
          example: 587
        username:
          type: string
          nullable: true
          description: SMTP authentication username.
        password:
          type: string
          writeOnly: true
          nullable: true
          description: >-
            Plaintext SMTP password. Accepted only on writes and never echoed back. Requires a
            configured secret backend; the request is refused otherwise.
        useStartTls:
          type: boolean
          default: false
          description: Upgrade the connection with STARTTLS.
        useSsl:
          type: boolean
          default: false
          description: Connect over implicit TLS.

    SmtpResponseFields:
      type: object
      description: SMTP transport settings as returned on reads. Carries the secret reference, never the plaintext password.
      required: [host, port]
      properties:
        host:
          type: string
          example: smtp.example.com
        port:
          type: integer
          example: 587
        username:
          type: string
          nullable: true
        passwordSecretRef:
          type: string
          nullable: true
          description: Opaque reference returned by the secret backend that stored the password. Resolved at transport construction time.
        useStartTls:
          type: boolean
          default: false
        useSsl:
          type: boolean
          default: false

    EmailAccountWrite:
      type: object
      description: Account configuration accepted by the upsert endpoint.
      required: [fromAddress]
      properties:
        transportId:
          type: string
          enum: [smtp]
          default: smtp
          description: The transport this account uses. SMTP is the only transport.
        fromAddress:
          type: string
          format: email
          description: Default sender address for messages sent through this account.
          example: no-reply@example.com
        fromName:
          type: string
          nullable: true
          description: Default sender display name.
        replyTo:
          type: string
          nullable: true
          description: Default reply-to address.
        smtp:
          $ref: '#/components/schemas/SmtpAccountFields'

    EmailAccount:
      type: object
      description: Account configuration as returned by the admin endpoints, with the password held behind a secret reference.
      required: [accountId, transportId, fromAddress]
      properties:
        accountId:
          type: string
          example: default
        transportId:
          type: string
          enum: [smtp]
        fromAddress:
          type: string
          format: email
          example: no-reply@example.com
        fromName:
          type: string
          nullable: true
        replyTo:
          type: string
          nullable: true
        smtp:
          $ref: '#/components/schemas/SmtpResponseFields'

    SendEmailRequest:
      type: object
      description: A raw email. Provide an HTML body, a plain-text body, or both.
      required: [to, subject]
      properties:
        to:
          type: array
          minItems: 1
          description: Primary recipients.
          items:
            $ref: '#/components/schemas/EmailAddress'
        subject:
          type: string
          example: Welcome to VDX
        htmlBody:
          type: string
          nullable: true
          description: HTML body.
        textBody:
          type: string
          nullable: true
          description: Plain-text body.
        from:
          $ref: '#/components/schemas/EmailAddress'
        replyTo:
          $ref: '#/components/schemas/EmailAddress'
        cc:
          type: array
          description: Carbon-copy recipients.
          items:
            $ref: '#/components/schemas/EmailAddress'
        bcc:
          type: array
          description: Blind carbon-copy recipients.
          items:
            $ref: '#/components/schemas/EmailAddress'
        accountId:
          type: string
          default: default
          description: Account configuration to send through. Defaults to the tenant's default account.

    SendTemplatedEmailRequest:
      type: object
      description: A templated email. The body is rendered from a named template and a string context before delivery.
      required: [to, subject, templateName]
      properties:
        to:
          type: array
          minItems: 1
          description: Primary recipients.
          items:
            $ref: '#/components/schemas/EmailAddress'
        subject:
          type: string
          example: Verify your tenant signup
        templateName:
          type: string
          description: Name of the registered template to render.
          example: tenant-signup-verification
        templateContext:
          type: object
          additionalProperties:
            type: string
          description: Flat string-to-string context passed to the template renderer.
          example:
            displayName: Alice Smith
            verificationLink: https://app.example.com/tenants/signup/confirm?token=abc
        from:
          $ref: '#/components/schemas/EmailAddress'
        replyTo:
          $ref: '#/components/schemas/EmailAddress'
        cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        accountId:
          type: string
          default: default
          description: Account configuration to send through. Defaults to the tenant's default account.