cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

API to Configure Email Templates

API to Configure Email Templates

An email template provides a structure to describe the content of an email that will be sent on a specific event. These templates ideally contain necessary information about the event/status/work item that the recipient should know about. A template provides the ability for us to use static text along with some variables in the subject and body of an email. At runtime, IdentityNow will render an email template by replacing variables with proper values.

 

NOTE: All RESTful APIs present in this document can change at any point without notice.  Always refer to this documentation for the latest supported RESTful APIs to complete this operation.

 

For example, when a user is trying to reset his password by email, IdentityNow sends an email with the password reset URL. The template for password reset email could have a line like the following:

 

<p>Click <a href='${resetUrl}'>here</a> to change/reset your password.</p>

 

At runtime, the ${resetUrl} variable will be replaced with an actual password reset URL.

 

In IdentityNow, a number of email templates are used in various parts of the product to notify users of certain milestones. To review the current templates available for customization, refer to the online help.​

IMPORTANT: These APIs are being deprecated in favor of the IdentityNow Platform APIs. Please note that while these APIs will continue to be available for the foreseeable future, SailPoint recommends that you transition to the new versions as soon as possible. For detailed information about all new platform APIs, go to IdentityNow Platform APIs.

 

Working with Email Templates

 

There are a set of REST APIs to read and update email templates. For now, we do not have APIs for create or delete but we can configure a template’s subject or body. There is also an API to reset a template to the default state.

 

Prerequisites

 

  • Sign in to the org as an administrator. Click Admin and use strong authentication to log in.

  • Open your preferred tool for making API calls

 

NOTE: If you're making these API calls, you'll need to use on of our supported authentication methods. As a best practice SailPoint recommends using OAuth 2. Also, the endpoint you use must be changed slightly based on the authentication method. For details, see the Authentication section of the Developer portal documentation.

 

REST APIs

 

The following APIs are available:

 

List all Templates

 

GET /cc/api/emailTemplate/list

 

where <org> is the URL for the customer's IdentityNow org.

 

The JSON that is returned lists the total number of templates under count along with a list of templates.

 

NOTE: The template attributes are returned ahead of the template name or ID.

 

 

Filter the List of Templates

 

You can filter the list of templates by providing the field name, value, and a matching operator (optional).

 

For example, if we want to retrieve the template for password reset email, we can make the following GET request from POSTMAN:

 

<org>/cc/api/emailTemplate/list?filter={property: 'name', value:'Cloud User Verification Token', operation: 'EQ'}

 

NOTES:

  • If an operation is not specified, application uses ‘LIKE’ matching by default. Options include LIKE (Similar to), EQ (Equal), NE (Not Equal), IN (Contains?), LE (Less Than), and GE (Greater Than).
  • Because the template names are known, using the name property is the simplest option for filtering. For a list of names to filter on, refer to the online help for Using Email Templates.

 

/GET <org>/cc/api/emailTemplate/list?filter={property: '<property>', value: '<value>', operation: '<operator>' }

 

where <org> is the URL for the customer's IdentityNow org, <property> is any searchable property of a template, <value> is the value of <property>, and <operator> is one of the operators mentioned in the NOTES above.The JSON that is returned contains the full contents of the template, including the ID which is needed for making edits.

 

 

Edit an Email Template

 

We can configure the subject, body, and values of some attributes. To update a template, we need to provide its ID and only the fields that we want to change.

 

1. Complete the steps described in Filter the List of Templates‌.

 

2. In the results that are returned, find the ID of the template, toward the bottom of the filter results. Refer to the image on the right for an example.


NOTE: The id is unique per template per org.

template id.png

3. Make the API call :
POST <org>/cc/api/emailTemplate/update

 

with the following parameters:

  • id - The value from step 2 above.
  • <template_element> - Specify the changes you want to apply to the specified <template_element> where <template_element> is either subject, body, or ,when available, an attribute defined for the template. 
 


The results return the full contents of the template after it has been edited.


In the example on the right, the edited portion of the template is highlighted at the bottom.

edit template results.png

 

Edit the Body of an Email Template

 

To configure the body of a template, we need to provide its ID and the full body with the requested changes.

 

1. Complete the steps described in Filter the List of Templates.

 

2. In the results that are returned, find the ID of the template. Refer to the image on the right for an example. edit body template.jpg
3. Make the call:
POST <org>/cc/api/emailTemplate/update

 

with the following parameters:
  • id - The value from step 2 above.
  • body - Specify the new content body in total.

 

Refer to the specific IdentityNow email template to see the default body.

 

NOTE: You should copy the current body to a text editor to edit it before pasting the complete body into the call.

 

 

The results return the full contents of the template after it has been edited.

 

Edit an Attribute Value

 

For the User Invite email, we have an UI where users are able to update values of two attributes: REPLY_TO and SLPT_TMPL_SUMMARY. At runtime, IdentityNow renders those attributes with the user-provided values.

 

In addition, you can redefine the values of those two attributes for the User Invite email in the API.

 

