POST SMTP Test

The POST /SMTPClosed Short for simple mail transfer protocol, SMTP is a protocol for sending email messages between servers./Test method is used to test the SMTP settings by sending a test email message. This method returns HTTP 200 OK on a success with with no content for version 2 of the endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server..

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

/system_setting/modify/

Important:  Version 1 of this endpoint has been deprecated. It is retained for backwards compatibility, but all new development should use version 2. For more information about versioning, see Versioning.

Version 2 of the POST /SMTP/Test method adds support for OAuth and PAMClosed PAM (Privileged Access Management): Controls privileged access by vaulting credentials, enforcing least-privilege/just-in-time access, rotating secrets, and auditing sessions. Across Keyfactor products, PAM protects diverse sensitive operations and secrets—for example certificate stores and CA credentials—via built-in or third-party providers; external integrations are delivered as custom PAM extensions (several published on Keyfactor’s public GitHub).-based email credentials.

Table 888: POST SMTP Test Input Parameters V2

Name In

Description
Host Body Required. A string indicating the fully qualified domain name of your SMTP host (e.g.,smtp.keyexample.com).
Id Body An integer indicating the Keyfactor Command reference ID of the SMTP record. This will be 1 in most environments.
Port Body

Required. An integer indicating the SMTP port. Common ports are:

  • 25 — Traditional SMTP (server-to-server relay). Often allowed only from trusted hosts; may be STARTTLS-capable. This is the default.

  • 587 — Message submission (MSA). The modern, recommended port for apps/services. Uses AUTH and usually STARTTLS.

  • 465 — SMTPS (implicit TLS). TLS from the first byte; some providers still prefer this.
RelayAuthenticationType Body

An integer indicating the type of authentication used to connect to the mail server. The default is 0 (zero).

RelayPassword Body

Required in some cases. An object indicating the password information to use for authentication along with the RelayUsername if the RelayAuthenticationType is 2 (Basic Authentication).

This value is Required if RelayAuthenticationType is 2.

Supported methods to store secret information are:

  • Store the secret in the Keyfactor secrets table.

    A Keyfactor secret is a user-defined value (e.g., password) that is encrypted and stored securely in the Keyfactor Command database.

  • Load the secret from a Keyfactor Command local or supported third-party PAM solution.

    See Privileged Access Management (PAM) and PAM Providers for more information.

For example, the password stored as a Keyfactor secret will look like:

Copy 
 {
   "SecretValue": "MySuperSecretPassword"
}

The password stored as a local Keyfactor Command PAM secret will look like (where the Provider value—1 in this example—is the Id value from GET PAM Providers and the SecretName is the name defined for the secret):

Copy 
{
   "Provider": "1",
   "Parameters":{
      "SecretName":"EmailSenderPassword"
   }
}

The password stored as a CyberArk PAM secret will look like (where the Provider value—2 in this example—is the Id value from GET PAM Providers and the Folder and Object reference the folder name and object name in the CyberArk safe):

Copy 
{
   "Provider": "2",
   "Parameters":{
      "Folder":"MyFolderName",
      "Object":"MyEmailUserPassword"
   }
}

The password stored as a Delinea PAM secret will look like (where the Provider value—3 in this example—is the Id value from GET PAM Providers and the SecretId is the ID of the secret created in the Delinea secret server for this purpose):

Copy 
{
   "Provider": "3",
   "Parameters":{
      "SecretId":"MyEmailUserPasswordId"
   }
}

Due to its sensitive nature, this value is not returned in responses.
RelayUsername Body

Required in some cases. An object indicating the username information to use for authentication along with the RelayPassword if the RelayAuthenticationType is 2 (Basic Authentication).

This value is Required if RelayAuthenticationType is 2.

Supported methods to store secret information are:

  • Store the secret in the Keyfactor secrets table.

    A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the Keyfactor Command database.

  • Load the secret from a Keyfactor Command local or supported third-party PAM solution.

    See Privileged Access Management (PAM) and PAM Providers for more information.

For example, the username stored as a Keyfactor secret will look like:

Copy 
 {
   "SecretValue": "command@keyexample.com"
}

The username stored as a local Keyfactor Command PAM secret will look like (where the Provider value—1 in this example—is the Id value from GET PAM Providers and the SecretName is the name defined for the secret):

Copy 
{
   "Provider": "1",
   "Parameters":{
      "SecretName":"EmailSenderUsername"
   }
}

The username stored as a CyberArk PAM secret will look like (where the Provider value—2 in this example—is the Id value from GET PAM Providers and the Folder and Object reference the folder name and object name in the CyberArk safe):

Copy 
{
   "Provider": "2",
   "Parameters":{
      "Folder":"MyFolderName",
      "Object":"MyEmailUsername"
   }
}

