email-openapi.yaml

openapi: 3.0.4
info:
  title: Email API
  version: 0.1.0
  x-products: [vdx]
  description: |
    Send transactional email on behalf of a tenant and manage the account that backs it. The
    service resolves the calling tenant from the bearer token, looks up that tenant's account
    configuration, and delivers over the configured transport. SMTP is the transport in this
    release.

    Two endpoints send mail directly: one takes a fully composed message, the other renders a
    registered template against a string context and sends the result. A diagnostic send exists for
    confirming an account works end to end. A status endpoint reports whether the tenant has a
    usable account, and an admin endpoint upserts the account itself.

    ## Accounts and secrets

    An account holds the default sender identity and the SMTP connection settings. Accounts are
    tenant-scoped and selected per request through `accountId`, which defaults to the well-known
    `default` account. The SMTP password is write-only. On an upsert the plaintext password is
    handed to the tenant's configured secret backend, and only the opaque reference the backend
    returns is stored and surfaced as `passwordSecretRef`. Responses never echo the plaintext value.
    When no secret backend is configured the upsert is refused with `501` and the password is not
    persisted.

    ## Sending mail

    A raw send carries the recipients, subject, and body. Supply an HTML body, a plain-text body, or
    both. A templated send names a registered template and passes a flat string context that the
    template renderer substitutes before delivery; the sender, recipients, and account selection work
    the same way as a raw send. A send that the transport accepts responds `202` with the delivery
    result; a send the transport rejects responds with an error.

    ## Status

    The status endpoint is unauthenticated and always responds `200`. Its body reports whether the
    tenant has a usable account and whether the transport is reachable, so a caller can gate its own
    behaviour before attempting a send.
  contact:
    name: Sphereon International B.V.
    email: support@sphereon.com
    url: https://sphereon.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: https://api.example.com/api/email/v1
    description: Production server.
  - url: http://localhost:8080/api/email/v1
    description: Local development server.

security:
  - bearer: []

tags:
  - name: Email
    description: Send transactional mail and report service status.
  - name: EmailAdmin
    description: Manage the tenant account that sends mail, including the SMTP secret.

paths:

  /status:
    get:
      tags: [Email]
      operationId: getEmailStatus
      summary: Report email-service configuration and health
      description: >-
        Reports whether the calling tenant has a usable account and whether the transport is
        reachable. Unauthenticated and always `200`; configuration problems are reported in the body,
        not as an HTTP error.
      security: []
      responses:
        '200':
          description: Email-service status for the tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailStatus'

  /send:
    post:
      tags: [Email]
      operationId: sendEmail
      summary: Send a raw email
      description: Sends a fully composed message through the selected account. Provide an HTML body, a plain-text body, or both.
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
      responses:
        '202':
          $ref: '#/components/responses/AcceptedDelivery'
        '400':
          $ref: './common-components.yml#/components/responses/ValidationError'
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'
        '500':
          $ref: './common-components.yml#/components/responses/Error'

  /send-templated:
    post:
      tags: [Email]
      operationId: sendTemplatedEmail
      summary: Render a template and send it
      description: Renders the named template against the supplied string context and sends the result through the selected account.
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendTemplatedEmailRequest'
      responses:
        '202':
          $ref: '#/components/responses/AcceptedDelivery'
        '400':
          $ref: './common-components.yml#/components/responses/ValidationError'
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'
        '500':
          $ref: './common-components.yml#/components/responses/Error'

  /test-send:
    post:
      tags: [Email]
      operationId: testSendEmail
      summary: Send a diagnostic email
      description: Sends a message through the selected account to confirm it delivers end to end. Takes the same body as a raw send.
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
      responses:
        '202':
          $ref: '#/components/responses/AcceptedDelivery'
        '400':
          $ref: './common-components.yml#/components/responses/ValidationError'
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'
        '500':
          $ref: './common-components.yml#/components/responses/Error'

  /accounts/{accountId}:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    put:
      tags: [EmailAdmin]
      operationId: putEmailAccount
      summary: Create or replace an email account
      description: >-
        Upserts the tenant account identified by `accountId`. A plaintext SMTP `password` in the
        request is written through the configured secret backend and replaced in the response by the
        opaque `passwordSecretRef`. Refused with `501` when no secret backend is configured; the
        password is not persisted in that case.
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailAccountWrite'
      responses:
        '200':
          description: The saved account, with the password held behind a secret reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAccount'
        '400':
          $ref: './common-components.yml#/components/responses/ValidationError'
        '401':
          $ref: './common-components.yml#/components/responses/Unauthorized'
        '403':
          $ref: './common-components.yml#/components/responses/Forbidden'
        '500':
          $ref: './common-components.yml#/components/responses/Error'
        '501':
          description: >-
            No secret backend is configured, so the SMTP password cannot be stored. The account is
            not persisted. Reported with the `UNSUPPORTED_OPERATION` error code and the
            `secret_backend_not_configured` reason.
          content:
            application/json:
              schema:
                $ref: './common-components.yml#/components/schemas/ApiError'

components:
  # Shared error/header/pagination components and the bearer scheme live in
  # ./common-components.yml. Entity, request, and value schemas live in
  # ./email-components.yml and are re-exported below so operations can reference
  # them with spec-internal `#/components/schemas/...` refs.

  securitySchemes:
    bearer:
      $ref: './common-components.yml#/components/securitySchemes/bearer'

  parameters:
    AccountId:
      $ref: './email-components.yml#/components/parameters/AccountId'

  responses:
    AcceptedDelivery:
      description: The message was accepted for delivery.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EmailDelivery'

  schemas:
    EmailAddress:
      $ref: './email-components.yml#/components/schemas/EmailAddress'
    EmailStatus:
      $ref: './email-components.yml#/components/schemas/EmailStatus'
    EmailDelivery:
      $ref: './email-components.yml#/components/schemas/EmailDelivery'
    EmailAccount:
      $ref: './email-components.yml#/components/schemas/EmailAccount'
    EmailAccountWrite:
      $ref: './email-components.yml#/components/schemas/EmailAccountWrite'
    SendEmailRequest:
      $ref: './email-components.yml#/components/schemas/SendEmailRequest'
    SendTemplatedEmailRequest:
      $ref: './email-components.yml#/components/schemas/SendTemplatedEmailRequest'