To get this feature - request it through our form.
This guide explains how to use Data Connection to dynamically retrieve external data in Optimove Native Channels. It covers everything from selecting a data connection to executing the campaign, all while integrating dynamic, personalized content such as images or product information.
Data Connection Builder Workflow
To start, open a Data Connection Builder in a template.
In OptiMail:
In OptiMobile Push, Web Push, OptiText:
1. Selecting a Data Connection
To start, pick a Data Connection from a list. The list includes all Data Connections created via the Opti-X UI or the Data Connection API.
You can only select one data connection at a time. If you've recently created a data connection but don't see it listed, it may still be processing, especially if it involves a large file. In this case, wait a few moments and then check again. Once processing is complete, the data connection will appear in the list for selection.
2. Choosing Property for the Template
After selecting a Data Connection, a list of available properties from your data source will be displayed. These properties are generated by parsing the structure of your data source—whether it's a table schema for CSV files or key/field names for JSON data.
Select which content you want to display in your template.
Where does this come from?
When connecting a data source, the system extracts field names (or "properties") based on the file format or API structure. These fields define the available data but don’t contain actual content — just a reference to the data structure.
- CSV file: The system reads the column names from the file. You’ll see a list of these fields to choose from.
- JSON file: The system detects keys (also called property names) that represent different pieces of data in the JSON structure.
- Third-party API: The system pulls the available fields from the API’s schema, similar to how it reads fields from a file.
At this step, you can define a fallback in case no data is available from your source. You have two options:
- Skip sending for that particular user if the required data is missing.
- Set a fallback value, replacing the missing data with a generic or default value.
3. Set Lookup Key and Value
Select a Lookup Key – this is the reference field from your Data Connection source structure—essentially, the primary key that we defined earlier.
Choose a Lookup Key Value:
- This tells the system what value to search for in the selected lookup key.
- You can choose either:
- An exact value from your data source (e.g.,
category_name = "Skincare"to pull skincare-related content). - A personalization tag from your customer attributes such as Favorite Category, Loyalty Level, Country, etc. This dynamically fetches data specific to each customer, enabling personalized content.
- A general tag, like Campaign ID, to apply lookup rules based on the campaign being sent.
- An exact value from your data source (e.g.,
4. Reviewing Your Selection
Before finalising, you can review selected properties, lookup keys, and conditions. This ensures that all the settings are correct, as Data Connections cannot be edited in the same Builder once they are created.
Once you finish setup in the builder, the Data Connection formula or tag is injected into the template.
How it Looks Like in Templates
Results in OptiMail
The formula always follows a specific structure:
[%DE_{dataConnectionUIID}:{lookupValue}:{external-api-placeholders-if-any}:{returnValue}:{fallback value}%]
Example:
[%DC_efb445ba-bd30-4f86-9dfd-70c65077886f:[%LOYALTY_TIER%]::Discount:10%]
The formula is editable, allowing you to copy, paste, and modify its style. Any changes you make will be reflected accordingly. However, if you manually edit the formula, please note that there is no validation in place to ensure it remains functional. Be cautious when making changes to avoid breaking the formula.
You can read more about the formula here.
Results in Other Channels
- Tags can be easily removed from the template like a regular text element.
- However, tags cannot be edited directly within the template; they are fixed once inserted.
Note: OptiMail’s Preview and Send Test features only support Data Connections formulas that use Customer Tags lookups. To test campaigns using General Tags or other lookup types, launch a live campaign against a designated test user group.
Working with Images
To retrieve image URL as a dynamic content in your template:
-
Follow the steps as above to construct the formula as part of text components.
-
Select the Image component in the editor.
- Copy the formula you've constructed before.
-
Enable the Dynamic URL option in the Image component.
-
Paste your formula into the Dynamic URL field.
⚠️ Note: If you leave the formula as plain text in the template (without enabling the Dynamic URL setting), it will not render as an image.
To achieve the same effect in other supported channels:
-
Click Add Image.
-
Switch to the URL option.
-
Use the Formula Builder to construct the Data Connection tag with image URL.
Lookups for API Placeholders
When you create a Data Connection using API methods, your technical team may define API Placeholders (Read more in Developer guides) - fields like Language, Country, or other parameters that help filter the data dynamically at send time.
Just like you define a lookup value for the Primary Key, you also need to define a lookup value for each API placeholder.
Execution: How the Data Connection Works During Send
Data Retrieval: When the campaign is executed, the channel converts the formula or tag into a query to the data source in the Data Connection, retrieves the requested data, and inserts it into the template.
- If the Data Connection contains a banner or image, that image is dynamically populated when the customer opens the email.
- For text-based content (e.g., product names), the data is retrieved just before the email is executed.
Constraints
You can include up to 3 different data connections to a single template.
You can include up to 10 parameters in a template in each email template. They can be sourced from one or up to 3 different data connections.
The use of the Data Connection feature within a template does not affect the standard execution limits for the channel.