Trigger an Emarsys Email Campaign via API using Postman/Bruno and WSSE Authentication

[Arne_Manthey]

Introduction

In SAP Emarsys Customer Engagement you can send emails or trigger automation programs using an external event. That external event needs to be created via API since there is no standard functionality for an end user to trigger such an event.

Preconditions

Please make sure that the following steps have been done:

Triggered Email Campaign

• Have a sender mailbox for triggered emails set up by the Emarsys support
• Create an external event via menu Management → External Event
  (see Triggered email end-user guide: Preparing the external events)
•  Create a triggered email campaign via menu Channels → Triggered Email
  (see Triggered email end-user guide: Creating Mail Streams)
• Use the previously created external event as trigger source 
• Activate the triggered email campaign

API Credentials

Create or re-use API credentials with an active permission for 'externalevent.trigger' via menu Management → Security Setting → API Credentials (see help page API Credentials)

API Endpoint to Trigger an External Event

The API endpoint as described in the developer portal is: 

https://api.emarsys.net/api/v2/event/{eventId}/trigger 

Where {eventId} is the id of the event you created before. The body payload you need for this use case would look like this:

{
  "key_id": "3",
  "external_id": "",
  "data": null,
  "contacts": [
    {"external_id": "contact1@email.com"},
    {"external_id": "contact2@email.com"}
  ]
}

The field key_id '3' specifies that you will give email addresses in the 'contacts' section where you need to specify all the email addresses of the contacts you want to send the email to.

Example with Postman

Postman is a tool to set up and run API calls (Download). It has a free option but requires you to create an account. If you look for an entire local setup please read further down on Bruno. At the end of this article you find a JSON code which you can import into Postman as a new collection. After doing so you will need to expand the collection and open the single item 'Trigger External Event'.

First you need to adjust the script in tab 'Pre-Request Script' and exchange the string '<API User>' with your API user and the string '<Secret>' with your API secret (Keep the double quotes around!):

Furthermore you need to exchange the string '<EventID>' with the ID of the external event you created before. Then you need to adjust the email addresses in the tab 'Body' with your own data:

 Finally you just need to press on 'Send' and the external event should be triggered for all the contacts you provided.

Postman JSON Collection for Import

In the box below you find a Postman collection which you can copy and store as a JSON file (file extension .json). Please note that this is just an example code and comes with no warranty and no support!

{
	"info": {
		"name": "Trigger_Event",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "Trigger External Event",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"exec": [
							"const crypto_js = require('crypto-js');",
							"var ts = (new Date()).toISOString();",
							"var nonce = crypto_js.lib.WordArray.random(16).toString(crypto_js.enc.Hex);",
							"var digest = crypto_js.enc.Base64.stringify(crypto_js.enc.Utf8.parse(crypto_js.SHA1(nonce + ts + \"<Secret>\").toString(crypto_js.enc.Hex)));",
							"pm.environment.set(\"wsse-header\",'UsernameToken Username=\"' + \"<API User>\" + '\", PasswordDigest=\"' + digest + '\", Created=\"' + ts + '\", nonce=\"' + nonce + '\"');"
						],
						"type": "text/javascript",
						"packages": {}
					}
				}
			],
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "X-WSSE",
						"value": "{{wsse-header}}",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n  \"key_id\": \"3\",\n  \"external_id\": \"\",\n  \"data\": null,\n  \"contacts\": [\n    {\"external_id\": \"contact1@email.com\"},\n    {\"external_id\": \"contact2@email.com\"},\n    {\"external_id\": \"contact3@email.com\"}\n  ]\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://api.emarsys.net/api/v2/event/<EventID>/trigger",
					"protocol": "https",
					"host": [
						"api",
						"emarsys",
						"net"
					],
					"path": [
						"api",
						"v2",
						"event",
						"<EventID>",
						"trigger"
					]
				}
			},
			"response": []
		}
	]
}

Example with Bruno

Bruno is another API client which is free and runs completely locally (Download). You can use the code at the end of this chapter as a JSON file to import into Bruno:

After importing the collection you need to provide the authentication credentials. Since version 1.31.0 Bruno offers native WSSE authentication support:

Expand the collection and select the item 'Trigger External Event'. Then you have to provide your API credentials in tab 'Auth' and exchange the string '<Your WSSE User>' with your API user and the string '<Your WSSE Secret>' with your API secret. Furthermore you need to exchange the string '<EventID>' with the ID of the external event you created before. Then you need to adjust the email addresses in the tab 'Body' with your own data:

Finally you need to save and run and the external event should be triggered for all the contacts you provided.:

Bruno JSON Collection for Import

In the box below you find a Bruno collection which you can copy and store as a JSON file (file extension .json). Please note that this is just an example code and comes with no warranty and no support!

{
  "name": "Trigger Email Campaign",
  "version": "1",
  "items": [
    {
      "type": "http",
      "name": "Trigger Email Campaign",
      "seq": 2,
      "request": {
        "url": "https://api.emarsys.net/api/v2/event/<EventID>/trigger",
        "method": "POST",
        "headers": [],
        "params": [],
        "body": {
          "mode": "json",
          "json": "{\n  \"key_id\": \"3\",\n  \"external_id\": \"\",\n  \"data\": null,\n  \"contacts\": [\n    {\"external_id\": \"contact1@email.com\"},\n    {\"external_id\": \"contact2@email.com\"},\n    {\"external_id\": \"contact3@email.com\"}\n  ]\n}",
          "formUrlEncoded": [],
          "multipartForm": []
        },
        "script": {},
        "vars": {},
        "assertions": [],
        "tests": "",
        "auth": {
          "mode": "wsse",
          "wsse": {
            "username": "<Your WSSE User>",
            "password": "<Your WSSE Secret>"
          }
        }
      }
    }
  ],
  "environments": [],
  "brunoConfig": {
    "version": "1",
    "name": "Trigger Email Campaign",
    "type": "collection"
  }
}

Further Information

There is also a Github page 'Emarsys Postman Collection' which contains a complete collection of most of the Emarsys APIs to import into Postman or Bruno. It also comes with a nice documentation and works with environment setups for better security regarding the credential handling.