Using Email and SMS Templates

This article will show you how to customize email, voice, and SMS templates for OTP, enchanted links, and magic links within Descope flows.

This guide will cover how to utilize a custom OTP email template, but the steps are the same for email, voice, and SMS templates for magic links and enchanted link authentication.

Templates

When you utilize an email connector instead of the Descope system connector, you can create multiple templates for user invitation. The ability to have multiple templates allows you to create tenant or role specific templates to better customize your user experience.

Templates can be created for user invitations as well as email, voice, or SMS messages sent for OTP, magic link, and enchanted link.

Creating an OTP Email Template

To Create an OTP email template, go to the One-Time Password within the Authentication Methods section of the Descope Console, select your connector for email, and then select + New Template

The templates are written via formatted HTML code. When customizing a template, you can utilize {{}} to add dynamic Descope values for the project, user, tenant, etc.

Below is an example of a customized email template with an embedded image.

You can also preview the email by clicking the preview tab.

When sending emails for an OTP, Descope also provides a capability of editing the component in plain text. These are for devices that only support plain text. Just below the Edit mode for HTML, there is a toggle button for viewing and editing component in plain text. This way a Descoper is able to configure the plain text of an email template. Below is an example of this feature.

Once you have configured your template, click Create within the modal.

Template Localization

If you would like to translate your email or SMS to be localized to the user's location, you can set up template localization using the Descope console. Refer to the Localization Configuration Overview for more details.

Using a Custom Template in Flows

To configure your flow to use a custom template, go to the Flows Page and select your desired flow. Once in the flow editor, find the Sign Up or In / OTP / Email action (note that if configuring for magic link or enchanted link, the name will include the other auth method) and select edit. Once you are editing the action, select your desired connector and template, and then save the flow.

You can then test and confirm that the connector and template is being utilized as expected.

Using Template Options (Dynamic Keys)

You can utilize template dynamic keys within Descope flows or the Descope SDKs. These are specific items you may want to pass to the email, SMS, or password reset templates for the various authentication methods.

Use cases range from extra user data within the emails to device information for the location of where the authentication flow started.

Within SDKs

Within all of the Descope SDKs, we have documented the template options flags within the sign up or log in options items. A brief example is below covering sign-up-or-in via magic link using the Node SDK; for specific examples, review the Descope SDK documentation within the applicable auth method guides.

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
const loginId = "email@company.com"
//    uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'
const uri = "http://auth.company.com/api/verify_magiclink"
//    deliveryMethod: Delivery method to use to send magic-link. Supported values include "email", "voice, or "sms"
const deliveryMethod = "email"
//    signUpOptions (SignUpOptions): this allows you to configure behavior during the authentication process.
const signUpOptions = {
      "templateOptions": {
        "deviceOS": "Value",
        "startHostName": "Value2"
        }
    }
 
const resp = await descopeClient.magicLink.signUpOrIn[deliveryMethod](loginId, uri, signUpOptions);
if (!resp.ok) {
  console.log("Failed to initialize signUpOrIn flow")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully initialized signUpOrIn flow")
}

Within Flows

Within Descope flows, click on the message-sending action (SMS, email, password reset, etc.) and click the + for adding template dynamic keys. Below is an example of a modified Magic Link Sign-Up-Or-In action.

Updating the Templates

Once you have configured the template options within the Descope SDK or flow, you can edit your template and use {{options_}} to prepend your template options provided. In this example, we use {{options_deviceOS}} and {{options_startHostName}}. See below:

Example of the received Magic Link email: