API Integration - FAQ

1. General Documentation.
2. How to Check API for Correct Performance and Valid Access Options.
3. How to Unsubscribe a Contact Who Has Unsubscribed in the Personal Account on the Site.
4. How to Use Dynamic Content in Emails.
5. How to Use Events to Create Triggers.
6. How to Pass Orders via API.
7. How to Get a Sent Status for a Message via API.
8. How to Integrate a Subscription Form via API.
9. How to Pass Additional Field Values via API.

1. General Documentation.

All technical documentation on the data format, standards and error codes is provided in Introduction to eSputnik public API. Updates on API resources and request code samples are provided in Public API resources available in the eSputnik system.

Below, there are provided answers to the most frequently asked questions on how to use API or solve a specific problem, with detailed descriptions and examples.

2. How to Check API for Correct Performance and Valid Access Options.

To check the API resources for the correct performance, first of all, try to get the current account info: api/v1/account/info.

To test API, install Postman. You may register to be able to save the request history, or you do a standard test without registration.

  1. To start a test, go to Authorization > Type and select Basic Auth.

Go to Authorization and select Basic Auth

  1. In Username and Password, enter the username and password you use to log into the eSputnik system.

Enter the username and password

  1. Select a method (GET in the example) and enter a resource (/api/v1/account/info in the example).

Select a method and enter a resource

  1. Click Send to call a request.

Click Send to call a request

The corresponding request body looks as follows:

Request body for the info resource

3. How to Unsubscribe a Contact Who Has Unsubscribed in the Personal Account on the Site.

To manage unsubscribes, there are two API resources - /v1/emails/unsubscribed/add and delete. Important! You unsubscribe not a contact, but their email address (other channels - SMS, Viber, Web Push - remain active). All contacts within the organization who may use this email address would stop receiving bulk emails from you.

1. Use /api/v1/emails/unsubscribed/add to add the email address to the unsubscribed list.

The request body would look as follows:

{

"emails" : [ "test1@mail.com", "test2@mail.com" ]

}

emails - the email addresses that will be marked as unsubscribed.

2. Use /api/v1/emails/unsubscribed/delete to remove the email address from the unsubscribed list.

The request body is similar to the previous resource: you enter the email addresses that will be deleted from the unsubscribed.

Let’s see how to use theses resources (/api/v1/emails/unsubscribed/add in the example) in Postman:

  1. Set configurations:

Select the method and enter the resource

  1. In Body, enable raw and select JSON (application/json):

Enable Raw and select JSON

  1. Enter the request body:

{

"emails" : [ "...", ... ]

}

and list of the email address to be unsubscribed.

Request body for the add resource

  1. Click Send to call a request.

Click Send to call a request

4. How to Use Dynamic Content in Emails.

You can send emails with dynamic content via two methods:

First method. Use the API resource v1/event to insert the data dynamically from the request body into the email body. The array params may contain a random number of parameters:

...

{

"name": "field name",

"value": "field value"

}

...

To insert dynamic data, use Velocity.

For example, you call such a request:

{

"eventTypeKey": "testEvent",

"keyValue": "example@email.com",

"params": [{

"name": "discount",

"value": "5%"

},{

"name": "link",

"value": "https://example.site.com/items_for_sale"

}

]

}

Use $!data.get('discount') and $!data.get('link') parameters, where individual sales values and links, configured in the request, would be inserted dynamically.

To enable insertion of the content generated by the resource /v1/event in the message body, create a workflow that would use this message.

Second method. To launch sending without workflow creation, use the API resource /v1/message/{id}/smartsend, where {id} is a message ID with the data necessary for sending.

The standard request body looks as follows:

{

"recipients" : [ {

"locator" : "...",

"jsonParam" : "..."

} ]

}

recipients - the array of email addresses of the message recipients;

locator - a recipient. For example, an email address for emails, a phone number for SMS or Viber messages;

jsonParam - data in json format to insert in the message.

