Integration with API

General documentation

All technical documentation by data format, standards and error codes can be found in article "Introduction to eSputnik Rest API". Latest description of API methods and code examples for calling of these methods is available at: "Available resources of eSputnik Rest API". 

In the next section you will find answers to frequently asked questions about API usage or fixing specific problems. It has more explanations, examples and descriptions than method description.

Frequently asked questions

How can I check that API works and access settings are correct?

The simplest API method is to get current version at: /api/v1/version. After following the link specify your username and password for authentication. If entered data are correct, you will get response like this:

{"version":"1.0-r20150908","protocolVersion":"1.0"}

 

How can I do quick testing or calling API method?

Chrome has a friendly plugin:  Postman for Chrome. You can add it and test requests in a user-friendly editor. For a simple request to get version it looks like:


After pressing button “Send”, you will be asked to specify access settings. Indicate those settings, which you have got for work with API.

 

 

How can I unsubscribe a contact if unsubscription was done in “My account” on website?

Use API method  API /v1/emails/unsubscribed/add or delete. or delete to manage unsubscription. Generally, unsubscription is done not for a contact, but for an email address. In other words, after unsubscription emails aren’t sent not only to this contact, but also to any other contact with the same email address.

Отписка контакта в Postman

1. To add email to the list of unsubscribed contacts use the following method: /api/v1/emails/unsubscribed/add
Request body looks as:
 
{
  "emails" : [ "test1@mail.com", "test2@mail.com" ]
}
 
emails - emails is a list of email addresses which will be marked as unsubscribed.
 
2. To delete email from list of unsubscribed contacts use the method: /api/v1/emails/unsubscribed/delete
Request body is similar to the method mentioned above: list of email addresses which will be deleted from unsubscribed.

How should I use events for triggers, for example, “Your order placed”?

It easy to send triggers using API method /v1/event. /v1/event. To do this you should:

1) create an email, which you would like to send;

Письмо в редакторе eSputnik

Note! Quoted value after $!data.get has to correspond to value of name in parameter array  params, which will be transferred in request later.

2) create a scenario in Scenario editor;

Редактор сценариев

3) create event (Triggers - Event types - Add event type) with a key, which will be used in request (field "eventTypeKey"), and bind scenario to event (see. п. 2);

Добавить тип события

4) call request in Postman;

Вид запроса в Postman

Minimum request body has the following view:

{

    "eventTypeKey": "...",

    "keyValue": "...",

    "params": [{

        "name": "..."

        "value": "...",

        }, ... ]

}

 

eventTypeKey - key identifier of event type. If there is no event type with such a key, it should be created;

keyValue - event identifier, can be the same as contact’s identifier or email address, repeated events of certain type with the same identifier will be ignored; 

params - list of parameters. 

After pressing button “Send” request will be sent. Within a minute, we will get an email: 

 

After successful sending of request you can do verification: 

 

1) record in Triggers - Event history;

2) email in Campaigns - Single;

3) email in mailbox.

 

How can I get sent a message status through API?

If you send single messages with methods  /v1/message/{id}/send, /v1/message/{id}/smartsend, /v1/message/email or /v1/message/sms, emails are sent in asynchronous mode, meaning that after request to API your email is put in a queue for sending and in over time (usually within several seconds) it will be sent. In response to each of these requests you will get the following structure:

{

    "id": "0",

    "results": {

        "id": "0",

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

        "status": "OK",

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

    }

}

After that, you need to call GET-request /api/v1/message/email/status?ids=3ff28330-f8ef-4636-92ac-86345c16995e (or /v1/message/sms/status to get this message status).

ids parameter is a list of comma-separated identifiers requestId. You will get the following response:

{

    "results": {

        "status": "DELIVERED",

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

        "failed": "false",

        "delivered": "true"

    }

}

If you need more details about data from this response including message statuses, go to:  /api/ns0_instantMessageStatusDto.html.

 

How can I use dynamic content in emails?

Sending email with dynamic content can be done in two ways: 1) substitution of specified keys with parameters in email body, 2) advanced engine to implement cycles of looping over arrays and checking conditions depending on values of fields.

1) API method /v1/message/{id}/send

Minimum request body:

{

  "groupId" : ...,

  "recipients" : [ "..." ],

  "params" : [ {

    "key" : "...",

    "value" : "..."

  } ]

}

groupId - group identifier for sending message

