Home | Cool ClickDimensions Features | Merge any Custom or Standard Entity Data into ClickDimensions Emails

Merge any Custom or Standard Entity Data into ClickDimensions Emails

Note: This is an updated version of an older post, which can be found here.

Recently we had a customer that wanted to have standard email templates that could bring in data from standard and custom entities. But there was a twist; they also wanted to be able to bring in multiple records for some entities. Here is the scenario: the customer is in the home building industry and they wanted to have a standard template that could contain information about the recipient the template was being sent to, as well as information about a specific subdivision and various homes in that subdivision.

A simplified version of the email template is pictured below. This could easily be complex HTML with graphics and formatting, but we are using this example for simplicity. You can see that in line one of the email, the template brings in the recipient’s (contact) full name. Then, in the next line, it brings in the name of a subdivision (a custom entity) and then a table with information about that subdivision. Below that, the email template will include information about one or more home records. This is achieved by using the FreeMarker list directive. FreeMarker is an open source template markup language that the ClickDimensions email engine uses for complex dynamic content.

The data fields in the template can come from any custom or standard field or entity in CRM. You add fields by simply using the same syntax that our standard data fields use. For example, ${Recipient.lead.firstname[0]!””} represents the first name field on the lead record. Following this syntax, we can include any data in the template. For example, if you have a custom entity named New Subdivision with a field named New Name, you can place the data field ${Recipient.new_subdivision.new_name} into your template (note that the characters [0]!”” at the end of the lead first name field are used to specify placeholder text and are optional).

New homes email template

Below is what the custom subdivision entity looks like. Prior to the email being sent out, our images appear as broken links because the source path for the file is being handled by FreeMarker as well. Once the email goes out, the source path will be dynamically pulled from the relevant subdivision or home record and display the appropriate image. Note that it also has home records linked to it (home is also a custom entity).

This is what our subdivision entity looks like in CRM. Relevant homes are connected to the subdivision and accessible through the related menu, and the aforementioned images can be seen at the bottom of the record.

Subdivision record

Below is what the home custom entity looks like. It also has paths to image files.

Home Record

Now that the email template is ready, we need a way to specify which subdivision and which homes should be merged into the template. We do this by using the CRM Connections feature. We simply link a subdivision and one or more home records to the ClickDimensions email send record using the standard CRM Connections functionality on the email send record. In the case of our subdivisions/homes example, we will link a subdivision record to the ClickDimensions email send record.

Subdivision lookup

Then we will link any number of home records to the ClickDimensions email send record. The result is that we have one subdivision and several home records linked to the email send record.

New homes email send connections

Of course, the email template we showed above is also linked to the ClickDimensions email send record.

New homes email send

Now we just add some recipients (leads, contacts, accounts and/or marketing lists in any combination) and when we send our email, all the data from the recipient, subdivision and home records are merged into the resulting email. Again, this was not meant to be a fancy email, but we could just as easily have formatted it any way we wanted.

Sent email

This has been a complex example, but hopefully you are seeing the power of our merging capability, as well as the advantages of enabling dynamic content through the FreeMarker language.

Happy Marketing!

About the Author:

Rhys Saraceni is a Training Developer at ClickDimensions.


  1. Christina July 31, 2017 at 5:52 pm - Reply

    Hi Liz,

    It looks like you are using the freestyle code editor, would I also be able to do this using the drag and drop editor?

    Please Advise,

    • mm
      ClickDimensions Marketing July 31, 2017 at 7:45 pm - Reply

      Thanks for your question, Christina! This is definitely possible in the ClickDimensions drag and drop editor as well.

  2. Christina October 10, 2017 at 5:54 pm - Reply

    Hi There,

    Is it possible to do this same process but with custom entities related to the contact record. I have a custom entity called interviews and I want to show only the interviews that are associated with the contact I am sending the email to.

    Is this possible?


    • mm
      ClickDimensions Marketing October 26, 2017 at 2:17 pm - Reply

      You absolutely can use custom entities (the entities in the example are custom entities), but they will have to be connected to the email send itself. Unfortunately, the FreeMarker doesn’t preemptively have a way of knowing which records are connected to the recipient contact and which aren’t, so the options here are either to only connect the specific interview records that are associated with the recipient, or if there is some field on the interview record that would indicate that it is connected to this particular recipient, you could set up a conditional statement inside the list such that it would only show connected interviews if the record is associated with the recipient.

  3. Morgan Holzberger June 13, 2018 at 1:06 pm - Reply

    Hi there,
    How are you able to do this with the Drag and Drop editor? This seems the same as what this article is describing: https://support.clickdimensions.com/hc/en-us/articles/115001166054-Add-a-User-Photo-to-an-Email-Dynamically-using-a-Photo-URL-Field

    Please advise.


    • mm
      ClickDimensions Marketing June 15, 2018 at 7:50 am - Reply

      If you are referring to the image URLs in the post, the help article you linked to is still applicable; dynamic image URLs couldn’t be used in Drag and Drop since the Drag and Drop editor doesn’t let users modify the source URL for images. Beyond that, everything else done the example could be done in the Drag and Drop editor since FreeMarker is placed in the email body, not the HTML. You could work around the image URL limitation by hardcoding in images then using conditional statements to specify which ones should be seen.

  4. DanielS August 31, 2018 at 10:28 am - Reply

    Hi there,
    Please could you confirm if this would be possible using Campaign Automation?


    • mm
      ClickDimensions Marketing August 31, 2018 at 3:15 pm - Reply

      There isn’t a way to set up a connection between the email send and referenced entity in the campaign automation, so it isn’t possible in this context.

  5. DanielS September 4, 2018 at 4:52 am - Reply

    Is there another way this could be achieved that you could recommend using Campaign Automation to display custom field entries?

  6. Viswanadh February 25, 2019 at 3:19 am - Reply

    Hi Team,

    we customized the related entity details in email template. it’s not working
    we are getting error while sending email “Email Send record contains dynamic tag for new_cordbloodcontract entity but no connection records were found”

    We placed the two fields on the email tamplate. One field is account name field on account record .


    andsecond field is custom entity field new_name, entity nam is new_cordbloodcontract.

    Its a 1: N relationship (Account: new_cordbloodcontract)


    • mm
      ClickDimensions Marketing February 25, 2019 at 8:06 am - Reply

      Please contact our support team for help. They should be able to assist with troubleshooting your specific situation.

  7. Olivier Uzan September 15, 2020 at 4:52 am - Reply

    Good morning,
    We are trying to create an email Send with Connection
    We would like to know what is the best way :
    1) Creating an email send with 500 contacts and 500 connections and using freemarker wit #list and #if to use the connection corresponding to the contacts
    2) Creating 500 email send with 1 contact and 1 connection
    Thanks for our help O

    • mm
      ClickDimensions Marketing September 15, 2020 at 4:19 pm - Reply

      For assistance with this specific issue, please visit support.clickdimensions.com to start a chat with our support team. They will be happy to help!

Leave A Comment