Email Scripting

Read the Velocity User Guide for a detailed explanation of Velocity Template Language behavior.

Apache Velocity is a Java-based language for templating and scripting HTML content. Use Velocity in Marketo email scripting tokens to access data stored in opportunities and custom objects and create dynamic email content.

Velocity provides if/else, for, and foreach control flow for conditional and iterative content.

Variables

Prefix variables with $. Create or update them with #set:

#set($variable = "value")

Retrieve variable values with reference types that provide different behaviors:

$variable ##outputs 'value'
$variablename ##outputs '$variablename'
${variable}name ##outputs 'valuename'

Quiet reference notation includes ! after $. By default, Velocity leaves the reference string in place when a reference is undefined. A quiet reference emits no value when it is undefined:

##Defined Reference

#set($foo = "bar")
$foo ##outputs "bar"

##Undefined Reference

##normal
$baz ##outputs "$baz"

##quiet
$!baz ##outputs nothing

For more information on how to reference variables, see the Apache User Guide.

Velocity Tools

The Apache Velocity Project provides Velocity Tools. These wrappers expose Java object methods through global variables available to all scripts.

For example, to use a method from ComparisonDateTool, access it from the $date variable in a script token:

#set($birthday = $convert.parseDate("2015-08-07","yyyy-MM-dd"))
##use whenIs to determine how many days away it is
$date.whenIs($birthday).days ##outputs 1

Creating a Script Token

Add Velocity scripts to emails with Email Script Tokens. Create a token in Marketing Activities within a marketing folder or program.

To use a token, the email must be a child of the program that owns the token or inherit it from a marketing folder. Go to a folder or program and select the My Tokens tab. Drag the Email Script option from the right menu into the token list.

Edit the token name, then select Click to Edit to open the editor:

In the editor, create a script that accesses variables in script-accessible objects. To add an object field reference, drag it from the right tree into the script:

Script Embedding and Testing

After defining the script in a program My Token, reference it from an email in the Marketo email editor.

Test the script with the Send Sample Email action in the Marketo email designer. Select an existing lead in the Lead field so the script processes correctly.

When testing $TriggerObject, select the triggering object with the Trigger parameter. Marketo uses the most recently updated object of that type as the $TriggerObject variable.

You can also test with Email Preview. Select View As: Lead Detail, then select a lead from a static list. The preview also displays exceptions from script execution:

Best Practices

The combined length of all Email Script Tokens in a given email may not exceed 100,000 bytes. This limit pertains to the total length of the token strings themselves (not the total length after tokens have been expanded).

<!-- Correct -->
#set($url = "www.example.com/${object.id}")
<a href="http://${url}">Link Text</a>

<!-- Correct -->
<a href="http://www.example.com/${object.id}">Link Text</a>

<!-- Incorrect -->
<a href="${url}">Link Text</a>

<!-- Incorrect -->
<a href="{{my.link}}">Link Text</a>

<!-- Incorrect -->
<a href="http://{{my.link}}">Link Text</a>