Trusted email domains

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

You can configure up to a maximum of 50 domains per account.

Trusted email domain representation

Property	Description
`id`	A string that specifies the auto-generated ID of the trusted email domain.
`domainName`	A string that specifies the resource name, which must be provided and must be unique within an account (for example, auth.shopco.com). This is a required property. Wildcards are not supported.

Trusted email domain ownership representation

Property Description

type A string that specifies the type of DNS record, with the value “TXT”.

regions

The regions collection specifies the properties for the 3 AWS SES regions that are used for sending email for the account. The regions are determined by the geography where this account was provisioned (North America, Europe and 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 trusted email domain ownership. Possible values:
- ACTIVE
- VERIFICATION_REQUIRED
key:
Record name.
value:
Record value.

Trusted email domain DKIM representation

Property Description

type A string that specifies the type of DNS record, with the value “CNAME”.

Property	Description
`type`	A string that specifies the type of DNS record, with the value “CNAME”.
`regions`	The regions collection specifies the properties for the 3 AWS SES regions that are used for sending email for the account. The regions are determined by the geography where this account was provisioned (North America, Europe and 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 trusted 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: `key`: Record name. `value`: Record value.

regions

name:
The name of the region.
status:
The status of the trusted 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:

key:
Record name.
value:
Record value.

Trusted email domain SPF representation

Property	Description
`type`	A string that specifies the type of DNS record, with the value “TXT”.
`status`	The status of the trusted email domain ownership. Possible values: ACTIVE VERIFICATION_REQUIRED
`key`	Record name.
`value`	Record value.

Create trusted email domain (POST)

Relative Path

/accounts/{accountId}/emaildomains

Request body structure

{
  "domainName": "<domain name>"
}

Create trusted email domain request example

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
   "domainName": "auth.shopco.com" \ 
 }' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains'

Create trusted email domain response example

{
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/40ea89b1-65aa-4ee9-8316-ef0e405567a2"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2"
  },
  "id": "40ea89b1-65aa-4ee9-8316-ef0e405567a2",
  "domainName": "auth.shopco.com"
}

Get bulk trusted email domains (GET)

Get all the trusted email domains in the account.

Relative Path

/accounts/{accountId}/emaildomains

Get trusted email domains request example

curl -X GET --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains'

Get trusted email domains response example

{
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains"
  },
  "emaildomains": [
    {
      "id": "40ea89b1-65aa-4ee9-8316-ef0e405567a2",
      "domainName": "auth.shopco.com"
    },
    {
      "id": "add668cd-6352-4a47-a5be-e258648a09bf",
      "domainName": "moderno.com"
    }
  ]
}

Get a trusted email domain (GET)

Get a specific trusted email domain.

Relative Path

/accounts/{accountId}/emaildomains/{emailDomainId}

Get trusted email domain request example

curl -X GET --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf'

Get trusted email domain response example

{
  "ownership": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/ownership"
  },
  "dkim": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/dkim"
  },
  "spf": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/spf"
  },
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2"
  },
  "id": "add668cd-6352-4a47-a5be-e258648a09bf",
  "domainName": "moderno.com"
}

Note: Use the expand query parameter to get details on one or more the following trusted email domain resources:

account
ownership
dkim
spf

Get trusted email domain request example (with expand query parameter)

curl -X GET --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf?expand=account%2C%20ownership%2C%20dkim%2C%20spf'

Get trusted email domain response example (with expand query parameter)

