Creating and Publishing an Email Template

A complete walkthrough of Email Studio for administrators and advanced end users: create a template, design it, declare placeholders, preview, test, publish, and manage versions.

Table of Contents

1. Before you start
2. Open Email Studio
3. Create the template
4. Design the email
5. Choose a data source
6. Declare placeholders
7. Preview and validate
8. Send a test email
9. Save drafts and versions
10. Publish
11. Manage versions, clones, and status
12. Delivery log
13. HTML rules
14. Best practices
15. Troubleshooting
16. A note on testing

Before you start

Who can do what

Email Studio uses role-based permissions. Your administrator controls them.

If a button is missing, your role does not include the matching permission.

What you need

• A unique template code that other parts of the system will call. Decide it before you create the template; it cannot be changed later.
• The intended audience and purpose.
• For workflow notifications: the workflow template whose fields you want to use.
• A working From address configured on the active mailer. Without one, test sends and live sends fail.

Open Email Studio

1. Sign in with an account that has the email permissions.
2. Go to System Administrator › Email › Email templates.
3. The library page lists every template with its name, code, category, status, version, and last update time.
4. Use the Filter templates box to search by name, code, or category.
5. Choose Open on a row to open the designer, or New template to start from scratch.

The library also has a Delivery log link when you have the matching permission.

Create the template

Choose New template and complete Template details.

Then complete Email content:

• Subject — the email subject line. It is required before publishing. A draft can start with an empty subject, but the system will not publish it.
• HTML Body — the formatted email body. Optional at draft time. HTML is sanitized when saved.
• Plain-Text Body — the fallback body for text-only mail clients. Provide HTML, plain text, or both. Publishing fails if both are empty.

Select Create draft. The system creates the template with status Draft and opens the designer.

The code is permanent. If you need a different code, create a new template instead of renaming an existing one.

Design the email

The designer opens in Split view: the editing area on the left and a live preview on the right. Use the view switch to show only the editor or only the preview.

Ribbon actions

Inspector panels

• Template settings — subject line, category, default reply-to, and change note.
• Data source — choose Template samples or a workflow template.
• Preview & validation — errors, warnings, missing placeholders, and the plain-text body.
• Before publishing — a checklist of publish requirements.

The editor tracks unsaved changes. If you try to leave with unsaved edits, the browser asks for confirmation.

Choose a data source

The data source controls which field names the designer offers and which sample values it uses for preview.

Template samples

The default. Sample values come from the placeholder definitions on the template itself. Use this for standalone notifications that are not tied to a workflow.

Workflow template

Use this for workflow-driven email. Search for a workflow template, then select it.

• The designer loads the workflow's reusable workflow.* fields and its document.* fields.
• If the workflow already has an instance, the sample values come from the latest instance. The designer labels this sample from latest workflow.
• If there is no instance yet, the designer uses generic sample values and takes the first step name for the current step.
• Clicking a field inserts the matching {{ ... }} token and automatically declares the placeholder.
• Selecting a workflow template also records the template's source as that workflow template. Workflow designers can then find this email template in their notification template pickers.

Workflow data sources require the preview permission. Without it, the designer falls back to template samples and explains that workflow data could not be loaded.

Declare placeholders

Every value you insert into the subject or body must be declared. An undeclared token fails validation.

There are two ways to declare a placeholder:

1. Click a data-source field. The designer inserts {{ field.name }} and adds the definition automatically, using the sample value and data type from the source.
2. Add it manually in the placeholder section. Provide the name and definition fields.

See the Placeholder Reference for every definition field, data type, and the full list of workflow tokens.

At minimum:

• The token in the content must exactly match the declared name.
• Names use letters, numbers, and underscores; dots are allowed between path segments.
• A name cannot start a segment with an underscore.
• A placeholder cannot be both a value and a path prefix. For example, do not declare both document and document.number.
• If a placeholder is marked required, it cannot define a default.

Preview and validate

Select Preview (or open Preview & validation) to render the current draft.

The result shows:

• Rendered subject and body — HTML and text modes.
• Errors — must be fixed before publishing. Examples: an undefined placeholder, a required value that is missing, an unsafe HTML tag, an empty subject, or an unsupported filter.
• Warnings — allowed but worth reviewing. Examples: an optional placeholder with no value (its default is used) or a declared placeholder that is not used anywhere.
• Missing placeholders — required names the sample context did not supply.

Preview uses the selected data source. When the data source is a workflow template, sample values may differ from a real workflow instance; always test against a representative instance when you can.

