Bento

Liquid Template Guide

Picture crafting an email template that seamlessly adapts with unique, personalized information. That's what Liquid helps you do. It's like a special recipe book for emails. You write some simple adlib like phrases, and boom! Your email can show different things to different people. Want to greet visitors by name? Show special deals? Liquid makes it possible. It's not super fancy, but it's pretty neat. Check out the basic Liquid guide below to learn its tricks.

The Basics

These essential tags will allow you to personalize your email extensively with links, buttons, images, and even audio to kick things off.

Name Personalization

Use these to make your emails feel more human, even when subscriber data is incomplete.

First name or fallback

Simple fallback when first name is missing.

First name, else last name, else default

Cascading fallback logic for better personalization.

Confirmation Emails

Ensure that order confirmations, receipts, and status updates work even if optional fields are missing.

Order confirmation with order ID

Display order confirmation when order ID exists.

Download link for digital products

Conditional download links for digital product purchases.

Trial period days left

Show remaining trial days with fallback for expired trials.

Marketing

Create subject lines, headlines, and calls-to-action that gracefully fallback when needed.

Friendly subject line

Personalized subject lines with fallback.

Greeting with company name fallback

Dynamic greetings that adapt to available data.

Plan name with default

Display subscription plan with sensible default.

Product Recommendations

Create dynamic product suggestions based on purchase history and preferences with smart fallbacks.

Category-based recommendations

Show products based on last purchased category.

Purchase history fallback

Recommend based on previous purchases or show general promotions.

Seasonal promotion with personalization

Combine seasonal offers with personal data.

Links are among the most common elements used. They are simple, accessible to users, and very recognizable for their functionality. The liquid tag consists of two parts: a URL and the label. Users familiar with HTML will recognize the components of an HTML ahref tag.

Required Attributes

  • Name
    url
    Type
    Url string
    Description

    Url you want the user to go to when they interact with the link.

  • Name
    hyperlink
    Type
    Label Text
    Description

    The text you want visible for the user to interact with.

A common gatcha we see with users including a full html ahref tag which causes the link to not work. For example a user will use
<a href="https://example.com"></a> when they only need to use the https://example.com

Preview

Click Here!

Button

Buttons offer the same functionality as links but come with a distinct, button-like appearance. They are perfect for Call to Actions, making them stand out more effectively than standard links within text.

Their syntax is the same as links, and follows the same rules, avoid using html inside for the link.

  • Name
    url
    Type
    Url string
    Description

    Url you want the user to go to when they interact with the link.

  • Name
    hyperlink
    Type
    Label Text
    Description

    The text you want visible for the user to interact with.

  • Name
    color
    Type
    hexcode
    Description

    HEX code color for the button. You can read more about hex code colors here. Or find some great colors here.

Preview

Audio

If you want to link to some audio for your users to enjoy, and their email client supports playback inside the client, there's a tag for that! It also includes a direct link to the audio for clients that don't support playback.

  • Name
    url
    Type
    Url string
    Description

    Public url to the audio file for users to play.

  • Name
    type
    Type
    string
    Description

    Defines this link is an audio file for playback.

Preview

If your email client does not support playing audio click here to listen.

Images

Images are worth a thousand words and play an essential visual role in any message, enhancing engagement and comprehension. This versatile image tag supports all HTML versions and options, ensuring compatibility across various platforms. Whether for informative content or captivating visuals, it seamlessly integrates to elevate your web presence.

  • Name
    url
    Type
    Url string
    Description

    Public url to the image file to display.

  • Name
    image_tag
    Type
    string
    Description

    comma seperated list of options, supports in order css classes, id tag, alternate text, width in pixels, height in pixels

Preview

alt

Greeting

Constructs a personalized greeting for the email recipient, formatted with a preference for using their first name, creating a warm and engaging tone that fosters a sense of familiarity and connection right from the start.

Liquid Tags like this only return the plain text, inheriting styling from the surrounding copy. This ensures a consistent and cohesive appearance with the rest of your template.

Preview

Hi Jesse,

Formatted Name

Constructs their full name from the name fields provided.

Liquid Tags like this only return the plain text, inheriting styling from the surrounding copy. This ensures a consistent and cohesive appearance with the rest of your template.

Preview

John Doe

Gravatar Avatar

This feature uses the user's email to show their Gravatar Avatar, ensuring a consistent and recognizable online presence. You can learn more about Gravatar Avatars here.

In the case that the user does not have a Gravatar avatar a fallback image is provided.

Preview
bento_docs_feedback@bentonow.com John

Operators & Conditionals

If Conditional

This is a fantastic way to showcase content based on subscriber tags. For instance, you can display a thank you message for subscribers who have completed a purchase. But if they have not they won't get the thank you.

You can check any element in an if conditional, can be tags, subscribers city, any tag or field you have created. By default the additional content will not display.

