GET SMTP

The GET /SMTPClosed Short for simple mail transfer protocol, SMTP is a protocol for sending email messages between servers. operation retrieves the SMTP configuration profile from Keyfactor Command. On success, the operation returns HTTP 200 OK with  details about the SMTP profile. Only one profile may be configured. There are no input parameters for this operation other than the standard headers (see Endpoint Common Features).

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

/smtp/read/

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

Version 2 of GET /SMTP 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 927: GET SMTP Response Data V2

Name

Description
Host A string indicating the fully qualified domain name of your SMTP host (for example,smtp.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 support STARTTLS. This is the default.

  • 587: Message submission (MSA). The modern, recommended port for applications and services. Uses AUTH and typically supports STARTTLS.

  • 465: SMTPS (implicit TLS). TLS is negotiated from the first byte. Some providers continue to prefer this port.
RelayAuthenticationType

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

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

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 (Basic Authentication).
SenderAccount

A string indicating the account used to send email, typically in the form of an email address (for example, 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

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.
UseSSL A Boolean indicating that mail should be delivered over TLS/SSL. Not all mail servers support this.
ClientId

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

An object indicating the client secret to use for authentication along with the ClientId if the RelayAuthenticationType is 3 (OAuth Client Credentials).
TokenEndpoint A string indicating the token endpoint URL of the identity provider, if RelayAuthenticationType is 3 (OAuth Client Credentials).
Scope 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 A string indicating the audience that should be included in token requests to the identity provider, if RelayAuthenticationType is 3 (OAuth Client Credentials).
RequestHeaders

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

Table 928: GET SMTP Response Data V2

Name

Description
Host A string indicating the fully qualified domain name of your SMTP host (for example,smtp.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 support STARTTLS. This is the default.

  • 587: Message submission (MSA). The modern, recommended port for applications and services. Uses AUTH and typically supports STARTTLS.

  • 465: SMTPS (implicit TLS). TLS is negotiated from the first byte. Some providers continue to prefer this port.
RelayAuthenticationType

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

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

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 (Basic Authentication).
SenderAccount

A string indicating the account used to send email, typically in the form of an email address (for example, 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

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.
UseSSL A Boolean indicating that mail should be delivered over TLS/SSL. Not all mail servers support this.
ClientId

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

An object indicating the client secret to use for authentication along with the ClientId if the RelayAuthenticationType is 3 (OAuth Client Credentials).
TokenEndpoint A string indicating the token endpoint URL of the identity provider, if RelayAuthenticationType is 3 (OAuth Client Credentials).
Scope 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 A string indicating the audience that should be included in token requests to the identity provider, if RelayAuthenticationType is 3 (OAuth Client Credentials).
RequestHeaders

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 GET /SMTP includes similar capabilities to version 2, except that it does not support OAuth or PAM.

Table 929: GET SMTP Response Data V1

Name Description
Host A string indicating the fully qualified domain name of your SMTP host (for example, 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 support STARTTLS. This is the default.

  • 587: Message submission (MSA). The modern, recommended port for applications and services. Uses AUTH and typically supports STARTTLS.

  • 465: SMTPS (implicit TLS). TLS is negotiated from the first byte. Some providers continue to prefer this port.
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 (for example, 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

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

This is considered deprecated and may be removed in a future release.
SenderName

A string indicating the name that appears as the “from” in the user's mail client (for example, 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 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. Reference and Utility, which allows you to call API operations and view results. It is primarily intended 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, and also serves as an interactive supplement to this API documentation. You can access it from the help menu () in the Management Portal.