Emarsys

2.2

Emarsys is omnichannel Customer Engagement Platform.

Overview

Copy

Emarsys is the largest independent marketing platform company available. The software creates personalised, one-to-one interactions between marketers and customers across all channels — helping to build loyalty, enrich the customer journey, and increase revenue.

Authentication

Copy

When using the Emarsys connector, the first thing you will need to do is go to your Tray.io account page, and select the workflow you wish to work on. Once in the workflow dashboard itself, search and drag the Emarsys connector from the connectors panel (on the left hand side) onto your workflow.

With the new Emarsys connector step highlighted, in the properties panel on the right, click on 'New Authentication' which is located under the 'Settings' heading.

This will result in a Tray.io authentication pop-up window. The first page will ask you to name your authentication appropriately, and state which type of authentication you wish to make ('Personal' or 'Organisational').

As you can see, the next page asks you for your 'Emarsys Client ID', 'Secret' and 'Base URL'.

Make sure you are logged into your Emarsys account. You should be able to confirm your base URL at Emarsys Overview docs section.

Both the 'Client ID' and the 'Secret' can be got by going through Emarsys support and authentication section: Emarsys Overview - Authentication . Please contact their support team for more details.

Once you have clicked the 'Add authentication' button, go to back to your authentication field (within the workflow dashboard properties panel from earlier), and select the recently added authentication from the dropdown options now available.

Your connector authentication setup should now be complete.

Available Operations

Copy

The examples below show one or two of the available connector operations in use.

Please see the Full Operations Reference at the end of this page for details on all available operations for this connector.

Using the Raw HTTP Request ('Universal Operation')

Copy

As of version 1.0, it is now possible to effectively create your own operations.

This is a very powerful feature which you can put to use when there is an endpoint in Emarsys which is not used by any of our operations.

To use this you will first of all need to research the endpoint in the Emarsys API documentation v2.0 , to find the exact format that Emarsys will be expecting the endpoint to be passed in.

Note that you will only need to add the suffix to the endpoint, as the base URL will be automatically set (the base URL is picked up from the value you entered when you created your authentication).

The base URL for Emarsys is: https://{base_url}/api/v2

Please check that this is relevant by going to

For example, say that the 'List Segments' operation did not exist in our Emarsys connector, and you wanted to use this endpoint, you would use the Emarsys API v2.0 docs to find the 'List Segments' endpoint (which is named as list-filter in the docs). Note that it is a GET request and the optional/ required fields:

So if you know what your 'segmentId' and 'X-WSSE' headers are, you can get the 'list-filter' details with the following settings:

Method: GET

Endpoint: filter/

segmentId: Not necessary: Connector automatically list segments in accordance to the owner

X-WSSE: Not necessary: This is generated automatically with the call

Final outcome being: https://{base_url}/api/v2/filter

Example usage

Copy

In our example, we've decided to send email advertisements for a special pen to all designers listed in our contacts. We can only sell this pen to those living within the UK, so we are going to ensure that we only send these emails to designers within our 'All contacts in UK' segment.

The steps will be as follows:

1. Setup with a manual trigger and an Emarsys connector, to find the contacts within "all" contacts that are designers.

2. Loop through said results one by one.

3. Check and compare each contact within said lists job position.

4. Gather the contacts within the allocated segment (in this case, UK based) from the original contacts list.

5. Setup a condition should the contact be UK based.

6. Email advertisement is sent out if this proves true.

1 - Setup trigger & Get relevant Contacts

Copy

Once you have clicked 'Create new workflow' on your main Tray.io dashboard (and named said new workflow), select the Manual trigger from the trigger options available:

Once you have been redirected to the Tray.io workflow dashboard, from the connectors panel on the left, add a Emarsys connector to your second step. Set the operation to 'Search Contact Data'.

The 'To return' field value can be a UID, a ID of contact, or a field ID.

To refresh yourself of which field to use, use and run the 'List fields' operation. We have found out that the field ID of Job position is an integer, aka: 17. Therefor 17 is placed within the 'To return' field in order to run the operation.

You should notice that the 'Limit' and 'Offset' though required are pre-filled for you.

At this point when we click into the debug tab at the top of this workflow and click into the latest run workflow, we should see in the results pane a list of contacts have been returned.

Feel free to re-name your steps as you go along to make things clearer for yourself and other users.

2 - Loop through List Results

Copy

Now that the list has been gathered each contact needs to be individually checked one after the other.

With this in mind, go back to your connector panel and select the 'Loop collection' connector and place it as the next step in the workflow. Set the operation to 'Loop List'.

In order to get the correct jsonpath, it is best to use the connector-snake, and have it start from the 'List' field in the loop step, and end on the first Emarsys step. Your result should end up being similar to: $.steps.emarsys-1.data.result.