recipients - array of recipients’ addresses

You need to specify at least one parameter.

params - array of pairs “key+value”. Keys are inserted in email body like this: %TEMPLATE.xxx%. Then value {"key":"xxx", "value":"<table><tr><td>test</td></tr></table>"} is transmitted. While sending all keys in email body are substituted with their values from params or deleted if value for specific key is not transmitted.

2) API method /v1/message/{id}/smartsend

Minimum request body:

{

  "recipients" : [ {

    "locator" : "...",

    "jsonParam" : "..."

  } ]

}

Unlike the first method where all recipients get the same email content, this method allows to generate unique content for each recipient. Data transmission is organized as pairs “email address+set of parameters”. Parameters are transmitted as arbitrary json-structure, where all fields can be addressed in email body as:  $data.get('field_name'). You can define display condition of any block of html-code:  #if($data.get('field_name').equals('0')) ... #end. Cycle on array elements can also be organized:  #foreach($item in $data.get('items')) ... $item.get('name') ... $item.get('price') ... #end. Besides arithmetical operations with values of fields can be done in email body. Note that double quotes within json-structure with parameters need to be escaped: "jsonParam" :  "{\"field1\":\"value1\", ... }".

 

How can I integrate Subscription form through API?

To integrate Subscription form it is necessary to call  /v1/contact/subscribe. Minimum request body looks like:

{

  "contact" : {

    "channels" : [ {

      "type" : "email",

      "value" : "test@mail.com"

    } ]

  }

}

The list of contact’s media channels contains one email address.

To set contact’s name it is necessary to add field firstName into request body in object contact:

{

  "contact" : {

    "firstName" : "...",

    "channels" : [ {

      "type" : "email",

      "value" : "test@mail.com"

    } ]

  }

}

To indicate the groups which subscribed contact will be attached to, it is necessary to add field groups to request - array of string value, group names. If any of the groups don’t exist, they will be created automatically.

{

  "contact" : {

    "firstName" : "...",

    "channels" : [ {

      "type" : "email",

      "value" : "test@mail.com"

    } ]

  },

  "groups" : [ "Subscribers" ]

}

After calling of this method one of two events is generated: subscribeFromAPI - if a new contact has been created, and subscribeUpdateFromAPI - if this contact already exists. These events can be found at Dashboard, Triggers - Event history.

Scenario can be bound to any event type and will be launched while event generation. In this case email for subscription confirmation should be sent to a new contact. You can contact our Support and we will help to configure necessary scenario.

To ensure that a new contact has been created you can go to Dashboard - Contacts - All contacts, and type necessary email address in Search string. You will see that contact’s email is highlighted with grey, that means that it is inactive and requires confirmation from the owner. It is impossible to send campaigns to such email addresses. Only subscription confirmation and transactional emails, such as email about cart abandonment or order confirmation can be sent to such contacts.

 

How can I transmit values of additional fields through API?

Let’s demonstrate adding additional fields using /v1/contacts - contact creation/update. Minimum request body looks like:

{
  "contacts": [{
    "channels": [{
      "type": "email",
      "value": "test@mail.com"
    }],
    "fields": [{
       "id": 12345,
       "value": "..."
    }]
  }],
  "customFieldsIDs": [12345]
}

channels is a list of contact’s media channels. In this case one media channel is transmitted - email address

fields is a list of additional fields transmitted in pairs: field identifier + value

There are two ways to get all identifiers of additional fields existing in your organization:

1. View identifiers in Account’s menu - Settings - Additional fields.

2. Call request /v1/addressbooks. This is GET-request without parameters, which will give you structure in response like:

{

    "addressBook": {

        "addressBookId": "7200",

        "name": "Основной",

        "fieldGroups": {

            "name": "Personal",

            "fields": [

                {

                    "id": "15867",

                    "name": "День рождения",

                    "description": {

                        "type": "date",

                        "required": "false",

                        "readonly": "false"

                    }

                },

                {

                    "id": "15868",

                    "name": "Пол",

                    "description": {

                        "type": "combobox",

                        "allowedValues": {

                            "possibleValues": [

                                "м",

                                "ж"

                            ]

                        },

                        "required": "false",

                        "readonly": "false"

                    }

                }

            ]

        }

    }

}

list fields is a list of all your additional fields. Additionally to all other information, each object of this list contains field identifier to be used while its value transmission.