Email templates reference - Tizra/Tizra-Customer-Tracker GitHub Wiki

Setting Custom Templates

Tizra can customize and configure a lot of individual types of email. The relevant settings are in the email tab of the Settings main admin tab. You can edit each email template. There is a popup menu of specific messages, pick one and the current value shows up for editing. The system send emails on the following events: account status change, account creation, account deletion, license addition/deletion to an account, password change, account verification (when email validation is on), and registration, etc.

You can revert a template to the system default. (This is a good idea when you are customizing for the first time, as the system default may have changed after the site went live). to do this, select a template, delete the entire content and save it. The template will revert to the system default value.

Mail template format

Mail templates start with headers which control the email delivery. These look a little like standard email headers, and many of them generate standard headers, but they are not exactly the same as the headers you see in email clients, so you should be careful in using them.

Like internet email headers the format is headername followed by ": " followed by the value, so a header To: with the value [email protected]

To: [email protected]

If you delete the entire content of a mail template, it will revert to the system default. If you delete the body of the template, it will be delivered to whoever is in the header (To, etc) but the email will be blank.

Specific headers
To:
From:
Subject:
Cc:
Bcc:
Html: true
SuppressEmail: false

They are case sensitive. Unlike standard email headers, blank lines are ignored between headers. Rather than the first blank line signalling the end of the mail header, our template header processing stops once the first non-blank line is read that could not be a header. That line and the rest of the lines then go into the the email. (This does mean that you can't start your email with a blank line).

The Html: true/false header lets you indicate whether the email should be packaged to the email server as HTML or plain text.

The SuppressEmail: true/false header lets you indicate whether actually sending the email should be prevented, on a template by template basis.

If you want to set more than one value in an address header, you must replicate the header. You can only replicate the To:, Cc: and Bcc: headers. example:

To: [email protected]
To: [email protected]

Multiple addresses in a header will not work. If you have two Subject: headers, the last one will be used. This won't work:

To: [email protected], [email protected]

There is a special email value -- not a variable -- called email.admins. So if the following appeared in a template, all site administrator accounts would be notified:

To: email.admins

Again, this is not a variable, if you try to use ${email.admins}, it will not work.

The entire template is implemented using a language called "freeMarker" which is pretty common in the java world. We currently use version 2.3.18. You can get documentation here:

This is the same template language used to substitute variable names in offers and so forth.

The "Template Model" we provide for email is a simple set of predefined variables available for all templates, as well as certain special variables (like the list of purchases) as required for various notifications.

All the headers are processed by the template language, not just the body of the email -- so you could, for instance, look at a property of a user and Cc a different person depending on that property, using freemarker [#if ] [/#if] for instance.

Any special variables available to each template are described in a freemarker comment [#-- --] at the top of the default template values.

Some values are available in all emails if you want them:

  • `address.adminAddress` -- generic Tizra administrator. Used currently for emailing users on many account update/admin type tasks. (currently: [email protected])

  • `address.supportAddress` -- generic enduser support address (currently: [email protected])

Some other global variables:

  • siteholds a description of the site, and has various fields:
    • site.hostname (default host name of the site)
    • site.homepage (url of the home page minus the trailing slash)
    • site.name (Name of the site, as configured in the admin panel)
    • site.email (contact email address specified in site properties)
    • site.address (physical address, etc. from site properties)
    • site.adminHostName (the permanent site hostname that you use for CNAME records)

Other From: Addresses and To: addresses

From addresses in the default templates are not completely consistent. They are set as originally implemented, because there are email filters, etc. that currently depend on them. If you are tailoring emails, you will want to think about who mail comes from, and probably make sure that that address has someone checking for email replies, as users will do that, even if you try to tell them not to.

The following two special values are more related to Tizra's core and you will not see these in most templates -- if you do, you can leave them alone.

  • address.serverAdmin -- the name of the person responsible for the administration of the Tizra servers. This is mostly used to make sure that error reports reach us. If you see this in a template please don't remove it. Similarly, don't add it, as some mail to it may actually trigger someone's cell phone.

  • address.siteAddress -- the origin address for emails to site owners about site updates, host name changes, etc. Also an address where Tizra receives reports and information.

Other things you might see in templates

various variables (like supportAddress). These are actually shorthand references to values set into system settings files for the whole server.