Email templates

Email license requirements

The license tier required for email features depends on the size of the email channels that you use:

  • Email microchannels – available for all license tiers
  • Standard size email channels – require the Advanced license tier

To learn more, see the description of the Channel size property for email channels.

Email templates define the overall layout of emails and add fixed content, such as a header or footer. You can reuse a single template for any number of emails. The template content is defined through HTML code and CSS styles. In many cases, the template code can be prepared in an external tool by a designer and then copied into Xperience. 

The basic template code needs to be extended by adding macros, which serve as placeholders for the fields of email content types, as well as system elements such as a regular email’s unsubscribe link URL.

The following diagram shows the structure of a sample email, with the template including pieces of content loaded from individual email fields.

Email template containing individual email fields

Email content types

Before you start creating email templates, you need to have exact knowledge of your email content types and their fields, as well as any linked content types used within.

Email templates display content from specific fields, so they are only compatible with content types containing these fields. For this reason, you need to configure which email templates are allowed for every email content type. You can assign templates when editing content types on the Allowed templates tab, or add allowed content types from the other side of the relationship when creating or editing email templates.

Configuration of rich text fields for emails

When creating text fields for email content types using the Rich text editor form component, we recommend using an empty (unselected) value for the component’s Configuration name setting. This allows the system to dynamically load the editor configuration based on the current email’s Purpose, i.e., the Email content configuration for regular and confirmation emails, and Email content (Form autoresponder) for autoresponder emails.

The Email content (Form autoresponder) editor configuration contains the additional Insert Double Opt-In Link toolbar button, which is only relevant for form autoresponder emails.

If you wish to use a custom editor configuration, you may need to create a separate configuration and content type for each email purpose.

Create email templates

  1. Open the Email templates application in Xperience.
  2. Select New email template.
  3. Fill in the template properties:
    • Email template name – the name of the template displayed in Xperience (for example when selecting the template for an email).
    • (Optional) Identifiers – specify the code name if you wish to use a code name different than the pre-filled value.
    • Description – allows you to add information and comments about the template. Only displayed to other editors in the Xperience administration.
  4. Select Save.
  5. Write or copy the HTML and CSS code of your template into the Source code area.
  6. Save again.
  7. On the Allowed content types tab, Select content types.
  8. Use the checkboxes to allow compatible content types for the email template.
  9. Select Save.

The basic template is now ready, but cannot yet display content from emails in Xperience. Continue by adding macros into the template.

You can assign the template when creating emails of allowed content types in email channel applications. You can reuse a template for any number of emails.

Email template macros

Email templates must contain macro expressions, which serve as placeholders for various kinds of email content.

The following macros are available for email system fields:

  • {% unsubscribeurl %} – can be placed into templates for emails with the Regular purpose. Resolves into the unsubscribe URL based on the settings of the email using the template. Position the placeholder into the href attribute of a suitable link tag, for example within the footer of your email template. See Send regular emails to subscribers for detailed information and instructions.

    HTML
    Unsubscribe link example
    
    
      <p>
          If you'd rather not receive future emails, <a href="{% unsubscribeurl %}">unsubscribe here</a>.
      </p>
    
      
  • {% previewtext %} – resolves into the Preview text of emails that use the template. Most email clients display a content preview, showing the starting characters of the email’s body. Insert this placeholder after the template’s opening <body> tag. Adding a hidden preview text placeholder allows editors to control the preview text, without needing to adjust the visible email content and design.

    HTML
    Preview text placeholder example
    
    
      <body>
      <!-- HIDDEN PREVIEW TEXT -->
      <div style="display: none; font-size: 1px; color: #ffffff; line-height: 1px; max-height: 0px; max-width: 0px; opacity: 0; overflow: hidden;">
         {% HTMLEncode(previewtext) %}
      </div>
    
      ...
    
    
      

Content type field macros

Add {% fieldname %} macros to position the content of individual content type fields. Use the exact Field name (not the Field caption). For most field data types, the macro returns the field’s value as text.

Email template macro reference

Field data type

Macro information

Example

Basic data types (Text, Number, Date, etc.)

Returns the field’s value as text.

{% field %}

Content items

Returns a collection of the selected content items. Use iteration or indexing to get individual items. Access item fields via the Data macro.

See: Linked content items

{% emailfield[0].Data.itemfield %}

Taxonomy

Use the Tags macro to access the taxonomy tags selected in the field. Each tag then provides the following macro fields:

  • Title
  • Name
  • Description

See: Taxonomy fields

{% field.Tags[0].Title %}

Media files

Returns a collection of media file objects. Use iteration or indexing to get individual objects. Access file properties via the following macros:

  • Url
  • Extension
  • Name

{% field[0].Name %}

Object code names

Returns a collection of the selected object code names. Use iteration or indexing to get individual code names.

{% field[0] %}

Object global identifiers

Returns a collection of GUIDs for the selected objects. Use iteration or indexing to get individual GUID values.

{% field[0] %}

Fields of linked content items

Content item asset

Returns data about the file stored in the field. Access file properties via the following macros:

  • Url
  • Extension
  • Name

See: Content item assets (files)

{% emailfield[0].Data.assetfield.Url %}

Pages

Returns a collection of objects with data about the selected pages. Each page object provides the following macro fields:

  • Url
  • Type

See: Linked pages

{% emailfield[0].Data.pagesfield[0].Url %}

Smart folder

Currently not supported for emails.

Language-specific formatting

For fields with the Date and time, Decimal number or Floating-point number data type, the macro value is resolved according to the Formatting culture of the language set for the email channel.

Time values

The values of fields with the Date and time data type are always returned in the time zone of the server where the application is running.

Linked content items

Fields with the Content items data type link to reusable content items of a different content type and require additional handling. In this case, the field macro returns a collection of the selected items. Use iteration (loops) or indexing to get individual items, and access their fields via the Data macro field. See Macro syntax and the example below for more details.

Note that secured content items with the Requires authentication flag enabled are not included in emails. If you send an email containing secured items, the corresponding content will be missing.

Content item assets (files)

When processing linked content items with a field that stores a file (Content item asset data type), you can access the file properties via the following macros:

  • Url – the URL through which the file can be displayed or downloaded. Resolved based on the Email service domain set for the email channel.
  • Extension – the file extension with a leading dot character.
  • Name – the file name, including the extension.

Example

The following example shows the field structure of an email content type:

Email

Field name

Data type

EmailContent

Rich text (HTML)

Signature

Content items (Signature)

SocialMediaLinks

Content items (Social media link)

and several linked reusable content types:

Signature

Social media link

Image

Field name

Data type

Field name

Data type

Field name

Data type

SignatureText

Text

LinkTitle

Text

ImageFile

Content item asset

SignatureImage

Content items (Image)

LinkUrl

Text

ImageDescription

Text

LinkImage

Content items (Image)

The content types and fields described above could be displayed within an email template using the following HTML and macros:

HTML


<table border="0" cellpadding="0" cellspacing="0" style="max-width: 500px;" width="100%">
  <tbody>
    <tr>
      <td>
        {% EmailContent %}
      </td>
    </tr>
    <tr>
      <td> 
        {% HTMLEncode(Signature[0].Data.SignatureText) %}
      </td>
    </tr>
    <tr>
      <td>
        <img src="{% Signature[0].Data.SignatureImage[0].Data.ImageFile.Url %}"
             alt="{% HTMLEncode(Signature[0].Data.SignatureImage[0].Data.ImageDescription) %}"
             title="{% HTMLEncode(Signature[0].Data.SignatureImage[0].Data.ImageDescription) %}"
             loading="lazy">
      </td>
    </tr> 
    <tr>
      <td>  
        {% foreach (link in SocialMediaLinks) { %}
          <a href="{% link.Data.LinkUrl %}" target="_blank">
            <img src="{% link.Data.LinkImage[0].Data.ImageFile.Url %}"
                 alt="{% HTMLEncode(link.Data.LinkTitle) %}"
                 title="{% HTMLEncode(link.Data.LinkTitle) %}"
                 loading="lazy">
          </a>
        {% } %}
      </td>
    </tr>
  </tbody>
</table>

Taxonomy fields

When processing emails with a taxonomy tag selector field (Taxonomy field data type), you can access the collection of tags selected in the field via the Tags macro. Each tag item in the collection then provides the following macro fields:

  • Title – the tag’s Title text.
  • Name – the tag’s Code name.
  • Description – the tag’s Description text.

Tag translations

When resolving a tag’s Title or Description, the system uses the translation in the language set for the email channel (if the translation is available for the tag).

For example, if an email has a Products field linking to product content items, which then have a ProductTags tag selector field, the tags could be displayed using the following email template code:

HTML


{% foreach (product in Products) { %}
  <div class="product">
    {% HTMLEncode(product.Data.ProductTitle) %}
    {% foreach (tag in product.Data.ProductTags.Tags) { %}
      <div class="tag">{% HTMLEncode(tag.Title) %}</div>
    {% } %}
  </div>
{% } %}

Linked pages

If you wish to model and display links to website channel pages in your emails:

  1. Create a reusable content type representing page links.
    • Include a title/name field to store the text of the page link.
    • Add a field with the Pages data type to select the target page.
  2. In your email content type, add a field with the Content items data type, and allow your page link content type.

In your email templates, use field macros, iteration (loops) and/or indexing to access the linked pages. The linked page objects provide the following macro fields:

See Macro syntax and the example below for more details.

Example

Content types:

Email (Emails)

Linked article (Reusable content)

Article (Pages)

Field name

Data type

Field name

Data type

Field name

Data type

EmailContent

Rich text (HTML)

ArticleTitle

Text

LinkedArticles

Content items (Linked article)

ArticlePage

Pages

Email template code:

HTML


<div>
  {% EmailContent %}
</div>
<ul>
  {% foreach (link in LinkedArticles) { %}
    <li>
      <a href="{% link.Data.ArticlePage[0].Url %}" target="_blank">
        {% HTMLEncode(link.Data.ArticleTitle) %}
      </a>
    </li>
  {% } %}
</ul>

Value encoding

Field macros in email templates resolve the text of fields without encoding. This means that the code of email templates can be broken, for example if a field’s value contains certain HTML characters.

To ensure that content is displayed correctly and securely in emails, enclose field macros into encoding methods:

  • HTMLEncode – encodes HTML characters to corresponding entities.

    • Use encoding to safely display HTML-like text.
    • Do NOT HTML encode fields using the Rich text editor form component, which return HTML elements for formatting and advanced content.
  • UrlEncode – performs URL encoding of the specified text. For example, use URL encoding when you have a text field that you insert as part of a URL.

HTML
Examples


<div>
   {% HTMLEncode(previewtext) %}
</div>

<a href="https://www.example.com/page?utm_content={% UrlEncode(UtmContent) %}">Link</a>

Delete email templates

Templates that are not currently assigned to any emails can be deleted from the main listing in the Email templates application. If you wish to delete a template that is currently being used, you first need to edit the given emails your email channel applications and assign a different template.