API

Subscribers editing and import using API

Subscribers import using API

All requests should contain API token.
POST request and response are sent in JSON.

See the example of the URL for request:

<domain>/api/v1.0/lists/<list_id>/import?token=xxx..xx

Minimal request form:

{
"Leads": [
  {"Email": "mail@mail.roo"}
          ]  
}

Here is the example of the request containing all field types:

The number of fields is not limited.

{
"Leads": [
  {
   "Email": "string" (at least abc@com),
   "FirstName": "string",
   "LastName": "string",
   "Birthday": "ISO date string" ("2012-12-31T00:00:00.000Z"),
   "Gender": "String" ("m" или "f") или Int (1 или 2),
   "RegDate": "ISO date string" ("2012-12-31T00:00:00.000Z"),
   "RegIP": "string" (IPv4, "127.0.0.1"),
   "RegCity": "string",
   "RegCountry": "string" ("US", only two letters short names),
   "RegUrl": "string" ("http://www.myurl.com"),
   "LastIP": "string" (IPv4, "127.0.0.1"),
   "LastCity": "string",
   "LastCountry": "string" ("US", only two letters short names),
   "Vendor": "String less or equal than 26 characters",
   "Custom_String_Field": "string",
   "Custom_Enum_Field_v1": "value" ,
   "Custom_Enum_Field_v2": int ,
   "Custom_Number_Field": int32,
   "Custom_Date_Field": "ISO date string" ("2012-12-31T00:00:00.000Z"),
   "Custom_Boolean_Field": boolean (True или False),
   "Custom_TAGS_Field": ["Tag 1", "Tag 2", ...]
   },
  {Block 2 , for the second subscriber},
  {Block 3 , for the third subscriber},
  ...
        ],
   "SkipUnknownFields": Boolean (True или False)
}

The “SkipUnknownFields” checkbox is not required. If it has value - True, only information from the existed fields will be imported.

If it has value - False, the information won’t be imported at all. The user will see the following error message: “Import error (email_1@yandex.ru): Unknown field: Field_AbCd”

Possible request errors

The character case has the following value - is case-sensitive. Mind, that fields “FirstName” and “firstname” are different fields.

The data format matters. “100” and 100 are not the same. The first is string, the second is int.

Let’s consider the following example:

Name: AvgTemperatureInCity
Type: Number

Correct request:

"AvgTemperatureInCity": -15

Incorrect request:

"avgtemperatureincity": -15
"AvgTemperatureInCity": "-15"

Responses:

Response if complete:

{
    "Status": "ok",
    "Updated": Int,
    "TotalCount": Int,
    "Invalided": 0,
    "Inserted": Int
}

Response in case of error message:

{
    "Status": "ok",
    "Updated": Int,
    "Errors": [list of errors],
    "TotalCount": Int,
    "Invalided": Int,
    "Inserted": Int
}

Response if the request is incorrect:

{
    "Status": "error",
    "ErrorCode": int,
    "ErrorMessage": "String"
}

API add tags

API add tags method is used to edit custom fields of the Tag type.

API add tags method allows to add new tags to the list, while the API import replaces old tags with the new ones.

API link:

<domain>/api/v1.0/lists/<list_id>/lead/tags_add
{
  "Lead": "email",  (<email|md5|xxh> - 3 ways to identify a subscriber)
  "FieldName": "Tag_Field_Name", (the field must have a tags type)
  "Tags": ["tag 1", "tag 2", ...]  (list of tags)
}

API remove tags

API remove tags method is used to edit custom fields of Tag type.

API remove tags method allows to remove tags from the list, while API import replaces old tags in the field with the new ones.

<domain>/api/v1.0/lists/<list_id>/lead/tags_remove
{
  "Lead": "email",  (<email|md5|xxh> - 3 ways to identify a subscriber)
  "FieldName": "Tag_Field_Name",  (the field must have a tags type)
  "Tags": ["tag 1", "tag 2", ...]  (list of tags)
}

How can I get subscriber’s details

The request should be in JSON and include API Token.

See the example of the URL for request:
<domain>/api/v1.0/lists/<list_id>/lead?token=xxx..xx
Request for one subscriber’s details:
{"Email": "email1@mail.roo"}
Request for several subscribers’ details:
{
  "Emails": [
      "email1@mail.roo",
      "email2@mail.roo",
      ...
             ]
}

How to unsubscribe a subscriber from the List

The request should be in JSON and include API Token.

See the example of the URL for request:
<domain>/api/v1.0/lists/<list_id>/lead/unsubscribe?token=xxx..xx
Unsubscribe request for one subscriber:
{"Email": "email1@mail.roo"}
Unsubscribe request for several subscribers:
{
  "Emails": [
      "email1@mail.roo",
      "email2@mail.roo",
      ...
             ]
}

Subscription recovery

The request should include API Token and be in JSON.

See the example of the URL for request:
<domain>/api/v1.0/lists/<list_id>/lead/subscribe?token=xxx..xx
Subscription recovery for one subscriber:
{"Email": "email1@mail.roo"}
Subscription recovery for several subscribers:
{
  "Emails": [
      "email1@mail.roo",
      "email2@mail.roo",
      ...
             ]
}

How to set the Complainer status to the subscriber

Subscribers with the Complainer status are excluded from all mailings.

The request should include API Token and be in JSON.

See the example of the URL for request:
<domain>/api/v1.0/lists/<list_id>/lead/complain?token=xxx..xx
Set the status to one subscriber:
{"Email": "email1@mail.roo"}
Set the status to several subscribers:
{
  "Emails": [
      "email1@mail.roo",
      "email2@mail.roo",
      ...
             ]
}

API Call trigger

API Call trigger campaign sends a message to one subscriber from the List in case of an API request.

There are two types of API requests: GET and POST.

GET

http://<tracking_domain>/trg/d1d255bc9e3c0bcf5c9d3947d9ffa76a7c1742a2f23fbacd/<email|md5|xxh>

A trigger message will be sent to the subscriber’s email | md5 | xxh listed in the request.

POST

http://<tracking_domain>/trg/d1d255bc9e3c0bcf5c9d3947d9ffa76a7c1742a2f23fbacd/<email|md5|xxh>

Subscriber’s data may be added to the POST API request in order to make a message more personal or to update subscriber’s personal details.

Please see the example:

{"fields": [
            {"name": "FirstName",
             "value": "Json",
             "option": 0},
            {"name": "Vendor",
             "value": "Altkraft",
             "option": 1},
            {"name": "Order",
             "value": "123abc456-78",
             "option": 2}}
            ]
 }

FirstName, Vendor - standard fields.

Order - custom field. Custom fields can be created in the List settings.

 Message code to insert data into a message:

<p>First Name: {lead._fname}</p>
<p>Your vendor: {lead._vendor}</p>
<p>Your order: {lead.Order}</p>

“name”: “FieldName” - a field name.

“value”: “MyValue” - a field value.

“option”: Integer - determines the way the request data should be used.определяет.

“option”: “0” - if the (“name”) field is filled in, its value will be in the message.

“option”: “1” - a value from the (“value”) box from the request will be in the message.

“option”: “2” - a value from the (“value”) box from the request will be in the message. ! The (“name”) field will be updated in the subscriber’s profile with the value from the (“value”) box. !

API response codes

Code Description
1 Token required in request
2 Invalid request
10 Invalid token
11 Permission denied
20 Restricted because of the leads overlimit
21 Restricted because of the messages overlimit
100 List not found
501 Connection to account refused