To help provide a more cohesive experience for your user base, FastComments provides an email customization solution so that the emails sent to your customers, from FastComments, can match your branding.

In this documentation we will cover the features of this solution, the template language, localization, and more.

Template Language Internal Link

FastComments Email Templates uses the EJS template language.

Example syntax is <%= object.someValue %> to print variables, and conditional statements can be done as so:

<% if (some_condition) { %>
    <div>Some content.</div>
<% } else { %>
    <div>Some other content.</div>
<% } %>

Printing raw HTML, like for the comment content, is done like so: <%- comment.commentHTML %>. Note the - instead of the =.

Refer to the above link for further documentation on syntax.

Localizing and Custom Text Internal Link

FastComments is a localized platform. All of our widgets, emails, and notifications are localized.

Localized means that we show a different language, and formatting, based on the user's location and preferred language. We determine this based off the information the user's browser provides us.

We can customize the text in the email by going to the Translations tab, selecting a Locale and editing the text. Text that is changed from the default is outlined in the UI. You may switch between locales and save at the end, without losing changes.

Localized text is accessed via the TEXT object, for example: <%= TEXT.INTRO %>.

SSO Note

For SSO integrations, if locale is not specified, it will be updated every time the user accesses the comment widget with a different locale. This means their language preference is automatically updated, and future emails will be sent in that locale.

This can also be set manually by providing locale in the SSO payload.

Per-Domain Templates Internal Link

Templates can be setup to be global - across your entire tenant for that template type, or per-domain. In the Settings tab select the desired domain.

Note that if you set up multiple templates for the same domain, only the first is picked at runtime. The templates list will warn you when this situation occurs.

Data and Variables Internal Link

Each template works within a different context, meaning different data is available.

A quick at-a-glance way to see what data is available is to check the test data provided for the template. When editing a template, click the Test Data tab to see a JSON structure.

We can also customize the test data in this area, to see how our template looks in different situations. The test data can be reset back to the default with the Reset button.

Render Failures Internal Link

Since email templates support variables, and logic, it is possible to create templates that fail to render, or sometimes fail to render.

This can be very frustrating to diagnose and debug, especially if it is an intermittent issue, or if it only occurs when the data looks a certain way.

To help, FastComments Email Templates has a couple features:

  1. If the template fails to preview, it cannot be saved. An error message will be shown.
  2. Template render failures are tracked and reported on in the admin UI.

The second bullet is describing render failures that happen in production. As in, you create a template which previews fine - but later fails for some reason. For example, if we have this in our template:

<% if (comment.commenterEmail.includes('test') { %>

This may fail sometimes if we have anonymous commenting enabled, since email will not always be available. So how do we find out about that?

The answer is that errors are surfaced in two places. First, the template list itself shows a render error count with each template.

Then, when viewing a template we can see a count, per-error, of the number times the template has failed to render.

A reset button is located next to each error, and its count, so that we can reset the counter after we have resolved an issue.

Applying Changes Internal Link

Creating and editing email templates is immediate. This means, the second you hit the Save button, the platform will start using the latest version of that email.