Mautic Plugin: External content¶

Warning

This plugin is deprecated and removed from the default Mautic setup. For an easier integration to include Drupal content in Mautic see Drupal content in Mautic which is now the default in our offering.

This Mautic plugin enables you to include content from external sources into e-mails send with Mautic. Via customizable tokens in e-mail templates, personalized, external content can be injected into the rendered html of an e-mail.

Warning

The external source is responsible for delivering the content in the correct format. It is highly likely that a developer is needed to make sure the correct format is served to Mautic.

The features of this plugin:

Admin form where you can configure API endpoint, authentication (none, basic auth or bearer token), method (GET or POST).
Configurable tokens that can be used in e-mail templates.
You can use multiple versions of the token in a single email.
Logic to convert a configurable token into actual data based on the preferences of a contact.
Logic to fetch that data from an external endpoint and embed it in the personalized email.
Caching of rendered html on Mautic’s side where possible.

Out of scope of this plugin:

Sync of the preferences of a contact from an external source to Mautic
Any filtering or processing of external data. This means that the external source is fully responsible for the processing of the incoming request from this plugin.

Difference between this plugin and Mautic's build in Dynamic Web Content (DWC):

Dynamic Web Content (DWC) enables you to embed personalised content into an external web page.
This plugin sends a personalised request to an external endpoint. The personalised response is then rendered in the e-mail that is sent to the contact.

Installation¶

Add this plugin to the /plugins folder in Mautic.
Go to the plugins overview in your Mautic environment.
Install the new module via the "Install/Upgrade Plugins" button.
Click on the "External Content" plugin and enable the plugin

Configuration¶

The configuration of this module happens in the Configuration menu in Mautic

Use the tab "External content - Token Replacement Settings"

Base URL:

The Base URL of your API endpoints. Without the trailing slash.

Default request method:

The default method that will be used for all your requests to the external API. This can be overwritten per token in the e-mail templates. Default: GET

Delimiter:

Choose a delimiter. When you use the delimiter in single value contact fields (textfields), the single value field will be handled by the plugin as a multi value field. Be aware of spaces, capitals and other characters, they will not be ignored.

Example: A contact textfield with value "dog,cat" will generate 2 filters: "dog" and "cat".

Default: ,

Authentication method:

Select the authentication method that is used for all requests to your API. The options are:

None (Default)
Basic Authentication (based on username and password)
Bearer token (a bearer token can be entered in the "Your bearer token"-field)
Advanced Authentication (the "Advanced Authorization Header"-field allows you to enter a custom Authorization header)

Advanced Authorization Header:

Only the actual Authorization header value is needed. The plugin will handle the header key.

Example: Apikey 1234567890abcdef will be converted by the plugin to Authorization: Apikey 1234567890abcdef

Usage¶

The plugin makes use of Mautic's build-in token (or variable) system. The base token is:

{external_content:[key=value]}

One or multiple variable options can be passed along in the token. Custom option values can be passed as both a string value or an array of values. Depending on how you would want them to be requested in your API. More information in the examples section.

Certain variable keys are reserved by the plugin:

method: The allowed values GET or POST define whether the request method will be a GET or POST request. If no method is entered, the default method that is defined in the configuration form will be used.
endpoint: This allows you to specify the endpoint that needs to be requested. With the forward slash.

Hardcoded options can be passed via the variable options like this:

key=value: the plugin will pass the parameter key=value as a string to the api.
key=[value]: the plugin will pass the parameter key[]=value as an array to the api.

Personalised contact info options can be passed via the variable options as well:

key=$field_name$: the plugin will pass the data of the contact field as a 1 dimensional array to the api. key[]=contact_value1&key[]=contact_value2
key=[$field_name$]: the plugin will pass the data of the contact field as a multidimensional array to the api. key[field_name][]=contact_value1&key[field_name][]=contact_value2

Examples¶

For the examples, we assume that Mautic's e-mail contact has the following custom fields with these values:

pets: dog, cat
fruit: apple, banana, orange

The External content plugin settings are the following:

Base URL: https://example.com/api
Default request method: GET
Authentication Method: None

Basic Token¶

Input

Token: {external_content:endpoint=/news}

Output request

Method: GET
Request URL & query string: https://example.com/api/news
Body: /

Overwrite the default method¶

Input

Token: {external_content:method=POST:endpoint=/news}

Output request

Method: POST
Request URL & query string: https://example.com/api/news
Body: []

Hardcoded filter¶

Input

Token: {external_content:endpoint=/news:filter=pets}

Output request

Method: GET
Request URL & query string: https://example.com/api/news?filter=pets
Body: /
Method: POST
Request URL & query string: https://example.com/api/news
Body: {"filter":"pets"}

Input

Token: {external_content:endpoint=/news:filter=[pets,fruit]}

Output request

Method: GET
Request URL & query string: https://example.com/api/news?filter[]=pets&filter[]=fruit
Body: /
Method: POST
Request URL & query string: https://example.com/api/news
Body: {"filter":["pets","animals"]}

Personalised filter¶

Input

Token: {external_content:endpoint=/news:filter=$pets$}

Output request

Method: GET
Request URL & query string: https://example.com/api/news?filter[]=cat&filter[]=dog
Body: /
Method: POST
Request URL & query string: https://example.com/api/news
Body: {"filter":["cat","dog"]}

Nested personalised filter¶

Input

Token: {external_content:endpoint=/news:filter=[$pets$]}

Output request

Method: GET
Request URL & query string: https://example.com/api/news?filter[pets][]=cat&filter[pets][]=dog
Body: /
Method: POST
Request URL & query string: https://example.com/api/news
Body: {"filter":{"pets":["cat","dog"]}}

Combination¶

Input

Token: {external_content:endpoint=/news:filter=[$pets$,$fruit$]:order=DESC}

Output request

Method: GET
Request URL & query string: https://example.com/api/news?filter[pets][]=cat&filter[pets][]=dog&filter[fruit][]=apple&filter[fruit][]=banana&filter[fruit][]=orange&order=DESC
Body: /

Input

Token: {external_content:method=POST:endpoint=/news:filter=[$pets$,$fruit$]:order=DESC}

Output request

Method: POST
Request URL & query string: https://example.com/api/news
Body: { "filter": [{ "pets": ["cat", "dog"], "fruit": ["apple", "banana", "orange"] }], "order": "DESC" }

Specific plugin opinions and requirements¶

The plugin has some specific settings and logic that cannot be altered. These should be taken into account when connecting it to an external API.

Successful responses are cached for 1h. Changes from the API will not be reflected directly in the emails.
The plugin expects the response to be an array of items in JSON format. Each item should contain the stand-alone html render (including the inline css) in the html key.
Other values may be passed along with each item, but this plugin will just ignore those values. Filtering, sorting, limiting of results should be handled by the API. This module will just render everything in the html key without any extra processing.
The allowed response of the api is application/json
When no valid response is received by the plugin, nothing will be rendered for that token.

Source: https://gitlab.internal.dropsolid.com/dropsolid-experience-cloud/marketing-automation/plugins/external-content

← Previous Mautic Plugin - whitelabel Next → Setting up resources for a webinar in Mautic