Setting up a message template with an email confirmation code

On this page:

1. Overview
2. Regulations modeling

1. Overview

To enable email notifications, the user must first confirm their consent to use the email communication channel. This way, the user verifies the exchange of data (email messages).

The confirmation of a communication channel is based on a data verification mechanism that uses a pseudorandom 6-digit OTP^[1] code that the Platform generates and sends to the email address specified by the user.

An email message with an OTP code is also a notification that requires a configured template in the registry regulations structure.

2. Regulations modeling

The base registry-regulations deployment repository includes the channel-confirmation directory containing an email message template with a placeholder for an OTP code that the Platform generates and sends to the email address specified by the user.

The message template must be created in HTML using the Apache FreeMarker template language. The recommended practice is using the .ftlh file extension for HTML templates and .ftl for regular text documents.

To learn more about Apache FreeMarker, refer to https://freemarker.apache.org/

A typical email message template has the following structure:

Where:

channel-confirmation is the directory containing the template resources.
channel-confirmation/css/style.css is a unified CSS file that contains the styles used in the HTML document. For example: <link rel="stylesheet" href="css/style.css">
channel-confirmation/image/*.* contains image files used in the HTML document. For example: <img src="images/image.jpg">

channel-confirmation/notification.ftlh is the HTML template used to generate the message body. The template contains a placeholder for an OTP code.

An HTML template used to generate the message body with an OTP code placeholder

<!DOCTYPE html>
<html lang="uk">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div class="header">
        <div class="logo-wrap">
            <img src="image/trident.jpg" alt="Diia" class="logo">
        </div>
        <div class="platform-name">Registry<br>Platform</div>
    </div>
    <div class="main">
        Verification code: ${verificationCode}
    </div>
    <div class="footer">
        <br>
        Contacts or service information
    </div>
</body>
</html>

channel-confirmation/notification.yml is the configuration file with OTP code email metadata.
Example 1. A configuration file with OTP code email metadata
title: "Email confirmation"

The generated 6-digit pseudorandom code (for example, 345870) will be automatically emailed to the user for verification and confirmation when they enter or change their email address in their citizen portal profile.

For details, see Confirming email address with OTP code in user profile.

After updating the registry, the regulations administrator must manually add the channel-confirmation folder with the corresponding confirmation template files to the notifications/email directory, as shown in the examples above.

1. A one-time password (OTP) is a password that is valid for only one authentication session. Its validity may also be limited to a specific time interval. The advantage of such a password over a static one is that it cannot be reused.