Email tokens

Custom item values can be used in the email tokens. The issue with that is that a contact can have multiple custom items linked to it. So the token should specify which custom item(s) they want to use. That's why the custom object tokens are a bit complicated over classic contact field tokens.

Emails are still sent to contacts, so don't forget to link the custom item(s) to a contact receiving the email if you want to show the values to the contact in the email.

Token options

Custom object tokens can have several options to ensure the value will be the one you wanted.

Example token

{custom-object=product:sku | where=segment-filter | order=latest | limit=1 | format=default | default=No SKU found}

Legend:

• custom-object static keyword that would tell the CO plugin to replace this token
• product alias of a specific custom object
• sku alias of a specific custom field
• where=... where condition that would tell the plugin which of the linked custom items we should take the value from.
• segment-filter static keyword that would tell us which custom items we should be looking for
• order=... if the where condition selects more then 1 item, what field and orientation to use to display them
• latest The order by clause
• limit How many custom items to load into consideration. Takes a number as a value
• format=... display multiple values as separated list
• default=[default|or-list|and-list|bullet-list|numbered-list] Default text value if no custom item was found
• No SKU found default value that will appear in the email instead of the token if we don't find any custom item

Where Conditions

There is only one where condition implemented so far and that is segment-filter. That is also the default option if you don't provide any condition. It means it will take the first segment of the segment email or the first campaign source segment of a campaign email, takes all the custom object related filters from it and builds the where conditions from them.

Warning:

1. If multiple segments are used for segment emails or campaign sources, each segment should have identical filters for custom objects. Only the filters of the first segment are taken into consideration during token replacement on email send.
2. Do not use OR conditions in the source emails.
3. Do not use include/exclude segment membership filters as the token replacement won't search all included/excluded segments. Only the root level segment filters.

Ordering

The only valid option is latest as of now. That is also the default option if you don't provide any order. It will order the custom items from the newest to oldest by date when the items were added.

Limit

Default limit is 1 even if no limit is provided. If you increase the limit to more than 1 then the values will be separated by comma.

Format

The value will allow customers to use multiple values in an email such as "Your pets Fluffball, Sparky, & Flash have an appointment tomorrow."

Available formats

• default - comma separated list, used by default
• or-list - comma separated with last value divided by or
• and-list - comma separated with last value divided by and
• bullet-list - bullet is used as list prefix
• ordered-list - numbers are used as list prefix

Tokens in the email builder

The custom object tokens can be added as usual in Mautic. Start typing { and then name of the custom object. Like {product. After that you will see available fields for that custom object.

There is known issue with the token UI. The options cannot be edited as the token JS library will think that you want to change the token completely. The suggested workaround is to edit the token in the HTML mode until there will be better UI that will support token option modifications.