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 through the use of scripting tokens. This gives access to data stored in Opportunities and Custom Objects, as well as allowing the creation of dynamic content in emails. Velocity offers standard high-level control flow with if/else, for, and foreach to allow conditional and iterative manipulation of content. Here’s a simple example to print a greeting with the correct salutation:

Velocity Template Language

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

##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:

Velocity Template Language

1

#set($variable = "value")

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

Velocity Template Language

1

2

3

$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:

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

Velocity Template Language

1

2

3

#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 through the use of Email Scripting Tokens. These can be created in Marketing Activities in either a Marketing Folder or a Program. In order for a token to be used inside of 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’re in the editor, you can create a script and will have access to all variables in script-accessible objects. To get a field reference from an object, just 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 need to select an existing lead to impersonate in the Lead field. If you’re testing a with $TriggerObject, you can select the triggering object via the ‘Trigger’ param. This will use 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 variables referenced in the email script need to exist in Marketo on one of the objects available to the script.

You can reference first and second level custom objects that are directly connected to the Lead, or Contact, but not third-level custom objects.

You can reference custom objects connected to a Lead, Contact, or an Account, but not more than one.

Custom objects may only be referenced through a single connection, Lead, Contact, or Account

You need to check the box in the script editor for the fields you’re using or they won’t process

For each custom object, the 10 most recently updated records per person/contact are available at runtime and are ordered from latest updated (at 0) to oldest updated (at 9).

If you include more than one Email Script within an email they will execute top to bottom. The scope of variables defined in the first script to execute will be available in subsequent scripts.

To ensure proper parsing of URLs, the whole path should be set as a variable and then printed, and variable should not be printed inside of URL references. The protocol (http:// or https://) must be included and must be separate from the rest of the URL. The URL must also be part of a fully formed anchor (<a>) tag. The script must output a fully formed anchor tag, in order for links to be tracked. Links will not be tracked if they are outputted from within a for or foreach loop.

Latest Blog Posts

Keep up with what's new in the developer world

Important Change to Activity Records in Marketo APIs March 1, 2017 Note: This post will be updated to reflect changes made to activity records returned by the API due to migration to new infrastructure.
With the rollout of Marketo’s next-generation Activity Service beginning in September 2017, we will be unable to enforce the uniqueness or presence of the integer “id” field in activities, data value changes, or lead ... Read More >

Spring 2018 Updates June 29, 2018 In the Spring 2018 release we are releasing new REST APIs, and web tracking privacy enhancements. See the full list of updates below.
REST API
Static List CRUD
Allows users to remotely Create, Read, Update, and Delete Static List Records. Enables management of the entire lifecycle of a static list through REST APIs, including populating and maintaining membership. ... Read More >

Winter 2018 Updates March 2, 2018 In the Winter 2018 release, we are releasing a few enhancements to our APIs. See the full list of updates below.
Asset APIs
Activate/Deactivate Trigger Campaigns
We have added the ability to activate and deactivate trigger campaigns, which can simplify the process of automating your program templates. This is achieved by calling two newly added endpoints: Activate Smart Campaign, Deactivate ... Read More >