Emarsys API Developer tooling

Written in the Postman format and tested with Bruno

This document describes the Emarsys Suite API v3, which uses OpenID Connect (OAuth 2.0 client credentials grant) authentication.

• Other API collections, including the Emarsys suite WSSE APIs: link
• Introduction to Emarsys API: link
• Creating your API credentials: link

For an open source alternative to Postman, this collection is also compatible with Bruno, as described here.

Creating your API user

1. Open your account, select Management by clicking the wrench icon from pop-out menu on the left of the page, then click "Security Settings"
2. Click the API icon from the menu on the left, then click "Create API Credentials" and select OpenID Connect as the authentication type to make credentials that will work with this collection
3. Your API user is now created! Be sure to copy your all of the credential details from the gray text boxes to a secure location immediately, as you won't be able to access them again
4. Still on the API credentials page, look through the Permissions table and toggle any API actions you need to the Enabled status. If your needs change in the future, you can return to this page and enable more endpoints

Using with Postman

Installing the collection in Postman

1. First, make sure you have Postman installed. These collections are meant to be used with the program Postman, which can be downloaded here: https://www.postman.com/downloads/
2. Download this repository by clicking on the Green "Code" button at the top of this page, then "Download Zip":
3. Extract the files from the .zip folder
4. With Postman installed and the collections downloaded, click on the import button in the top-left:
5. Select The upload files option:
6. Select the file "Emarsys Postman Collection" from the downloaded files
7. Finally, select the import button to confirm and the package will be fully installed!

Setting up your API user in Postman

1. In Postman, click on the folder for the Emarsys API collection, then select the Authorization tab
2. Scroll down to the "Configure New Token" section where you will see red text in the boxes for Client ID and Client Secret
3. Hover your mouse over the red text for {{OIDC_ClientID}} to see the options of where to store this variable. Click the Environment section to save the variable. If you see text that says "No environment selected", click "Create One" and give it a name like "Emarsys environment"
4. In the "Enter Value" checkbox, enter the value you saved from the Emarsys API user creation screen. Do this for Client ID and Client Secret. The text for each will turn from red to blue once it's configured correctly Note If you are using SAP Cloud Identities to manage your Emarsys API credentials, you will need to replace the Access Token URL as well
5. Scroll to the bottom of the window and click the Orange "Get New Access Token" button. Postman will take a moment to make sure your credentials work, then report it was successful. Click "Proceed" on this window, then click "Use Token"
6. Your credentials are now configured!

Using this collection with Bruno

Bruno is an open-source API tool that is very similar to Postman, but is fully free to use and is supported by the Open-Source community.

Installing the collection in Bruno

1. Make sure you have Bruno installed. You can download Bruno here: https://www.usebruno.com/downloads

2. Download this repository by clicking on the Green "Code" button at the top of this page, then "Download Zip":

   

3. Extract the files from the .zip folder

4. With Bruno downloaded and the collections downloaded, click on the Import Collection button:

   

5. Select "Postman Collection" for the collection type

6. Select the file "Emarsys_postman_collection.json" from the files you downloaded previously and press open:

   

7. Bruno will then ask you where you'd like to save the imported collection. Select any location on your computer you would like to store your work in Bruno

8. In Bruno, find the section on the left titled "Emarsys - Suite and Sales APIs - V3" and click on the three-dot menu, then click settings. This page is the Collection configuration page, where we will be updating the Script using the script tab. In that tab, paste the following into the "Pre Request" section:

const h=require('https');class OAuth{async sr(s,ci,cs){s=s?s:"https://auth.emarsys.net/oauth2/token"
    const date=new Date().getTime();let t=bru.getVar('OAUTH_TOKEN_'+ci);let te=bru.getVar('OAUTH_TOKEN_'+ci+'_EXPIRY');if(!t||te<date){const jwt=await this.gt(s,ci,cs);if(jwt.expires_in&&jwt.access_token){const ed=date+(jwt.expires_in-60)*1000;bru.setVar('OAUTH_TOKEN_'+ci,jwt.access_token);bru.setVar('OAUTH_TOKEN_'+ci+'_EXPIRY',ed);t=bru.getVar('OAUTH_TOKEN_'+ci);}}
    req.setHeader('Authorization','Bearer '+t)}
    async gt(s,ci,cs){return new Promise((resolve,reject)=>{const url=s;const options={method:'POST',headers:{'content-type':'application/x-www-form-urlencoded','Accept':'application/json','authorization':'Basic '+Buffer.from(ci+':'+cs).toString('base64'),},};const req=h.request(url,options,(res)=>{let data='';res.on('data',(chunk)=>{data+=chunk});res.on('end',()=>{try{resolve(JSON.parse(data))}catch(error){reject()}})});req.on('error',()=>{reject()});req.write('grant_type=client_credentials');req.end()})}}
    await new OAuth().sr(bru.getEnvVar('OIDC_SCI_HOST'),bru.getEnvVar('OIDC_CLIENT_ID'),bru.getEnvVar('OIDC_SECRET'))

Be sure to click Save

1. Bruno is now configured and ready for you to fill in your API credentials.Follow the steps for configuring your environments in the next section before sending your first request

Setting up your API user in Bruno

This collection uses Bruno Environment Variables to manage the credentials for the account(s) you work with. This guide goes over how to create those environments

The required variables are:

• OIDC_CLIENT_ID
• OIDC_SECRET

Note If you are using SAP Cloud Identities to manage your Emarsys API credentials, you will need to add your Access Token URL in the variable "OIDC_SCI_HOST"

Bruno-specific notes

1. Bruno doesn't support "path parameters" which are parts of the link before the question mark that can be changed to determine what data you retrieve. These parameters are marked with a colon and then the parameter name (such as ":languageId" in the Fields/List Available Fields API). To use these in Bruno, simply replace the colon and the name with the value you'd like to send in your API request