Integration with API

The Getting Started With API section provides all technical documentation on the data format, standards, error codes, updates on API resources, and request code samples.

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.

How to Check API for Correct Performance and Valid Access Options

To check the API resources for the correct performance, first, try to get the current account info: Get 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.

2. To access your account resources, you need to enter any value for the Username field and the value of your API key in the Password.

3. Select a method (GET in the example) and enter a resource (Get account info in the example).

4. Click Send to call a request.

The corresponding request body looks as follows:

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

To manage unsubscribes, there are two API resources - Add emails to unsubscribed list and Remove emails from unsubscribed list.

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 Add emails to unsubscribed list 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 Remove emails from unsubscribed list 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 these resources (Add emails to unsubscribed list in the example) in Postman:

2.1. Set configurations:

• select the method POST;
• enter the resource Add emails to unsubscribed list.

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

2.3. Specify the request body in the format:

{
"emails" : [ "...", ... ]
}

2. 4. Click Send to send the request.

How to Use Dynamic Content in Emails

You can send emails with dynamic content via two methods:

First method. Use the API resource Generate 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 Generate 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 Send prepared message, 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 HTML code: #if($data.get('field_name').equals('0')) ... #end.
• Loop through array elements: #foreach($item in $data.get('items')) ... $item.get('name') ... $item.get('price') ... # end.
• Perform arithmetic operations with field values in the body of the email.

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

For more information, see the article Using the smartsend API resource.

How to Use Events to Create Triggers

Use the API resource Generate 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.Prepare the request body. The minimum request body is:

{
"eventTypeKey": "...",
"keyValue": "...",
"params": [{
"name": "...",
"value": "..."
}, ... 

where

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.

2. Create an email with dynamic content (Messages → Messages → Create Email).

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

3. Create a workflow so that the content passed by the Generate event resource is substituted into the body of the message (Automation → Workflows → New Workflow).

4. Create an event (Automation → Event types → New Event) with the key that will be used in the request (eventTypeKey field) and attach the workflow created in the previous step to the 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:

• Select POST request method
• Enter resource Generate event

2. In the Body section, select raw and the JSON data transfer format (application/json).

3. Specify the request body in the format:

After clicking on the Send button, the request will be sent, and within a minute we will receive an email of the form:

After a successful request, check the correctness of:

1) event transfer to the system: Automation → Event history;

2) email sending: Campaings → Single reports;

3) email receiving with correctly substituted elements: inbox.

How to Pass Orders via API

To pass orders, use the Add orders resource. 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. 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 newly created order.
• IN_PROGRESS for an order being delivered.
• DELIVERED for a paid and delivered order.
• CANCELLED for canceled orders.

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.

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

How to Get a Sent Status for a Message via API

Single messages sent via the Send prepared message, Send email message, Send SMS message, Send viber message resources 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 of any other message sent via any channel, call a GET-request of the resource Get single 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"
}
}

How to Pass Additional Field Values via API

Use the Add/update contacts resource 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.

The first is to view the identifiers in the Account menu → Settings → Additional fields.

The second is to call the Get catalog list resource. This is a parameterless GET method that returns a structure like this:

{
"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.