E-mail Templates

E-mail Templates

A template is one message: its subject, its body, and whatever it merges in.

Where to find it

Architect Panel → Layout & Pages:

• E-mail Templates — the templates
• E-mail Designs — the wrapper they use

Architect Panel → Integration & Connections:

• E-mail Accounts — the accounts mail is sent and received through

What a template holds

• A name and a subject.
• The body, with merge fields.
• A design to wrap it.
• Attachments.
• A tracking switch.
• Optionally a calendar invitation.

Content, not layout

The discipline that makes templates maintainable. Header, footer and styling belong to the design; a template carrying its own has opted out and will not follow the next rebrand.

When you find yourself adding layout, the design is missing something — fix it there.

Templates can be built with the page builder

Where a message needs more than plain content — a structured layout, a richer arrangement — a template can be a page builder document rather than hand-written markup. That suits marketing-style messages and keeps the authoring visual.

For ordinary transactional mail, simple content in a good design is usually better and far more robust across mail clients.

Open tracking is per template

A switch on each template rather than a global setting, which is the right granularity — tracking a marketing message is a different proposition from tracking a password reset.

What it records is worth knowing: not merely that a message was opened, but the identity of who opened it, with the time, address and browser. That is personal data about a named individual, not anonymous statistics.

So switch it on deliberately

Leave it off for transactional mail, where it adds nothing you will act on and collects behavioural data about people receiving something they asked for. Turn it on where you will genuinely use the result — and cover it in your privacy information.

Open tracking is also unreliable, since many clients block or pre-load images. Treat it as directional at best.

Subjects do most of the work

A subject is what decides whether a message is opened. Be specific and factual — "Your appointment on 14 March" rather than "Important information" — and keep it short enough to survive truncation on a phone.

Name templates so they can be found

You will accumulate dozens. "Appointment reminder — 24 hours" is findable; "Email 7" is not, and somebody will eventually edit the wrong one.

Review them occasionally

Templates outlive the processes that send them. A periodic look for ones nothing sends any more, and ones whose wording has drifted out of date, keeps the set honest.

Worked example

An organisation runs about forty templates, all using one design and holding only content. Tracking is on for two campaign templates and off for everything transactional. Names describe the message and its trigger, so the annual review found six templates nothing had sent in a year.

Recommendations

• Keep templates to content.
• Leave tracking off for transactional mail.
• Write specific subjects, short enough for a phone.
• Name them for the message and its trigger.

Merge Fields

Merge fields put values from the record into the message, so one template serves every recipient.

Where to find it

Architect Panel → Layout & Pages:

• E-mail Templates — where fields are inserted

Architect Panel → Data:

• Datastores — the fields being merged

Architect Panel → Activity:

• E-mail Log — every message sent, with its result

What can be merged

Values from the record the message concerns, and context about the send. The available set depends on what is sending — a template used by one process may have fields another does not.

Empty fields are the main hazard

The failure everybody has received: "Dear ," or "Your appointment on is confirmed."

It looks careless, it undermines the message, and it happens whenever a field is optional and somebody left it blank. Merge fields do not fail loudly — they simply produce nothing.

Design for the blank case

Two approaches, and both are better than hoping:

• Make the field required where the message genuinely depends on it.
• Write around it — "Hello" rather than "Dear [first name]" — so a blank is invisible.

The second is usually the more robust, because required fields get worked around and imported data arrives incomplete.

Check the field is the one you meant

Similar names are easy to confuse — the contact's name and the account's, the site address and the billing address. The mistake is invisible until somebody receives a message addressed to their company's parent, and the log will show it went out that way to everybody.

Formatting

A date merged raw may not read as you would write it. Where a value has a natural presentation — a date, an amount, a reference — check how it appears in a real message rather than assuming.

Do not merge what should not be there

A merge field is a way to put data into an outgoing message, which means it is a way to disclose it. Think about whether each value should be in an e-mail at all — mail is not confidential, is forwarded, and sits in mailboxes indefinitely.

Reference numbers are usually better than the details behind them: "regarding case TKT-00042" rather than the case's contents.

Test with real records

Including an awkward one — the record with a blank optional field, an unusually long name, an apostrophe, an accented character. A template tested only against a tidy example will meet all of those in its first day.

Check the log after a template change

The log holds what was actually sent, so it is where a merge problem is visible. Reading a few real sends after changing a template catches an error before hundreds go out.

Worked example

A reminder template was tested against a record with every field populated and went out to 400 people, forty of whom had no title recorded and received "Dear ,". The template now opens with "Hello" and no merged salutation, and template changes are checked against a deliberately sparse test record.

Recommendations

• Write around optional fields rather than requiring them.
• Verify you have the field you meant.
• Prefer a reference to the details behind it.
• Test with a sparse record, not a tidy one.

Testing Before You Send

Testing e-mail properly takes a few minutes and prevents the class of problem that is impossible to take back.

Where to find it

Architect Panel → Layout & Pages:

• E-mail Templates — the template under test

Architect Panel → Activity:

• E-mail Log — every message sent, with its result

Architect Panel → Commercial:

• Campaign Manager — where a bulk send is paused if it goes wrong

A preview is not a test

It shows the template rendering in your browser. It does not exercise the design, the account, the merge fields against a real record, or any mail client's interpretation.

Nearly every e-mail problem worth catching is invisible in a preview.

Send a real one