{
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf"
  },
  "ownership": {
    "regions": [
      {
        "name": "ap-southeast-2",
        "status": "VERIFICATION_REQUIRED",
        "key": "_amazonses",
        "value": "3vDRz9Evh1Qf5TtglUro06QEViQzrNIiBrz4px8noDk="
      },
      {
        "name": "us-east-1",
        "status": "VERIFICATION_REQUIRED",
        "key": "_amazonses",
        "value": "yN29qOsJrbOrfaddIqg03EifLkuZrPE6Fdq8KHJ2mYo="
      },
      {
        "name": "us-west-2",
        "status": "VERIFICATION_REQUIRED",
        "key": "_amazonses",
        "value": "pbcu8O26XMPeGRVA2L5/XWJbstzoAd5K3HIrkaaSeYY="
      }
    ],
    "type": "TXT"
  },
  "dkim": {
    "regions": [
      {
        "name": "ap-southeast-2",
        "status": "VERIFICATION_REQUIRED",
        "tokens": [
          {
            "key": "pia3vzqt3rssvtirdivjpzxhbu26losl._domainkey",
            "value": "pia3vzqt3rssvtirdivjpzxhbu26losl.dkim.amazonses.com"
          },
          {
            "key": "lyyvbb6czfp54344pzs7zehtqsz2zkgv._domainkey",
            "value": "lyyvbb6czfp54344pzs7zehtqsz2zkgv.dkim.amazonses.com"
          },
          {
            "key": "3cvwg3d5wavqg6c3vjkhlbqinwxjjulw._domainkey",
            "value": "3cvwg3d5wavqg6c3vjkhlbqinwxjjulw.dkim.amazonses.com"
          }
        ]
      },
      {
        "name": "us-east-1",
        "status": "VERIFICATION_REQUIRED",
        "tokens": [
          {
            "key": "ue4chbovo52shhztq72s6t5kpnj4dhdh._domainkey",
            "value": "ue4chbovo52shhztq72s6t5kpnj4dhdh.dkim.amazonses.com"
          },
          {
            "key": "lhhfzxqoyzelh3cgdcrjtoyxeaqem3dp._domainkey",
            "value": "lhhfzxqoyzelh3cgdcrjtoyxeaqem3dp.dkim.amazonses.com"
          },
          {
            "key": "zu54qx5krvrbwadvy2ch2qfbce5mpr6u._domainkey",
            "value": "zu54qx5krvrbwadvy2ch2qfbce5mpr6u.dkim.amazonses.com"
          }
        ]
      },
      {
        "name": "us-west-2",
        "status": "VERIFICATION_REQUIRED",
        "tokens": [
          {
            "key": "2uyzgl4yvyzlgspqiixdvzvudfucnchz._domainkey",
            "value": "2uyzgl4yvyzlgspqiixdvzvudfucnchz.dkim.amazonses.com"
          },
          {
            "key": "oownlf6p5oib4ecxhnswd2523jgnc2m5._domainkey",
            "value": "oownlf6p5oib4ecxhnswd2523jgnc2m5.dkim.amazonses.com"
          },
          {
            "key": "rsnuxsnuc7bm6vkzzpiof4ztpcrcyjow._domainkey",
            "value": "rsnuxsnuc7bm6vkzzpiof4ztpcrcyjow.dkim.amazonses.com"
          }
        ]
      }
    ],
    "type": "CNAME"
  },
  "spf": {
    "status": "VERIFICATION_REQUIRED",
    "key": "@",
    "value": "v=spf1 include:amazonses.com ~all",
    "type": "TXT"
  },
  "account": {
    "id": "f851a4da-1239-4008-9456-8b93279558f2",
    "name": "Moderno",
    "accountType": "TRIAL"
  },
  "id": "add668cd-6352-4a47-a5be-e258648a09bf",
  "domainName": "moderno.com"
}

Get trusted email domain ownership status

The GET ownership operation verifies ownership for the trusted email domain resource with the specified ID.

Relative Path

/accounts/{accountId}/emaildomains/{emailDomainId}/ownership

Get trusted email domain ownership status request example

curl -X GET --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/ownership'

Get trusted email domain ownership status response example

{
  "emailDomain": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf"
  },
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/ownership"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2"
  },
  "regions": [
    {
      "name": "ap-southeast-2",
      "status": "VERIFICATION_REQUIRED",
      "key": "_amazonses",
      "value": "3vDRz9Evh1Qf5TtglUro06QEViQzrNIiBrz4px8noDk="
    },
    {
      "name": "us-east-1",
      "status": "VERIFICATION_REQUIRED",
      "key": "_amazonses",
      "value": "yN29qOsJrbOrfaddIqg03EifLkuZrPE6Fdq8KHJ2mYo="
    },
    {
      "name": "us-west-2",
      "status": "VERIFICATION_REQUIRED",
      "key": "_amazonses",
      "value": "pbcu8O26XMPeGRVA2L5/XWJbstzoAd5K3HIrkaaSeYY="
    }
  ],
  "type": "TXT"
}

Note: Use the expand query parameter to get details on a trusted email domain.

Get trusted email domain ownership status request example (with expand on email domain)

curl -X GET --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/ownership?expand=emailDomain'

Get trusted email domain ownership status response example (with expand on email domain)

{
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/ownership"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2"
  },
  "emailDomain": {
    "id": "add668cd-6352-4a47-a5be-e258648a09bf",
    "domainName": "moderno.com"
  },
  "regions": [
    {
      "name": "ap-southeast-2",
      "status": "VERIFICATION_REQUIRED",
      "key": "_amazonses",
      "value": "3vDRz9Evh1Qf5TtglUro06QEViQzrNIiBrz4px8noDk="
    },
    {
      "name": "us-east-1",
      "status": "VERIFICATION_REQUIRED",
      "key": "_amazonses",
      "value": "yN29qOsJrbOrfaddIqg03EifLkuZrPE6Fdq8KHJ2mYo="
    },
    {
      "name": "us-west-2",
      "status": "VERIFICATION_REQUIRED",
      "key": "_amazonses",
      "value": "pbcu8O26XMPeGRVA2L5/XWJbstzoAd5K3HIrkaaSeYY="
    }
  ],
  "type": "TXT"
}

