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.
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.
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.
The following APIs are available:
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.
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:
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.
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:
|
|
|
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. |
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.
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.
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.
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: