PingOne Advanced Identity Cloud

Email templates

PingOne Advanced Identity Cloud provides preconfigured email templates for common end-user journeys.

You can customize email templates using Markdown language. Advanced Identity Cloud uses a parser to let you preview your markup.

Email templates utilize Handlebar expressions to reference object data dynamically. For example, to reference the userName of an object:

{{object.userName}}

Create a new email template

  1. In the Advanced Identity Cloud admin UI, go to Email > Templates.

  2. On the Email Templates page, click + New Template.

  3. Provide the following details:

    • Template Name: Display name for the template.

    • From Address: Enter an email address for the group or individual sending the email.

    • From Name: Enter a name for the group or individual sending the email.

    • Description: A brief description of the template.

  4. Click Save. The new email opens in the email editor.

  5. Learn more in Edit an email template.

Edit an email template

  1. In the Advanced Identity Cloud admin UI, go to Email > Templates.

  2. On the Email Templates page, click a template name to open the email editor.

  3. To change the wording in the email template, edit the Markdown text in the left window on the page. You can also:

  4. Add, modify, or delete locales to suit your end-user audience. Learn more in Manage email template locales.

  5. Repeat step 3 for each template locale.

  6. To edit the template styles, click Styles, and edit the CSS style code.

  7. To view available variables that you can use in the template, click Variables, and view the content on the Available Properties page. Click Done.

  8. To edit the template settings, click the More () icon at the top right of the page, and select Settings.

  9. Provide the following details:

    • Template Name: Display name for the template.

    • From Address: Enter an email address for the group or individual sending the email.

    • From Name: Enter a name for the group or individual sending the email.

    • Description: Enter a brief description of the template.

  10. Click Update.

  11. Click Save. This saves content changes in all template locales.

