Skip to main content
All CollectionsIntegrationsEmail messaging providers
Integrate Salesforce Marketing Cloud with Fresh Relevance
Integrate Salesforce Marketing Cloud with Fresh Relevance

Learn to integrate Salesforce Marketing Cloud.

Updated over a week ago

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:

  1. A List or Data Extension in Salesforce Marketing Cloud to load the data (e.g. email address) onto

  2. An email in Salesforce Marketing Cloud to send to the recipient

  3. An Interaction in Salesforce Marketing Cloud to trigger the email send, and a Journey if you with to use Journey Builder

  4. A suitable user account in Salesforce Marketing Cloud with API access and permission to send

  5. An email sending channel in Fresh Relevance to provide configuration of what to trigger

  6. 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:

  1. Login to Salesforce Marketing Cloud and select Email under Email Studio.


    ​

  2. Hover over Subscribers in the top menu and then select Data Extensions

  3. Select Create and select Standard Data Extension in the popover that appears, then select OK
    ​

  4. 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:

  1. EmailAddress relates to subscribers on Email Address

  2. 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.

  1. To create an email, select Content in the top menu

  2. Select Create and select Email Message

  3. 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

  4. Give your email a name, for example, Cart Abandon Stage 1

  5. Select the location you wish to save your email, e.g. the folder you may have created earlier

  6. 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.
    ​

  7. Select Next and build the email. See the section below on including cart content to show carted/browsed/purchased products

  8. 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.
    ​

  9. 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:

  1. Open the Interactions page and find the new Interaction in the list (note that the Status column should say New)

  2. Select the checkbox to the left of the name

  3. Select Start/Restart in the menu bar

  4. 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:

  1. Open the Interactions page and find the affected Interaction in the list

  2. Seelct the checkbox to the left of the name

  3. Select Pause in the menu bar.
    You should then see a confirmation message and the value in the Status column will change to Paused

  4. Select the checkbox to the left of the name again

  5. 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:

  1. Hover over your username and select Setup.

  2. Select Users.

  3. Select Create in the menu above the list of users

  4. Enter the required fields (name, email address, username, external key).

  5. Select both the Enabled and API User checkboxes.

  6. 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:

  1. Hover over your username and select Setup.

  2. Select Account Settings under Company Settings, which is below the Settings heading on the left-hand menu

  3. 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.

Did this answer your question?