PingOne Platform APIs

Email Delivery Settings

Use the emailDeliverySettings endpoint to configure the sending of notifications via an external email service.

Note that you can only have a single set of email delivery settings for an environment, whether it be a custom SMTP mail server or an external email service.

Email delivery settings data model

Property Type Required Mutable Description

authentication

Object

Required

Mutable

Contains the information for authenticating with the email provider.

authentication.assertion

String

Required

Mutable

The assertion to use if authentication.grantType is set to JWT_BEARER. Must be a valid JWT.

authentication.authToken

String

Required

Mutable

If you specified BEARER as the authentication method, use authToken to provide the bearer token to use.

authentication.authUrl

String

Required

Mutable

The URL of the authorization server that provides the access token.
Required when authentication.method=OAUTH2

authentication.clientAuthenticationMethod

String

N/A

Read-only

The method used for sending credentials for OAuth2. Returned in responses for custom providers that require OAuth 2 authentication. For authentication based on client ID and secret, the value returned is BASIC_AUTH_HEADER. For JWT-based authentication, the value returned is BODY.

authentication.clientId

String

Required

Mutable

The client’s public identifier.
Required when authentication.grantType is set to CLIENT_CREDENTIALS.

authentication.clientSecret

String

Required

Mutable

The client’s secret.
Required when authentication.grantType is set to CLIENT_CREDENTIALS.

authentication.grantType

String

Optional

Mutable

The grant type used. Relevant for custom providers that require OAuth 2 authentication. Set to JWT_BEARER for JWT-based authentication, and to CLIENT_CREDENTIALS for authentication based on client ID and secret. If not specified in the request, the default value is CLIENT_CREDENTIALS.

authentication.headerName

String

Required

Mutable

The name of the custom header used for authentication.
Required when authentication.method=CUSTOM_HEADER

authentication.headerValue

String

Required

Mutable

The value to use for the custom header used for authentication.
Required when authentication.method=CUSTOM_HEADER

authentication.method

String

Required

Mutable

The custom provider account’s authentication method. Possible values:

* BASIC - username/password

* BEARER - bearer token

* OAUTH2 - OAuth 2

* CUSTOM_HEADER - authentication using a custom header

authentication.password

String

Required

Mutable

If you specified BASIC as the authentication method, use password to provide the password for authenticating with the email provider.

authentication.scopes

Array

Optional

Mutable

When authentication.method is set to OAUTH2, use scopes to specify the capabilities that the issued token should have, for example, ["mail.send"].

authentication.username

String

Required

Mutable

If you specified BASIC as the authentication method, use username to provide the username for authenticating with the email provider.

environment.id

String

N/A

Read-only

The environment’s unique identifier.

from

Object

Optional

Mutable

Contains the "from" information to use for the notifications.

from.name

String

Optional

Mutable

The "from" name to use in the notifications that are sent.

from.address

String

Optional

Mutable

The "from" address to use in the notifications that are sent.

name

String

Required

Mutable

Name to use to identify the provider.

protocol

String

Required

Immutable

Set to HTTP when configuring an external email provider.

provider

String

Required

Immutable

Must be set to CUSTOM_PROVIDER.

replyTo

Object

Optional

Mutable

Contains the "reply-to" information to use for the notifications.

replyTo.name

String

Optional

Mutable

The "reply-to" name to use in the notifications that are sent.

replyTo.address

String

Optional

Mutable

The "reply-to" address to use in the notifications that are sent.

requests

Array

Required

Mutable

Contains the object that is used to configure the API requests sent to the email provider.

requests[].body

String

Required

Mutable

Required if method is set to POST. Use body to provide the content of the body for the request sent to the email provider. The body that you define must include the mandatory PingOne variables for notifications: ${from}, ${to}, and ${message}. You can also include any optional notification variables.
If you are including the header content-type: application/json in requests[].headers:

* The content of requests[].body must be valid JSON

* You must enclose the JSON object in quotation marks and escape all quotation marks within the string, for example, "{\"From\": \"${from}\",\"To\": \"${to}\",\"message2\": \"${message}\"}".

requests[].deliveryMethod

String

Required

Immutable

Should be set to EMAIL.

requests[].headers

Object

Required

Mutable

Use this object to specify the headers that your email provider’s API expects.

requests[].method

String

Required

Mutable

Use method to specify the type of API request the email provider requires. Valid values are GET and POST.

requests[].url

String

Required

Mutable

Use url to specify the endpoint for your email provider, for example, https://api.example.com/email. If method is set to GET, append to the URL the various query parameters that the email provider’s API requires. The URL must also include the required PingOne variables, as described for the body parameter.

updatedAt

Date

N/A

Read-only

The date and time the email delivery settings were last updated.

Email delivery settings errors

In addition to the general error codes, email delivery 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 or OUT_OF_RANGE

Message: Validation Error : [<field> <message>] (for example, Validation Error : [name Name may not be blank], Validation Error : [authentication Authentication may not be null], Validation Error : [requests Requests may not be empty], Validation Error : [requests[0].url must be a valid URL], Validation Error : [requests[0].method invalid value], or Validation Error : [authentication.method invalid value])

When and details

When: A create or update request body fails constraint validation (for example, the request omits name, authentication, or requests, sets requests[].url to a value that is not a valid HTTPS URL, or specifies an unsupported requests[].method or authentication.method value).

Details: Per violated constraint: detail EMPTY_VALUE for NotNull, NotBlank, or NotEmpty constraints, OUT_OF_RANGE for Size constraints (with rangeMinimumValue and rangeMaximumValue in innerError), INVALID_VALUE otherwise, target = the field path, message = the constraint message.

400

INVALID_REQUEST

INVALID_VALUE or None

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

When and details

When: A request body is malformed JSON or contains a value of the wrong type (for example, an unknown authentication.method subtype).

Details: For a JSON field conversion error, detail INVALID_VALUE with target = the JSON path of the failing property and message Invalid value for attribute. Otherwise no detail is returned.

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: An update request changes the authentication method without providing a new secret.

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

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A create or update request defines invalid OAuth2 authentication (a CLIENT_CREDENTIALS grant without clientId or clientSecret, a JWT_BEARER grant without assertion, or a client authentication method that the grant type does not support).

Details: Detail INVALID_VALUE with the field reason: must not be null on authentication.clientId, authentication.clientSecret, or authentication.assertion, or BODY client authentication method is not supported for CLIENT_CREDENTIALS grant type / BASIC_AUTH_HEADER client authentication method is not supported for JWT_BEARER grant type on authentication.clientAuthenticationMethod.

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A create or update request defines 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

INVALID_VALUE

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

When and details

When: A create or update 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:update:notificationsSettings (create and update operations), notifications:read:notificationsSettings (GET operations), or notifications:delete:notificationsSettings (reset operations).

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 create or update 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>.