Email Scripting

NOTE: It is highly recommended that you read the Velocity User Guide for a deep-dive into the behavior of the Velocity Template Language.

Apache Velocity is a language built on Java which is designed for templating and scripting HTML content. Marketo allows it to be used in the context of Emails by using scripting tokens. This gives access to data stored in Opportunities and Custom Objects, and allowing the creation of dynamic content in emails. Velocity offers standard high-level control flow with if/else, for, and for each to allow conditional and iterative manipulation of content. Here’s a simple example to print a greeting with the correct salutation:

//check if the lead is male
if(${lead.MarketoSocialGender} == "Male")
    if the lead is male, use the salutation 'Mr.'
    set($greeting = "Dear Mr. ${lead.LastName},")
//check is the lead is female
elseif(${lead.MarketoSocialGender} == "Female")
    if female, use the salutation 'Ms.'
    set($greeting = "Dear Ms. ${lead.LastName},")
else
    //otherwise, use the first name
    set($greeting = "Dear ${lead.FirstName},")
end
print the greeting and some content
${greeting}

    Lorem ipsum dolor sit amet...

Variables

Variables are always prefixed with ‘$’ and are set and updated using #set:

#set($variable = "value")

Their values can then be retrieved via several different reference types with different behaviors:

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

There is also quiet reference notation, where there is a ! Included after the $. Normally when velocity encounters an undefined reference, the string representing the reference is left in place. With quiet reference notation, if an undefined reference is encountered, then no value is emitted:

##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 makes functionality available through the use of Velocity Tools. These are simply wrappers for Java objects and expose their methods through global variables which are made available to all scripts.

For example, to use a method from ComparisonDateTool, access if 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

Velocity script is included in emails by using Email Scripting Tokens. These can be created in Marketing Activities in either a Marketing Folder or a Program. For a token to be used inside an email, the email must be a child of a program which either owns the token, or inherits it from a marketing folder. To create a token, navigate to a folder or program, and select the My Tokens tab. From the right-hand menu drag the ‘Email Script’ option into the token list

From here, you can edit the name of the token, and open the editor via the Click to Edit option:

Once you are in the editor, you can create a script with access to all variables in script-accessible objects. To get a field reference from an object, drag it from the right-hand tree into your script:

Script Embedding and Testing

Once you have your script defined within a Program My Token, you can reference it within a given email using the Marketo email editor.

You can test your script using the Send Sample Email email action within the Marketo email designer. For the script to process correctly, you must select an existing lead to impersonate in the Lead field. If you’re testing with $TriggerObject, you can select the triggering object via the Trigger param. This uses the data from the most recently updated object of that type as the $TriggerObject variable.

You can also use the Email Preview to test your script. To do so, you must select View As: Lead Detail, and select a lead from an available static list. This has the added benefit of outputting any exceptions that may have occurred during script execution:

Helpful Hints

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>