How to Use the v1/event API Resource

The v1/event resource can be used to transfer to the email any custom data:

  • Login/password change or reset;
  • Order;
  • Abandoned browse and cart;
  • Unfinished registration;
  • Customer activity on the website or in app.

The resource generates an event that further triggers a workflow to send a message, create or update a contact.

For Abandoned Browses and Carts

Request sample:

{
  "eventTypeKey": "abandoned_cart",
  "keyValue": "site@en.net",
  "params": [
{
   "name": "email",
   "value": "site@en.net"
},
{
   "name": "items",
   "value": "{\"array\":[{\"name\":\"Hair styler\",\"price\":\"341\",\"url\":\"https://www.cultbeauty.co.uk/olaplex-no-4-bond-maintenance-shampoo.html\",\"imageurl\":\"https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg\",\"brand\":\"Le Petit Olivier\",\"tags_weight\":\"200\",\"tags_oldprice\":\"467\"},{\"name\":\"Magnolia Nobile\",\"price\":\"2341\",\"url\":\"https://www.cultbeauty.co.uk/olaplex-no-4-bond-maintenance-shampoo.html\",\"imageurl\":\"https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg\",\"brand\":\"Acqua Di Parma\",\"tags_weight\":\"100\",\"tags_oldprice\":\"4467\"}]}"

}
  ]
}

After the request is sent, the system generates an event in your account. You can see it in Automation > Event types.

Generated event

To view the event body, go to Automation > Event history and click the necessary event.

Event body

It should contain the following variables:

  • eventTypeKey is a variable whose value will be the name of the transferred event;
  • keyValue is the event key;
  • params are event parameters that can be used in a workflow. Their number is unlimited.

An array is a required format for the event {"name," "value": "site@en.net."}

This means that the data contains a variable email with the value of site@en.net. It should be specified in the workflow > block Email > Contact’s email for the email to be sent to site@en.net.

Workflow with the contact's email

Note that values of the field items must be serialized for the correct transfer; otherwise, JSON will be invalid. A deserialized array looks as follows:

{

"array": [{

"name": "Hair styler",

"price": "341",

"url": "https://www.cultbeauty.co.uk/olaplex-no-4-bond-maintenance-shampoo.html",

"imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",

"brand": "Le Petit Olivier",

"tags_weight": "200",

"tags_oldprice": "467"

}, {

"name": "Magnolia Nobile",

"price": "2341",

"url": "https://www.cultbeauty.co.uk/olaplex-no-4-bond-maintenance-shampoo.html",

"imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",

"brand": "Acqua Di Parma",

"tags_weight": "100",

"tags_oldprice": "4467"

}]

}

The array contains two items (two products here) with a set of variables: name, price, url, imageurl, brand, tags_weight, tags_oldprice. The number of arrays is unlimited. The names of variables are arbitrary.

To deserialize the array data, in the block Email > JSON, specify the name of the field items:

Where to select JSON

You insert the data from the request into the message using Velocity.

To refer to the data, use the following loop:

$!item.get('name')

$!item.get('price')

$!item.get('url')

$!item.get('imageurl')

$!item.get('brand')

$!item.get('tags_weight')

$!item.get('tags_oldprice')

You can refer to the array elements straight with the index (order starts at 0). This method can cause errors in content substitution if an array element is absent.

First array:

$!data.get('array').get(0).get('name')
$!data.get('array').get(0).get('price')
$!data.get('array').get(0).get('url')
$!data.get('array').get(0).get('imageurl')
$!data.get('array').get(0).get('brand')
$!data.get('array').get(0).get(''tags_weight')
$!data.get('array').get(0).get('tags_oldprice')

Second array:

$!data.get('array').get(1).get('name')
$!data.get('array').get(1).get('price')
$!data.get('array').get(1).get('url')
$!data.get('array').get(1).get('imageurl')
$!data.get('array').get(1).get('brand')
$!data.get('array').get(1).get(''tags_weight')
$!data.get('array').get(1).get('tags_oldprice')

The number of arrays is unlimited.

Important!

Use variables including the register as they are register-dependent. If an email contains $!item.get ('ImageUrl') and the request transfers imageurl, the variable won’t be inserted.

To view and check dynamic data in the email, click Additional settings > Configuring dynamic content.

Dynamic data in the email

Insert the deserialized array with dynamic data and click View message.

Parameters

  • In case of an error in the dynamic content substitution, check Velocity syntax in the message.
  • If you see the Wrong Format error, check the JSON request body.
  • If there are no errors but the data isn’t inserted in preview, check whether the variables in the request and variables in the email correspond and whether variables are referred to correctly.
  • If there are no errors and the data is substituted correctly, run a test by sending an API request to the account.

To Create or Update a Contact

Request sample:

{
  "eventTypeKey" : "create_contact",
  "keyValue" : "site@com.net",
  "params": [
{
   "name": "email",
   "value": "site@en.net"
},
{
   "name": "json",
   "value": "{\"profileInputs\": [{\"profileInputId\":10001,\"value\":\"2020-11-23\"}]}"
}
  ]
}

where

  • 10001 – id of the additional field.
  • 2020-11-23 – value of the additional field.

The body of the nested JSON array or object should also be serialized.

Ensure the correctness of the transferred data:

  • name and surname size (up to 60 characters);
  • phone number in the international format (+1-541-754-3010);
  • value of an additional contact field in the corresponding format.

In case of incorrect data transfer, the system will ignore the entire array and won’t add or update data in the contact card.

For correct workflow work, in the block Task (Create contact/Update contact), specify a variable ${email} in the field Contact’s email and a variable ${json} in the field JSON.

Contact's email and JSON

Learn more on the Task block

In addition to that the v1/event resource can be used to create or update a contact and to launch a workflow that will send messages with dynamic content, it can also be used to send orders to the system.

Any Questions?
We’re always happy to help!
Request a Callback
Fill in the form, and our specialists will call you back as soon as possible.
Request a Callback
Chat Support
We’re waiting for your questions!
Send a Chat Message
Email
Contact the eSputnik support team
Send an Email