PingOne Platform APIs

Notifications Settings (SMTP)

The SMTP notifications settings endpoints provide the ability to configure the organization’s own SMTP service to send email notifications for each environment, instead of the built-in email service of PingOne. These endpoints implement operations to read, update and reset the SMTP notification settings for the environment.

  • You need the Environment Admin role to perform operations on SMTP notifications settings resources.

  • You can configure only one SMTP server per environment.

Notifications settings (SMTP) properties

Property Type Mutability Description

host

String

Mutable

The organization’s SMTP server.

port

String

Mutable

The port used by the organization’s SMTP server to send emails. The default port is 465.

protocol

String

Read-only

The SMTP protocol used by the organization. Ports 25, 2525, and 587 use SMTP. All other ports use SMTPS.

username

String

Mutable

The organization’s SMTP server username.

password

String

Write-only

The organization’s SMTP server password. Encrypted.

environment.id

String

Read-only

The environment resource’s unique identifier.

from.name

String

Mutable

The email’s "from" name .

from.address

String

Mutable

The email’s "from" address.

replyTo.name

String

Mutable

The email’s "reply to" name.

replyTo.address

String

Mutable

The email’s "reply to" address.

Notifications settings (SMTP) events generated

Refer to Audit Reporting Events for the events generated.

Notifications SMTP settings errors

In addition to the general error codes, notifications SMTP settings operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [<field> <message>] (for example, Validation Error : [host must not be blank], Validation Error : [host must be a valid hostname], Validation Error : [port must be greater than 0])

When and details

When: A PUT Update Notifications SMTP Settings request body fails constraint validation (for example, the request omits host, username, or password, specifies an invalid hostname for host, or a non-positive port).

Details: Per violated constraint: detail EMPTY_VALUE for NotBlank constraints, INVALID_VALUE for the HostnameTag and Positive constraints, target = the field path, message = the constraint message.

400

INVALID_REQUEST

None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A PUT Update Notifications SMTP Settings request body is malformed JSON or contains a value of the wrong type (for example, a non-integer port).

Details: For JSON deserialization failures, detail INVALID_VALUE with target = the JSON path of the failing property and message Invalid value for attribute.

400

INVALID_DATA

None

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT Update Notifications SMTP Settings request changes the authentication method of a custom email provider without providing a new providerCredentialsSecret.

Details: Detail INVALID_VALUE with message Credentials secret must be provided for <method> authentication method..

400

INVALID_DATA

None

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT Update Notifications SMTP Settings request defines custom provider requests that are invalid (a GET request with a body, a POST body whose form-encoded content does not match its content-type header, or a request missing the ${message} or ${to} variable).

Details: Detail INVALID_VALUE with the reason, for example URL cannot be empty for EMAIL delivery method, Body required to be empty in GET request for EMAIL delivery method, Invalid body. Form pattern does not match the format for EMAIL delivery method, ${message} variable is missing for EMAIL delivery method, or ${to} variable is missing for EMAIL delivery method.

400

INVALID_DATA

None

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT Update Notifications SMTP Settings request references an mTLS key pair that is expired, has the wrong usage type, or cannot be loaded.

Details: Detail INVALID_VALUE with target tlsClientAuthKeyPair.id and the reason: Key pair is expired <keyPairId>, Key pair must be of the OUTBOUND_MTLS usage type, but <usageType> was found, or Could not load key store <keyPairId>.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the permission for the operation: notifications:read:notificationsSettings (GET Read Notifications SMTP Settings), notifications:update:notificationsSettings (PUT Update Notifications SMTP Settings), or notifications:delete:notificationsSettings (DELETE Reset Notifications SMTP Settings).

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A request specifies an environment that does not exist.

Details: None.

404

NOT_FOUND

INVALID_VALUE

Message: The request could not be completed. The requested resource was not found.

When and details

When: A PUT Update Notifications SMTP Settings request references an mTLS key pair that does not exist.

Details: Detail INVALID_VALUE with target tlsClientAuthKeyPair.id and message Could not find key pair <keyPairId>.