Email configuration

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

Download specification

Endpoints

GET

/v1/transports/email-config
PATCH

/v1/transports/email-config
DELETE

/v1/transports/email-config
POST

/v1/transports/email-config/actions/send-test-email
POST

/v1/transports/email-config/actions/validate
POST

/v1/transports/email-config/actions/verify-connection

Facts

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

Responses

200

application/json

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

application/json

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

application/json

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 /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"
}

Facts

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

Request Body

Required

application/json

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

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

application/json

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

application/json

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

application/json

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 /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"
  }
]

Facts

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

Responses

204

Success.

403

application/json

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

application/json

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

application/json

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 /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

Facts

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

Request Body

Required

application/json

application/jsonobject
Show application/json properties
- bodystring
  
  email body
- subjectstring
  
  email subject
- recipientstring
  
  email recipient (email address)

Responses

200

application/json

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

application/json

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

application/json

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

application/json

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 /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
}

Facts

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

Responses

200

application/json

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

application/json

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 /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"
}

Facts

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

Responses

200

application/json

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

application/json

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

application/json

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 /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
}

Email configuration

Endpoints

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

Facts

Responses

200

403

default

Response

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

Facts

Request Body

Responses

204

400

403

default

Request

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

Facts

Responses

204

403

404

default

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

Facts

Request Body

Responses

200

403

404

default

Request

Response

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

Facts

Responses

200

default

Response

Verifies connection to email server for tenant provided via JWT

Facts

Responses

200

404

default

Response