Skip to content

Using Email Templates

Email notifications are sent to users by IdentityNow to inform them of system or process status changes, to alert them to assigned work, and more. You can customize notification messages using variable values provided by the system through a fixed set of variables specific to the notification and global variables available across multiple email templates.

SailPoint's email templates are defined using the Apache Velocity templating syntax. This allows the emails to support variable substitutions as well as simple logic like conditional contents.

Editing the Email Contents

You can customize the subject and body of your email notifications by editing the templates.

  1. Go to Admin > Global > Email Templates. Choose the email template you wish to edit.

  2. Edit the Subject and Body text to meet the needs of your organization.

    • Emails are HTML-enabled. You can edit text in the default WYSIWYG editor or select the Source Edit icon to edit the message as HTML.

    • Review the variables available to each template and reference them as needed in the message contents using the appropriate Velocity variable syntax.

    Note

    The WYSIWYG editor cannot render tables. If the email template includes a table, you can still edit the HTML source for the template. To reenable the WYSIWYG editor, remove table references by deleting all blocks between <table> and </table> tags.

  3. Select Save and then test the email to verify that your content appears as expected.

Important

Once you customize an email template, it is not updated when SailPoint makes changes to the default template text, even if you manually restore the template contents to the default text. To reset a customized template to the default settings so that any future template updates will be auto-applied, you must contact SailPoint Support.

Specifying Variables

Many variables passed to email templates are simple text variables. To include their values in the email message, use the syntax: ${<variableName>}, such as ${approverName}.

Some variables are objects containing multiple properties or fields. To reference those properties in an email template, use the syntax: ${<objectVariable>.<property>}. For example, if you want to reference the user's work phone number in an email, you would enter ${user.workPhone}.

Refer to the Apache Velocity guide for more syntax details.

Permitted HTML Contents

Email template are validated by an HTML sanitizer that enforces a list of allowed HTML elements and attributes.

  • Allowed elements:
    • Basic elements: body, img, html, a
    • Block elements: p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote
    • Formatting elements: b, i, font, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em
    • Table elements: table, tr, td, th
  • Allowed attributes within elements:
    • All elements support the style attribute.
    • All basic, block, and table elements support the id attribute.
    • The img element also allows src, alt, height, and width attributes.
    • The a element also supports the href attribute.

Comments, including conditional comments, are not supported.

Using Images in Email Templates

To insert an image into an email template:

  1. Find the section(s) of the email where you want the image to appear.

    If the Velocity scripting in the email includes conditional content based on system and user data, you might need to add the image to multiple sections of the template body.

  2. Identify the URL of a hosted image reference.

    Best Practice

    When adding logos to email templates, you may use any external internet-accessible image, but SailPoint recommends using the logo image you used when customizing your UI.

    To use this image, right-click the logo in the upper-left corner of your IdentityNow site and choose Copy image address to copy the URL. Note the exact menu label, such as Copy image address/link/location, depends on your browser.

  3. In the email template, use tagging like:

    <div><p style="text-align:right"><img src="[URL]" width="150" ></p></div>

    where [URL] is the URL from step 2 above.

    This example, specified as the first line of the email template body, adds the image at the top right of the message above the text.

    Notes

    • You can add the HTML for an image directly in the WYSIWYG editor or through the HTML source editor.
    • Unless you are certain of your image’s dimensions, it is best to specify only a width or a height and allow the image to auto-scale accordingly.

  4. Select Save and then test the email to verify that your content appears as expected. 

Embedding Base 64 Encoded Files

You can also embed a base-64 encoded file for the image src instead of referencing a URL. Encoded image formats must be one of the following content/types:

  • data:image/jpeg
  • data:image/jpg
  • data:image/png
  • data:image/pdf
  • data:image/gif

Use caution when embedding base-64 encoded files:

  • Some browsers do not support embedded images that use the data URI scheme.
  • Some email clients default to filtering out encoded images.
  • Embedding an image increases the size of your email message. Many email servers block email messages larger than a particular size. To avoid bounced emails, resize the image to your desired height and width before base-64 encoding.

Setting a Reply To Address

Each template can have its own reply-to email address, specified in the Reply To field on the template's configuration page. This determines the email address that appears in the To field when a user replies to an email sent from IdentityNow. This lets you direct users to the right enterprise contacts for help with a topic or process.

Note

Even when you customize the 'From:' address for your notifications, the Reply To field on each email template always displays the default no-reply@sailpoint.com for templates where it has not been overridden. Templates that do not have a customized reply-to address will automatically use the configured 'From:' address as the reply-to address when emails are sent.

Setting the 'From:' Address

'From:' addresses are set globally for all emails sent from IdentityNow, for the whole tenant or per brand, rather than as a per-template configuration.

Testing Email Templates

Test any email templates you have changed to verify that the content will display as intended when they are sent to your system users. You can do this per email template after you save changes.

  1. Go to Admin > Global > Email Templates.

  2. Choose the desired email template, edit as needed, and select Save.

  3. Select Test Email. The email message will be sent to the email address of the logged-in user.

Notes

  • Only global variables render within the generated test email. The other variables are populated by the process that triggers the email and are null in the email test.
  • Conditional sections of the message are not included in the test emails.

Redirecting Emails

In non-production tenants, admins commonly redirect all emails to a test address rather than allowing them to be sent to business users. To configure this redirection:

  1. Go to Admin > Global > Email Templates.

  2. Navigate to the bottom of the list and select Email Config.

  3. Choose Test Address:, enter the email address you want to use, and select Save.

An audit event is created whenever the test address is changed.

Caution

Use this option with care in a production environment. All emails will be redirected until you return to this page and choose Intended Recipients.

Stopping Automated Emails

Some system notifications can be enabled or disabled through process configurations. For example, you can choose to send or suppress emails related to:

You can also prevent IdentityNow from sending emails on a per-email-template basis by specifying any of the following keywords as the first word in the template’s Subject field:

  • #stop
  • no_send
  • Stop

Best Practice

Leave the rest of the subject text intact to simplify future reinstatement of the template.