--- title: Trusted Email Domains description: 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. component: pingone-api page_id: pingone-api:platform:notifications/trusted-email-domains canonical_url: https://developer.pingidentity.com/pingone-api/platform/notifications/trusted-email-domains.html section_ids: trusted-email-domain-properties: Trusted email domain properties trusted-email-domain-ownership-properties: Trusted email domain ownership properties trusted-email-domain-dkim-properties: Trusted email domain DKIM properties trusted-email-domain-spf-properties: Trusted email domain SPF properties trusted-email-domains-events-generated: Trusted email domains events generated trusted-email-domains-response-codes: Trusted email domains response codes custom-mail-from-domains: Custom MAIL FROM domains mail-from-domain-data-model: MAIL FROM domain data model --- # 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-addresses.html). []() ## 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](../reference/audit-reporting-events.html) 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. |