PUT SMTP

The PUT /SMTPClosed Short for simple mail transfer protocol, SMTP is a protocol for sending email messages between servers. method is used to update the SMTP configuration profile information. This method returns HTTP 200 OK on a success with details about the SMTP configuration profile.

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

/system_setting/modify/

Important:  Version 1 of this endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. has been deprecated. It is retained for backwards compatibility, but all new development should use version 2. For more information about versioning, see Versioning.
Important:  Any previously populated fields that are not submitted with their full existing data using this method will be cleared of their existing data. When using this method, you should first do a GET to retrieve all the values for the record you want to update, enter corrected data into the field(s) you want to update, and then submit all the fields using PUT, including the fields that contain values but which you are not changing.

Version 2 of the GET /SMTP method provides support for the use of PAM for the email user credentials.

Table 830: PUT SMTP v2 Input Parameters

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 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 (e.g. 25).
RelayAuthenticationType Body

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

Required*. An object indicating the password information to use for authentication along with the RelayUsername if the RelayAuthenticationType is 2 (Explicit Credentials).

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.

ClosedShow password values and examples.

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 if 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*. An object indicating the username information to use for authentication along with the RelayPassword if the RelayAuthenticationType is 2 (Explicit Credentials).

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.

ClosedShow username values and examples.

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 if the secret created in the Delinea secret server for this purpose):

Copy 
{
   "Provider": "3",
   "Parameters":{
      "SecretId":"MyEmailUserPasswordId"
   }
}
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.
SenderAddress Body

A string indicating the sender for email messages delivered from Keyfactor Command, in the form of an email address (e.g. jsmith@keyexample.com).

This is considered deprecated and may be removed in a future release.
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.
UseSSL Body A Boolean indicating that mail should be delivered over TLS/SSL. Not all mail servers support this.

Table 831: PUT SMTP v2 Response Data

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 (e.g. 25).
RelayAuthenticationType

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

An object indicating the password information to use for authentication along with the RelayUsername if the RelayAuthenticationType is 2 (Explicit Credentials).

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

An object indicating the username information to use for authentication along with the RelayPassword if the RelayAuthenticationType is 2 (Explicit Credentials).
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.
UseSSL A Boolean indicating that mail should be delivered over TLS/SSL. Not all mail servers support this.

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

Table 832: PUT SMTP v1 Input Parameters

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 (e.g. 25).
RelayAuthenticationType Body

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

Required*. 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*. A string indicating the username of the account providing authentication to the mail server if RelayAuthenticationType is set to 2. 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.
UseSSL Body A Boolean indicating that mail should be delivered over TLS/SSL. Not all mail servers support this.

Table 833: PUT SMTP v1 Response Data

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 (e.g. 25).
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. 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.
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 top of the Management Portal page next to the Log Out button.