Developer Guide

FAQ: Integrating with API

ISee answers to the most common questions about eSputnik API integration.

You can find all technical documentation on the data format for calling API requests here.

How to Check API for Correct Performance and Valid Access Options

For example, you can get information about your account using the Get account info method. Follow these steps:

  1. Generate an API key and copy it to your clipboard.

  2. Go to the https://docs.esputnik.com/reference/getaccountinfo-1 page.

  3. Enter the username and password that is the copied API key above the example request.

Get account info
  1. Click Try it!
Try it!

You should see your username and your organization name in the response:

Response

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

There are two API resources to manage unsubscribes β€” Add emails to unsubscribed list and Remove emails from unsubscribed list.

πŸ“˜

Important

The method unsubscribes not contacts but their email addresses (other channels β€” SMS, Viber, Web Push β€” remain active). All contacts within the organization who may use these email addresses will stop receiving bulk emails from you.

The request body would look as follows:

{  
  "emails" : [ "[email protected]", "[email protected]" ]  
}

where emails β€” the email addresses that will be marked as unsubscribed.

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

Let's look at working with the Remove emails from unsubscribed list method:

  1. Go to the https://docs.esputnik.com/reference/deletefromunsubscribed-1 page.

  2. Click ADD STRING in BODY PARAMS and enter the addresses of unsubscribed contacts in the strings.

Remove emails from unsubscribed list
  1. Click Try it!

If the addresses in the request have been unsubscribed from your eSputnik account, they will be removed from this list.

How to Use Dynamic Content in Messages

There are two ways to implement sending an email with dynamic content:

Using a Workflow

Use the Generate event API method to insert the data dynamically from the request body into the message. The array params may contain a random number of parameters:

{  
"name": "field name",  
"value": "field value"  
}

Use Velocity variables to insert dynamic data into a message.

For example, you call the request in the following format:

{  
    "eventTypeKey": "testEvent",  
    "keyValue": "[[email protected]](mailto:[email protected])",  
    "params": [{  
        "name": "discount",  
        "value": "5%"  
        },{  
        "name": "link",  
        "value": "https://example.site.com/items_for_sale"  
        }  
]  
}

The message must use the variables $!data.get('discount') and $!data.get('link'), instead of which the data from the request will be substituted.

To insert the content sent by the Generate event method into the body of the message, prepare a workflow using this message, which the corresponding event will trigger. Details >

Using the Send Prepared Message Method

This method involves sending messages without using a workflow. The {id} in the link https://esputnik.com/api/v1/message/{id}/smartsend is the identifier of the message into which the data will be inserted when sent to the recipient.

Minimum request body:

{  
  "recipients" : [ {  
    "locator" : "...",  
    "jsonParam" : "..."  
  } ]  
}

where:

  • recipients are the array of the message recipients’ contact data;
  • locator is a recipient. For example, an email address for emails and a phone number for SMS or Viber messages;
  • jsonParam is data in the JSON format to insert in the message.

This method allows for generating different content for each recipient. The entered data is organized in "email + a set of parameters” pairs. The parameters are entered as a random JSON structure, and all fields 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\", ... }".

How to Use Events for Triggers

Triggered campaigns can be launched using the Generate event API method. This method is suitable for creating custom events.

We also recommend using the Generate event method to transfer orders. Manual >

How to Pass Orders via API, e.g., for Their Confirmation

You can also use the Add orders method to pass orders. One request can contain up to 1,000 orders. Pass the array of items with the data on these products in orders to insert products in emails. You may not pass the array if you don't insert the product data in emails or pass orders only for RFM analysis.

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": "[[email protected]](mailto:[email protected])",  
        "phone": "380942583691",  
        "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 must contain the following obligatory fields:

Body params

The response to a successful request will have the 200 status.

You can use several statuses for orders:

  • INITIALIZED for a newly created order.
  • IN_PROGRESS for an order being delivered.
  • DELIVERED for a paid and delivered order.
  • CANCELlED for cancelled orders.

πŸ“˜

Important

Only orders with the DELIVERED status are used for RFM analysis.

To update the status or other order details, pass the updated order with the same externalOrderId. The system uses this parameter 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 to see all the fields in the JSON format.

Order details

More about using order information in emails >

How to Get a Sent Status for a Message via API

Single messages are sent in the asynchronous mode via the following methods:

After an API request is called, your message is scheduled for sending and is sent within seconds.

The body of the response looks as follows:

{
    "id": "0",
    "results": {
        "id": "0",
        "locator": "[email protected]",
        "status": "OK",
        "requestId": "3ff28330-f8ef-4636-92ac-86345c16995e"
    }
}

To get the status of the message sent via any channel, call a request of the Get single message status method.
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 Subscription Form via API

eSputnik offers built-in functionality for creating widgets without additional API settings.

To integrate a subscription form created using a third-party service, call the request using the Subscribe a contact method. The minimum request body looks like this:

