Developer Guide: Code Blocks in Behavioral Journeys

Chapter 1

What is a code block?

A code block is a block-like structure of code that groups together multiple declarations and statements. A code block can be used to make control structures, where separate elements work in conjunction with one another.

This is useful for many reasons, but its primary use is to group together statements (directives) and treat them as one. You can cause multiple parts of your email to act together, without activating the other parts of the emails.

This also allows you to control elements of an email that share the same name without affecting the other, assuming it’s outside of the code block. This will create a pathway between HTML files (the standard coding language) and data stores.

There are also specific types of code blocks, such as Shopify’s Liquid, that simplify this process by acting as a template.

You can use inline CSS with code blocks, which alters the style of your email. VML, a file format for on-screen graphics like background images, is also supported. You can even use conditional comments with code blocks, which allow you to alter the style of your according to the browser it’s opened in.

You can think of a code block as holding down the control key and selecting specific files, then moving them all at once. This is much more useful than moving files by themselves or using the shift key to only select files that are beside each other.

Chapter 2

When you should use code

With so many user-friendly applications on the web, you may be wondering why you would bother using your own code for marketing automation software.

Using your own code has many benefits in terms of creating the ideal customer’s journey.

It allows you to customize your email in exactly the way you want without having to rely on pre-supplied tools that only have so many options, so you can create a unique email that achieves precisely what you want it to.

Some email marketing services even allow you to import your own HTML into their service so that you can get the best of both worlds.

Another benefit of using your own code is that you can create personalized displays for individual contacts. Among these customized displays are dynamic links, which can only be seen by individuals that you allow.

Image maps are also possible, meaning that clicking on different areas of an image will take you to different locations. This feature could be incredibly useful if showing off the different parts of a device, car, or workout.

Source: Pretty Good Emails

Many drag-and-drops don’t offer those features.

Chapter 3

What you can do with the code block

The code block accepts Liquid, HTML, inline CSS, conditional comments, and VML.

Liquid

In code blocks, you can interact with data passed with the event that triggered the journey, using the Liquid template language.

Properties passed in the trigger event are available under the triggerEvent object.

To output a value from the trigger event data, prefix the property name with triggerEvent. and enclose it in braces.

Example

{{ triggerEvent.order_number }}

Event data can also be accessed through Liquid tags for logic or iteration.

Example

{% if triggerEvent.line_items %}
  <table>
  {% for line_item in triggerEvent.line_items %}
    <tr>
      <td><img src="{{ line_item.image }}" alt=""></td>
      <td>{{ line_item.title }}</td>
      <td>{{ line_item.price }}</td>
    </tr>
  {% endfor %}
{% endif %}
</table>

Liquid filters can also be applied to event data.

Example

{{ triggerEvent.total | prepend: "AUD " }}

The following filters are supported:

• append
• capitalize
• date
• divided_by
• downcase
• escape
• first
• join
• last
• map
• minus
• modulo
• newline_to_br
• plus
• prepend
• remove
• remove_first
• replace
• replace_first
• round
• size
• slice
• split
• strip_html
• times
• truncate
• upcase
• url_encode

Basic HTML and inline CSS

For the safety of you and your recipients, the code block supports the following safelist of HTML elements:

• <a>
• <abbr>
• <acronym>
• <address>
• <area>
• <article>
• <aside>
• <b>
• <bdi>
• <big>
• <blockquote>
• <br>
• <button>
• <caption>
• <center>
• <cite>
• <code>
• <col>
• <colgroup>
• <data>
• <datalist>
• <dd>
• <del>
• <details>
• <dfn>
• <dir>
• <div>
• <dl>
• <dt>
• <em>
• <fieldset>
• <figcaption>
• <figure>
• <font>
• <footer>
• <h1>
• <h2>
• <h3>
• <h4>
• <h5>
• <h6>
• <header>
• <hr>
• <i>
• <img>
• <ins>
• <kbd>
• <keygen>
• <label>
• <legend>
• <li>
• <main>
• <map>
• <mark>
• <menu>
• <menuitem>
• <meter>
• <nav>
• <ol>
• <optgroup>
• <option>
• <output>
• <p>
• <pre>
• <progress>
• <q>
• <rp>
• <rt>
• <ruby>
• <s>
• <samp>
• <section>
• <select>
• <small>
• <span>
• <strike>
• <strong>
• <sub>
• <summary>
• <sup>
• <table>
• <tbody>
• <td>
• <tfoot>
• <th>
• <thead>
• <time>
• <tr>
• <tt>
• <u>
• <ul>
• <var>
• <wbr>

On these elements, we allow the following safelist of HTML attributes:

• abbr
• accept
• accept-charset
• accesskey
• action
• align
• alt
• ARIA attributes
• autocomplete
• autosave
• axis
• bgcolor
• border
• cellpadding
• cellspacing
• challenge
• char
• charoff
• charset
• checked
• cite
• clear
• color
• cols
• colspan
• compact
• contenteditable
• coords
• Data attributes
• datetime
• dir
• disabled
• draggable
• dropzone
• enctype
• for
• frame
• headers
• height
• high
• href
• hreflang
• hspace
• ismap
• keytype
• label
• lang
• list
• longdesc
• low
• max
• maxlength
• media
• method
• min
• multiple
• name
• nohref
• noshade
• novalidate
• nowrap
• open
• optimum
• pattern
• placeholder
• prompt
• pubdate
• radiogroup
• readonly
• rel
• required
• rev
• reversed
• role
• rows
• rowspan
• rules
• scope
• selected
• shape
• size
• span
• spellcheck
• src
• start
• step
• style
• summary
• tabindex
• title
• type
• usemap
• valign
• value
• vspace
• width
• wrap

