PingOne Platform APIs

Trusted Email Domains

PingOne supports the ability to configure up to 50 trusted email domains for each environment. A trusted email domain with its associated email addresses enable PingOne to send emails on your organization’s behalf. To implement a trusted email domain, you’ll need to add DNS records and setup DKIM and SPF.

To create and manage trusted email addresses associated with your trusted email domain, refer to Trusted email addresses.

Trusted email domain properties

Property Type Required Mutable Description

id

String

Required

Immutable

The auto-generated ID of the email domain.

domainName

String

Required

Mutable

A string that specifies the resource name, which must be provided and must be unique within an environment (for example, auth.shopco.com). Wildcards are NOT supported.

environment.id

String

Required

Immutable

The environment resource’s unique identifier associated with the resource.

Trusted email domain ownership properties

Property Type Required Mutable Description

environmentDnsRecord

Object

N/A

Read-only

environmentDnsRecord contains a key-value pair for a text record that reflects the association of the domain with the specific PingOne environment. If you add this record to your DNS, any sender email address belonging to the domain is set to active status as soon as you create it, with no need for a verification email. In addition to key and value, the object contains a status field. In the initial call to check ownership status, status is returned with the value VERIFICATION_REQUIRED. If you add the record to your DNS, the next time you use the ownership endpoint to check ownership status, the value returned for status will be ACTIVE.

regions

Object[]

Required

Immutable

The regions collection specifies the properties for the 4 AWS SES regions that are used for sending email for the environment. The regions are determined by the geography where this environment was provisioned (North America, Canada, Europe & Asia-Pacific). Each item in the regions collection is an object with these properties:

* name: The name of the region.

* status: The status of the email domain ownership. Possible values:

* ACTIVE

* VERIFICATION_REQUIRED

* key: Record name.

* value: Record value.

type

String

Required

Mutable

The type of DNS record, with the value "TXT".

Trusted email domain DKIM properties

Property Type Required Mutable Description

type

String

Required

Mutable

The type of DNS record, with the value "CNAME".

regions

Object[]

Required

Immutable

The regions collection specifies the properties for the 4 AWS SES regions that are used for sending email for the environment. The regions are determined by the geography where this environment was provisioned (North America, Canada, Europe & Asia-Pacific). Each item in the regions collection is an object with these properties:

* name: The name of the region.

* status: The status of the email domain ownership. Possible values:

* ACTIVE

* VERIFICATION_REQUIRED

* tokens: A collection of key and value pairs. Each item in the tokens collection is an object with these properties:

Trusted email domain SPF properties

Property Type Required Mutable Description

type

String

Required

Mutable

The type of DNS record, with the value "TXT".

status

String

Required

Mutable

The status of the email domain ownership. Possible values:

* ACTIVE

* VERIFICATION_REQUIRED

key

String

Required

Mutable

Record name.

value

String

Required

Mutable

Record value.

Trusted email domains events generated

Refer to Audit Reporting Events for the events generated.

Trusted email domains response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

Custom MAIL FROM domains

To reduce the likelihood of PingOne notification messages getting flagged as spam, you can use the {{apiPath}}/v1/environments/{{envID}}/emailDomains/{{emailDomainID}}/mailFromDomain endpoint to define a custom MAIL FROM domain for trusted email domains that you have configured. Specifying a MAIL FROM domain results in SPF alignment with the FROM header, reducing the chances that the DMARC check will fail.

Send a PUT request to define the custom MAIL FROM domain, and then send a GET request to retrieve the MX record that you have to add to your DNS records in order to use the feature. The SPF record is also modified so you must also send a GET request with the {{apiPath}}/v1/environments/{{envID}}/emailDomains/{{emailDomainID}}/spf endpoint to obtain the updated SPF record to put in your DNS.

MAIL FROM domain data model

Property Type Required Mutable Description

key

String

N/A

Read-only

The name to enter for the MX record that should be added to your DNS.

mailFrom.domain

String

