Email configuration

Transports supports configuration of the tenant-level SMTP service. For the SMTP service in Qlik Automate, review the automation-connections API.

Download specification

Returns the email configuration for a given tenant id (retrieved from JWT).

Facts

Rate limit Tier 1 (1000 requests per minute)
Categories manage

Responses

200

Email configuration. If configuration does not exist in database then { isValid false, passwordExists false} is returned.

  • application/jsonobject
    Show application/json properties
    • statusobject

      Contains statusCode and statusReason

      Show status properties
      • statusCodenumber

        Status code

      • statusReasonstring

        Status reason
    • isValidboolean

      Is the configuration valid

    • tenantIdstring

      The tenant Id

    • usernamestring

      user name

    • errorCodestring

      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

    • serverPortnumber

      smtp server listening port

      minimum = 1

    • lastUpdatedstring
    • authFailuresnumber

      Number of authentication failures

    • emailAddressstring

      used for SMTP authentication

    • securityTypestring

      one of none, StartTLS or SSL/TLS

    • serverAddressstring

      domain name or IP address of SMTP server

    • passwordExistsboolean

      Indicates if password is defined for this smtp config. The password itself is not returned!

    • providerConfigobject
      One of:
      • getMicrosoft365Configobject
        Show getMicrosoft365Config properties
        • clientIdstring

          Microsoft365 client identifier

        • emailAddressstring

          The email address that should appear in From field when sending emails with this account

        • providerTenantIdstring

          Microsoft365 tenant identifier
      • getBasicAuthConfigobject
        Show getBasicAuthConfig properties
        • usernamestring

          user name used for SMTP login

        • serverPortnumber

          smtp server port

          minimum = 1

        • emailAddressstring

          The email address that should appear in From field when sending emails with this account

        • securityTypestring

          The selected SMTP security mechanism. Could be either 'none', 'StartTLS' or 'SSL/TLS'

        • serverAddressstring

          domain name or IP address of SMTP server
    • serviceProviderstring

      Name of the service provider for authentication

      Can be one of: "Microsoft365""BasicAuth"

    • modificationTimestring

      Last modification time. Formatted as a ISO 8601 string.

403

Must be a tenant admin.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem

default

Unexpected error.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem.
GET /api/v1/transports/email-config 
curl "https://your-tenant.us.qlikcloud.com/api/v1/transports/email-config" \
-H "Authorization: Bearer <access_token>"
const https = require('https')
  const data = JSON.stringify("")
  const options =   {
    'hostname': 'https://your-tenant.us.qlikcloud.com',
    'port': 443,
    'path': '/api/v1/transports/email-config',
    'method': 'GET',
    'headers': {
      'Authorization': 'Bearer <access_token>'
    }
  }
  const req = https.request(options)
This API is not included yet in qlik-cli

Response

{
  "status": {
    "statusCode": 0,
    "statusReason": "OK"
  },
  "isValid": true,
  "tenantId": "mcdd-mkw_Ebo0fR2vLl8_YsQYFsYrTdP",
  "username": "john.smith@company.com",
  "errorCode": "INVALID_CREDENTIALS",
  "serverPort": 587,
  "lastUpdated": "string",
  "authFailures": 0,
  "emailAddress": "john.smith@company.com",
  "securityType": "StartTLS",
  "serverAddress": "smtp.company.com",
  "passwordExists": true,
  "providerConfig": {
    "clientId": "12345678-1234-1234-1234-123456789012",
    "emailAddress": "abc@example.com",
    "providerTenantId": "12345678-1234-1234-1234-123456789012"
  },
  "serviceProvider": "Microsoft365",
  "modificationTime": "2022-06-30T09:57:40.954Z"
}

Patch the email configuration for a given tenant id (retrieved from JWT).

Facts

Rate limit Tier 2 (100 requests per minute)
Categories manage

Request Body

Required
  • application/jsonarray of objects

    A JSON Patch document as defined in https://datatracker.ietf.org/doc/html/rfc6902.

    Show application/json properties
    • opstring
      Required

      The operation to be performed.

      Can be one of: "replace, remove, add"

    • pathstring
      Required

      The path for the given resource field to patch.

      Can be one of: "/username""/serverAddress""/serverPort""/securityType""/emailAddress""/emailPassword"

    • valuestring
      Required

      The value to be used for this operation.

Responses

204

Success.

400

Bad request.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem

403

Must be a tenant admin.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem

default

Unexpected error.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem.
PATCH /api/v1/transports/email-config 
curl "https://your-tenant.us.qlikcloud.com/api/v1/transports/email-config" \
-X PATCH \
-H "Content-type: application/json" \
-H "Authorization: Bearer <access_token>" \
-d '[{"op":"replace","path":"/username","value":"New name"}]'
const https = require('https')
  const data = JSON.stringify([{"op":"replace","path":"/username","value":"New name"}])
  const options =   {
    'hostname': 'https://your-tenant.us.qlikcloud.com',
    'port': 443,
    'path': '/api/v1/transports/email-config',
    'method': 'PATCH',
    'headers': {
      'Content-type': 'application/json',
      'Authorization': 'Bearer <access_token>'
    }
  }
  const req = https.request(options)
  req.write(data)
This API is not included yet in qlik-cli

Request

[
  {
    "op": "replace",
    "path": "/username",
    "value": "New name"
  }
]

Deletes email configuration for a given tenant id (retrieved from JWT).

Facts

Rate limit Tier 2 (100 requests per minute)
Categories manage

