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:

Velocity Tools

Velocity makes functionality available through the use of 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:

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 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.
  • You need to check the box in the script editor for the fields you’re using or they won’t process
  • Script tokens cannot be used in emails which have Dynamic Content
  • For each custom object, the 10 most recently updated records per person/contact are available at runtime and are ordered from lastest 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.
  • Tools Reference: http://velocity.apache.org/tools/releases/2.0/summary.html
  • 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.
    • Right:
      #set($url = “www.example.com/${object.id}”)
      <a href=”http://${url}”>Link Text</a>
    • Right:
      <a href=”http://www.example.com/${object.id}”>Link Text</a>
    • Wrong:
      <a href=”${url}”>Link Text</a>
    • Wrong:
      <a href=”{{my.link}}”>Link Text</a>
    • Wrong:
      <a href=”http://{{my.link}}”>Link Text</a>
    • The url must be part of an anchor tag