Template helpers
The helper functions you can use in message copy, with syntax, arguments, examples and the output they produce.
Helpers are small functions you call inside a personalization tag. They format a value, supply a fallback, or fetch something that only exists at send time, such as a short link or a coupon code. The tags and data they work on are described in Personalization syntax.
Helpers work in message template fields on every channel that sends a message, and in journey Webhook node bodies and headers. They are not available in on-site and in-app content, which has its own, smaller language. The personalization dialog's Syntax help lists the common ones with a copy icon.
A helper is written first, followed by its arguments: {{upper .Profile.Attributes.city}}. Put a call in brackets to use it as an argument of another call: {{upper (default "friend" .Profile.Attributes.nick)}}.
Summary
| Helper | What it does |
|---|---|
default | A fallback when a value is missing or empty. |
upper, lower | Change case. |
date | Format a date. |
json | Print a value as safe JSON. |
redacted | Test whether an attribute was withheld. |
file | A download link for a library file. |
shortlink | A short link, with optional click tracking. |
items | Recommended items to loop over. |
coupon | A unique code from a coupon pool. |
| Built-in words | if, range, with, comparisons, len, index, printf and more. |
default
default FALLBACK VALUE
Prints VALUE, or FALLBACK when VALUE is missing or an empty text. The fallback comes first so that it also works in a pipe.
| Input | Output |
|---|---|
{{default "friend" .Profile.Attributes.first_name}} with first_name = Anna | Anna |
The same, with first_name missing | friend |
The same, with first_name = an empty text | friend |
{{default 0 .Profile.Attributes.points}} with points = 0 | 0 (zero and false are real values) |
Only a missing value and an empty text count as empty. When the value was withheld from campaigns by your data-protection settings, default prints the fallback.
upper and lower
upper VALUE, lower VALUE
Return the text in upper or lower case. The value must be text; a number or a list is an error and the message for that profile fails.
{{upper .Profile.Attributes.city}} → BRATISLAVA
{{lower .Profile.Attributes.city}} → bratislavadate
date LAYOUT VALUE
Formats a date. LAYOUT shows what the result should look like, written using one fixed example date, Monday 2 January 2006, 15:04:05. Replace each part of that example with the form you want:
| To show | Write in the layout |
|---|---|
| Four-digit year | 2006 |
| Two-digit year | 06 |
| Month as number (with leading zero) | 01 |
| Month as number (no leading zero) | 1 |
| Month name | January (short: Jan) |
| Day (with leading zero) | 02 |
| Day (no leading zero) | 2 |
| Weekday | Monday (short: Mon) |
| Hour, 24-hour | 15 |
| Minute | 04 |
| Second | 05 |
VALUE can be a date attribute, or text in one of these forms: 2026-10-15, 2026-10-15T09:30:00Z (and other RFC 3339 forms), or 2026-10-15 09:30:00.
| Input | Output |
|---|---|
{{date "02.01.2006" .Profile.Attributes.birth_date}} with 1990-04-07 | 07.04.1990 |
{{date "January 2, 2006" .Profile.Attributes.birth_date}} | April 7, 1990 |
{{date "2006" "bad"}} | An error: the message for that profile fails. |
A value that is not a date is an error, not an empty result. Guard optional dates with a condition:
{{with .Profile.Attributes.birth_date}}Born {{date "2 January 2006" .}}{{end}}json
json VALUE
Prints the value as JSON, with quotes and special characters escaped. Use it when you build the body of a Webhook, so that a name containing a quote cannot break the JSON.
{"email": {{json .Profile.Attributes.email}}, "tags": {{json .Profile.Attributes.tags}}}For email = anna@example.com and tags = vip and newsletter, this prints:
{"email": "anna@example.com", "tags": ["vip","newsletter"]}Note that text values are printed with their surrounding quotes. Do not add quotes of your own.
redacted
redacted "NAME"
True when the attribute NAME was withheld for this recipient by your data-protection settings (for example because the sending application is not cleared for it). A withheld attribute otherwise prints as empty, so use redacted when you need different wording.
{{if redacted "first_name"}}Hello,{{else}}Hello {{.Profile.Attributes.first_name}},{{end}}It is false for an attribute that is simply missing; use a plain condition for that.
file
file "ITEM_ID" "VARIANT"
Prints a download link for a file in the content library. Use the Personalization dialog to build it: under File link, pick a content item and a variant, then copy the tag.
Download the guide: {{file "9c7e…" "pdf"}}Only published items that are public can be linked. The link is an opaque download address for that file. If the item is missing, not public, or the variant is not published, the message for that profile fails rather than going out with a broken link.
shortlink
shortlink "URL" or shortlink "URL" true or shortlink "URL" false
Prints a short link that redirects to URL. In the dialog, under Short link, enter the Target URL and tick or clear Track clicks, then copy the tag.
| Form | Result |
|---|---|
{{shortlink "https://example.com/sale"}} | A short link. Whether clicks are tracked follows your Optima instance's default. |
{{shortlink "https://example.com/sale" true}} | A link just for this recipient. A click is recorded as an event on their profile and counted for the campaign, if they have consented. |
{{shortlink "https://example.com/sale" false}} | One shared link for everyone. The redirect works; nothing is recorded. |
The target must be an absolute address starting with http:// or https://. In the dialog a bad address is flagged as The target must be an absolute http(s) URL. When short links are set up on your Optima instance, a bad address fails the message at send time; when they are not, the address is used as written, without a check.
Previews show the full target address instead of a short link, so that previewing never creates a tracked link. If short links are not set up on your Optima instance, messages are also sent with the full address.
The URL can include tags, for example {{shortlink (print "https://example.com/p?ref=" .Profile.ID)}}.
items
items "CATALOGUE" "STRATEGY" COUNT or items "CATALOGUE" "similar_to" COUNT SEED
Returns a list of recommended items from a recommendation catalogue, for the profile being messaged. Loop over it with range. Needs the recommendations feature of the Decision package.
| Argument | Meaning |
|---|---|
CATALOGUE | The catalogue's name, as a quoted text. |
STRATEGY | trending, recently_viewed, similar_to or affinity. |
COUNT | How many items to return, a plain number from 1 up to your Optima instance's maximum (50 by default; ask the provider of your Optima instance). The Personalization dialog offers 1 to 20. |
SEED | Required for similar_to and not allowed for the others. Either an item key in quotes, such as "SKU-123", or a tag such as .Run.State.seed. |
Each item in the loop carries the fields of your catalogue's dataset, named as the dataset names them, and three extra fields: item_key, score and reason.
{{range items "products" "trending" 3}}
{{.title}}: {{shortlink .url}}
{{end}}Items the customer has already bought are left out of messages and journey decisions, but not of on-site content. When there is nothing to recommend, the loop prints nothing, so wrap the whole block in a condition if the surrounding text would look odd without items. Items are chosen when the message is built and are recorded with the message.
In an email, the dialog's Item recommendations group builds a ready block for you: choose the Catalogue, Strategy and Count (and the seed for Similar to), then copy it. It lays out each item's title, image and price as defined by the catalogue. This block is offered only for the email HTML body.
The editor's preview shows recommended items only when you enter a Profile ID in the Render preview panel; without one it reports an error. Like a message, the preview leaves out items the customer has already bought.
coupon
coupon "POOL"
Prints a unique code taken from the named coupon pool. Choose the pool in the dialog under Coupon code, which also shows how many codes are left in each pool, then copy the tag.
Use code {{coupon "SPRING-2026"}} at checkout.Each recipient gets their own code, and every occurrence of the same pool within one message (for example in the HTML and plain-text bodies) prints the same code. The pool name must be written in the template as a quoted text, not a calculated value.
The preview prints SAMPLE-CODE and never uses up a code. If the pool has run out of codes when the message is sent, that message fails permanently; the template itself still saves. Watch the pool's remaining count. Holdout (control-group) recipients do not receive a message and do not use a code. Needs the coupon codes feature; without it the dialog says Coupon code pools are not on this account's licence.
Built-in words
Besides the helpers above, these standard words are available.
| Word | Use | Example |
|---|---|---|
if, else if, else, end | Conditions | {{if .Profile.Attributes.vip}}VIP{{end}} |
range, end | Loop over a list | {{range .Profile.Attributes.tags}}{{.}} {{end}} |
with, end | Run only when a value exists | {{with .Offer.Payload.code}}Code {{.}}{{end}} |
eq, ne, lt, le, gt, ge | Compare two values | {{if ne .Profile.Attributes.tier "free"}}…{{end}} |
and, or, not | Combine conditions. or returns its first non-empty value. | {{or .Profile.Attributes.nick "friend"}} |
len | Length of a list or text | {{len .Profile.Attributes.tags}} prints 2 |
index | One entry of a list | {{index .Profile.Attributes.tags 0}} prints vip |
slice | Part of a text | {{slice .Profile.Attributes.first_name 0 2}} prints An |
print, printf | Format values | {{printf "%.2f" .Profile.Attributes.balance}} prints 1250.50 |
urlquery | Make text safe inside a web address | ?q={{urlquery .Profile.Attributes.city}} |
printf uses the usual formatting codes. A number from a profile is a decimal number, so use %.2f or %v; %d does not format it. printf refuses a withheld attribute.
Variables hold a value for reuse: {{$name := .Profile.Attributes.first_name}}Hello {{$name}}. Inside a loop, {{range $i, $item := .Run.State.cart}} gives you the position as well as the entry.
Related
- Personalization syntax for tags, data and the personalization dialog.
- Channels and delivery for what happens when a message fails to build.