The username stored as a Delinea PAM secret will look like (where the Provider value—3 in this example—is the Id value from GET PAM Providers and the SecretId is the ID of the secret created in the Delinea secret server for this purpose):

Copy 
{
   "Provider": "3",
   "Parameters":{
      "SecretId":"MyEmailUserId"
   }
}
SenderAccount Body

Required. A string indicating the account used to send email, typically in the form of an email address (e.g., jsmith@keyexample.com).

  • If Anonymous (0) is selected for RelayAuthenticationType, you may enter any value (your mail server must allow anonymous connections).

  • If Basic Authentication (2) or OAuth Client Credentials (3) is selected, you must enter a valid account recognized by your mail server.
SenderName Body

Required. A string indicating the display name used as the sender of the messages coming from Keyfactor Command. This does not typically need to be a valid value in your mail server. This value is used for all configurations of RelayAuthenticationType.
TestRecipient Body Required. A string indicating the recipient name, in email format (e.g., mjones@keyexample.com), for a test message to be sent using the SMTP configuration to confirm functionality.
UseSSL Body A Boolean indicating that mail should be delivered over TLS/SSL. Not all mail servers support this.
ClientId Body

Required in some cases. An object indicating the client ID to use for authentication along with the ClientSecret if the RelayAuthenticationType is 3 (OAuth Client Credentials).

This value is Required if RelayAuthenticationType is 3.

Supported methods to store secret information are:

  • Store the secret in the Keyfactor secrets table.

    A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the Keyfactor Command database.

  • Load the secret from a Keyfactor Command local or supported third-party PAM solution.

    See Privileged Access Management (PAM) and PAM Providers for more information.

For example, the client ID stored as a Keyfactor secret will look like:

Copy 
 {
   "SecretValue": "command-email"
}

The client ID stored as a local Keyfactor Command PAM secret will look like (where the Provider value—1 in this example—is the Id value from GET PAM Providers and the SecretName is the name defined for the secret):

Copy 
{
   "Provider": "1",
   "Parameters":{
      "SecretName":"EmailSenderID"
   }
}

The client ID stored as a CyberArk PAM secret will look like (where the Provider value—2 in this example—is the Id value from GET PAM Providers and the Folder and Object reference the folder name and object name in the CyberArk safe):

Copy 
{
   "Provider": "2",
   "Parameters":{
      "Folder":"MyFolderName",
      "Object":"MyEmailClientID"
   }
}

The client ID stored as a Delinea PAM secret will look like (where the Provider value—3 in this example—is the Id value from GET PAM Providers and the SecretId is the ID of the secret created in the Delinea secret server for this purpose):

Copy 
{
   "Provider": "3",
   "Parameters":{
      "SecretId":"MyEmailUserClientId"
   }
}
ClientSecret Body

Required in some cases. An object indicating the client secret to use for authentication along with the ClientId if the RelayAuthenticationType is 3 (OAuth Client Credentials).

This value is Required if RelayAuthenticationType is 3.

Supported methods to store secret information are:

  • Store the secret in the Keyfactor secrets table.

    A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the Keyfactor Command database.

  • Load the secret from a Keyfactor Command local or supported third-party PAM solution.

    See Privileged Access Management (PAM) and PAM Providers for more information.

For example, the client secret stored as a Keyfactor secret will look like:

Copy 
 {
   "SecretValue": "MySuperSecretClientSecret"
}

The client secret stored as a local Keyfactor Command PAM secret will look like (where the Provider value—1 in this example—is the Id value from GET PAM Providers and the SecretName is the name defined for the secret):

Copy 
{
   "Provider": "1",
   "Parameters":{
      "SecretName":"EmailSenderClientSecret"
   }
}

The client secret stored as a CyberArk PAM secret will look like (where the Provider value—2 in this example—is the Id value from GET PAM Providers and the Folder and Object reference the folder name and object name in the CyberArk safe):

Copy 
{
   "Provider": "2",
   "Parameters":{
      "Folder":"MyFolderName",
      "Object":"MyEmailUserClientSecret"
   }
}

The client secret stored as a Delinea PAM secret will look like (where the Provider value—3 in this example—is the Id value from GET PAM Providers and the SecretId is the ID of the secret created in the Delinea secret server for this purpose):

Copy 
{
   "Provider": "3",
   "Parameters":{
      "SecretId":"MyEmailUserClientSecretId"
   }
}
TokenEndpoint Body A string indicating the token endpoint URL for the identity provider, if RelayAuthenticationType is 3 (OAuth Client Credentials).
Scope Body A string indicating any scopes that should be included in token requests to the identity provider, if RelayAuthenticationType is 3 (OAuth Client Credentials). If multiple scopes are desired, they should be separated by spaces.
Audience Body A string indicating the audience that should be included in token requests to the identity provider, if RelayAuthenticationType is 3 (OAuth Client Credentials).
RequestHeaders Body

