Hubspot Emails with Custom Data

Using the standard email feature from Hubspot and working with the Drag&Drop editor is pretty fine. However, you may want to create some more sophisticated emails for your customers in some situations including complex data.

Currently, the email templates of Hubspot are very limited in respect of adding custom data. You can use so-called personalization tokens to insert data from connected objects of your CRM (Contact, Product, Deal data). This is handy for inserting a personal greeting, some product offers or providing some details on the last deal you made with this customer.

When working with custom objects, you may introduce more complex data instead of simple strings. Maybe you are saving structured data (CSV, JSON, XML, etc.) and even pre-rendered HTML into your custom object properties. In this case, adding this data to your email template is very limited and frustrating.

This is where transactional emails and the Hubspot API come in very handy. With the help of the Single-Send API, we can send a transactional email template and pass any custom property to it. The custom property can be used within the email template by simply inserting it as a template token like {{custom.myCustomProperyName}}.

Attention: When using a custom code function in your workflow and Node.js as the implementation language, be aware that the @hubspot/api-client version 3.4.1 is available only at the moment of writing this post. Since the documentation of the Hubspot API is more recent, you will face some pitfalls when using the coding examples because of deprecated or no longer existing framework interfaces. You also have the option to develop your function with Python and use the @hubspot/api-client version 4.0.4 package.

Getting the work done and send your mail with custom data is done in three simple steps. We will create a workflow and implement a custom function to showcase this.

Setup the mail template

Start with a new email based on a template. In Hubspot, access Marketing -> Emails -> Create email and select Automated as email type.

Next, lay out your email template and add all the necessary message body. You can insert personalization tokens by using the text module wherever you like. For our example, we want to display a table with some statistics about the reading count of medium articles of a given user. Insert an HTML module and edit the code to display the table. At this point, we insert our own custom token {{custom.readingStats}}. This token will contain the statistics as pre-rendered HTML rows.

Finally, go to the email settings and add all the details like subject, sender, language, etc. It is very important to change the subscription type to Transactional. Emails marked as transactional emails can be used within workflows and the API. It is also unnecessary to insert unsubscribe links and other GDPR-relevant information in this case.

Before saving the email convert it to a single-send email via the Actions menu. After saving the email, write down the ID of the email template. You will find it in the current URL or on the details page of the email. This ID is used in the custom function to send the email via the API.

Create the workflow

Next, access Workflows -> Create workflow and set up the workflow based on the relevant data for your use case. For our example, we choose a Contact-based trigger with a monthly execution, and the workflow will execute on the first day of each month.

Our workflow definition is pretty simple and includes all active contacts. The schedule trigger step is responsible for executing this workflow regularly. As the last step, we insert a custom code action. As implementation language, we choose Node.js 12.x. Also, we will need to add a secret, so we can access the Hubspot API within our code. We simply name the secret API_KEY, and it will be available as an environment variable within our code.

Implement the custom function

After adding the custom code workflow step, we are ready to add our custom function. Basically, we need to do the following things:

Set up the Hubspot API client
Get the contact details of the current workflow contact
Fetch or prepare some custom data
Send the email by using the Single-Send API and provide our custom data as an additional parameter

Below, you will find the example code for adding the readingStats custom data, containing some pre-rendered HTML table rows. This is a fixed string for simplicity, but you can complement it with a particular data fetching method.

Finally, you can directly test your custom code by selecting an existing contact. Be careful selecting some of your testing contacts because the function will send the email in any case.

Tip: For the purpose of debugging, you can use console.log and the output will be shown directly in the web user interface after the execution.

Resources: