Email Template Builder

Introduction

The Email Template Builder adds a drag-and-drop builder to Joget for designing reusable email templates, the same way the Form Builder designs forms. Instead of hand-writing HTML in the Email Tool's message box, you build the email from blocks, preview it, send yourself a test, and then send it from any process.

Templates are built on MJML, the open-source email framework, compiled inside the plugin. The emails come out as table-based HTML that works in Outlook, Gmail, and Apple Mail, and layouts adapt to phones. Nothing is sent to an outside service to build the email.

The Email Template Builder is a plugin for the Addon Builders. It works on Joget DX 9 and later.

Get started

Where to get the plugin

You can download the Email Template Builder plugin from the Joget Marketplace.

How to install

1. Go to the Joget Marketplace and download the plugin as a .jar file.
2. Log in as an admin on your Joget server.
3. Go to Admin Bar > Settings > Manage Plugins.
4. Click the Upload Plugins button.
5. Upload the .jar file you downloaded.

The Joget Knowledge Base has more information on managing and developing plugins.

How to use it

1. Open an app in the App Composer and create a new Email Template. It gets an ID such as ET-001 and starts blank.
   
2. In the builder, click Templates and pick a starter, or drag blocks from the palette onto the canvas.
   
3. Click text on the canvas to edit it, and click any block to change it in the properties panel.
4. Click Settings and set the email's Subject.
5. Click Preview to see the email as it will be sent, and Send test to email it to yourself.
6. Save the template.
7. In the Process Builder, drag Send Templated Email from the Tools section of the palette onto the process, then click it, open the Mapping tab, and pick the template. See Send Templated Email tool.

The builder

Most toolbar buttons show only an icon. Hover over a button to see its name.

• Canvas: Click text to edit it in place, and click any block to change it in the properties panel. Switch between desktop and mobile views to see how the email looks on a phone.
• Templates: A gallery of 27 ready-made designs with live thumbnails. Picking one replaces the current design but keeps the template's ID, name, and description. Undo reverts it.
• Components: A gallery of 24 ready-made parts, such as headers, footers, status trackers, stat tiles, callouts and button pairs. Each one is inserted after the selected block.
• Email style: The colours, font, width, corners, and shadow of the whole email. Clicking the page background opens it too.
• Settings: The template's subject, preheader and template variables.
• Test data: A form record and test values used to fill merge fields on the canvas, in Preview and in Send test. It is kept in your browser only, and real emails never use it.
• Preview: The email as it will be sent, with merge fields filled from the Test data. Fields that came out empty are listed.
• Send test: Emails the current design, saved or not, to up to five addresses. The subject is prefixed [Test]. It uses the app's Email Tool SMTP settings, or the server's.
• Size meter: At the bottom left of the canvas. It shows the email's size against Gmail's limit of about 102 KB, above which Gmail clips the email. It turns amber from 80 KB and red from 102 KB.

Blocks

• Row and Column: Put blocks side by side. Columns stack on phones unless Keep side by side on mobile is ticked.
• Outside the card: Places a logo above the email's content card, or a footer below it.
• Datalist Table: Shows rows of an app datalist in the email, such as an order's line items or a daily digest. It can filter by the current record, for example order_id = #form.orders.id#.
• Repeat: Repeats a card of blocks once per datalist row. Inside it, use {row.COLUMN} to show a column's value.
• Steps, Progress bars, Facts list, Timeline, Stat tiles, Badge and Callout: Ready-styled parts for status trackers, KPIs, detail lists and notices, set up in properties without any HTML. Steps and Progress bars can be driven by a field, for example #form.request.status#.
• Custom HTML: Your own markup. Use it only for HTML your app produces, never for what users type into a form.

Configure template properties

Click Settings in the toolbar.

Fields to configure:

• Name: The template's name, shown when you pick it in the Send Templated Email tool (mandatory).
• Description: Notes for other designers.
• Subject: The email's subject line. Merge fields are allowed, for example Request #form.request.ref# approved.
• Preheader: The preview line most inboxes show after the subject. It is hidden in the email itself.
• Template variables: Values the sender supplies when the email is sent, used as {var.NAME} anywhere in the email: subject, text, links, datalist filters and Repeat cards.
  • Name: The variable's name, for example boardId (mandatory).
  • Description: What the sender should put in it.
• Public server address: The address recipients can reach this Joget server at, for example https://apps.example.com/jw. It's only needed for a Hero background image picked from App Resources.

Configure the email style

Click Email style in the toolbar, or click the page background.

Fields to configure:

• Page background: The colour around the email.
• Content background: The colour of the email's content card.
• Text colour and Link colour: The colours of the email's text and links.
• Corner radius (px): Rounds the content card, for example 8px. Classic Outlook on Windows shows square corners.
• Shadow: A soft shadow around the content card. Apple Mail and some webmail show it, and Outlook desktop ignores it.
• Font: The email's font.
  • Arial
  • Helvetica
  • Georgia
  • Verdana
  • Tahoma
  • Trebuchet MS
• Width (px): The email's width, from 320 to 800. 600px suits most email apps.
• Language: The email's language code, for example en.

Merge fields and template variables

• Merge fields: Joget hash variables such as #form.request.title# or #assignment.activityName# can go anywhere in the text, subject, preheader, and links. They are filled in from the process when the email is sent. Their values are HTML-escaped, so what users type into a form shows as plain text and can't add links or scripts to the email. To try them out, set a form record in Test data, and Preview and Send test fill the fields from it.
• Template variables ({var.NAME}): The email's own inputs, declared in Settings. The Send Templated Email tool gives each one a value, which makes one template reusable across processes. For example, a daily digest sent once per board inside an Iterator Process Tool maps boardId = {id}.
• Row fields ({row.COLUMN}): Used only inside a Repeat block. They show the current datalist row's columns.

Send the email

Send Templated Email tool

The recommended way to send a template. In the Process Builder, drag Send Templated Email from the Tools section of the palette onto the process and connect it. Click it and open the Mapping tab, where Tools already shows Send Templated Email. A plain Tool works too: pick Send Templated Email in its Tools field.

Fields to configure:

• Email template: The template to send. Its merge fields are filled in with this process's data (mandatory).
• Template variables: A value for each of the template's variables. Merge fields are allowed. Inside an Iterator Process Tool, use {column} of the iterated record. A variable left out is sent empty.
  • Variable: The template's variable, chosen from a list.
  • Value: Its value for this email.
• To (Specific email address): The recipients' email addresses. Merge fields are allowed, for example #form.request.email#.
• To (Participant ID): A process participant's ID. The email goes to the users mapped to that participant.
• CC and BCC: Copies, as in the Email Tool.
• Subject: Leave it empty to use the template's subject.
• SMTP settings, attachments, calendar invite (ICS), digital signature and retries: The same as in the Email Tool. When the SMTP fields are empty, the tool uses the app's Email Tool default settings, and then the server's.

The tool sends the email's HTML together with a plain-text version, for email apps that show text only. Images picked from App Resources are embedded in the email, so recipients don't need to reach your Joget server to see them.

Email Tool

A template can also be sent with the standard Email Tool, using the hash variables below. Tick HTML in the Email Tool, then set:

• Message: #emailTemplate.ET-001?noescape#
• Subject: #emailTemplate.ET-001.subject#

Email template hash variables

• #emailTemplate.ID?noescape#: The template's email HTML, where ID is the template ID.
• #emailTemplate.ID.subject#: The template's subject.
• #emailTemplate.ID.text#: The plain-text version of the email.

Example hash variable:

#emailTemplate.ET-001?noescape#

Tips and limitations

• Links: Must start with http, https, mailto or tel, or point to a place in the same email. Any other link is replaced with # and a warning.
• Classic Outlook on Windows: Draws square corners, no shadows, and no Timeline dots. The layout itself works.
• Gmail: Clips emails larger than about 102 KB. Keep an eye on the size meter.
• Unsubscribe links: Some starters include one. Point it at a real opt-out in your app.
• Hero background images: These are linked rather than embedded, because most email apps don't load embedded background images. The image must be public, and the template's Public server address must be set.

Related documentation

• Email Tool
• Iterator Process Tool
• Hash Variable

Download plugin

• Email Template Builder Plugin
• Email Template Builder Plugins Source code