An array of objects specifying one ore more custom OIDC request headers for the identity provider given as name/value pairs.

Parameters configured in this value are added to the headers when Keyfactor Command sends an OIDC request to the OAuth server for the following request types:

  • Discovery Document

  • JSON Web Key Set

  • Token

Version 1 of the POST /SMTP/Test method includes similar capabilities to version 2, except that it does not support OAuth or PAM.

Table 889: POST SMTP Test Input Parameters V1

Name In Description
Host Body Required. A string indicating the fully qualified domain name of your SMTP host (e.g., corpexch02.keyexample.com).
Id Body Required. An integer indicating the Keyfactor Command reference ID of the SMTP record. This will be 1 in most environments.
Port Body

An integer indicating the SMTP port. Common ports are:

  • 25 — Traditional SMTP (server-to-server relay). Often allowed only from trusted hosts; may be STARTTLS-capable. This is the default.

  • 587 — Message submission (MSA). The modern, recommended port for apps/services. Uses AUTH and usually STARTTLS.

  • 465 — SMTPS (implicit TLS). TLS from the first byte; some providers still prefer this.
RelayAuthenticationType Body

An integer indicating the type of authentication used to connect to the mail server.

RelayPassword Body

Required in some cases.  A string indicating the password of the user specified by RelayUsername if RelayAuthenticationType is set to 2. This field is required if RelayAuthenticationType is set to 2.

No data is output in this field on a GET.
RelayUsername Body

Required in some cases. A string indicating the username of the account providing authentication to the mail server if RelayAuthenticationType is set to 2. For Active Directory integrated mail servers, the username should be provided in DOMAIN\\username format. This field is required if RelayAuthenticationType is set to 2.

For most mail server configurations, the username provided must have as a valid email address the email address you set in the SenderAccount parameter.
SenderAccount Body

Required. A string indicating the sender for email messages delivered from Keyfactor Command, in the form of an email address (e.g., jsmith@keyexample.com). Depending on the email configuration in your environment, the sender account may need to be a valid user on your mail server or you may be able to put anything in this field.
SenderName Body

Required. A string indicating the name that appears as the “from” in the user's mail client (e.g., Keyfactor Command). This value is used for both configurations of RelayAuthenticationType.
TestRecipient Body A string indicating the recipient name, in email format (e.g., mjones@keyexample.com), for a test message to be sent using the SMTP configuration to confirm functionality.
UseSSL Body A Boolean indicating that mail should be delivered over TLS/SSL. Not all mail servers support this.

Table 890: POST SMTP Test Response Data V1

Name Description
Host A string indicating the fully qualified domain name of your SMTP host (e.g., corpexch02.keyexample.com).
Id An integer indicating the Keyfactor Command reference ID of the SMTP record. This will be 1 in most environments.
Port

An integer indicating the SMTP port. Common ports are:

  • 25 — Traditional SMTP (server-to-server relay). Often allowed only from trusted hosts; may be STARTTLS-capable. This is the default.

  • 587 — Message submission (MSA). The modern, recommended port for apps/services. Uses AUTH and usually STARTTLS.

  • 465 — SMTPS (implicit TLS). TLS from the first byte; some providers still prefer this.
RelayAuthenticationType

An integer indicating the type of authentication used to connect to the mail server. ClosedShow authentication details.
RelayUsername

A string indicating the username of the account providing authentication to the mail server if RelayAuthenticationType is set to 2. For Active Directory integrated mail servers, the username should be provided in DOMAIN\\username format.

For most mail server configurations, the username provided must have as a valid email address the email address you set in the SenderAccount parameter.
SenderAccount

A string indicating the sender for email messages delivered from Keyfactor Command, in the form of an email address (e.g., jsmith@keyexample.com). Depending on the email configuration in your environment, the sender account may need to be a valid user on your mail server or you may be able to put anything in this field.
SenderName

A string indicating the name that appears as the “from” in the user's mail client (e.g., Keyfactor Command). This value is used for both configurations of RelayAuthenticationType.
TestRecipient A string indicating the recipient name, in email format (e.g., mjones@keyexample.com), for a test message to be sent using the SMTP configuration to confirm functionality.
UseSSL A Boolean indicating that mail should be delivered over TLS/SSL. Not all mail servers support this.
Tip:  See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. endpoints can be called and results returned. It is intended to be used primarily for validation, testing and workflowClosed A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. development. It also serves secondarily as documentation for the API. The link to the Keyfactor API Reference and Utility is in the dropdown from the help icon () at the bottom of the Management Portal side menu.