Through the actual account, using a real record, to a real mailbox. That single step catches the design not applying, the from name being wrong, merge fields empty, and the message landing in spam.

Check it on a phone

Most mail is read on one. A layout that works on a laptop and breaks on a handset is the common case, not the exception — and the subject line truncates far earlier than you expect.

Check more than one client

At minimum a desktop client, a webmail service and a phone. Mail clients differ enormously, and a message that looks right in one can be unreadable in another.

Test the awkward record

Blank optional fields, a long name, an apostrophe, an accent. A template tested only against tidy data will meet all of those immediately.

Check where it landed

Not just that it arrived — whether it reached the inbox or the spam folder. A message the log records as sent successfully can be filed as junk, and that is invisible from your side.

Read it as the recipient

Does the from name identify you? Does the subject say what it is? Does the first line make sense without the subject? Is it obvious what to do next?

This is the check most likely to improve the message rather than merely confirm it works.

For a bulk send, go in stages

1. Test to yourself.
2. Send to a small internal group.
3. Only then to the audience, throttled.

And know where the pause control is before you start. The moment you need it is not the moment to be looking for it.

Test again after any change

Including a change to the design, which affects every template at once. A design edit is a change to all of your outgoing mail and deserves testing as such.

Worked example

A team tests every template change by sending one real message to four mailboxes including two phones, using a deliberately sparse record. A campaign goes to three colleagues before its audience. The one time a link was wrong, it was found by the second colleague rather than by 4,000 customers.

Recommendations

• Always send a real message — a preview proves nothing.
• Check a phone and more than one client.
• Use a sparse record for the test.
• Stage bulk sends, and find the pause control first.

E-mail Wording per Organisation

E-mail Wording lets one organisation on a shared, multi-tenant system send its own version of an e-mail that a shared process sends. Use it when several organisations run applicants through the same user input view and each wants its own name, tone and contact details in the messages, without duplicating the form.

Where to find it

Admin Panel → Processes:

• E-mail Wording — your own wording for the e-mails a shared process sends

How it works

An override says: "when this organisation would have been sent the standard e-mail, send this one instead". The swap happens at the moment the e-mail is generated, before the template is loaded, so the replacement brings its own subject, body, design and attachments. Nothing about the shared process changes, so no other organisation's mail changes either.

The screen does not list every template on the system. It reads every user input view, works out which templates its stages and notifications actually send, and offers only those. Each row shows:

• Standard E-mail and Subject: the shared template.
• Sent By: which process sends it and when, for example "Applications - Confirmation" or the name of a stage.
• This Organisation Gets: "Standard", or the name of your replacement.
• Actions: a picker, Use, Copy & use and (once set) Reset.

Before anyone can use it

1. Grant the panel item. E-mail Wording ships visible to nobody. Give it to the security group of the people who manage each organisation's mail (see Admin Panel).
2. Grant the datastore permissions. On the E-mail Template Overrides datastore, Read lets someone see the screen, Edit Existing lets them choose a replacement or reset, and Add New additionally enables Copy & use. See Permissions.
3. Work inside the organisation. Overrides are set per tenant. A session not working within an organisation sees a note that the templates in E-mail Templates are the standard wording, and cannot change anything.

Giving an e-mail your own wording

1. Open E-mail Wording and find the row for the message, using Sent By to be sure it is the one you mean.
2. Click Copy & use and confirm. The platform copies the standard template, names the copy after it with your organisation's name in brackets, and starts sending the copy straight away.
3. Open the copy in E-mail Templates and edit its subject and body. See E-mail Templates.
4. Alternatively, if a suitable template already exists, choose it in the picker and click Use.
5. To go back to the shared wording, click Reset and confirm.

Limits worth knowing before you promise anything

• Mail sent by a scheduled task gets the standard wording. Confirmation, progress, decline, cancellation, completion and approver e-mails sent as someone uses the form are overridden. Stage time-out notices, stage reminders and delayed stage e-mails, which a task sends, are not.
• One step only. If A is replaced by B and B by C, the organisation gets B. Replacements never chain or loop.
• The platform level cannot override itself. The shared templates are the standard; only an organisation sets an override.

What goes wrong and how to tell

• "Your version has been deleted - standard wording is being sent": the replacement template was deleted. Mail did not fail; the organisation silently got the standard e-mail. Copy again or choose another.
• "No longer used by any process" in Sent By: you overrode a template the process no longer sends. The override does nothing; reset it to tidy up.
• No Copy & use button: you have Edit Existing but not Add New on the overrides datastore.
• "That is the same e-mail. To go back to the standard wording, use Reset.": you picked the template itself as its own replacement.

Worked example

Three trusts share one work-experience application form on a regional hub. Applicants at all three received an identical confirmation signed "The Placements Team". The co-ordinator at the second trust opens E-mail Wording, finds "Work Experience Applications - Confirmation", clicks Copy & use, then edits the copy in E-mail Templates to name the trust, its placement office's phone number and its parking arrangements. Their applicants get the new wording from the next submission; the other two trusts see no change. They note that the stage reminder is sent by a task and so still carries the shared wording.

Recommendations

• Start from Copy & use, so the replacement keeps the standard design and merge fields.
• Keep Add New for the few people who should decide what your organisation's e-mails say.
• Write shared wording that works for everyone, because task-sent reminders cannot be overridden.
• Send yourself a test application after setting an override. See Testing Before You Send.