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

If you have experience with base-64 encoding, you can also embed a base-64 encoded file for the image src instead of referencing a URL.

Be aware that embedding an image increases the overall size of your email message. Many email servers block email messages larger than a particular size. To lessen the chance of a bounced email when using embedded images, scale your image down to the same size as your desired height and width settings first, and then base-64 encode the scaled image.

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

The from address is a global setting that applies to all emails sent from IdentityNow, rather than varying by template. You can set a single from address for your whole org, or you can specify one per brand when you configure brands within your tenant.

Important

If you change the from address, use one of the options outlined in Ensuring Successful Delivery of Emails to make sure employees can receive the emails.

Notes

  • You can assign up to 10 from addresses for each org.
  • Each email address can only be used as a from address for one org. If you need to reuse the same email address on multiple orgs, such as a staging org and a production org, contact SailPoint Support.

To change the from address:

  1. Go to Admin > Global > System Settings. The Product Branding page is displayed.

  2. If you have multiple brands defined, select the Brand Identity Attribute for the brand you want to configure. The from address used will be the one specified for the brand the recipient is part of.

    If brands have not been set up, this option will be disabled, and the email address you choose will be used for all users in your org.

  3. Navigate to 'From:' Address.

  4. Email addresses used as from addresses must first be validated. To add and validate a new email address:

    • Select New.

    • Specify an email address and select Add.

    • Check email at that address. You will receive an email from AWS to confirm that you own that email address. Select the link in that email within 24 hours.

  5. Once the email has been validated, choose it from the Select a validated email list to set it as the from address for the chosen brand or for the org.

  6. Select Save.

  7. Repeat these steps for all configured brands.

Removing a From Address

To remove a from address from your org, select the X icon beside it in the All email addresses list.

If the X icon beside an email address is disabled, the from address is in use in one or more of your brands. Select another email for those brands and try the removal again.

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.