{  
  "contact" : {  
    "channels" : [ {  
      "type" : "email",  
      "value" : "[email protected]"  
    } ]  
  }  
}

A contact with an email address will appear in the system.

To set the contact name, add the firstName field in the contact object to the request body:

{  
  "contact" : {  
    "firstName" : "...",  
    "channels" : [ {  
      "type" : "email",  
      "value" : "[email protected]"  
    } ]  
  }  
}

To specify which segments the subscribed contact should be in, add the groups field to the request β€” an array of string values for segment names. If any segments do not exist in the system, they will be created automatically:

{  
  "contact" : {  
    "firstName" : "...",  
    "channels" : [ {  
      "type" : "email",  
      "value" : "[email protected]"  
    } ]  
  },  
  "groups" : [ "Subscribers" ]  
}

Two event types are automatically generated in the system after the call:

  • subscribeFromAPI – in case of creating a new contact;
  • subscribeUpdateFromAPI – if such a contact already exists.

You can see these events in the Triggers β†’ Event history section.

Event history

Any type of event can be associated with a workflow launched when the event is generated. We recommend sending an email to confirm a new contact subscription.

To ensure a new contact has been created, go to Contacts β†’ All contacts section and enter the contact ID in the search field.

Contacts

You will see that the contact's email is grayed out, meaning it is inactive and requires confirmation from the owner.

Inactive contact

It is impossible to send newsletters to such addresses; they can only receive subscription confirmation emails and other trigger messages, for example, an abandoned cart email or confirmation of a completed order.

How to Pass Additional Field Values via API

Let's look at updating additional fields using the Add/update contacts method. The standard request body looks as follows:

{  
"contacts": \[{  
"channels": [{  
"type": "email",  
"value": "[email protected]"  
}],  
"fields": [{  
"id": 12345,  
"value": "..."  
}]  
}],  
"customFieldsIDs": [12345]  
}

where

  • channels is a list of the contact’s media channels (in the example, one media channel β€” email address β€” is passed);
  • fields is a list of additional fields passed in pairs: field ID + value.

There are two ways to get all the IDs available in 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 the list of catalogs method. This parameterless method will return you a structure like this:

{
    "addressBook": {
        "addressBookId": "7200",
        "name": "Main",
        "fieldGroups": {
            "name": "Personal",
            "fields": [
                {
                    "id": "15867",
                    "name": "Birthday",
                    "description": {
                        "type": "date",
                        "required": "false",
                        "readonly": "false"
                    }
                },
                {
                    "id": "15868",
                    "name": "Gender",
                    "description": {
                        "type": "combobox",
                        "allowedValues": {
                            "possibleValues": [
                                "M",
                                "F"
                            ]
                        },
                        "required": "false",
                        "readonly": "false"
                    }
                }
            ]
        }
    }
}

The fields list is a collection of all your additional fields. In addition to other information, each object in this list contains a field identifier that must be used when passing its value.

How to Test API Using Postman

Postman is a popular API testing tool. It provides a user-friendly interface for creating, sending, and tracking requests.

To get started with Postman, download and install it on your computer.

Testing the Get Account Info Method

  1. Select Basic Auth in the parameters, Authorization tab, Type line:
Basic Auth
  1. Log in:
    • enter any value in the Username field,
    • enter the value of your API key in the Password field.
Log in
  1. Select the GET method and enter the https://esputnik.com/api/v1/account/info link.
Get account info
  1. Click the Send button.

You should see your username and your organization name in the response:

{  
    "userEmail": "api-user162065",  
    "organisationName": "ExamleName"  
}

Testing the Remove Emails from Unsubscribed List Method

  1. Select the POST request method and enter the https://esputnik.com/api/v1/emails/unsubscribed/delete link.
Remove emails from unsubscribed list
  1. Select raw and JSON data transfer format in the Body section.
Body section
  1. Specify the request body in the following format:
{  
  "emails" : [ "...", "..." ]  
}
  1. Click Send.

If the addresses in the request have been unsubscribed from your eІputnik account, they will be removed from this list.

Testing the Generate Event v2 Method

  1. Select the POST request method and enter the https://esputnik.com/api/v2/event link.
  2. Select raw and JSON data transfer format in the Body section.
  3. Specify the request body in the following format:
{
    "eventTypeKey": "create_contact",
    "keyValue": "[email protected]",
    "params":
    [
        {
            "name": "email",
            "value": "[email protected]"
        },
        {
            "name": "phone",
            "value": "380501234567"
        },
        {
            "name": "externalCustomerId",
            "value": "AV13760"
        },
        {
            "name": "json",
            "value":
            {
                "profileInputs":
                [
                    {
                        "profileInputId": 10001,
                        "value": "2020-11-23"
                    }
                ]
            }
        }
    ]
}
  1. Click Send.

A successfully submitted request will appear in the event history in your eSputnik account.