openapi: 3.2.0
info:
  title: transports Email Config API
  version: ''
servers:
- url: https://{tenant}.{region}.qlikcloud.com
  variables:
    region:
      default: us
      description: The region the tenant is hosted in
    tenant:
      default: your-tenant
      description: Name of the tenant that will be called
tags:
- name: email-config
paths:
  /api/v1/transports/email-config:
    get:
      tags:
      - email-config
      summary: Get email configuration
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getEmailConfig'
          description: Email configuration. If configuration does not exist in database then { isValid false, passwordExists false} is returned.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantAdminError'
          description: Must be a tenant admin.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsPublic'
          description: Unexpected error.
      description: Returns the current email configuration and configuration status for the tenant.
      operationId: getEmailConfig
      x-qlik-stability: stable
      x-qlik-visibility: public
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '1'
        limit: 1000
    patch:
      tags:
      - email-config
      summary: Patch email configuration
      responses:
        '204':
          description: Success.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateEmailConfigError'
          description: Bad request.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantAdminError'
          description: Must be a tenant admin.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsPublic'
          description: Unexpected error.
      description: Patches the email configuration for the tenant. This endpoint is deprecated, use `PUT /transports/email-config` to replace the entire configuration instead.
      operationId: patchEmailConfig
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/emailConfigPatch'
        required: true
      x-qlik-stability: stable
      x-qlik-deprecated: true
      x-qlik-visibility: public
      x-qlik-deprecated-sunset: 2026-11
      x-qlik-deprecated-version: 2025-11
      x-qlik-deprecated-description: Migrating to PUT /email-config
      x-qlik-tier:
        tier: '2'
        limit: 100
    put:
      tags:
      - email-config
      summary: Update email configuration
      responses:
        '204':
          description: 'Email configuration validated and saved successfully.

            - For "BasicAuth": Connection to the email server verified with provided credentials.

            - For "Microsoft365": Authentication token successfully retrieved with provided credentials.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateEmailConfigError'
          description: Bad request.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantAdminError'
          description: Must be a tenant admin.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsPublic'
          description: Unexpected error.
      description: Creates or replaces the email configuration for the tenant. Validation of the configuration is done as part of the request.
      operationId: putEmailConfig
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putEmailConfig'
        required: true
      x-qlik-stability: stable
      x-qlik-visibility: public
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
    delete:
      tags:
      - email-config
      summary: Delete email configuration
      responses:
        '204':
          description: Success.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantAdminError'
          description: Must be a tenant admin.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteConfigNotFoundError'
          description: Not found.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsPublic'
          description: Unexpected error.
      description: Deletes the email configuration for the tenant.
      operationId: deleteEmailConfig
      x-qlik-stability: stable
      x-qlik-visibility: public
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
components:
  schemas:
    putBasicAuthConfig:
      type: object
      properties:
        username:
          type: string
          example: john.smith@company.com
          description: user name used for SMTP login
        senderName:
          type: string
          example: John
          description: The name that should appear in From field when sending emails with this account
        serverPort:
          type: number
          example: 587
          minimum: 1
          description: smtp server port
        emailAddress:
          type: string
          example: abc@example.com
          description: The email address that should appear in From field when sending emails with this account
        securityType:
          type: string
          example: StartTLS
          description: SMTP security mechanism to use. Could be either 'none', 'StartTLS' or 'SSL/TLS'
        emailPassword:
          type: string
          example: password
          description: password for SMTP basic authentication
        serverAddress:
          type: string
          example: smtp.company.com
          description: domain name or IP address of SMTP server
      description: SMTP basic authentication configuration. Provides server address, credentials, and sender information for standard SMTP email delivery.
    emailConfigFieldPatch:
      type: object
      required:
      - op
      - path
      - value
      properties:
        op:
          enum:
          - replace, remove, add
          type: string
          example: add
          description: The operation to be performed.
        path:
          enum:
          - /username
          - /serverAddress
          - /serverPort
          - /securityType
          - /emailAddress
          - /emailPassword
          type: string
          example: /emailAddress
          description: The path for the given resource field to patch.
        value:
          type: string
          example: john.smith@company.com
          description: The value to be used for this operation.
      description: A JSON Patch document as defined in https://datatracker.ietf.org/doc/html/rfc6902.
    ErrorPublic:
      type: object
      required:
      - code
      - title
      properties:
        code:
          type: string
          description: The error code.
        title:
          type: string
          description: Summary of the problem.
      description: An error object.
    DeleteConfigNotFoundError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            required:
            - code
            - title
            properties:
              code:
                type: string
                example: DELETE-1
                description: The error code.
              title:
                type: string
                example: No email config for tenant
                description: Summary of the problem
            description: An error object
    getMicrosoft365Config:
      type: object
      properties:
        clientId:
          type: string
          example: 12345678-1234-1234-1234-123456789012
          description: Microsoft365 client identifier
        emailAddress:
          type: string
          example: abc@example.com
          description: The email address that should appear in From field when sending emails with this account
        providerTenantId:
          type: string
          example: 12345678-1234-1234-1234-123456789012
          description: Microsoft365 tenant identifier
    UpdateEmailConfigError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            required:
            - code
            - title
            properties:
              code:
                type: string
                example: INPUTCHECK-1
                description: The error code.
              title:
                type: string
                example: serverAddress is not a string
                description: Summary of the problem
            description: An error object
    smtpConfigStatus:
      type: object
      properties:
        statusCode:
          type: number
          example: 0
          description: Status code
        statusReason:
          type: string
          example: OK
          description: Status reason
      description: Contains statusCode and statusReason
    putEmailConfig:
      type: object
      properties:
        providerConfig:
          oneOf:
          - $ref: '#/components/schemas/putMicrosoft365Config'
          - $ref: '#/components/schemas/putBasicAuthConfig'
        serviceProvider:
          enum:
          - Microsoft365
          - BasicAuth
          type: string
          example: Microsoft365
          description: Name of the service provider for authentication
    putMicrosoft365Config:
      type: object
      properties:
        clientId:
          type: string
          example: 12345678-1234-1234-1234-123456789012
          description: Microsoft365 client identifier
        clientSecret:
          type: string
          example: -123a5678_1234/1234*1234-123b567b12
          description: secret to authenticate the Microsoft365 account
        emailAddress:
          type: string
          example: abc@example.com
          description: The email address that should appear in From field when sending emails with this account
        providerTenantId:
          type: string
          example: 12345678-1234-1234-1234-123456789012
          description: Microsoft365 tenant identifier
      description: Microsoft 365 authentication configuration. Provides OAuth credentials and tenant information for Microsoft 365 email delivery.
    ErrorsPublic:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorPublic'
    emailConfigPatch:
      type: array
      items:
        $ref: '#/components/schemas/emailConfigFieldPatch'
      example:
      - op: replace
        path: /username
        value: New name
    TenantAdminError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            required:
            - code
            - title
            properties:
              code:
                type: string
                example: ROLECHECK-1
                description: The error code.
              title:
                type: string
                example: Must be a tenant admin
                description: Summary of the problem
            description: An error object
    getEmailConfig:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/smtpConfigStatus'
        isValid:
          type: boolean
          example: true
          description: Is the configuration valid
        tenantId:
          type: string
          example: mcdd-mkw_Ebo0fR2vLl8_YsQYFsYrTdP
          description: The tenant Id
        username:
          type: string
          example: john.smith@company.com
          description: user name
        errorCode:
          type: string
          example: INVALID_CREDENTIALS
          description: Indicates error with this email configuration. OK means that no error is indicated. Possible values are OK, CONFIG_NOT_SET, INCOMPLETE_CONFIG, INVALID_CREDENTIALS, PROVIDER_ERROR
        serverPort:
          type: number
          example: 587
          minimum: 1
          description: smtp server listening port
        lastUpdated:
          type: string
        authFailures:
          type: number
          example: 0
          description: Number of authentication failures
        emailAddress:
          type: string
          example: john.smith@company.com
          description: used for SMTP authentication
        securityType:
          type: string
          example: StartTLS
          description: one of none, StartTLS or SSL/TLS
        serverAddress:
          type: string
          example: smtp.company.com
          description: domain name or IP address of SMTP server
        passwordExists:
          type: boolean
          example: true
          description: Indicates if password is defined for this smtp config. The password itself is not returned!
        providerConfig:
          oneOf:
          - $ref: '#/components/schemas/getMicrosoft365Config'
          - $ref: '#/components/schemas/getBasicAuthConfig'
        serviceProvider:
          enum:
          - Microsoft365
          - BasicAuth
          type: string
          example: Microsoft365
          description: Name of the service provider for authentication
        modificationTime:
          type: string
          example: '2022-06-30T09:57:40.954Z'
          description: Last modification time. Formatted as a ISO 8601 string.
    getBasicAuthConfig:
      type: object
      properties:
        username:
          type: string
          example: john.smith@company.com
          description: user name used for SMTP login
        senderName:
          type: string
          example: John
          description: The name that should appear in From field when sending emails with this account
        serverPort:
          type: number
          example: 587
          minimum: 1
          description: smtp server port
        emailAddress:
          type: string
          example: abc@example.com
          description: The email address that should appear in From field when sending emails with this account
        securityType:
          type: string
          example: StartTLS
          description: The selected SMTP security mechanism. Could be either 'none', 'StartTLS' or 'SSL/TLS'
        serverAddress:
          type: string
          example: smtp.company.com
          description: domain name or IP address of SMTP server