This method allows to generate different content for each individual recipient. The entered data is organized in "email + a set of parameters” pairs. The parameters are entered in the form of a random json structure, all fields of which are assigned $data.get('field_name').

Using this method, you can:

  • set the condition for displaying a block of an html code: #if($data.get('field_name').equals('0')) ... #end..
  • loop through an array based on the array elements: #foreach($item in $data.get('items')) ... $item.get('name') ... $item.get('price') ... #end.
  • make arithmetic operations with field values in the message body.

Note: the double quotes inside the json structure with the parameters should be modified by an escape character: "jsonParam" : "{\"field1\":\"value1\", ... }".

5. How to Use Events to Create Triggers.

Use the API resource /v1/event to create triggers. All external data integrated into the message get to the parameter data. To set the right parameter, configure $!data.get('parameter name'). To do this:

  1. Call a request. The standard request body looks as follows:

{

"eventTypeKey": "...",

"keyValue": "...",

"params": [{

"name": "...",

"value": "..."

}, ... ]

eventTypeKey - a key ID of the event type. It’s created in the system for each new event;

keyValue - an event ID that can be identical to the contact ID or email;

name - a parameter name;

params - a list of parameters.

  1. Create an email with dynamic content (Messages > Messages > Create Email).

Create an email with dynamic content

Note! The quoted value after $!data.get should correspond to the name value in the params array, which is specified in the request.

  1. Create a workflow (Automation > Workflows > Add new workflow).

Create a workflow

  1. Create an event (Automation > Event Types > Create New Event) with a key to be used in the request (eventTypeKey), and add it to the created workflow.

Create an event

Important! You don’t necessarily have to create the event beforehand. After you call the first request, the event will be created automatically.

To test, call a request in Postman.

  1. Set configurations:
  1. In Body, enable raw and select JSON (application/json).
  2. Enter the request body.

Enter the request body

  1. Click Send to call a request. You will receive the corresponding email in one minute.

Delivered dynamic email

After a successful request, check the correctness of

  • event integration in the system: Automation > Event history;

Check the event integration

  • campaign launch and the corresponding statistics: Campaigns > Single reports;

Check the campaign launch

  • email layout and design: your Inbox.

6. How to Pass Orders via API.

To pass orders, use the resource /v1/orders. You can pass 1 to 1,000 orders in one request. To insert products in emails, pass in orders the array items with the data on these products. The request body and field descriptions are provided here. If you don't insert the product data in emails, or pass orders only for RFM analysis, you may not pass the array.

The standard request body looks as follows:

{

"orders": [{

"externalOrderId": "100500",

"externalCustomerId": "12345",

"totalCost": 1000,

"status": "INITIALIZED",

"date": "2017-03-08T09:30:00+02:00",

"email": "mail@example.com",

"phone": "447911123456 ",

"firstName": "John",

"lastName": "Smith",

"currency": "USD",

"shipping": 10,

"discount": 0,

"deliveryMethod": "express",

"paymentMethod": "cash",

"deliveryAddress": "First str. 1",

"items": [{

"externalItemId": "200600",

"name": "Super Device",

"category": "devices",

"quantity": 1,

"cost": 990,

"url": "http://example.com/item/200600",

"imageUrl": "http://example.com/item/200600/image.png",

"description": "High quality"

}]

}]

}

Each order contains the obligatory fields (highlighted in bold) and optional fields. A successful response to a request will contain a status 200.

For orders, you can use several statuses:

  • INITIALIZED for a new order;
  • IN_PROGRESS for an order that is being delivered;
  • DELIVERED for a paid and delivered order;
  • CANCELLED for a cancelled order.

Important! Only orders with the DELIVERED status are used to form cells for the RFM analysis.

To update the status or other order details, pass the updated order with the same externalOrderId. This parameter is used by the system to determine the uniqueness of orders.

To check whether the order has been sent into the system and whether the fields have been passed correctly, go to Automation > Orders. Click the order ID to see all the fields in JSON format.

Order view

See this article to learn how to use order information dynamically in emails and create triggered campaigns.

7. How to Get a Sent Status for a Message via API.

Single messages sent via the resources /v1/message/{id}/smartsend, /v1/message/email, /v1/message/sms, /v1/message/viber are sent in the asynchronous mode. After an API request is called, your message is scheduled for sending and is sent within seconds.

The body of each response looks as follows:

{

"id": "0",

"results": {

"id": "0",

"locator": "test@gmail.com",

"status": "OK",

"requestId": "3ff28330-f8ef-4636-92ac-86345c16995e"

}

}

To get the status of this message and any other message sent via any channel, call a GET-request of the resource /api/v1/message/status.

Ids - the identifiers requestId separated by a comma.

The request body looks as follows:

{

"results": {

"status": "DELIVERED",

"requestId": "3ff28330-f8ef-4636-92ac-86345c16995e",

"failed": "false",

"delivered": "true"

}

}

Learn more about the data on this request and message statuses.

8. How to Integrate a Subscription Form via API.

To integrate a subscription form, use the API resource /v1/contact/subscribe.

The standard request body looks as follows:

{

"contact" : {

"channels" : [ {

"type" : "email",

"value" : "test@mail.com"

} ]

}

}

After a resource call, one contact with the email address test@mail.com will be added to the system.

To configure the contact name, add the firstName value to the contact field:

{

"contact" : {

"firstName" : "...",

"channels" : [ {

"type" : "email",

"value" : "test@mail.com"

} ]

}

}

To specify the segments where the subscribed contact will be added, add to the request the groups field - the string array, segment names. If the specified segments don’t exist in the system, they will be created automatically:

{

"contact" : {

"firstName" : "...",

"channels" : [ {

"type" : "email",

"value" : "test@mail.com"

} ]

},

"groups" : [ "Subscribers" ]

}

Once this resource is called, the system automatically generates one of two events:

  • subscribeFromAPI for a new contact;
  • subscribeUpdateFromAPI - for existing contacts.

You can see these events in Automation > Event history.

Event history

Any event can be added to a workflow. When an event that is incorporated in a workflow is triggered, the workflow launch begins. For new contacts, it is advisable to send a subscription confirmation.

To make sure a new contact is created, go to Contacts - All Contacts, and enter the necessary email address into the search.

All contacts

The found contact will be highlighted in gray. This means the contact’s email address is inactive and requires confirmation.

Inactive contact is highlighted in gray

You can't send any campaigns to such addresses besides a subscription confirmation email and other transactional emails, for example, an abandoned cart or order confirmation.

9. How to Pass Additional Field Values via API.

Use the resource /v1/contacts to add or edit additional fields. The standard request body looks as follows:

{

"contacts": [{

"channels": [{

"type": "email",

"value": "test@mail.com"

}],

"fields": [{

"id": 12345,

"value": "..."

}]

}],

"customFieldsIDs": [12345]

}

channels - a list of the contact’s media channels (in the example, one media channel - email address - is passed);

fields - a list of additional fields passed in pairs: field ID + value.

There are two ways to get all the IDs available for your account:

  1. Go to your Personal profile > Settings > Additional fields.

Additional fields

  1. Call the resource /v1/addressbooks. This is a GET-method with no parameters. Its response body looks as follows:

{

"addressBook": {

"addressBookId": "7200",

"name": "Main",

"fieldGroups": {

"name": "Personal",

"fields": [

{

"id": "15867",

"name": "Date of birth",

"description": {

"type": "date",

"required": "false",

"readonly": "false"

}

},

{

"id": "15868",

"name": "Gender",

"description": {

"type": "combobox",

"allowedValues": {

"possibleValues": [

"M",

"F"

]

},

"required": "false",

"readonly": "false"

}

}

]

}

}

}

fields - a list of all additional fields. Besides other information, each element of the list has a field ID to be used when passing its value.