✉️

Email Templates Guide

Customize the subject and body of file and load notification emails from System Settings. Saved changes apply to future live emails as well as test emails.

Choose a template

Open Administration → System Settings → Global, then find Email Templates in the email settings. Editing requires permission to save System Settings.

Tab
Used for
File Received
Confirmation that a file was received.
File Failed
File validation failure notices. Other processing or conversion alerts can use separate system templates.
Load Success
Confirmation that a production load completed successfully.
Load Fail
A failed production load attempt.

Each tab has its own Subject, Body, test-recipient field, and Test button. These are global templates: changes apply to notifications for all clients that use that template.

Edit, test, and save

  1. Open the template tab you want to change.
  2. Copy the current Subject and Body into a backup text file before editing. You can paste these back if you need to undo a change.
  3. Edit the wording or variables. Keep the existing indentation and layout unless you intend to redesign the email.
  4. Enter your email address beside the Test button, then click Test. This sends an actual email using example data and your current edits.
  5. Check the result message and the received email. Check the subject, layout, variable values, and links.
  6. Click the settings Save button and wait for confirmation. Testing does not save your edits.
  7. Future live emails use the saved subject and body. No worker restart is required; previously delivered emails do not change.

Email must be enabled and delivery settings must be configured. A test uses sample data, not your most recently loaded file. For example, the test destination is an example path, so it will not demonstrate a replacement that only matches your real share path.

Pug basics

The Subject and Body fields use Pug, a text format that generates the email. You do not need to replace the whole template to change a sentence.

  • Keep indentation consistent. It controls which lines belong inside a section.
  • Keep quotes, commas, brackets, and parentheses balanced.
  • In the body, p starts a paragraph, #{...} inserts a value into text, and p= ... displays an expression as a paragraph.
  • Keep the helper definitions near the top, including mixin metadata and mixin failureDetails, if the body uses +metadata(...) or +failureDetails(...).

These examples use Pug's standard variable and attribute syntax. See Pug interpolation and Pug attributes.

Change the subject

For a load-success subject containing the original filename:

!= `Production Load Complete: ${file.fileName}`

For a fixed subject with no variable:

| Production Load Complete

The backticks in the first example are intentional. Keep ${file.fileName} inside them. The != form is used here for a plain-text subject; for variables in the HTML body, use the escaped forms #{...} or = ... shown below.

Change body wording or add a variable

p Your file has been loaded successfully.
p File: #{file.fileName}
p Sender: #{clientNode.name}

When adding these lines to the existing template, indent them to the same level as the nearby paragraphs. Use #{...} or = ... for variable values in the body so characters in filenames and other values are escaped correctly.

Common variables

Variables are case-sensitive. A variable can exist in a live email but be empty for a particular file or absent from a particular notification type.

Variable
Meaning and availability
file.fileName
Original filename. Used by default in the subject and Filename field; there is no automatic alias fallback.
file.alias
Optional friendly file name. Use a fallback when it is empty.
file._id
System file ID.
file.recordCount
Input record count when available. This is not necessarily the number of records loaded or exported.
file.byteSize
File size in bytes when available.
file.belongsTo
ID of the owning client, brand, or title.
client.name
Parent client's name, when that client is available.
clientNode.name
Name of the owning client, brand, or title.
run._id
Conversion run ID, when a run is available. Used in load notifications.
run.environment
Run environment, such as PRODUCTION.
run.output.filename
Output filename, when output information is available.
run.output.directory
Output destination directory or prefix. Does not automatically include the bucket, hostname, or output filename.
occurredAt
Notification-generation timestamp in UTC ISO format for load notifications. It is not a separate measurement of the exact transfer completion time.
errors
Error-message array for load-failure notifications.
convertValidation.errors
Validation error messages for File Failed. In load notifications this is a shared message wrapper, not a full validation report.

Load notifications also receive event (load-success or load-failed), title, and an initially empty customBody. The full file, client, clientNode, and run objects are available, but nested fields are not guaranteed to exist. Use the guarded examples below for optional data. The receipt and validation templates do not guarantee a run object.

Use the alias, with the filename as a fallback

In the subject:

!= `Production Load Complete: ${file.alias || file.fileName}`

In the body:

p File: #{file.alias || file.fileName}

Or change just the Filename entry in an existing metadata line to:

['Filename', file.alias || file.fileName]

That last example is one entry inside +metadata([...]), not a complete Pug line.

Add or remove a metadata field

The default template uses +metadata to display label/value rows. For example:

+metadata([['Filename', file.fileName], ['File ID', file._id]])

To add the sender, add another bracketed pair:

+metadata([['Filename', file.fileName], ['File ID', file._id], ['Sender', clientNode.name]])

To remove a row, remove its entire pair and the adjoining comma. The default helper displays Unavailable for an empty value. Keep the helper definition if you keep these calls.

Handle optional run/output information

if run && run.output
    p Output filename: #{run.output.filename || 'Unavailable'}
    p Destination: #{run.output.directory || 'Unavailable'}

This avoids trying to read output information when no run/output object is available. See Pug conditionals.

Show a user-friendly destination path

A destination may use a path that is meaningful inside the application, such as:

/load/UNC_SHARE/dir1/CLIENT_A

If users access that share as //server/dir, you can replace the displayed root in the Load Success template. Find the existing Output filename/Destination metadata line and replace it with:

+metadata([['Output filename', run.output.filename], ['Destination', (run.output.directory || '').replace(/^\/load\/UNC_SHARE(?=\/|$)/, '//server/dir')]])

Keep this line inside the existing if run and if run.output sections, at its original indentation level. Replace //server/dir with your actual user-facing share root.

The example displays:

//server/dir/Processed_ftp/CLIENT_A

The replacement only matches /load/UNC_SHARE at the start of the path and retains the remaining directories. Other destinations remain unchanged. This changes email text only; it does not change the upload/load location, mount, bucket, filename, or file access permissions. The User Friendly Output Root setting used for clipboard paths does not automatically rewrite this email field.

Add a link

To add a help or support link, insert a paragraph like this at the same indentation as neighboring content:

p
    a(href='https://example.com/support') Contact support

Replace the example URL and link text with your own. Use a full https:// URL for web links. A network-share path is best shown as text: email clients may block or decline to open local/file-share links. Displaying a share path does not grant access to that share.

Recipients and reloads

Templates control what an email says. Recipient settings control who receives it.

  • In Global Email Notifications, enable the matching flag for each global recipient.
  • For client-associated recipients, enable the matching flag on the contact for the owning client, brand, or title, then save the client settings.
  • Load Success and Load Fail are separate subscriptions. File Fail does not automatically enable load emails.
  • Each completed Reload attempt sends its matching outcome notification to subscribed global and owning-node contacts, even if an earlier attempt failed with the same error. Duplicate addresses are combined.
  • The Test button sends to the test address you enter; it does not verify that contact subscription settings have been saved.

Troubleshooting

What you see
What to check
FAILED when testing
Check indentation, quotes, brackets, and optional fields. Restore your backup if needed, then test smaller edits.
The variable name appears literally
Body variables need #{...} or = .... Dynamic subjects need the Pug expression and backticks shown above.
A blank field or Unavailable
The example/live data may not contain that value. Check spelling and use a fallback or an if guard.
Test shows edits, but live email does not
Save System Settings and wait for confirmation. Confirm that you edited the matching template tab.
Friendly destination root does not appear in a test
The sample path does not match your real root. Verify the replacement against the intended real destination.
One recipient does not receive the email
Check the matching global/contact flag, email address, client save, mail delivery settings, and spam folder.

Official Pug references