Responses

204

Success.

403

Must be a tenant admin.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem

404

Not found.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem

default

Unexpected error.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem.
DELETE /api/v1/transports/email-config 
curl "https://your-tenant.us.qlikcloud.com/api/v1/transports/email-config" \
-X DELETE \
-H "Authorization: Bearer <access_token>"
const https = require('https')
  const data = JSON.stringify("")
  const options =   {
    'hostname': 'https://your-tenant.us.qlikcloud.com',
    'port': 443,
    'path': '/api/v1/transports/email-config',
    'method': 'DELETE',
    'headers': {
      'Authorization': 'Bearer <access_token>'
    }
  }
  const req = https.request(options)
This API is not included yet in qlik-cli

Send a test mail with the supplied email info (subject, body, recipient). Email config from database is used for the connection.

Facts

Rate limit Tier 2 (100 requests per minute)
Categories manage

Request Body

Required
  • application/jsonobject
    Show application/json properties
    • bodystring

      email body

    • subjectstring

      email subject

    • recipientstring

      email recipient (email address)

Responses

200

Attempted send request. Response body indicates success/failure

  • application/jsonobject
    Show application/json properties
    • messagestring

      error message from SMTP middleware .. a bit technical but could be useful to administrator

    • successboolean

      was SMTP operation successful or not. Other fields herein provide more detail

    • connectionFailedboolean

      could not resolve domain name, connection refused, connection timed out, SSL mismatch

    • smtpResponseCodeinteger

      smtp result code string from the SMTP server. eg. "250 2.6.0"

403

Must be a tenant admin.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem

404

No email config exists for tenant.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem

default

Unexpected error.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem.
POST /api/v1/transports/email-config/actions/send-test-email 
curl "https://your-tenant.us.qlikcloud.com/api/v1/transports/email-config/actions/send-test-email" \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer <access_token>" \
-d '{"body":"string","subject":"string","recipient":"string"}'
const https = require('https')
  const data = JSON.stringify({"body":"string","subject":"string","recipient":"string"})
  const options =   {
    'hostname': 'https://your-tenant.us.qlikcloud.com',
    'port': 443,
    'path': '/api/v1/transports/email-config/actions/send-test-email',
    'method': 'POST',
    'headers': {
      'Content-type': 'application/json',
      'Authorization': 'Bearer <access_token>'
    }
  }
  const req = https.request(options)
  req.write(data)
This API is not included yet in qlik-cli

Request

{
  "body": "string",
  "subject": "string",
  "recipient": "string"
}

Response

{
  "message": "string",
  "success": true,
  "connectionFailed": true,
  "smtpResponseCode": 42
}

Returns the isValid value for the email configuration for the tenant. Will return false if no email configuration exists.

Facts

Rate limit Tier 2 (100 requests per minute)
Categories manage

Responses

200

Returns boolean isValid for the email config.

  • application/jsonobject
    Show application/json properties
    • isValidboolean

      true if smtp config is correct and complete. Will return false if smtp-config does not exist at all

    • errorCodestring

      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

default

Unexpected error.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem.
POST /api/v1/transports/email-config/actions/validate 
curl "https://your-tenant.us.qlikcloud.com/api/v1/transports/email-config/actions/validate" \
-X POST \
-H "Authorization: Bearer <access_token>"
const https = require('https')
  const data = JSON.stringify("")
  const options =   {
    'hostname': 'https://your-tenant.us.qlikcloud.com',
    'port': 443,
    'path': '/api/v1/transports/email-config/actions/validate',
    'method': 'POST',
    'headers': {
      'Authorization': 'Bearer <access_token>'
    }
  }
  const req = https.request(options)
This API is not included yet in qlik-cli

Response

{
  "isValid": true,
  "errorCode": "INVALID_CREDENTIALS"
}

Verifies connection to email server for tenant provided via JWT

Facts

Rate limit Tier 2 (100 requests per minute)
Categories manage

Responses

200

Performed email connection. Response body indicates success/failure

  • application/jsonobject
    Show application/json properties
    • messagestring

      error message from SMTP middleware .. a bit technical but could be useful to administrator

    • successboolean

      was SMTP operation successful or not. Other fields herein provide more detail

    • connectionFailedboolean

      could not resolve domain name, connection refused, connection timed out, SSL mismatch

    • smtpResponseCodeinteger

      smtp result code string from the SMTP server. eg. "250 2.6.0"

404

No email config exists for tenant.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem

default

Unexpected error.

  • application/jsonobject
    Show application/json properties
    • errorsarray of objects

      An error object.

      Show errors properties
      • codestring
        Required

        The error code.

      • titlestring
        Required

        Summary of the problem.
POST /api/v1/transports/email-config/actions/verify-connection 
curl "https://your-tenant.us.qlikcloud.com/api/v1/transports/email-config/actions/verify-connection" \
-X POST \
-H "Authorization: Bearer <access_token>"
const https = require('https')
  const data = JSON.stringify("")
  const options =   {
    'hostname': 'https://your-tenant.us.qlikcloud.com',
    'port': 443,
    'path': '/api/v1/transports/email-config/actions/verify-connection',
    'method': 'POST',
    'headers': {
      'Authorization': 'Bearer <access_token>'
    }
  }
  const req = https.request(options)
This API is not included yet in qlik-cli

Response

{
  "message": "string",
  "success": true,
  "connectionFailed": true,
  "smtpResponseCode": 42
}