{
  "info": {
    "title": "transports",
    "version": ""
  },
  "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.\n- For \"BasicAuth\": Connection to the email server verified with provided credentials.\n- For \"Microsoft365\": Authentication token successfully retrieved with provided credentials.\n"
          },
          "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.\n",
        "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
        }
      }
    },
    "/api/v1/transports/email-config/actions/send-test-email": {
      "post": {
        "tags": [
          "email-config-actions"
        ],
        "summary": "Send test email",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/smtpResult"
                }
              }
            },
            "description": "Attempted send request. Response body indicates success/failure"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantAdminError"
                }
              }
            },
            "description": "Must be a tenant admin."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendTestMailConfigNotFoundError"
                }
              }
            },
            "description": "No email config exists for tenant."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorsPublic"
                }
              }
            },
            "description": "Unexpected error."
          }
        },
        "description": "Attempts to sends a test email using the active configuration, with the supplied email info (subject, body, recipient).",
        "operationId": "sendTestEmailAction",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/email"
                  }
                ]
              }
            }
          },
          "required": true
        },
        "x-qlik-stability": "stable",
        "x-qlik-visibility": "public",
        "x-qlik-deprecated": false,
        "x-qlik-tier": {
          "tier": "2",
          "limit": 100
        }
      }
    },
    "/api/v1/transports/email-config/actions/validate": {
      "post": {
        "tags": [
          "email-config-actions"
        ],
        "summary": "Get configuration status",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/smtpCheck"
                }
              }
            },
            "description": "Returns boolean isValid for the email config."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorsPublic"
                }
              }
            },
            "description": "Unexpected error."
          }
        },
        "description": "Returns the current isValid value for the email configuration for the tenant. Does not attempt to connect to a server to verify the connection or send a test email. Will return false if no email configuration exists.",
        "operationId": "validateAction",
        "x-qlik-stability": "stable",
        "x-qlik-visibility": "public",
        "x-qlik-deprecated": false,
        "x-qlik-tier": {
          "tier": "2",
          "limit": 100
        }
      }
    },
    "/api/v1/transports/email-config/actions/verify-connection": {
      "post": {
        "tags": [
          "email-config-actions"
        ],
        "summary": "Verify configuration",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/smtpResult"
                }
              }
            },
            "description": "Performed email connection. Response body indicates success/failure"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyConnectionConfigNotFoundError"
                }
              }
            },
            "description": "No email config exists for tenant."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorsPublic"
                }
              }
            },
            "description": "Unexpected error."
          }
        },
        "description": "Attempts to verify connection to email server using a low-level protocol handshake to confirm the server is reachable and the credentials are valid, without sending a test email.",
        "operationId": "verifyConnectionAction",
        "x-qlik-stability": "stable",
        "x-qlik-visibility": "public",
        "x-qlik-deprecated": false,
        "x-qlik-tier": {
          "tier": "2",
          "limit": 100
        }
      }
    }
  },
  "openapi": "3.0.0",
  "components": {
    "schemas": {
      "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"
            }
          }
        }
      },
      "email": {
        "properties": {
          "body": {
            "type": "string",
            "description": "email body"
          },
          "subject": {
            "type": "string",
            "description": "email subject"
          },
          "recipient": {
            "type": "string",
            "description": "email recipient (email address)"
          }
        }
      },
      "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."
      },
      "emailConfigPatch": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/emailConfigFieldPatch"
        },
        "example": [
          {
            "op": "replace",
            "path": "/username",
            "value": "New name"
          }
        ]
      },
      "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."
      },
      "ErrorsPublic": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorPublic"
            }
          }
        }
      },
      "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"
          }
        }
      },
      "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."
          }
        }
      },
      "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"
          }
        }
      },
      "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."
      },
      "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."
      },
      "SendTestMailConfigNotFoundError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "code",
                "title"
              ],
              "properties": {
                "code": {
                  "type": "string",
                  "example": "SENDTESTEMAIL-1",
                  "description": "The error code."
                },
                "title": {
                  "type": "string",
                  "example": "No email config for tenant",
                  "description": "Summary of the problem"
                }
              },
              "description": "An error object"
            }
          }
        }
      },
      "smtpCheck": {
        "type": "object",
        "properties": {
          "isValid": {
            "type": "boolean",
            "description": "true if smtp config is correct and complete. Will return false if smtp-config does not exist at all"
          },
          "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"
          }
        }
      },
      "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"
      },
      "smtpResult": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "error message from SMTP middleware .. a bit technical but could be useful to administrator"
          },
          "success": {
            "type": "boolean",
            "description": "was SMTP operation successful or not. Other fields herein provide more detail"
          },
          "connectionFailed": {
            "type": "boolean",
            "description": "could not resolve domain name, connection refused, connection timed out, SSL mismatch"
          },
          "smtpResponseCode": {
            "type": "integer",
            "description": "smtp result code string from the SMTP server. eg. \"250 2.6.0\""
          }
        }
      },
      "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"
            }
          }
        }
      },
      "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"
            }
          }
        }
      },
      "VerifyConnectionConfigNotFoundError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "code",
                "title"
              ],
              "properties": {
                "code": {
                  "type": "string",
                  "example": "VERIFYCONNECTION-1",
                  "description": "The error code."
                },
                "title": {
                  "type": "string",
                  "example": "No email config for tenant",
                  "description": "Summary of the problem"
                }
              },
              "description": "An error object"
            }
          }
        }
      }
    }
  },
  "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"
        }
      }
    }
  ]
}