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:
- Working with Email Templates
- Prerequisites
- REST APIs
- List all Templates
- Filter the List of Templates
- Edit an Email Template
- Edit the Body of an Email Template
- Edit an Attribute Value
- Reset an Email Template
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.
|
 |
|
3. Make the API call :
with the following parameters:
|
|
|
|
 |
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. |  |
| 3. Make the call: POST <org>/cc/api/emailTemplate/update with the following parameters:
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. |
 |
|
3. Make the call:
with the parameters:
|
|
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.