This connector enables us to look through each contact in the list on an individual basis.

3 - Check for Designers within Contacts List

Copy

Now that the contact list has been called and "created", and a loop is being used to circulate through the contacts within said list, the next step is to filter out the Designers from said list.

.

Through the above link, it is made clear that "Job Position" can have a number of options, each with their own unique identifier. By using said link, is it clear that the ID for Designers is 11.

Add a 'Boolean Condition' Helper connector to your workflow's next step, taking care to place it WITHIN the loop step itself. Set the operation to 'Boolean condition' as well.

If a condition is met and the result is TRUE, the workflow will pass on to the next step. If the condition is not met, aka FALSE, the workflow will do nothing. You can add a conditional step within the false branch at a later stage should you wish to expand the workflow later on.

To set up the boolean condition correctly, use the connector-snake once more to jsonpath the value needed. This time starting from 'Conditions' -> 'Condition' -> '1st Value', and ending on the value option from the loop connector dropdown list presented.

The result should be similar to: $.steps.loop-1.value. As the it is the job position that is being checked, which itself has a value of 17, make sure to add .17 to the end of the jsonpath itself.

Set the next field, 'Comparision type' to Equal to.

The last field ('Conditions' -> 'Condition' -> '2nd Value') should be set to 11. This means your boolean condition will check if the job position (aka, field 17), for a specific job role (Designers = 11).

Due the the numeric fields, make sure you set your datatype correctly in all three inputs else the workflow will fail. '1st value' should be set to jsonpath and the 'Comparision type' and '2nd value' need to be set to STRING. While this may seem confusing for the last field, this is how the API accepts the value input regardless.

Your workflow is now able to gather your list of contacts, and check each one within said list to see if their job role is set to designer.

4 - Gather Contact Location

Copy

Add another Emarsys connector to the workflow, and once more make sure the connector is placed WITHIN the loop of the previous step (i.e. the boolean circle). Set the operation to 'Check for user in segment'.

Select an option from the dropdown list for the 'Segment ID'. In this use case, 'All contacts in the UK' is chosen.

Using the connector-snake once more, drag it from the next field 'Contact ID' all the way back to the loop step, and select value from the options. Your results should be similar to: $.steps.loop-1.value. As the ID is needed in this case, append .id to the end of the jsonpath: $.steps.loop-1.value.id.

This connector gathers checks if the contacts currently available are from the UK, via their ID field gathered at the loop step.

Your workflow now gathers your list of contacts, and checks each contact within said list to see if their job role is set to designer. There is now a another information gathering step, that checks if said designer contacts are from the UK.

5 - Check if Contact is within UK

Copy

The next stage is to confirm an action based on whether the contact found is indeed found in the UK. Therefore another 'Boolean Condition' Helper connector is needed.

Add this to the workflow as the next step, after the second Emarsys connector. Set the operation to 'Boolean condition'.

If a condition is met and the result is TRUE, the workflow will pass on to the next step. If the condition is not met, aka FALSE, the workflow will do nothing. You can add a conditional step within the false branch at a later stage should you wish to expand the workflow later on.

To set up the boolean condition correctly, use the connector-snake once more to jsonpath the value needed. This time starting from 'Conditions' -> 'Condition' -> '1st Value', and ending on the data option from the SECOND Emarsys step, connector dropdown list presented.

The result should be similar to: $.steps.emarsys-2.data. Set the next field, 'Comparision type' to Equal to.

The last field ('Conditions' -> 'Condition' -> '2nd Value') should have its data type set to BOOLEAN and therefore will automatically be set to The 2nd of 2 values to compare with the check box ticked to confirm this.

6 - Email advertisement to Contact if True

Copy

Add a final Emarsys step WITHIN the last boolean conditional step, on the TRUE branch. Set the operation to 'Get Contact Data'.

Set the 'Key ID' to: id and the 'Key values' -> 'Item' to $.steps.loop-1.value.id like in the step three instructions from earlier. The 'Language ID' is set to 'English' and the 'Fields' -> 'field' is set to 3.

This connector step gathers the contact information we will need in order to email the individual, at the next stage.

Add a final 'Send Email' connector to your workflow, underneath the last Emarsys step. Set the operation to 'Send email'.

The 'To recipients' field will need another connector-snake jasnpath, starting here and gathering its information from the Emarsys step above. Select result from within the data options presented.

As the only result field required is email address, make sure to append your jsonpath with .3. The end result should be similar to: $.steps.emarsys-3.data.result.3.

Set your 'Subject', 'Content' and 'From Email' fields as appropriate.

You may want to try using interpolation at this stage, in order to auto-generate your Designers names at the beginning of each email.

And there you have it! Once you run your workflow, you will be emailing all the Designers that are based in the UK with your incredible Pen based ad campaign!