Updating email templates in Asgardeo using APIs

With the increased security threats in the digital world, providing a secure authentication and authorization mechanism has become an essential requirement. Due to that, managing a large user base while providing security has become a burden for the developers. Asgardeo was introduced to help developers implement secure authentication flows to apps or websites in a few simple steps. It is the modern IDaaS (Identity as a Service) solution introduced by WSO2 by improving the developer experience.

Asgardeo is available for everyone to tryout. If you haven’t already registered, go to https://asgardeo.io/signup and create your own account. You can refer Asgardeo documentation for more information. When you create an asgardeo account, an organization will be created for you and it will be set as the default. If you need to have multiple organizations, that can be achieved through the Asgardeo console.

If you have some experience with Asgardeo, you should have observed that there are multiple emails send for the users in your organization when trying out user related flows such as user registration, password reset, account lock etc. By default, the styles of those email templates are similar to Asgardeo theme.

So, let me explain the issue we are addressing here and how we are doing that.

The Problem

When you want someone to register in your organization or consume the applications provided by your organization, the user needs to create an account or you can invite the user to register. Here, the user will receive an email containing information on how to get them registered. If this email looks different compared to the organization brand (i.e colour palette, fonts, logo etc.), it will be a bad experience for the users and they will get an insecure feeling. This will be the same for other scenarios as well like password reset, account lock/unlock etc.

The Solution

As a solution for the above problem, you can update the email templates as you wish or according to your organization brand, which will give a sense of security and a good user experience to the users.

This blog explores on how to achieve this in Asgardeo using the Email Templates Management API.

Update email templates using API

For the ease of explanation, I will separate this task into two steps as follows.

  1. Generate access tokens
  2. Update email templates

Generate access tokens

To view and update email templates using APIs, the first requirement is to have an access token with required permissions. In Asgardeo, if you need to configure organization settings using any management API, you have to create an access token. It can be done by providing the client credentials and the required scopes.

Since we are going to use the email templates management API, we need to provide following scopes when requesting for a access token in order to view and update email templates.

  • To view email templates — “internal_email_mgt_view”
  • To update email templates — “internal_email_mgt_update”

Follow the below steps to create an access token, which will be used to invoke the API.

  1. Go to the Asgardeo console and navigate to Develop -> Applications.
  2. Click new application and select Standard-Based Application.
  3. Provide a name for the application, select “OAuth2.0 OpenID Connect” as the protocol, select the Management Application checkbox and click on Register.

4. Once you successfully create the application, you can see the Client ID and the Client Secret in the protocol tab of your application. Make a note of those.

5. Make sure that Client Credential is selected as the Allowed grant type.

Note: Client ID and Client Secret are sensitive information that should be protected. Anyone with those information can generate access tokens with the access level of the admin of the organization.

6. Now you can generate the access token using the below CURL command.

curl -X POST \
https://api.asgardeo.io/t/<org_name>/oauth2/token \
-u '<client_id>:<client_secret>' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=<scope>'

Replace the <client_id> and the <client_secret> with the values you obtained in above steps and <org_name> with your organization name. Provide the <scope> as “internal_email_mgt_view” and “internal_email_mgt_update”.

Sample request:

curl -X POST \
https://api.asgardeo.io/t/myorg/oauth2/token \
-u 'tOym9SimOJEIDOSNpI0OSAfHZwgaYi:tOym9SimJDYWICMApI0MYfHZwgYUa' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=internal_email_mgt_view internal_email_mgt_update'

Following is a sample response you get which consists of the access token.

{
“access_token”: “4e12kee8–4782–3er5–972a-rw13vf35e630”,
“scope”: “internal_email_mgt_update internal_email_mgt_view”,
“token_type”: “Bearer”,
“expires_in”: 3600
}

If you are sharing this access token with another developer, you can mitigate the risk of misuse by giving only the required scopes for the specific task as above. Further, you can reduce the expiry time of the access token by updating the “Application access token expiry time” in your application (protocol tab) through the Asgardeo console before generating the token.

Update email templates

You can use the generated access token as the Authorization bearer header to invoke the Email Template Management API. You can use the following CURL commands to update the email templates.

  1. Get all email template types
curl — location — request GET ‘https://api.asgardeo.io/t/<org_name>/api/server/v1/email/template-types' \
— header ‘Authorization: Bearer <access_token>

Using the response, you can locate the endpoint of the email template type to be used in the next request.

Sample response:

{
“id”: “QXNrUGFzc3dvcmQ”,
“displayName”: “AskPassword”,
“self”: “/t/<org_name>/api/server/v1/email/template-types/QXNrUGFzc3dvcmQ”
}

To give a clear explanation, I will consider “AskPassword” as the email template that I need to update.

2. Get the list of email templates for the template type you need to update.

curl — location — request GET ‘https://api.asgardeo.io/t/<org_name>/api/server/v1/email/template-types/{template-type-id}/templates' \
— header ‘Authorization: Bearer <access_token>

Since I’m using “AskPassword” as the template type, {template-type-id} should be “QXNrUGFzc3dvcmQ” according to the above response.

Sample response:

[
{
“id”: “en_US”,
“self”: “/t/<org_name>/api/server/v1/email/template-types/QXNrUGFzc3dvcmQ/templates/en_US”
}
]

3. Get the full template for the template id retrieved above.

curl — location — request GET ‘https://api.asgardeo.io/t/<org_name>/api/server/v1/email/template-types/{template-type-id}/templates/{template-id}' \
— header ‘Authorization: Bearer <access_token>

According to the above response, {template-id} should be “en_US”.

Sample response:

{
“contentType”: “text/html; charset=UTF-8”,
“subject”: “Here is your new account in the organization {{tenant-domain}}”,
“body”: “HTML BODY”,
“footer”: “---”,
“id”: “en_US”
}

4. With the above request, you received the current body of the email template that you need to update. Change it according to your requirements. Use following request to update the email template.

curl — location — request PUT ‘https://api.asgardeo.io/t/<org_name>/api/server/v1/email/template-types/{template-type-id}/templates/{template-id}' \
— header ‘Authorization: Bearer <access_token>’ \
— header ‘Content-Type: application/json’ \
— data-raw ‘{
“contentType”: “text/html; charset=UTF-8”,
“subject”: “Here is your new account in the organization {{tenant-domain}}”,
“body”: “Updated HTML BODY”,
“footer”: “ — -”,
“id”: “en_US”
}’

Congratulations! 🎉 Now you are done with updating the email template according to your requirements. Try out the related flow and see whether you get the emails with the updated styles. You can find the postman collection for the above requests here. For more information on using Email Templates API, refer to the Asgardeo official documentation.

There are more Asgardeo features and improvements on the way. Stay tuned! 😍

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Rashmini Naranpanawa

Rashmini Naranpanawa

Software Engineer @WSO2 | Graduate @Department of Computer Science and Engineering, University of Moratuwa