In inline style attributes, all CSS properties are allowed. CSS from the email template will not be automatically inlined onto HTML elements in the code block.

External images

Background images and <img> are allowed with external images you have control over.

Please refer to our tips for web-based images, which also apply to images you use in code blocks.

Example

<img src="https://placehold.it/400x300" style="height: auto; max-width: 100%;" width="400" alt="" />

Conditional comments

The following syntaxes are supported for conditional comments:

<!--[if expression]>Downlevel-hidden conditional comment<![endif]-->
<!--[if expression]>Downlevel-hidden conditional comment<![endif]-->
<!--[if expression]>-->Downlevel-revealed conditional comment<!--<![endif]-->
<!--[if expression]><!-->Downlevel-revealed conditional comment<!--<![endif]-->

VML

VML, commonly used for bulletproof background images and buttons, is supported when placed inside downlevel-hidden conditional comments.

VML elements with href attributes will be treated like normal links, but images referenced in VML will not be imported and hosted on our servers.

Chapter 4

What you can't do with the code block

Unsupported Liquid filters

The following Liquid filters are unsupported or poorly supported in code blocks:

• abs
• ceil
• compact
• default
• escape_once
• floor
• lstrip
• reverse
• rstrip
• sort (with case-sensitive order)
• sort_natural
• strip
• truncateword
• uniq
• url_decode

Spread code across multiple code blocks

Each code block you add to your email is parsed separately, so an HTML element or Liquid tag you open in one code block must be closed in the same code block.

Variables assigned in one code block also do not persist to the next block.

Stylesheets and media queries

CSS is only supported using inline style attributes, which limits the ability to code responsive elements that rely on media queries. Interactive email techniques are also prevented by the lack of support for embedded or external stylesheets.

Uploaded images

If you use images in code blocks, you will need to host them on an external server. Make sure the hosted images are under your control, as images hosted by other people may change or be deleted by the time your email is sent.

Personalization tags, dynamic content, and custom field data

Personalization and dynamic content tags are not supported in code blocks, and the custom field data is not available for use in Liquid. Any subscriber data that you need to interact with in Liquid must be included in the trigger event.

IDs and classes

Because the code block doesn’t support stylesheets, HTML elements do not need IDs and classes. These are removed to prevent conflicts with the values used in the email builder’s template.

Javascript, forms, iframes, etc.

Any HTML not mentioned on the safelist above will be removed from the “Code” block’s resulting output.

Invalid conditional comment syntax

Most conditional comment syntaxes are supported in code blocks, but the following will cause parsing issues, since it’s not valid HTML or XHTML:

<![if expression]>Invalid downlevel-revealed conditional comment<![endif]>

What does marketing automation software do?

If writing code seems too complicated, there are alternatives, like marketing automation software. Using such software will allow you to achieve many of the same goals, without the degree of customization.

This software usually comes in the form of a service, meaning you’ll work with industry professionals and their tools to design the perfect automated campaign.

When it comes to the best marketing automation software, providers like Campaign Monitor offer a visual journey designer that can create automated campaigns that branch off, depending on the user’s actions.

Chapter 5

Working with code blocks

Testing code blocks

For privacy reasons, real data from live events is not available for testing.

To test how code blocks will render with event data, you enter a sample event with non-sensitive data which will be used in the email builder preview and in test emails. You can freely update the sample event to test what the output will be under different conditions.

Inline styles

By default, code blocks will inherit your default styles for “Normal text”. Stylesheets are not supported in code blocks, so the way you can override the default styles is with inline style attributes on your HTML elements.

If you prefer to code your CSS as a stylesheet initially, you can use a CSS inliner to help you inline it onto your markup, although this may not be feasible for code involving Liquid.

CSS from the email builder’s template will not be automatically inlined onto your markup, but may affect how your code blocks render in email clients that support embedded stylesheets.

Mobile version

For the best experience for your recipients reading emails on mobile, it is recommended to keep your code blocks to a simple one-column design.

The email builder’s template is coded with a mobile-first approach to make it responsive in as many email clients as possible, using the mobile version as the fallback when not supported. This technique requires a stylesheet, which is not available in the code block.

Because you can not make use of such responsive techniques in code blocks, the safest strategy for making your design adapt well to the mobile size is to limit your content to a maximum width of 100%.

Text already behaves this way by default, reflowing to fill the available column width.

Multi-column layouts and tabular data can be used, but can not easily be stacked on mobile in a controlled way. Be cautious of content which may exceed the width of the mobile version, especially when event data is involved.

On images, we recommend setting the CSS width to the image file’s pixel width and the max-width to 100% or vice versa. For Outlook, you can set the HTML width attribute to the width the image should have in the desktop version. For the image to maintain its aspect ratio, avoid setting an HTML height attribute, and set the CSS height to auto instead.

Example

<img style="width: 840px; max-width: 100%; height: auto;" src="https://placehold.it/840x630" alt="" width="560" />

Because of potential rendering differences between email clients that support embedded stylesheets and ones that do not, extra thorough email client testing is strongly recommended.

Unbalanced tags

The HTML tags in the output from each “Code” block will always be balanced. If your code results in unbalanced tags, these will be resolved automatically, although maybe not in the way you would do so. For this reason, we recommend validating your own HTML to help identify unbalanced tags.