SAP Emarsys API example: Using Static Placeholders

WillYoung · ‎05-18-2021

This is the first in a series of blogs looking at different scenarios for using placeholders with the SAP Emarsys API.

Disclaimer: As well as providing some real code examples, we thought we'd have a go at demystifying some of the elements here with [simple explanations] for people (like me) who work in marketing or content and who use this kind of thing without really knowing how it works. We'd be happy for your feedback on whether this approach is useful, or if it falls between the two stools.

In the first 4 blogs we will cover:

Simple Static Placeholders

The For Each Loop and Arrays

Using API Placeholders with a Relational Database

Passing raw HTML through the API

If you'd like to know when the next ones come out, just follow the tag SAP Emarsys API. You can also use this tag to ask us a question.

Using Static Placeholders

In this example I will demonstrate how to send an email using the Emarsys API to trigger an external event, and populating some simple external data into the email.

Use case

Our use case for marketers is sending an automatic welcome email that uses static placeholders, for example to include a voucher code that comes from an external source, rather than an Emarsys voucher pool.

The code

First let’s take a peek at how the HTML of the email will look:

<!DOCTYPE html> 

<html lang="en"> 

<head> 

    <meta charset="UTF-8"> 

    <meta http-equiv="X-UA-Compatible" content="IE=edge"> 

    <meta name="viewport" content="width=device-width, initial-scale=1.0"> 

    <title>Exercise 1 - Static Placeholders</title> 

</head> 

<body> 

    <h2> 

 Exercise 1 - Static Placeholders 

 </h2> 

 <p> 

 Welcome to the club, {{event.firstName}}!<br> 

 As a welcome gift, please enjoy this voucher which gives you 15% off from your first order. 

 </p> 

 <p> 

     {{event.voucherCode}} 

 </p> 

</body> 

</html>

In this example, we have two different placeholders:

firstName

voucherCode

These both sit in their own HTML paragraph tag.

Note: API placeholders always have the following syntax: {{event.placeholdername}}
They must contain the event. prefix - using the name alone will not work!

The name of the placeholder (e.g. firstName) is what we will be using in our JSON Payload.

Let's see what the JSON of this campaign would look like:

{  

"key_id": "3",  

"external_id": "elston.gunn@example.com"

",  

"data":   

{  

"firstName": "Elston",  

"voucherCode": "ABC123456789" 

} 

}

The JSON opens using a { curly bracket, and then defines where the campaign should go to. We use the key_id as 3 (which is email), and the external_id contains the email address of the recipient.

key_id refers to the field ID of the field that you wish to use.
[This is like asking the database 'Do you have a field with the ID '3'? If so, then look in that field for the following value.']

external_id, which refers to the value that populates the field which is chosen for the key_id.
[If the database does find the field with ID '3', this now gives it the value to look for, and if found, to trigger the following data to that value (the email address.]

Next, inside this, we declare a new object called data. We then open this object, using a new curly bracket, and here is where we define the data for the placeholders we have in our email.

We must reference the placeholders used in our email with the exact spelling. If the word is made up out of several parts, e.g. First(1) Name(2), we recommend using the camelCase convention, e.g.: firstName.

We then close the data object using a } curly bracket, and finally we close the entire JSON object using another curly bracket. The payload is now finished. When we test the API call using the Emarsys Developer Hub (https://dev.emarsys.com/v2/events/trigger-external-events):

it will send the following email content (all wrapped up in your lovely email template, of course):

And that's it - I hope you found it useful!