Get trusted email domain DKIM status

The GET operation returns the verification status and the verification token for the trusted email domain, for the 3 AWS SES regions. The verification status of the domain is VERIFICATION_REQUIRED, until the trusted email domain owner adds CNAME records in the trusted email domain’s DNS settings. After that, the domain’s status is ACTIVE.

Relative Path

/accounts/{accountId}/emaildomains/{emailDomainId}/dkim

Get trusted email domain DKIM status request example

curl -X GET --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/dkim'

Get trusted email domain DKIM status response example

{
  "emailDomain": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf"
  },
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/dkim"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2"
  },
  "regions": [
    {
      "name": "ap-southeast-2",
      "status": "VERIFICATION_REQUIRED",
      "tokens": [
        {
          "key": "lyyvbb6czfp54344pzs7zehtqsz2zkgv._domainkey",
          "value": "lyyvbb6czfp54344pzs7zehtqsz2zkgv.dkim.amazonses.com"
        },
        {
          "key": "pia3vzqt3rssvtirdivjpzxhbu26losl._domainkey",
          "value": "pia3vzqt3rssvtirdivjpzxhbu26losl.dkim.amazonses.com"
        },
        {
          "key": "3cvwg3d5wavqg6c3vjkhlbqinwxjjulw._domainkey",
          "value": "3cvwg3d5wavqg6c3vjkhlbqinwxjjulw.dkim.amazonses.com"
        }
      ]
    },
    {
      "name": "us-east-1",
      "status": "VERIFICATION_REQUIRED",
      "tokens": [
        {
          "key": "zu54qx5krvrbwadvy2ch2qfbce5mpr6u._domainkey",
          "value": "zu54qx5krvrbwadvy2ch2qfbce5mpr6u.dkim.amazonses.com"
        },
        {
          "key": "lhhfzxqoyzelh3cgdcrjtoyxeaqem3dp._domainkey",
          "value": "lhhfzxqoyzelh3cgdcrjtoyxeaqem3dp.dkim.amazonses.com"
        },
        {
          "key": "ue4chbovo52shhztq72s6t5kpnj4dhdh._domainkey",
          "value": "ue4chbovo52shhztq72s6t5kpnj4dhdh.dkim.amazonses.com"
        }
      ]
    },
    {
      "name": "us-west-2",
      "status": "VERIFICATION_REQUIRED",
      "tokens": [
        {
          "key": "rsnuxsnuc7bm6vkzzpiof4ztpcrcyjow._domainkey",
          "value": "rsnuxsnuc7bm6vkzzpiof4ztpcrcyjow.dkim.amazonses.com"
        },
        {
          "key": "oownlf6p5oib4ecxhnswd2523jgnc2m5._domainkey",
          "value": "oownlf6p5oib4ecxhnswd2523jgnc2m5.dkim.amazonses.com"
        },
        {
          "key": "2uyzgl4yvyzlgspqiixdvzvudfucnchz._domainkey",
          "value": "2uyzgl4yvyzlgspqiixdvzvudfucnchz.dkim.amazonses.com"
        }
      ]
    }
  ],
  "type": "CNAME"
}

Note: Use the expand query parameter to get details on a trusted email domain. See Get trusted email domain ownership status request example (with expand on email domain).

Get trusted email domain SPF status

The GET operation returns the verification status and the verification token for the trusted email domain. The verification status of the domain is VERIFICATION_REQUIRED, until the trusted email domain owner adds TXT records in the trusted email domain’s DNS settings. After that, the domain’s status is ACTIVE.

Relative Path

/accounts/{accountId}/emaildomains/{emailDomainId}/spf

Get trusted email domain SPF status request example

curl -X GET --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/spf'

Get trusted email domain SPF status response example

{
  "emailDomain": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf"
  },
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf/spf"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2"
  },
  "status": "VERIFICATION_REQUIRED",
  "key": "@",
  "value": "v=spf1 include:amazonses.com ~all",
  "type": "TXT"
}

Note: Use the expand query parameter to get details on a trusted email domain. See Get trusted email domain ownership status request example (with expand on email domain).

Delete trusted email domain (DELETE)

Note:

Before you delete a trusted email domain resource, all associated email addresses must be deleted.
Before (or after) you delete a trusted email domain resource, it is recommended that you remove the CNAME record that you created for this domain from the DNS manager. This step is optional.

The sample shows the operation to delete the trusted email domain resource entity, specified by its ID in the request URL.

Relative Path

/accounts/{accountId}/emaildomains/{emailDomainId}

Delete trusted email domain request example

curl -X DELETE --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/emaildomains/add668cd-6352-4a47-a5be-e258648a09bf'

Delete trusted email domain response example

HTTP 204 status