Email templates

When an application is configured to permit users to pair and authenticate using an OTP sent to them via email, PingID SDK requires an email template associated with that application. An email template is the framework which includes email elements such as the email’s subject and body text, to generate an email to send to the user.

During pairing and authentication by email, the application’s email template is retrieved by specifying the type and locale.
Each application may have a single email configuration per type and locale.
Each account may have a maximum of 1000 email configurations.
It is not possible to create an email template with an unverified email address. See Trusted email domains and Trusted email addresses.

Application’s email-related attribute: `email_enabled`

Attribute	Description
email_enabled	Indicates whether the application is configured to permit pairing and authentication via email OTP. (Default is false.)

Create email template (POST)

Relative Path

/accounts/{accountId}/applications/{applicationId}/emailconfigurations

Request body structure

{
  "fromAddress":       "<from address>",
  "emailSubject":      "<subject line>",
  "emailBody":         "<email body encoded in BASE64 or in raw text>",
  "replyToAddress":    "<replyto address>",
  "contentType":       "<text/html or text/plain>",
  "characterSet":      "<character set>",
  "locale":            "<locale>",
  "type":              "<type>",
  "emailBodyEncoding": <base64 or raw>
}

Request parameters

Parameter	Description
fromAddress	This address will be used in the email "from" field. The address has to be validated for the account. Mandatory. The address can be an email address (for example: "noreply@example.com"), or an email address that contains a display name. In order to configure the display name, the syntax is: "${name}" <${email address}> where ${name} should be replaced with the desired display name, and ${email address} with the email address, for example: { ... 'fromAddress': '"Example From Display Name" <help@example.com>'', ... } Note: The address "noreply@pingidentity.com" is verified for all the accounts by default. Other addresses can be configured in coordination with Ping.
emailSubject	The email subject line. Optional. If empty, the email will have no subject.
emailBody	A string comprising the email body. Optional. This string can be encoded in base64. If the string is encoded in base64, the "emailBodyEncoding" should be "base64". If empty, the email will have no body. An email configuration with an empty subject and body is invalid.
replyToAddress	This address will be used in the email "replyto" field. The address has to be validated for the account. Mandatory. The address can be an email address (for example: "help@example.com"), or an email address that contains a display name. In order to configure the display name, the syntax is: "${name}" <${email address}> where ${name} should be replaced with the desired display name, and ${email address} with the email address, for example: { ... 'replyToAddress': '"Example Reply To Display Name" <help@example.com>', ... } Note: You can use the address "noreply@pingidentity.com" that is verified for all the accounts by default, or you can configure a customized email adress in coordination with Ping.
contentType	The email content-type header. Optional. Valid values: "text/html" (default) "text/plain"
characterSet	A valid charset according to Internet Assigned Numbers Authority (IANA) charset registry (more info in RFC-2987 and wikipedia). default: UTF-8 Optional.
locale	Used to retrieve the email configuration. Must be a valid locale. Optional. Default is "en". Email templates support the following case-insensitive locale language tag formats, complying with the ISO-639 language code and ISO-3166 country code standards: Two-character language code, for example, "en". Two-character language code followed by a two-character country code, separated by an underscore or dash, for example: "en_GB", "en-GB".
type	Required for retrieving the email configuration in the pairing and authentication operations. Mandatory. The possible values for "type" are determined by the app designers. For example, pairing and authentication email templates have different subject lines and body texts. The "type" parameter could be assigned the value "pairing" for the pairing template, and "authentication" for the authentication template. Thus, the app flow can use the relevant email template for the combination of a particular locale and the "type" value that matches a specific logic scenario.
emailBodyEncoding	The encoding of the emailBody. Optional. Valid values: "raw" (default) "base64"

Create email template request example

curl -X POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: PINGID-HMAC=<JWT>' \
  --header 'Accept: application/json' -d '{ \
  "fromAddress": "noreply%40pingidentity.com", \
  "emailSubject": "subject&#33;", \
  "emailBody": "bWFpbCBib2R5ICR7T1RQfQ==", \
  "replyToAddress": "noreply%40pingidentity.com", \
  "contentType": "text/html", \
  "characterSet": "UTF-8", \
  "locale": "en", \
  "type": "authentication", \
  "emailBodyEncoding": "base64" \
  }' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/emailconfigurations'

Create email template response example

Note: emailBody will be encoded according to the specification in emailBodyEncoding.

{
  "fromAddress": "noreply@pingidentity.com",
  "emailSubject": "subject!",
  "emailBody": "mail body ${OTP}",
  "replyToAddress": "noreply@pingidentity.com",
  "contentType": "text/html",
  "characterSet": "utf-8",
  "locale": "en",
  "type": "authentication",
  "emailBodyEncoding": "RAW",
  "id": "b6b796e8-88d3-455d-8d09-2e1428dfa6c3"
}

Create email template with placeholders - request example

curl -X POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: PINGID-HMAC=<JWT>' \
  --header 'Accept: application/json' -d '{ \
  "fromAddress": "noreply%40pingidentity.com", \
  "emailSubject": "${greeting} ${user}!", \
  "emailBody": "Hi ${USR}, your OTP is ${OTP}.", \
  "replyToAddress": "noreply%40pingidentity.com", \
  "contentType": "text/html", \
  "characterSet": "UTF-8", \
  "locale": "en", \
  "type": "authentication", \
  "emailBodyEncoding": "raw" \
  }' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-
d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/
emailconfigurations'

Create email template with placeholders - response example

{
  "fromAddress": "noreply@pingidentity.com",
  "emailSubject": "${greeting} ${user}!",
  "emailBody": "Hi ${USR}, your OTP is ${OTP}.",
  "replyToAddress": "noreply@pingidentity.com",
  "contentType": "text/html",
  "characterSet": "utf-8",
  "locale": "en",
  "type": "authentication",
  "emailBodyEncoding": "RAW",
  "id": "b6b796e8-88d3-455d-8d09-2e1428dfa6c3"
}

Update email template (PUT)

Relative path

/accounts/{accountId}/applications/{applicationId}/emailconfigurations/{id}

Update email template request example

curl -X PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: PINGID-HMAC=<JWT>' \
  --header 'Accept: application/json' -d '{ \
  "fromAddress": "noreply%40pingidentity.com", \
  "emailSubject": "subject&#33;", \
  "emailBody": "bWFpbCBib2R5ICR7T1RQfQ==", \
  "replyToAddress": "noreply%40pingidentity.com", \
  "contentType": "text/html", \
  "characterSet": "UTF-8", \
  "locale": "en", \
  "type": "authentication", \
  "emailBodyEncoding": "base64" \
  }' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/emailconfigurations/b6b796e8-88d3-455d-8d09-2e1428dfa6c3'

Update email template response example

{
  "fromAddress": "noreply@pingidentity.com",
  "emailSubject": "subject!",
  "emailBody": "mail body ${OTP}",
  "replyToAddress": "noreply@pingidentity.com",
  "contentType": "text/html",
  "characterSet": "utf-8",
  "locale": "en",
  "type": "authentication",
  "emailBodyEncoding": "RAW",
  "id": "b6b796e8-88d3-455d-8d09-2e1428dfa6c3"
}

Get bulk email templates (GET)

Get an application’s email templates

Relative path

/accounts/{accountId}/applications/{applicationId}/emailconfigurations

Query parameters

Parameter	Description
type	Optional, filters the configurations by type
locale	Optional, filters the configurations by locale

Request example

curl -X GET \
--header 'Authorization: PINGID-HMAC=<JWT>' \
--header 'Accept: application/json' \
'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-
d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/
emailconfigurations?type=authentication&locale=en'

Response example

{
  "emailconfigurations": [
  {
    "fromAddress": "noreply@pingidentity.com",
    "emailSubject": "subject!",
    "emailBody": "mail body ${OTP}",
    "replyToAddress": "noreply@pingidentity.com",
    "contentType": "text/html",
    "characterSet": "utf-8",
    "locale": "en",
    "type": "authentication",
    "emailBodyEncoding": "RAW",
    "id": "5a832315-55bf-4e17-bcc6-392f3fea0661"
  }
 ]
}

Get email template

Relative path

/accounts/{accountId}/applications/{applicationId}/emailconfigurations/{id}

Request example

curl -X GET \
--header 'Authorization: PINGID-HMAC=<JWT>' \
--header 'Accept: application/json' \
'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-
d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/
emailconfigurations/5a832315-55bf-4e17-bcc6-392f3fea0661'

Response example

{
    "fromAddress": "noreply@pingidentity.com",
    "emailSubject": "subject!",
    "emailBody": "mail body ${OTP}",
    "replyToAddress": "noreply@pingidentity.com",
    "contentType": "text/html",
    "characterSet": "utf-8",
    "locale": "en",
    "type": "authentication",
    "emailBodyEncoding": "RAW",
    "id": "5a832315-55bf-4e17-bcc6-392f3fea0661"
}

Delete email template (DELETE)

Relative path

/accounts/{accountId}/applications/{applicationId}/emailconfigurations/{id}

Request example

curl -X DELETE \
--header 'Authorization: PINGID-HMAC=<JWT>' \
--header 'Accept: application/json' \
'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-
d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/
emailconfigurations/emailconfigurations/5a832315-55bf-4e17-
bcc6-392f3fea0661'

Response example

HTTP 204 status

Email templates

Application’s email-related attribute: email_enabled

Create email template (POST)

Update email template (PUT)

Get bulk email templates (GET)

Get email template

Delete email template (DELETE)

Application’s email-related attribute: `email_enabled`