Add an image to an email template

  1. Upload your image to a hosted service, such as a content delivery network (CDN), so it is available over HTTPS. Local image paths are not permitted.

  2. In the Advanced Identity Cloud admin UI, go to Email > Templates.

  3. On the Email Templates page, click a template name to open the email editor.

  4. Edit the Markdown text to reference your image:

    • To add an image at full size:

      ![alt text](<image url>)

      For example, the Markdown would look like this for an image hosted at https://example.com/image.ext where the alt text is this is an example image:

      ![this is an example image](<https://example.com/image.ext>)

    • To add an image and resize it in pixels:

      ![this is an example image](<https://example.com/image.ext> =100x100)

    • To add an image and resize it as a percentage:

      ![this is an example image](<https://example.com/image.ext> =50%x50%)

  5. Click Save.

Use HTML formatting in an email template

Although you can’t see HTML formatting in the editor, you can use inline HTML to format your email. Learn more in Markdown Syntax: Inline HTML.

  1. In the Advanced Identity Cloud admin UI, go to Email > Templates.

  2. On the Email Templates page, click a template name to open the email editor.

  3. Edit the Markdown text:

    • Specify HTML tags to format your content. For example:

      <h1>Reset Password</h1>

    • To add a table, include both the <thead> and <tbody> tags; otherwise the table will not convert correctly to Markdown when saved. For example:

      <table>
  <thead>
    <tr>
     <th>Header 1</th>
     <th>Header 2</th>
     <th>Header 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell Text 1</td>
      <td>Cell Text 2</td>
      <td>Cell Text 3</td>
    </tr>
  </tbody>
</table>

  4. Click Styles, and add CSS styles for the tag to format it as required. For example:

    h1 {
    font-family: Arial, Helvetica, sans-serif;
    color: #f96700;
    background-color: #032b75;
    font-size: 25px;
    padding: 10px;
}

  5. Click Save.

After saving your changes, the inline HTML tags are converted to Markdown, but the CSS styles for the tags persist. The CSS styles apply to all locales.

Alternatively, you can click Advanced Editor and modify the template in HTML. However, if you swap to the Advanced Editor, you cannot change back to Markdown.

Use ESV variables in an email template

You can use ESV variables in email templates to dynamically present different text, images, or links depending on the specific tenant environment.

For background on ESVs in PingOne Advanced Identity Cloud, learn more in ESVs.

To add ESV variables to an email template, you must use the Advanced Editor. After you have swapped to the Advanced Editor, you cannot change back to Markdown.

Add ESV variables to an email template

  1. Create the ESV variables to use in the email template:

    1. Create the variables using the Advanced Identity Cloud admin UI or variables APIs.

    2. Restart Advanced Identity Cloud services by applying updates in the Advanced Identity Cloud admin UI or using the restart API.

  2. In the Advanced Identity Cloud admin UI, go to Email > Templates.

  3. On the Email Templates page, click a template name to open the email editor.

  4. Click Advanced Editor.

  5. Add the placeholder for one or more ESV variables. For example:

    &{esv.my.variable}

  6. Click Save.

Example

  1. In step 1, add these two ESV variables:

  2. In step 5, add the link and image:

    • Add the link using the ESV placeholder, where the link text is the URL, for example:

      <p>For more information, go to our website: &{esv.test.link}</p>
      You can also add the link using the <a> tag with the href attribute. This is useful if you want to display different link text.

    • Add the image using the ESV placeholder, for example:

      <p>
<img src="&{esv.test.image}">
</p>

    The preview in the left window shows the ESV placeholder and an image placeholder rather than the actual link and image as these are only resolved when the email is sent.

Manage email template locales

You can create email content for different locales. When an email is sent during an end-user journey, Advanced Identity Cloud automatically selects the appropriate email template based on the value of the accept-language header, typically derived from the language set in the end user’s browser.

You can use the browser’s developer tools to check the value set in the accept-language header.

The locale selector in the top left of the email template editor displays the current template’s locale in the format Locale: code, where code is a ISO-639-1 language code, for example, en or de. Some preconfigured email templates, such as the registration template, already include content for the en (default) and fr locales.

To manage email template locales:

  1. In the Advanced Identity Cloud admin UI, go to Email > Templates.

  2. On the Email Templates page, click a template name to open the email editor.

  3. Switch, add, modify, or delete a locale:

    • To switch locale:

      1. Click Locale: code.

      2. Select a locale.

    • To add a locale:

      1. Click Locale: code.

      2. Click add Add Locale to open the Add Locale modal.

      3. Enter a ISO-639-1 language code in the Code field.

      4. (Optional) Select Make Default to make the new locale the default for this template.

      5. Click Save to add the new locale to the template, populated with a copy of the content from the default locale. The changes apply immediately without saving the main template.

    • To modify a locale:

      1. Click Locale: code.

      2. Click the locale’s edit icon (edit) to open the Edit Locale modal.

      3. To change the locale, enter a ISO-639-1 language code in the Code field.

      4. To make the locale the default locale for the template, select Make Default.

      5. Click Save to close the modal window. Any changes apply immediately without saving the main template.

    • To delete a locale:

      1. Click Locale: code.

      2. Click the locale’s edit icon (edit) to open the Edit Locale modal.

      3. Click Delete Locale to delete the locale and its content. The deletion applies immediately without saving the main template.

Delete an email template

Deleting an email template cannot be undone.

  1. In the Advanced Identity Cloud admin UI, go to Email > Templates.

  2. On the Email Templates page, click the More () icon adjacent to any template.

  3. Select Delete.

  4. In the dialog box, click Delete.

Manage email templates

  1. In the Advanced Identity Cloud admin UI, go to Email > Templates.

  2. On the Email Templates page, click the More () icon adjacent to any template, and do any of the following:

    • To disable a template, click Deactivate.

    • To enable a template, click Activate.

    • To duplicate a template, click Duplicate.

      1. In the Duplicate Template window, enter the following details:

        • Template Name: Display name for the template.

        • From Address: Enter an email address for the group or individual sending the email.

        • From Name: Enter a name for the group or individual sending the email.

        • Description: A brief description of the template.

      2. Click Save.

More information