use_dbi
This plug-in enables SQL database connection in templates, without the necessity of attaching the datasource to the template. This can, for example, simplify the template migration or distribution, without having to do manual changes in the template settings. It can also be used in campaigns which don’t use Smart Templates or Content Styles, but Visual Builder instead. Datasource connection can be done in two ways:
- by using the datasource name: [% 'datasource_name' | use_dbi -%]
- by using the datasource ID: [% 'datasource_ID' | use_dbi -%]
Following steps are the same as if you attached the SQL datasource in the template settings, and used it via DBI plug-in. So if we would, for example, want to use a datasource Stock with ID 1234, it would look like so:
[% USE dbh_sql = DBI (dbh = shared.DBI_DS_SQL_STOCK) -%]
[% query_items = dbh_sql.prepare('SELECT * FROM ds_1234_table_name ORDER BY RAND() LIMIT 5') %]
[% items = query_items.execute () -%]
[% FOREACH items -%]
<pre>[% USE Dumper; Dumper.dump(items) -%]</pre>
[% END -%]
This code snippet connects the datasource ID 1234 SQL database, and following commands display 5 random table records. This is done via the Dumper plug-in, which displays data structure.
Events
Another similar situation to the aforementioned database connection, would be Events data. These data can be automatically accessed in remarketing campaign data structures, which react to Events, but often times the ability to access those data from regular campaigns can be handy as well.
In that case, we can use the Events plug-in. The data can be accessed via this plug-in like so:
The plug-in has 3 parameters:
- tag – the tag (name) of the event we want to use
- status – to choose open or finished events
- limit – to limit the recipient events which will be returned
The only required parameter is the tag, without which only the untagged events will be returned. If the status parameter isn’t specified, it’s default value is “open”, and if the limit isn’t specified, the output will be limited to the maximum of the latest 20 events of the specific recipient.
Then we can display the contents via the FOREACH loop:
Date: [% modify_date -%]
[% FOREACH EventItems -%]
Name: [% name -%]<br>
[% END -%]
[% END -%]
In this example we display the date of the latest event change, and then name of all items in the event.
Since events are tied to a specific recipient, the plug-in will always return only the data of the current recipient. Therefore, if you look at the preview in the template editing you won’t see any data, because the preview in the template editing doesn’t have a recipient. So the testing has to be done in the campaign preview where you can select a recipient which you know that has the data.
ATTENTION: Even if you don’t want to use any data from the event itself, just the data from the event items, you still have to use the event, otherwise you can’t access the item data. In that case, the code would look like this:
[% FOREACH EventItems -%]
Name: [% name -%]<br>
[% END -%]
[% END -%]
Recombee
As the name suggests, this plug-in is for getting recommendations from the Recombee service. Recommendations for individual recipients are returned in real time, both in campaign preview and sending. Recommendations are returned as an array with recommended products IDs, then you can get the products by the ID from the SQL data source, and insert them into the message. Alternatively, you can use the returnProperties parameter, which will return complete information about the product as they are stored in Recombee from your product feed, then insert those into the message.
It’s important to note that when using recommendations, there can occur a case when the recommendation system won’t return any data – either because it doesn’t know the recipient yet, or doesn’t have enough data about them. This also matters, because there can be a variable amount of recommendations – when you set the amount, you are setting the upper limit, not a fixed amount. Therefore it may happen that there won’t be enough data for some recipients, so they will see fewer products - this should be considered when designing the template.
Last but not least, you should also consider that using this filter affects the sending speed, because there has to be a data request to Recombee for each recipient. That means it’s best to use the recommendations in campaigns with small amounts of recipients and clear targeting, like for example an abandoned cart, or a campaign for a small segment. In campaigns for tens or hundreds of thousands recipients, we recommend to consider very carefully both the benefits and slow sending speed.
The plug-in is used like this:
database => 'name', # required
userId => <string>, # optional custom userId (eg. token) otherwise email is being used
count => <int>, # desired recommendation (defaults to 1)
scenario => recombee scenario, # see recombee UI for parameter descriptions
cascadeCreate => <boolean>,
returnProperties => <string list>,
filter => <string>,
booster => <string>,
logic => <string/object>,
minRelevance => <string>,
rotationRate => <decimal>,
rotationTime => <decimal>,
) -%]
[% FOREACH Recombee.data.recomms -%]
<div><a href="[% values.URL -%]">[% values.PRODUCT -%]</a></div>
[% END -%]
The only required parameter is database for the database name in Recombee. The rest is the same as in the Recommend Items to User function, as described in the Recombee documentation. Also the data structure returned by plug-in corresponds with the data structure from Recombee API.
Fetch
The option to insert the content which is current for a recipient in the very moment the campaign is sent, is a frequent request in campaigns. Most cases are discount codes, exchange rates, weather forecasts and so on.
This is where the Fetch plug-in comes in. It enables inserting data from a URL into the template. Plug-in automatically detects the content type, and if it’s a JSON (application/json) or an XML (application/xml), it will automatically decode the content into data structure, which can be accessed like structured data. In case the content isn’t either JSON or XML, it will be available as a string.
Fetch can be used under the following conditions:
- response URL can’t be longer than 4 kB
- automatic hard 1 second timeout
- URL has to be secured by https protocol and valid server certificate
- at most one URL redirect
These conditions are the result of data transfer security and performance requirements. Since Mailkit generates messages at an astounding speed, it’s necessary that the server which houses the data is able to respond to hundreds or thousands requests per second, because when the server doesn’t respond in time, the e-mail is sent without the data from the response.
The plug-in is used like this:
password=> 'password'); -%]
The only required parameter is URL, from which the data should be retrieved. In case the server requires name and password authentication, it’s possible to use parameters username and password. Plug-in returns content in the content structure, in this case it’s Fetch.content.
Depending on the data format, this may be textual content for responses that are not in JSON or XML format (or couldn’t be decoded), or content in the form of structured data extracted from JSON or XML formats.
Errors are stored in the error variable, in case of error responses from the server, code and message variables containing the status code of the response and its text are also available.
