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:

Variables

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

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

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 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, in order to use a method from ComparisonDateTool, we access this from the $date variable in a script token:

Note: The following methods and variables will be explicitly forbidden from use in Marketo Email Scripts after the June 2019 release:

  • $class
  • getClass()
  • $context
  • $text

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

ResizedImage600222-Script-Token

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

ResizedImage60099-Edit

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:

ResizedImage600386-Script-Editor

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.

email-script-marketo-email

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.

ResizedImage600380-testing-your-velocity-script

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:

View-As

Helpful Hints

        • The combined length of all Email Script Tokens in a given email may not exceed 100,000 bytes.  Note that this limit pertains to the total length of the token strings themselves (not the total length after tokens have been expanded).
        • 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 which originate from your natively integrated CRM that are directly connected to the Lead, or Contact, but not third-level custom objects.  Custom Objects may not be parents of the Lead or Company
        • For Marketo custom objects, you can reference second level custom objects with Parent-Child relationship.  e.g. Lead <- Parent <- Child.  You cannot reference second level custom objects with Edge-Bridge relationship.  e.g. Lead <- Bridge -> Edge
        • 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 most recently updated (at 0) to oldest updated (at 9).  You can increase the number of records available by following the instructions here.
        • 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.
        • Tools Reference: http://velocity.apache.org/tools/2.0/index.html
        • A note regarding tokens that contain newline characters “\n” or “\r\n”.  When an email is sent via Send Sample or via a Batch Campaign, newline characters in tokens are replaced with spaces.  When email is sent via Trigger Campaign, newline characters are left untouched.
        • 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.