You are not limited to what content can be inside the conditional.
They can be text links, buttons, images or full parts of your template.

Preview
This visitor has a 'customer' tag.

If/Else Conditional

Once more, this is an excellent method to display content tailored to subscriber tags. Continuing with our example, if they haven't made a purchase, rather than expressing gratitude, you can utilize else to include a CTA encouraging them to buy.

You can check any element in an if conditional, can be tags, subscribers city, any tag or field you have created.

You are not limited to what content can be inside the conditional.
They can be text links, buttons, images or full parts of your template.

Preview
You are in Sydney!

Operators

These options enable math and comparison operations. For instance, if you want to offer a discount to subscribers with more than 10 orders or who have spent over $100, you can use an operator to achieve this.

Math can be performed on any numeric field, but for non-numeric fields, you will need to use count.

You are not limited to what content can be inside the conditional.
They can be text links, buttons, images or full parts of your template.

Preview
This visitor has ordered over 10 times!

Visitors Reference

Liquid TagResult
[email protected]
bento confirmation url
users unsubscribe url
control
Sydney
Australia
true/false
Subscribers Tags
Male
John
Doe

Liquid Filters

Liquid filters are powerful keywords that instruct Liquid how to manipulate the variables we provide. They are commonly used for tasks such as appending text, rounding numbers, performing basic math operations, formatting data, and sorting lists. These filters go beyond mere inactive template filling; they actively transform and refine the input to produce dynamic, polished outputs. For instance, you can use filters to truncate lengthy descriptions, convert strings to uppercase, or even handle complex date manipulations. By leveraging these versatile tools, developers can create more responsive and interactive web experiences. Ultimately, Liquid filters are essential for anyone looking to maximize the functionality and presentation of their templated content, ensuring that the final output is both accurate and aesthetically pleasing. Below is a list of filters, but you can find the full specification documentation here.

Append

Adds the specified string to the end of another string.


Capitalize

Makes the first character of a string capitalized and converts the remaining characters to lowercase.


Default

Sets a default value for any variable with no assigned value. default will show its value if the input is nil, false, or empty.


Divide By

Divides a number by another number.


The result is rounded down to the nearest integer (that is, the floor) if the divisor is an integer.


Downcase

Makes each character in a string lowercase. It has no effect on strings which are already all lowercase.


Minus

Subtracts a number from another number.


New Line Br

Inserts an HTML line break <br /> in front of each newline \n in a string.


Pluralize

Pluralizes a word based on a count.


Plus

Adds a number to another number.


Prepend

Adds the specified string to the beginning of another string.


Remove

Removes every occurrence of the specified substring from a string.


Replace

Replaces every occurrence of the first argument in a string with the second argument.


Round

Rounds a number to the nearest integer or, if a number is passed as an argument, to that number of decimal places.


Truncate

Shortens a string down to the number of characters passed as an argument. If the specified number of characters is less than the length of the string, an ellipsis (…) is appended to the string and is included in the character count.


Upper

Makes each character in a string uppercase. It has no effect on strings which are already all uppercase.


Helpers Reference

Environment Variables

Interact and check the env variables.

Liquid TagResult
{{ ENV.webhooks }}true / false
{{ ENV.laravel }}true / false
{{ ENV.block_form_tracking }}true / false

Encryption / Hashing

These helpers offer a convenient way to encrypt or hash string values, enabling you to encrypt something for a user on demand without needing to store it for retrieval. Excellent for removing PII out of plain text.

Liquid TagResult
{{ "secret_string" | md5 }}312f946cb92aaa541723382cda411c31
{{ "your secret string" | hmac_sha256: "key" }}63fa337d0a0e6520a12e223657d17184a5e2b131

Time

These tools provide an interface to dynamically work with time, which proves invaluable when managing extensive subscriber lists that necessitate batching. By calculating the precise time for each user when the email is queued for sending, you mitigate concerns about information in the template becoming outdated if a batch is sent several hours later. This ensures that all recipients receive the most current and relevant information. This can also be used for example remind a user that their birthday is coming up in X number of days, or that it's been X number of weeks since they last signed in or made a purchase.

All the time responses are time formatted string
Liquid TagResult
{{ "2010-10-31" | advance_date_to_next: "monday" }}2010-11-01 00:00:00 +0000
{{ "2024-12-31" | days_until }}116
{{ "2024-12-31" | weeks_until }}16
{{ "2022-12-31" | weeks_since }}87
{{ "2022-12-31" | days_since }}614
{{ "2022-12-31" | at_midnight }}2022-12-31 00:00:00 +0000
{{ "2010-10-31" | in_time_zone: "America/Denver" | date: "%Y-%m-%d %H-%M-%S %z" }}2010-10-31 00-00-00 -0600
{{ "2010-10-31" | timestamp }}1288483200
{{ visitor.created_at | time_ago_in_words }}about 2 months

