Login

Courses

Courses

Omnichannel

Security and Compliance

Integration

Website Integration

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 of all, 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.

Go to Authorization and select Basic Auth

  1. 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.

Postman

  1. Select a method (GET in the example) and enter a resource (Get 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

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

2.1. Set configurations:

Select the method and enter the resource

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

Request body for the add resource

2.3. Specify the request body in the format:


{

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

}

2. 4. Click Send to send the request.

Click Send to call a 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).

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.

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).

Create a 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.

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:

  • 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:

Enter the request body

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

Delivered dynamic email

After a successful request, check the correctness of:

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

Check the event integration

2) sending email: Campaings → Single reports;

Check the campaign launch

3) receiving an email with correctly substituted elements: inbox.

How to Pass Orders via API

To pass orders, use the resource Add 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. 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:

  • For a newly created order, use the INITIALIZED status.
  • For an order in the process of delivery - IN_PROGRESS.
  • For a paid and delivered order - DELIVERED.
  • For canceled orders - CANCELLED.

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.

How to Get a Sent Status for a Message via API

Single messages sent via the resources Send prepared message, Send email message, Send SMS message, Send viber message 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 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 Integrate a Subscription Form via API

To integrate a subscription form, use the API resource Subscribe contact.

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:

1) subscribeFromAPI if a new contact has been created;

2) subscribeUpdateFromAPI - if such a contact exists.

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.

How to Pass Additional Field Values via API

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

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

Additional fields

The second is to call the Get catalog list resource. This is a parameterless GET method that will return you 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.

Any Questions?
We’re always happy to help!
Discount services
Schedule a Call
Fill in the form, and our specialists will call you back as soon as possible.
Discount services
Chat Support
We’re waiting for your questions!
Discount services
Email
Contact the support team