20.2. Email Templates

Email templates are a powerful instrument to customize layout and content of email messages. Templates are defined as XML files, and are located in the /opt/savapage/server/custom/template/ directory by default (alternative locations can be configured).

Default templates are present in the SavaPage i18n jars. Therefore, after a first-time installation the custom template/ directory will be empty. However, when SavaPage finds a suitable i18n XML file in the custom directory, that belongs to an Email Message Type, it will use that template.

You can create i18n variants of template XML files by appending the locale to the base file name. For example: template_de.html is the German variant of template.xml.

20.2.1. Email Template Syntax

The base syntax of an Email Template[41] is described by example in the following XML file:

<?xml version= "1.0" encoding= "UTF-8" ?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> 1

    <!-- $obj.attr$ placeholders are replaced at runtime --> 2

    <!-- TEXT --> 3
    <entry key="text"><![CDATA[Text with $obj.attr$ placeholders.]]></entry>

    <!-- HTML --> 4
    <entry key="html"><![CDATA[<b>HTML</b><p>
      with $obj.attr$ and other placeholders</p>]]>



DTD of XML persisted java.util.Properties file.


Placeholder object attributes are identified by a $ character at the beginning and the end. Valid objects are defined for each Email Message Type. The global Application Object is valid for all types.


Content for plain text message body.


Content for html message body. Embedded Images

HTML content may contain Embedded (Inline) Images.

Images are first defined in separated template entries with keys that have cid_ prefix. Those keys can then be used as placeholders for cid scheme values. SavaPage email processor will embed the image file and replace cid placeholders with a unique Content-ID for the Embedded (Inline) Image.

Custom image files are referred to by their relative path from the custom template/ directory. Internal stock images can simply be referred to by their upper-case identifier, as shown in the table below.



SavaPage Icon: 32 x 32 pixels, 705 bytes.


SavaPage Logo with "SavaPage" text at the bottom: 148 x 174 pixels, 5.6 kB.

Table 20.1. Stock Image Identifiers

The XML snippet below shows how it works:

<entry key="cid_1">SAVAPAGE_ICON</entry>           1
<entry key="cid_2">images/mysite-logo.png</entry>  2

<entry key="html"><![CDATA[
  <img src="cid:$cid_1$" alt="$app.name$">         3

  <a href="https://mysite.xyz">
    <img alt="mysite.xyz" src="cid:$cid_2$"/>      4 



cid_1 holds a stock image.


cid_2 holds the relative path to a custom image file.


Note that the URL of the image has scheme cid. SavaPage email processor will embed the image and replace $cid_1$ with a unique Content-ID for the Embedded (Inline) Image with key cid_1.


The cid_2 image is handled just as its cid_1 sibling.

20.2.2. Email Stationary Template

An Email Stationary Template is used by an Email Message Template as container to embed its content in. A stationary is typically used by many Email Messages Types, and thus gives a common look-and-feel to various email output.

A Stationary Template contains the following placeholder objects:

And this is how it looks like:

<?xml version= "1.0" encoding= "UTF-8" ?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">


    <!-- TEXT -->     
    <entry key="text"><![CDATA[Plain text with $stationary.header$  1
$stationary.content$ and additional app placeholders]]></entry>     2

    <!-- HTML -->
    <entry key="html"><![CDATA[HTML with <b>$stationary.header$</b>
      <p>$stationary.content$ and additional cid_ and app placeholders</p>]]> 3



$stationary.header$ is replaced by the header entry of the embedded template.


$stationary.content$ is replaced by the text entry of the embedded template.


$stationary.content$ is replaced by the html entry of the embedded template.


SavaPage uses its own stationary types. These types can be overwritten. See Section 20.2.5, “Email Stationary Types”.

20.2.3. Email Message Template

Email Message Templates are used by Email Message Types.

Template and Type are tied by name.

For example: the JobTicketCompleted message type will look for the nearest i18n version of a JobTicketCompleted.xml template file. In this way, JobTicketCompleted_de.xml will be the perfect match when a German email message is requested.

Email Message Template adds the entry key subject to the syntax. Optionally, entry keys stationary and header can be used to link to an Email Stationary Template.

The syntax is described by example in the following XML file:

<?xml version= "1.0" encoding= "UTF-8" ?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">

    <!-- Email subject -->        1
    <entry key="subject">Text with $obj.attr$ placeholders</entry>
    <!-- Optional stationary -->  2
    <entry key="stationary">EmailStationary</entry>
    <entry key="header">Stationary header with placeholders</entry>

    <!-- TEXT -->     
    <entry key="text"><![CDATA[Plain text with placeholders.]]></entry>

    <!-- HTML -->
    <entry key="html"><![CDATA[<p>HTML with placeholders.</p>]]></entry>



The subject text of the email.


The stationary value (just the template file basename, without the .xml suffix) refers to EmailStationary.xml, including i18n EmailStationary_*.xml variants. When a stationary is linked this way, the header value is injected into the stationary.header placeholder of the target stationary, and the text and html values are injected into the stationary.content placeholder of their counterpart stationary entry.

20.2.4. Email Placeholders Objects

Placeholder Objects are used in Email Stationary, and in Email Message Templates tied to Email Messages Types. Stationary

Object uniquely used by Email Stationary Template.



The header entry of the embedded template.


The text or html entry of the embedded template.

Table 20.2. Placeholder: Stationary Application

A global object with SavaPage application attributes. This object can be used in any Email Message Type context.



Application name: SavaPage


Formatted name and version, like:

SavaPage Major.Minor.Revision


Formatted name, version and build, like:

SavaPage Major.Minor.Revision (Build)


Short slogan describing the application:

Open Print Portal

Table 20.3. Placeholder: Application Ticket

A Print Job Ticket. See Chapter 5, Job Tickets Web App.



Ticket number.


Document name.


Name of the Job Ticket Operator.


The return message to Job Ticket Creator (optional).

Table 20.4. Placeholder: Ticket User

A User as Person.



The full name of the user.

Table 20.5. Placeholder: User

20.2.5. Email Stationary Types

SavaPage uses its own Email Stationary Types. As the table below shows, currently there is just one type in use. You can use this type in your own custom Email Message Template files. Or, you can override this type by creating your own EmailStationary.xml i18n variants in the custom template/ directory.



All Email messages

Table 20.6. Email Stationary Types

20.2.6. Email Message Types

The sections below describe email message types that can be customized. The list is limited for now, but will grow as more messages are refactored for this purpose.


The global Application Object is valid for each message type. JobTicketCanceled Email

Email sent when a Job Ticket is canceled. See Table 3.7, “Job Ticket Print Configuration Properties”.

The following placeholder objects apply:



Canceled Job Ticket.


Job Ticket Creator.

Table 20.7. Placeholder Objects: JobTicketCanceled JobTicketCompleted Email

Email sent when a Job Ticket is completed successfully. See Table 3.7, “Job Ticket Print Configuration Properties”.

The following placeholder objects apply:



Completed Job Ticket.


Job Ticket Creator.

Table 20.8. Placeholder Objects: JobTicketCompleted

20.2.7. Custom Template Locations

Custom templates are located in the /opt/savapage/server/custom/template/ directory. Sub-locations can be defined for different template groups. These sub-locations can then be activated for different applications, with the following configuration properties:

Configuration propertyDescription


Home location of all template files, relative to the default location. For example: a value of group-1 will resolve to:



Home location of Email template files, relative to the default location. For example: a value of group-1/mail will resolve to:


Table 20.9. Configuration Properties for Custom Template Locations

See Section 4.11.14, “Config Editor” on how to set these items.

[41] Email Template syntax is based on StringTemplate.