Create emails with programmable content

Last updated:

This feature is currently in beta. By using this functionality you agree to the developer beta terms. This guide refers to functionality available only through that beta. Opt-into the beta in your templates or modules.

APPLICABLE PRODUCTS
  • Marketing Hub
    • Professional or Enterprise

Using programmable content to personalize emails with data from your HubSpot account using HubL. 

The data sources you can use in a programmable email depend on your HubSpot subscription:

  • If you have a Marketing Hub Professional subscription, you can use data from standard CRM objects, such as contacts, companies, and products.
  • If you have a Marketing Hub Enterprise subscription, you can also use structured data sources such as HubDB tables and custom objects. This data can be filtered based on the contact properties of the recipient.

For example, a real estate website could have prospects fill out a form with their home needs. The form submission could then trigger a workflow that sends the prospect an email with homes they may be interested in.

Email sending limits

You can include the crm_object, crm_objects, and crm_associations CRM HubL functions in a programmable email, but any email that includes these specific functions are subject to the following limits that are based on the number of recipients you're sending to:

Total recipients Maximum number of CRM HubL functions
500,000 1
250,000 2
165,000 3
125,000 4
100,000 5

Sending an email that meets or exceeds one of the limits above will delay or cancel the sending of your email.

In addition to the limits outlined above, be aware of the additional caveats listed below:

  • If you clone a programmable email, it cannot be sent while the original is still in a processing state. You should wait at least 1 hour between each email send.
  • You cannot conduct an A/B test for a programmable email that includes a crm_object, crm_objects, or crm_associations HubL function.

1. Create a programmable email module

To create the email module to access your HubDB or custom object data:

  • In your HubSpot account, navigate to MarketingFiles and TemplatesDesign Tools.
  • In the upper left, click File, then select New file.
  • In the dialog box, select Module for the file type, then click Next. Then, select the Emails checkbox and enter a name for the file.
  • Click Create
  • To enable programmable email for the module:
    • In the inspector on the right, toggle the Enable module for programmable email beta switch on. programmable-email-switch0
  • You can also enable programmable email for a coded email template by adding isEnabledForEmailV3Rendering: true to the top of the file. 

    enable-design-manager-template-for-programmable-email

 

With the module created, you'll then add code to access data from your CRM. The following examples below demonstrate how to query from different data sources.

Standard objects

You can use the HubL functions such as crm_object, crm_objects, and crm_associations to query data from standard objects in your account, such as contacts, companies, or products.

The code below uses the crm_object HubL function to query the data from a product with an ID of 2444498793 and render the name, description, and price:

{% set product = crm_object("product", 2444498793, "name,description,price") %} <div> <p> <span>Name: </span> <span>{{ product.name }}</span> </p> <p> <span>Description: </span> <span>{{ product.description }}</span> </p> <p> <span>Price: </span> <span>{{ product.price }}</span> </p> </div>

Custom objects

If you have a Marketing Hub Enterprise account, you can query data from a custom object you've created in your account.

The code below retrieves data from a custom object named Property, returning values (e.g. location, price) stored in the custom object's properties.

Note that the example below uses the custom object's fully qualified name as the first argument when invoking the crm_objects HubL function.

  • The fully qualified name begins with the HubSpot account ID (prefixed by p), followed by an underscore and the lower-cased plural name of the custom object (e.g., properties).
  • You can retrieve an object's fullyQualifiedName by making a GET request to the CRM Objects schema API.
{% set real_estate_listings = crm_objects("p2990812_properties", "", "listing_name,location, price, address, type") %} {% for home in real_estate_listings.results %} {{ home.address}} <br> {{ home.price }} <br> <img alt="{{ home.name }}" src="{{ home.hero_image }}" style="outline: none; max-width: 100%;" width="260px" /> <br> <hr> {% endfor %}
Please note: if the name of your custom object contains hyphens (e.g., My-Custom-Object), its properties can not be rendered in a programmable email. You can recreate the custom object with the hyphens omitted directly in your HubSpot account, or you can use the custom object API.

To filter the data returned for each recipient, you can add a query parameter, which will filter the results by the recipient's contact properties. View the full list of filter options.

{% set query = "price__lte="~contact.budget_max|int~"&price__gte="~contact.budget_min|int~"&city="~contact.city"&order=listing_name" %} {% set real_estate_listings = crm_objects("p2990812_Property", query, "listing_name,location, price, address, type") %} {% for home in real_estate_listings.results %} ... {% endfor %}

HubDB

If you have a Marketing Hub Enterprise account, you can use data from a HubDB table in your email.

The code below uses the hubdb_table_rows HubL function to retrieve all data from the table. This will list all the real estate properties in the email, outputting the details of each property along with their image.

{% set real_estate_listings = hubdb_table_rows(1234567) %} {% for home in real_estate_listings%} {{ home.address}} <br> {{ home.price }} <br> <img alt="{{ home.name }}" src="{{ home.hero_image.url }}" style="outline: none; max-width: 100%;" width="260px" /> <br> <hr> {% endfor %}

To filter the data returned for each recipient, you can add a query parameter, which will filter results by the specified contact properties. View the full list of filter options.

{% set query = "price__lte="~contact.budget_max|int~"&price__gte="~contact.budget_min|int~"&persona="~contact.hs_persona.value~"&order=listing_name" %} {% for home in real_estate_listings %} ... {% endfor %}

In the above example, the contact property Budget max is referenced with contact.budget_max, while Persona is referenced  with contact.hs_persona.value. This is because Persona is an enumeration property, which requires an additional .value to parse the property's value, while other property types do not.

2. Add the module to an email

With the module published, you'll now add it to the body of the drag and drop email.

  • In your HubSpot account, navigate to MarketingEmail.
  • Select the email that you created.
  • In the left sidebar, under Content, click More. Find your programmable email module, then drag it into the email body.
drag-and-drop-email-editor-more-modules

If you've set up the module to filter data by specific contact properties, the email preview will appear blank. This is because the email tool hasn't been set to preview the email by a specific contact.

To preview what the email will look like for a specific contact:

  • In the upper right, click Actions, then select Previewemail-actions-menu0
  • On the next screen, click the Preview as a specific contact dropdown menu, then select a contactpreview-email-as-specific-contact0

You should now see only the data relevant to the recipient, filtered by their contact properties.

Screenshot of Email Preview

It's important to always have fallback data to send in the case that there are no HubDB rows or custom object records that meet the criteria you've set. Otherwise, the recipient might receive a blank email.

This beta may cause issues with existing templates. It's important to test any changes thoroughly before publishing and sending a live email.

More HubDB focused tutorials


Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.