Before you start
Things you need to know:
You must have:
Login details to Fresh Relevance.
Login details to a Salesforce Marketing Cloud account, with permission to create Data Extensions, Lists, Emails, Data Fields, Users and Interactions.
Decide where you want Fresh Relevance data loaded (see the relevant section below). Note that you will require a List regardless of which option you choose, but this can be an existing one.
Our integration requires several components be set to allow data to be uploaded and emails to be triggered:
A List or Data Extension in Salesforce Marketing Cloud to load the data (e.g. email address) onto
An email in Salesforce Marketing Cloud to send to the recipient
An Interaction in Salesforce Marketing Cloud to trigger the email send, and a Journey if you with to use Journey Builder
A suitable user account in Salesforce Marketing Cloud with API access and permission to send
An email sending channel in Fresh Relevance to provide configuration of what to trigger
A trigger in Fresh Relevance to determine what and when to send
Check the email address field name
Be aware of the email address field name in the Data Extensions/Lists you plan to use (or create) in Salesforce Marketing Cloud, for example "email" or "email address", because you must use the exact same name whenever these instructions refer to the email address field.
Upload data to Salesforce Marketing Cloud
The data from Fresh Relevance can be loaded into different locations within Salesforce Marketing Cloud.
a List, or
a Data Extension
The most commonly used option is a Data Extension.
Load Data to a Data Extension
To load data into a Data Extension:
Login to Salesforce Marketing Cloud and select Email under Email Studio.
Hover over Subscribers in the top menu and then select Data Extensions
Select Create and select Standard Data Extension in the popover that appears, then select OK
Select Create, set the Creation Method to Create from Template, choose TriggeredSendDataExtension and select OK.
5. Give the Data Extension a name (something obvious is recommended), an external key (without spaces ideally) and select Next.
6. You can leave the Data Retention Policy turned off or enable and change the settings to whatever you require.
7. On the Fields tab, you should already see the following two fields (this may vary based on your account's setup):
Field Name | Type | Size | Notes |
SubscriberKey | Text | 254 | (Should already be present) |
EmailAddress | EmailAddress | 254 | (Should already be present) |
Additional fields can be added if you wish to upload other data, and these then need to be added to the Field Mapping within Fresh Relevance.
To do this, in Fresh Relevance, expand the User menu, then go to Settings > Triggers and Messaging integrations > Messaging Provider(s). Then select field mappings next to the relevant channel.
For example, you may wish to load the recipient's first name:
8. Look at the 'Send Relationship' setting. Then within the dropdown options, select either:
EmailAddress relates to subscribers on Email Address
EmailAddress relates to subscribers on Subscriber Key (if your Salesforce Marketing Cloud account is setup with a primary key other than email address)
The first option is generally the most common scenario.
The send relationship setting will be dependent on your Salesforce Marketing Cloud account setup as well as the Fresh Relevance data you wish to use to identify a recipient when sending. Contact support should you need any assitstance or have a query about this.
9. Finally, select Create.
Loading Data to a List
1. Login to Salesforce Marketing Cloud
2. Hover over Subscribers in the top menu and select Lists
3. Optionally, add a folder under My Lists in the tree on the left to keep the lists you create organized.
You can do this by right-clicking on an existing folder and selecting New Folder. Type in a name and select Enter to save it.
Create List Folder
4. Select Create, and complete the Name and External Key fields, then select a folder to save the list inside if required:
5. Select Save to finish
Create an email to send
The main email body will typically sit within Salesforce Marketing Cloud, allowing you to build it as you would any other email campaign and to use existing templates. The cart content can then be pulled into this email to display the personalized content for the recipient.
You may wish to create a new folder to store your email(s) in, to do this, right-click on the Content Builder folder, or any sub-folder, and select Create Folder.
To create an email, select Content in the top menu
Select Create and select Email Message
Expand the Create Email drop-down menu, then select the appropriate option for how you wish to create the email, i.e. from a template, using HTML, etc
Give your email a name, for example, Cart Abandon Stage 1
Select the location you wish to save your email, e.g. the folder you may have created earlier
Optional: add URL parameter values to one of the Parameter fields if these are required (and the fields are exposed, only Salesforce Marketing Cloud can enable these). See the Campaign-based ID instructions for more details.
Select Next and build the email. See the section below on including cart content to show carted/browsed/purchased products
Once complete, select Next and perform a test send.
At this stage you may see an error. One reason for this may depend on the list/Data Extension you select and the name of the email field entered in your AMPScript to merge in the cart contents. Check the two values match exactly. In the example below, the field is called EmailAddress in the AMPScript, but it should be Email Address.
Select Save and Exit. Once you are happy, the email renders as intended.
Including the Cart Layout in your Cart/Browse Abandonment messages
The approach for this depends on your messaging provider.
To merge the carted/browsed/purchased items you can use AMPScript (Dotdigital's own scripting language). Copy the following and paste into the HTML of your email template in Dotdigital at the point where you want the cart to be shown.
When the abandoned cart email is sent, Dotdigital fetches the cart contents from Fresh Relevance and merges them into the email.
Example cart merge AMPScript
%%[Set @url = Concat('https://c8.dycdn.net/[your Website ID here]/content/email/?k=ocemgn4&f=cart_html&e=',URLEncode([email],1,1))]%%
%%=HTTPGet(@url)=%%
Be aware of the email field name
Make sure the final "email" matches your email address field name.
For example, if your email address field name is "email address", use the following:
Example AMPScript with alternative field name
%%[Set @url = Concat('https://c8.dycdn.net/[your Website ID here]/content/email/?k=ocemgn4&f=cart_html&e=',URLEncode([email address],1,1))]%%
%%=HTTPGet(@url)=%%
Note that when you are testing your email template in Dotdigital, the personalized content will only display if you use the "send preview" function or send the campaign to your test list.
Create an Interaction
An Interaction is the most common way to trigger an email send, but it's also possible to load data to a list/Data Extension and then use the Salesforce Marketing Cloud Journey Builder to pick up newly added records and trigger emails to them. This will not be real-time, instead running on a batched basis at the interval you set. To use the Journey Builder method, you still need to create an Interaction, but leave it paused rather than activate it.
To create an Interaction:
1. Hover over the Interactions entry in the top menu, and select Triggered Emails
2. Select Create and enter the relevant details. These typically consist of:
Field | Value |
Name | Pick a name for the Interaction, e.g. Cart Abandon Stage 1 |
External Key | Set the external key of the Interaction, e.g. CartAbandon1 |
Send Classification | Leave as Default Transactional unless you have a reason to change |
Content | Navigate to and select the email you want to send (i.e. the one you created earlier) |
List | Select the list you wish to use (an existing one or the one you created earlier) |
Data Extension | Select the data extension you wish to use (i.e. the one(s) you created earlier) |
3. Once done, select Save at the top
Activating an Interaction
Once you have saved an Interaction you need to activate it to allow sends to be dispatched.
If you do not activate the Interaction, it will look like the email has sent from the Fresh Relevance side, but the email will never be delivered.
To activate an Interaction:
Open the Interactions page and find the new Interaction in the list (note that the Status column should say New)
Select the checkbox to the left of the name
Select Start/Restart in the menu bar
You should see a confirmation that the Interaction has started (and the Status column will change to Running)
Reactivating an Interaction
If you make changes to an email, these will not be picked up by the Interaction until it has been restarted. To do that:
Open the Interactions page and find the affected Interaction in the list
Seelct the checkbox to the left of the name
Select Pause in the menu bar.
You should then see a confirmation message and the value in the Status column will change to PausedSelect the checkbox to the left of the name again
Select Start/Restart in the menu bar.
You should see a confirmation that the Interaction has restarted (and the Status will change again)
Errors when creating an Interaction
When you save the Interaction, it validates the Data Extension and the email and can throw an obscure message if it finds a problem.
The usual cause of this issue is that the email contains fields that are not present in the Data Extension, so check the email and update it or the Data Extension as appropriate.
For example, a common scenario is the email address field has been referred to in an incorrect way -- unlike other ESPs, Salesforce Marketing Cloud does not use a consistent name so the field can be email, email address or EmailAddress (and potentially others). Check the value in the Data Extension and confirm the email using the same value.
Create a sending user account
In order for Fresh Relevance to trigger emails it needs a user account with the correct privileges.
To configure these:
Hover over your username and select Setup.
Select Users.
Select Create in the menu above the list of users
Enter the required fields (name, email address, username, external key).
Select both the Enabled and API User checkboxes.
Select the Grant the user access to the web services option.
Find your API endpoint URL
Each Salesforce Marketing Cloud account uses a unique API endpoint (what our code calls to load and send). To get this value for your account you need to:
Hover over your username and select Setup.
Select Account Settings under Company Settings, which is below the Settings heading on the left-hand menu
Copy the SOAP Service Endpoint URL. This should end in asmx.
Update the ESP Settings in Fresh Relevance
The final step is to enter the details of the elements you have created into the ESP Settings page.
Initial Settings
Enter the following required information on the initial settings page:
Field Name | Description |
Username | Enter the username of the new user you created earlier |
Password | Enter the password of the new user you created earlier |
API Endpoint | Enter the SOAP Service Enpoint value you copied in the preview step |
Once done, select Next to move to the next screen.
Additional settings
These settings largely relate to the other elements you set up in the previous steps.
Field Name | Required? | Description |
Business Unit | Optional | The Business Unit to use within your account. This must be an integer (whole number). |
Optional List used for Triggers Programs | Optional | The List to load data to in your account |
Optional Data Extension used for Cart Abandons | Optional | The Data Extension to load data to in your account |
Triggered send External Key for Cart Abandonment | Recommended | The Interaction to use as the default if none set on the trigger |
List ID to use to check Send Permission on your ESP | Optional | The List to check against before allowing a send and to only send if the address is on that list |
Data Extension to use to check Send Permission on your ESP | Optional | The Data Extension to check against before allowing a send and to only send if the address is on that list |
Use EID Instead of Email Address | Required | Defaults to false. Whether to use an external ID in place of email address as the unique ID |
New Contact Permission Behavior | Required | Defaults to Add the contact with a status of "subscribed". This dictates how addresses that are not on the List/Data Extension are handled |
Contact Exists Permission Behavior | Required | Defaults to Change status of the contact to "subscribed"... This dictates how addressed that already exist on the List/Data Extension are handled |
That's it
All of the steps have now been completed, and you should have a working integration. Head to the Triggers page to configure a trigger and perform a test send.
If you experience any issues during any of the steps, or in sending a test email, please contact our support team.