Skip to main content

Email templates

Email templates are prepared email messages, containing subject, HTML and text content, with variables, placeholders and template code that will be processed and replaced when an email is sent.

Email templates can be previewed from the Editor menu of an individual Email template.

Import/Export​

Email templates can be imported/exported to/from Trivore Identity Service. These templates are saved as JSON files. All field names in the JSON file will correspond to the field found in the Email template editor.

Example​

email-template.json
{
  "meta" : { },
  "name" : "Hello world",
  "description" : "Test",
  "templateEngine" : "VELOCITY",
  "defaultLocale" : "fi",
  "defaultTimeZone" : "Europe/Helsinki",
  "subjectTemplate" : "$subject",
  "htmlTemplate" : "<html><body><h1>Dear recipient</h1></body></html>\n$recipientUser\n\n$verificationUrl",
  "textTemplate" : "$heading\n\n$content",
  "localeProperties" : {
    "fi" : {
      "heading" : "Hei",
      "subject" : "Mitä kuuluu",
      "content" : "No eipä mitään tässä."
    },
    "en" : {
      "heading" : "Hi",
      "subject" : "How are you",
      "content" : "Eh, nothing much going on."
    }
  },
  "namespaceIds" : [ ]
}

Locale = Language​

During template processing the used Locale becomes important. It is used for example when choosing a translation, or how a date or time representation is generated.

A locale can consist of several parts, but the most important is Language. It can also contain a Country. These parts are often shown like this: en or en_US. The first locale contains only a language (English) while the second locale specifies also a country (American English). If you need to customise the translations for different regions, you can do that by adding the country to the locale.

If you add Locale specific properties, you should also specify a default Locale in your template. It is used if no other locale is selected when the email is being processed. Using locales and properties allows for easier creation of email templates as a single property can have multiple languages.

Template engines​

Templates can be written as-is, but likely you will want to add dynamic content. Dynamic content may be parameters in links, the recipient’s name, or even the whole content using translations. How these dynamic parts are defined depends on the selected template engine.

You can use templates in the subject, HTML and text content. They will all be processed identically. It is up to you to make sure the templates are valid and produce valid output.

Apache Velocity​

TIS supports templates written for Apache Velocity 2.2. The Generic Tools 3.0 package is included with standard tool names.

You can reference properties using the $ prefix followed by the property name. If the property has sub-properties, you can chain the names together separated by . period characters.

For this reason you cannot have period characters in property names.

Example:

Template
Hi ${recipientUser.firstName}!
The time and date is currently ${date.systemDate}.
Your email is $recipientEmailAddress.
Rendered as
Hi Sue!
The time and date is currently Fri Mar 13 14:42:23 EET 2020.
You email is [email protected]

There are many options and tools you can use to create dynamic content. Check the links below for more information.

Variables in translations​

With Velocity you can have property references and dynamic content in properties, including locale properties (the translations). You can use $render.eval() method to “evaluate” these parts in properties before they are displayed.

Example:

Properties
firstname=Sue
subject=How are you ${firstname}?
Template
<h1>
$render.eval($subject)
</h1>
Rendered as
<h1>
How are you Sue?
</h1>