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 100 email configurations.
  • Email related attribute:
    • Application:
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 subject.

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".

type

Used to retrieve the email configuration.

  • Mandatory.

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-HMC=<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

{
  "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-HMC=<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-HMC=<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/{id}

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-HMC=<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-HMC=<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-HMC=<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