Required

Mutable

The full name to use for the MAIL FROM domain, for example, p1notifications.example.com. Do not use a subdomain that you use to send email from. Do not use a subdomain that you use to receive email.

priority

Integer

N/A

Read-only

The priority to enter for the MX record that should be added to your DNS.

status

String

N/A

Read-only

Before the MX record has been added to the DNS, value returned is VERIFICATION_REQUIRED. Once the record has been added and propagated, the value returned is ACTIVE.

type

String

N/A

Read-only

The type of record returned. Value is always MX.

value

String

N/A

Read-only

The value to enter for the MX record that should be added to your DNS.

Trusted email domain errors

In addition to the general error codes, trusted email domain 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

Message: Validation Error : [<field> <message>] (for example, Validation Error : [domainName must not be blank])

When and details

When: A POST Create Trusted Email Domain request omits domainName, or a PUT Create Mail From Domain request omits the mailFrom object or its domain property.

Details: Detail EMPTY_VALUE with target domainName or mailFrom.domain and message must not be blank, or with target mailFrom and message must not be null when the whole mailFrom object is omitted.

400

INVALID_REQUEST

INVALID_VALUE or None

Message: The request could not be completed. The request was malformed or invalid. for a malformed request body, or The request could not be completed. One or more validation errors were in the request. for an invalid path variable.

When and details

When: A request body is malformed JSON or contains a value of the wrong type, or a path variable such as emailDomainID is not a valid UUID.

Details: For JSON deserialization failures, 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: A POST Create Trusted Email Domain request specifies a domainName that is not a valid domain name with a valid TLD, ends with a dot, contains non-ASCII characters, or contains uppercase characters.

Details: Detail INVALID_VALUE with target domainName and the specific reason: must be a valid domain name with a valid TLD, cannot end with a dot, cannot contain non-ascii characters, or cannot contain uppercase characters.

400

INVALID_DATA

UNIQUENESS_VIOLATION

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

When and details

When: A POST Create Trusted Email Domain request specifies a domainName that already exists in the environment (case-sensitive).

Details: Detail UNIQUENESS_VIOLATION with target environmentId and message the domain: <domainName> already exists.

400

REQUEST_LIMITED

QUOTA_EXCEEDED

Message: The request will exceed your quota.

When and details

When: A POST Create Trusted Email Domain request exceeds the maximum of 50 trusted email domains per environment.

Details: Detail QUOTA_EXCEEDED with target domainName, message Too many email domains exists, and quotaLimit of 50 in innerError.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request violates a constraint imposed by the service.

When and details

When: A DELETE Delete Trusted Email Domain request targets a domain that still has trusted email addresses associated with it.

Details: A detail with no code, carrying target emailDomain and message cannot delete emailDomain with trustedEmails. The service sets the detail’s code slot to the message The request violates a constraint imposed by the service. instead of a code.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request violates a constraint imposed by the service.

When and details

When: A PUT Create Mail From Domain or DELETE Delete Mail From Domain request is submitted for a domain whose environment DNS ownership record is not yet verified.

Details: Detail CONSTRAINT_VIOLATION with no target and message MailFrom domain configuration is restricted until the environment DNS record is verified..

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 PUT Create Mail From Domain request fails AWS SES verification of the custom MAIL FROM domain (the domain is rejected by AWS).

Details: Detail INVALID_VALUE with the AWS SES error message.

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:create:emailDomain (POST Create Trusted Email Domain, PUT Create Mail From Domain), notifications:read:emailDomain (GET operations), or notifications:delete:emailDomain (DELETE Delete Trusted Email Domain, DELETE Delete Mail From Domain).

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

None

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

When and details

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

Details: Detail without a code, carrying the message Email Domain not found, Id: <emailDomainID>.

500

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request violates a constraint imposed by the service.

When and details

When: The service encounters a database error or an AWS SES domain verification failure while processing the request.

Details: Detail without a code, carrying the underlying AWS SES or database error message.