CAUTION: While it is possible to make a call to update attribute values for other templates, those calls will have no effect on the rendered email.

 

To update an attribute value, we have to make a POST request with the template's ID, the name of the attribute we want to update, and the new value.

 

1. Complete the steps described in Filter the List of Templates‌ specifically for the Cloud User Invite template.

 

2. In the results that are returned, find the ID of the template, toward the bottom of the filter results. Refer to the image on the right for an example.

 

NOTE: The ID is unique per template per org.
user invite id.jpg

3. Make the call:
POST <org>/cc/api/emailTemplate/update

 

with the parameters:

  • id - The value from step 2 above.
  • attributes - A JSON snippet that contains the following:
[{"name": "<attribute>", "value": "<new_value>"}]Where <attribute> is either REPLY_TO and SLPT_TMPL_SUMMARY and <new value> is any appropriate replacement for the default value described here.

 

For example, the following changes the Reply To email in the invitation to testemailadd@sailpoint.com:

[{"name": "REPLY_TO", "value": "testemailadd@sailpoint.com"}]

 

The results return the full contents of the template after it has been edited.

 

In the example on the right, the edited portion of the template is highlighted at the bottom.

 

Reset an Email Template

 

As we can update template contents now, there might be scenarios where we would like to go back to the default template. For example, a customer might have updated the user invite email template in such a way that we can not show the UI preview anymore. In that case, they might want to go back to default state to bring the preview back.

 

Contact DevOps for assistance.

Labels (2)
Comments

Hi

I miss a section on how to move email templates from the sandbox to production, preferably in bulk.

A bulk transfer/update capability from sandbox to production would be MOST useful. Also, where is the listing of the variables called out in the email templates? I'd like a full listing so I can craft the emails to my liking. 

The beta/sp-config APIs are being built to help move objects from sandbox to production. You can find more information at https://developer.sailpoint.com/idn/docs/saas-configuration

 

Hi All!

While trying to call API for "email template update" using POST option for link "https://allspring-sb.api.identitynow.com/cc/api/emailTemplate/update", we are getting below error. Please Advise. Thanks in advance for checking on it.

 

        {
            "attributes": [
                {
                    "description""account entitlements",
                    "name""accountAccess",
                    "type""List",
                    "value"null
                },
                {
                    "description""account that was created",
                    "name""accountUserName",
                    "type""string",
                    "value"null
                },
                {
                    "description""source on which the account was created",
                    "name""source",
                    "type""string",
                    "value"null
                },
                {
                    "description""identitynow user name",
                    "name""username",
                    "type""string",
                    "value"null
                },
                {
                    "description""Map of AD account attributes.  ONLY SUPPORTED FOR AD.",
                    "name""accountAttributes",
                    "type""Map",
                    "value"null
                },
                {
                    "description""The attribute in the source that's used for the account ID.",
                    "name""accountIdAttribute",
                    "type""string",
                    "value"null
                },
                {
                    "description"null,
                    "name""REPLY_TO",
                    "type"null,
                    "value""patan.firoz@mphasis.com"
                }
            ],
            "body""<font face=\"helvetica,arial,sans-serif\">Hello,</font><p>The ${PRODUCT_NAME} system has created an account for ${username} on the ${source} system. Here are the details about this account:</p><p>User Name: <strong>${accountUserName}</strong></p><p>Access: <br /> #foreach ($access in $accountAccess) </p><li>$access</li> <br />\t#end <p>If you have any questions, contact your administrator.</p><p>Thanks,<br /> The ${PRODUCT_NAME} Team </p>",
            "cc"null,
            "description""Send an email notification containing new account details.",
            "meta": {
                "created""2022-06-29T18:35:41+00:00",
                "modified""2022-11-07T11:30:33+00:00",
                "type""templates"
            },
            "name""Cloud User New Account Notification",
            "state""modified",
            "subject""${source} - Account Created For ${username}"
        }

Hi all,

Please make sure that the APIs that will replace this functionality will still support everything we can currently do with the old APIs (Or at least specifically mention which functionality will be deprecated). In addition, please compare it with other APIs IdentityNow has to ensure that they bahave in a similar way (support pagination, filter, GET/PUT/PATCH/DELETE et cetera), so that IdentityNow will stick to their conventions which increases user experience.

Not all identities should receive all emails. We can achieve this by having an identity attribute (notifySetting) that is "notify" if people should receive emails and "doNotNotify" if they should not. In this case we can replace the subject by the following:

#if( ${user.notifySetting} == "doNotNotify" )no_send#{else}<subject>#end

Also please make sure that this page gets updated whenever needed (or alternatively update documentation.sailpoint.com and deprecate this page with a link to the new documentation). SailPoint Support is still sending this link to us.
Please ensure that the new APIs will continue to support this functionality, both for version 1 templates AND version 2 templates.
Version history
Revision #:
8 of 8
Last update:
‎Oct 29, 2022 10:39 AM
Updated by:
 
Contributors