Building Emails with programmable content from HubDB or Custom Objects

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.

Programmable content in email enables you to send emails containing data from either your HubDB tables or Custom Objects records. This data can be filtered based on the contact properties of the recipient.

A real estate website could have prospects fill out a form with their home requirements. Submission of the form could trigger a workflow sending the prospect an email with properties they may be interested in based on their requirements and a HubDB of real estate listings.

This guide assumes you know how to create HubDB tables and Custom Objects.

Once you have custom objects defined in your portal, you can access custom objects using HubL similar to how you would with HubDB.

HubL
{% set query = "price__lte="~contact.budget_max~"price__gte="~contact.budget_min~"&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 %}

1. Create a HubDB Table

Go to HubDB, click the “Create table" button. Give your table a descriptive label like "Real estate listings". Set a table name like "real_estate_listings". Click "Create".

Add some columns to your table. In our example we have added columns Address, City, and Price. We have also added 3 example properties to our table. Publish your table.

2. Create contact properties

We will need to create contact properties to store the information that we want to filter against. These properties can then be updated via. Automation, API, Form Submissions etc.

3. Create a marketing Email to show your listings

Head over to the Marketing Email tool. Create a new Automated email. For this example we will use a simple drag and drop template and delete the default modules.

4. Create a custom module to show Listings

We will create an email module to access HubDB to retrieve our listings. In the Design Manager create a new Module by clicking File > New File . Under "Components" choose "Module". We will make the module available in Emails and name it properties_module.

Now we will write some HubL to access our Listings.

We will use the hubdb_table_rows function to retrieve all the properties in the table.

HubL
{% set real_estate_listings = hubdb_table_rows(1234567) %}

You can get the ID of your table from the HubDB tool.

To start off, we will just list all the properties in the email. We’ll output the details of each property along with their image.

HubL
{% 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 %}

Lets publish this module and make use of it in the email we created. Heading back over to the Marketing Email tool, open the email we created earlier.

 In the sidebar, under Content > More we can find our properties_module module. Drag this module into the email.

content tab

 We will then see the preview populate with all the listings as we have not yet applied any filtering.

email content editor screenshot

We can now go back to design manager and add some extra logic to filter our properties based on the current contact that the email is being sent to. To do this we will use filter parameters for HubDB.

HubL
{% set query = "price__lte="~contact.budget_max~"price__gte="~contact.budget_min~"&city="~contact.city~"&order=listing_name" %}
{% set real_estate_listings = hubdb_table_rows(1234567, query) %}

{% for home in real_estate_listings %}
  
	...

{% endfor %}

Our API documentation has a full list of query parameters.

Lets publish this module again and head back over to the email editor to take a look. You will notice that the module doesn’t appear to be doing anything now. That’s because we aren’t previewing this email for a contact. So let click Actions > Preview and select a contact that fits the constraints for both the properties we’re filtering for and that we have corresponding listings for.

Screenshot Actions > Preview in page editor

We can now see just the properties relevant to the contact being shown in the email.

Screenshot of Email Preview

Things to be aware of

It is important to always have fallback data to send in the case that there are no records that satisfy the constraints you have programmed. Otherwise the recipient might see a blank email like we see in the preview. This could include a list of alternative properties not quite matching the criteria.

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

More HubDB focused tutorials

HubSpot Academy


Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.