Send a test email

Select Test send, then enter one or more Recipients, optionally CC and BCC.

• Recipients are comma-separated and validated before sending.
• CC/BCC require the CC/BCC permission and must be allowed by system policy.
• The test uses the current draft, not the published version.
• Test subjects normally receive a configurable prefix so they are easy to identify.
• The test is recorded in the delivery log as a test delivery.

Test sending is the best way to confirm layout and links in real mail clients.

Save drafts and versions

Select Save to persist the working draft.

• Each save updates the current draft version.
• If the template already has an active version and no draft, saving creates a new draft based on the active version.
• A change note is optional but recommended. It appears in the version history.
• The first version is v1. Version numbers increase; they are never reused.

Version statuses:

Publish

Select Publish when the preview is clean.

Publishing performs these steps:

1. Checks that a draft exists.
2. Re-validates the draft: subject, content, placeholder definitions, tokens, filters, and HTML.
3. Marks the draft Published, records the publisher and time, and applies the change note.
4. Sets the template's active version to the published version.
5. Sets the template status to Active.
6. Creates a fresh draft copy of the published content at the next version number, ready for the next edit.

If validation fails, nothing is published and the errors are shown. Fix them and publish again.

A template can only send email when it is Active and has a published active version.

Assigning the template to a workflow

After publishing, the template can be selected in the workflow designer:

• Map a notification type to the template code, or
• Set the template code on a workflow step, or
• Configure a workflow-wide fallback in settings.

If a workflow notification has no email template selected, the workflow's email channel is skipped and the delivery is logged as failed with No email template selected.

Manage versions, clones, and status

Version history

Open Versions to see every version with its number, status, publisher, timestamps, and change note.

• Restore copies an old version into a new draft. It does not overwrite the active version. Restoring is safe.
• The previous draft is archived when a restore replaces it.

Clone

Clone creates a new template with the code suffix _COPY (then _2, _3, and so on if needed). The clone starts as a draft and copies the current content and placeholder definitions.

Deactivate and activate

• Deactivate sets the template to Inactive. Live sends stop until it is activated again. The active version is kept.
• Activate sets an inactive template back to Active if it already has a published version. If it has no published version, activating publishes the draft.

Delivery log

The Delivery log lists email deliveries with status, template code, recipients (permission-dependent), subject, timestamps, and errors.

Failed deliveries can be retried, and queued or failed deliveries can be cancelled, when you have the matching permissions. Delivery bodies may be purged by retention policy; a purged delivery cannot be retried.

HTML rules

Email HTML is sanitized. Unsafe or unsupported markup is rejected or removed.

Allowed structure: basic email markup such as div, p, headings, lists, tables, links, images, strong, em, span, br, hr, blockquote, pre, and inline style.

Not allowed: script, iframe, object, embed, form, input, button, select, textarea, svg, math, and template. Event-handler attributes such as onclick are rejected. Links and images may only use http, https, or mailto.

Full-document wrappers (html, head, body) are unwrapped, and metadata tags (meta, link, base) are dropped. Only a limited set of CSS properties is accepted, and unsafe CSS values such as expression, javascript:, @import, and url( are rejected.

Practical rules:

• Keep styling inline on elements for the widest mail-client support.
• Do not paste scripts, forms, or embedded videos.
• Use placeholders in href and src only for values you intend to be URLs; they are validated after rendering.

Best practices

• Name templates by purpose, and keep the code stable. Codes are contracts with the rest of the system.
• Publish before mapping the template to a workflow; workflow pickers prefer sendable templates.
• Declare only the placeholders you use. Unused declarations create warnings; undeclared tokens create errors.
• Use workflow data sources for workflow notifications so the designer offers the correct workflow.* and document.* fields.
• Mark a placeholder required when the email is meaningless without it. Do not give required placeholders defaults.
• Provide a plain-text body as well as HTML. If omitted, it is generated from the HTML at send time.
• Write a change note on every meaningful save.
• Test against a real workflow instance when the content depends on document fields.
• Restore instead of retyping an old version, then publish the restored draft.
• Deactivate rather than delete when retiring a template still referenced by workflows, so references are easy to trace.

Troubleshooting

A note on testing

Per project rules, the developer or agent does not run or claim test results. The user is solely responsible for all testing and validation of the output described in this guide.

Related guides

• Placeholder Reference
• Email Templates — User & Admin Guide
• Workflow — Developer Index