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}}/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}}/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.