Money

Format money according to the currency assigned to the subscriber or visitor.

Liquid TagResult
{{ money.formatted }}$900.00 USD

Lottery Element

Lottery or randomly pick an element from the provided list. No limitations or weighting applied to elements, ensuring each item has an equal chance of selection.

Supports only strings and you must provide the split delimiter
Liquid TagResult
{{ "Offer One||Offer 2||Offer 3" | split: "||" | pluck_at_random }}Offer 3

Broadcasts

These liquid tags are designed to function specifically within the context of your broadcast and will not work anywhere else.

Liquid TagResult
{{ subject }}Broadcast Subject
{{ name }}Name of the broadcast
{{ created_at }}Timestamp when broadcast was created

The Timestamp returned by created_at can be reformatted using the time helpers, providing you with the flexibility to display the date and time in various formats. Additionally, you can easily adjust the timezone to align with your specific use case needs, whether it's for local time representation or to represent time in the subscribers local time.

Sequences

These liquid tags are designed to function specifically within the context of your sequences and will not work anywhere else.

Cancel the sequence

This creates a hyper link that allows the user to stop the sequence they are in. This helpful to provide subscribers as an alternative to unsubscribe. This is used in the Bento signup drip sequence.

Preview
No more emails like this!

Skip forward to the next email in the Sequence

This feature lets you seamlessly skip forward to the next email in the sequence and offers the option to redirect recipients to a specific web URL.

When redirecting the URL, ensure it matches the domain of the author sending the emails.

Preview
Instantly get the next email.
Instantly get the next email with redirect.

Ecommerce

Render Last Cart

This feature enables you to display the user's last cart, perfect for reminder emails to encourage users to complete their purchase.

Preview

Apple Watch Ultra 2 - 799.00 USD - 1
49mm Indigo Alpine Loop - 99.00 USD - 1
49mm Orange Ocean Band - 99.00 USD - 1

Render Products

This feature allows you to showcase a list of products.

This is available exclusively within flows.

This functions just like render cart but works seamlessly in flows and can extends beyond the user's most recent cart.

Preview

Apple Watch Ultra 2 - 799.00 USD - 1
49mm Indigo Alpine Loop - 99.00 USD - 1
49mm Orange Ocean Band - 99.00 USD - 1

Abandoned Cart Checkout URL

A quick and convenient method for generating a personalized URL to seamlessly guide users back into their shopping cart from a reminder email. This makes it easier for users to return to their cart.

This provides the string URL, offering flexibility to create a full HTML hyperlink as needed.

This is available exclusively within flows.
Liquid TagResult
{{ abandoned_checkout_url | default: "https://example.com/cart" }}URL string

Stripe and Shopify

These Liquid tags enable you to seamlessly integrate with the Stripe and Shopify platforms, offering convenient methods to generate on-demand coupon codes.

This only returns a string value of the coupon code.

Shopify coupon

Generate a unique coupon code with Shopify.

  • Name
    coupon name
    Type
    string
    Description

    Name for the coupon code.

  • Name
    dicount amount
    Type
    string
    Description

    Defines the discount amount.

  • Name
    discount type
    Type
    string
    Description

    Defines the type of discount valid options: fixed_amount percentage.

Preview

100OFF

Create a distinctive discount code using Stripe

Generate a unique coupon code with Stripe

  • Name
    coupon name
    Type
    string
    Description

    Name for the coupon code.

  • Name
    dicount %
    Type
    string
    Description

    Defines the discount amount.

  • Name
    length
    Type
    string
    Description

    In months how long the coupon will be valid.

Preview

TEST

Stripe billing portal link

Create a user-specific Stripe payment portal link.

Generates the url does not create a full html link.
  • Name
    URL
    Type
    string
    Description

    Name for the coupon code.

Preview

https://bentonow.com

External Data

This feature enables you to seamlessly integrate public data from external sources outside of bento directly into your templates, enhancing the richness and relevance of your content with broader data and context.

RSS | JSON | HTML Parse

You define the url as your data source followed by the type option for how to handle the data. Once you have defined your data you will use a loop to iterate over each item in the returned data.

Generates the string content. Requests must be public, and utilize a GET method.
Response data will be string data only.

  • Name
    URL
    Type
    string
    Description

    Name for the coupon code.

  • Name
    type
    Type
    string
    Description

    Supported data types are rss fetch_json youtube fetch_html

fetch_html has an addition parameter that allows you to define a html tag as the parent data wrapper, and what defines the children.

Preview

Milk

Eggs

Bread

Gmail Promo

Add Promo Annotation

Please note that this feature depends on Gmail's discretion.

Promo annotation

  • Name
    promo
    Type
    string
    Description

    What the promo is, often use the amount.

  • Name
    annotation
    Type
    string
    Description

    The supporting annotation to the promo, can be the coupon code.