Using Smartsend API Resource

The resource Send prepared message is intended to send a prepared message to one or several contacts—up to 1,000 recipients can be transferred in one request. The request can be parameterized for each contact individually. Stating the id in the URL supports the possibility to work with email, SMS, Viber, Mob push, and web push notifications.

1. Request Description

A call to the resource is made using the POST method at api/v1/message/1853402/smartsend, where 1853402 is the id (identifier) of the message prepared in your account.

{

"recipients" : [{

"contactId" : "The identifier of a contact (may not be indicated when the locator parameter is indicated).",

"locator" : "A recipient. For example, an email address for email messages, a phone number for SMS or Viber.",

"jsonParam" : "The parameter is in JSON format. It is used for emails with complex velocity templates",

"languageCode" : "The desired language for messages selected by the contact. It is used for multilingual messages."

  }],

"email" : "Message type: true for email, false for the rest of the media channels.",

"fromName" : "Sender’s name. It is required to indicate only the sender’s name, no need for the email address. The sender’s email selected in the message is used. The alpha name is indicated for SMS. If the parameter is not indicated, the name selected in the message is used."

"externalRequestId" : "The optional parameter. It allows you to assign your own identifier to the sent message and receive the status of the sent message using Get contacts activity afterward."

}

2. Server Response

When the request is successful, the server returns the result of single messages delivery.

id – always returns 0;

locator – returns an email or phone number the message was sent to;

When the request is successful, containing no errors, the server’s response to a single request containing two emails looks as follows:

{
    "id": 0,
    "results": [
        {
            "id": 0,
            "locator": "example@mail.com",
            "status": "OK",
            "requestId": "8b2e65d9-060b-4c61-bbd7-73c6796fa504"
        }, {
            "id": 0,
            "locator": "new. example@mail.com",
            "status": "OK",
            "requestId": "458f3533-51d9-439e-a5d0-5fb7c2490c41"
        }
    ]
}

status is the result. OK – if the message is successfully placed in a queue for delivery. You can find out the message status using requestId and a request to the resource.

ERROR – failure to place the message in a queue for delivery.

message – error description, it returns together with the ERROR status.

Example: "message": "'example@mail.com' is not valid email"

3. Use Case for Emails

3.1 Sending Message without Parameterization

You may disregard most of the parameters when delivering single email messages, and no additional parameterization is required for each receiver.

In this case, the body of a request for sending one message looks as follows:.

{
  "recipients": [
    {
      "jsonParam": null,
      "locator": "example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

And for two recipients correspondingly:

{
  "recipients": [
    {
      "jsonParam": null,
      "locator": "example@mail.com"
    }, {
      "jsonParam": null,
      "locator": "new.example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

When the fromName field contains the null value, the name used in the email is the one specified when adding the sender address:

Transmission of the jsonParam field with the null value means that the dynamic parameterization is not intended or anticipated to be used in the email.

Besides null, jsonParam can contain JSON objects, nested objects, and nested arrays requiring serialization before sending a request―in other words, the objects have to be converted consequently to a JSON string.

3.2 Transmission of JSON Objects

Formatting of a JSON object is set using curly braces { } containing the data with the key values. The pairs of key values are separated by a colon: {"key" : "value"}. Every pair of the values is separated by a comma, so the middle section of the JSON object looks like this: {"key" : "value", "key" : "value", "key": "value"}.

As an example, the object containing two pairs of key values looks as follows:

{
  "discount": "5%",
  "link": "https://example.site.com/items_for_sale"
}

For correct transmission, convert an object in the request body to a string to look like this:

{
  "recipients": [
    {
      "jsonParam": "{\"discount\":\"5%\",\"link\":\"https:\/\/site.com\/items_for_sale\"}",
      "locator": "example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

To display the transmitted values in a message, you have to use the velocity structure: $!data.get('discount') and $!data.get('link')

In the text editor:

After data substitution, the message has the following look:

The value “5%” substitutes the discount variable, and the value “https://site.com/items_for_sale” substitutes the link variable as the link for the button.

3.3 Transmission of Nested JSON Objects

The format of an nested JSON object is ”objectName”: {"key" : "value", "key": "value"}.

The example of the customerData and orderData nested objects looks like this:

{
  "customerData": {
    "firstName": "Serhei",
    "lastName": "Ivanov"
  },
    "orderData": {
    "name": "Apple iPhone X 64GB Black",
    "cost": 25999,
    "url": "https:\\example.site.com\smartfon-apple-iphone-x-64gb.html",
    "imageUrl": "https:\\example.site.com\smartfon-apple\apple_iphone_x_64gb.jpg"
  }
}

The data have to be converted to the string (serialization), and the request gets the following look:

{
  "recipients": [
    {
      "jsonParam": "{
\"customerData\":{\"firstName\":\"Serhii\",\"lastName\":\"Ivanov\"},
\"orderData\":{\"name\":\"Apple iPhone X 64GB Black\",
\"cost\":"25999",\"url\":\"https:\/\/example.site.com\/smartfon-apple-iphone-x-64gb.html\",
\"imageUrl\":\"https:\/\/example.site.com\/smartfon-apple\/apple_iphone_x_64gb.jpg\"}
}",
      "locator": "example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

To display the data in a message, use the following velocity structure:

$!data.get('customerData').get('firstName') and $!data.get('orderData').get('name') 

The variables for the dynamic content in the message editor:

As the result of data substitution, the recipient sees the following message:

3.4 Transmission of Nested JSON Array

Arrays are the ordered collections of values. Use square brackets [ ] to define an array. Separate the values inside the brackets with commas.

The format of an nested JSON array is ”arrayName”:[{"key":"value", "key":"value"},{...}]. Several arrays can be transmitted within one request.

{
  "orderData": [
    {
      "name": "Smartphone Apple iPhone Xs 512Gb",
      "price": "49999",
      "url": "http://example.com/smartfon-apple-iphone-27.html",
      "imageUrl": "http://example.com/apple_iphone_xs_silver.jpg"
    },
    {...},
    {
      "name": "Apple Watch Series 4 GPS 44mm Space Gray",
      "price": "13699",
      "url": "http://example.com/smart-chasy-apple-watch-series-4-gps-45-2mm.html",
      "imageUrl": "http://example.com/apple_watch_series_4_gps_44mm.jpg"
    }],
  "recommendationsData": [
    {
      "name": "Smartphone protection glass MakeFuture 3D Apple iPhone X/XS",
      "url": "http://example.com/zaschitnoe-steklo-dlja-smartfona-makefuture.html",
      "imageUrl": "http://example.com/makefuture_3d_apple_iphone_xxs_black.jpg",
      "price": "399"
    },
    {...},
    {
      "name": "Apple 44mm Black Sport Band",
      "url": "http://example.com/remeshok-dlja-smart-chasov-apple-44mm.html",
      "imageUrl": "http://example.com/apple_44mm_black_sport_band.jpg",
      "price": "1999"
    }
  ]
}

Important: Same as for the object and the nested JSON object, the JSON array shall also be converted to a string (serialization).

It is preferable to use arrays when operating with a large amount of data that can be grouped.

To get access to the array data, the structure of the foreach cycle built in velocity has to be used in the message. Having orderData array as an example, the velocity code looks as follows:

// Inside the structure, the data are extracted in a sequence from every element of the array
#foreach($order in $!data.get('orderData'))
  // To extract the value from the name field of the order 
  $!order.get('name') 
  // For the url field
  $!order.get('url') 
  // For the imageUrl field
  $!order.get('imageUrl')
  // For the price field
  $!order.get('price')
#end 

Similarly for an array transmitting recommendationsData:

// Inside the structure, the data are extracted in a sequence from every element of the array
#foreach($recomm in $!data.get('recommendationsData'))
  $!recomm.get('name')
  $!recomm.get('url')
  $!recomm.get('imageUrl')
  $!recomm.get('price')
#end 

A prepared email containing velocity code has the following look:

The following message is the result of data substitution regarding three items from the order and three associated recommendations:

4. Use Case for SMS

Let’s assume we have a task to additionally inform a user via SMS that their order has been completed and shipped.

Then we prepare the following request body:

{
  "recipients": [
    {
      "jsonParam": "{\"firstName\":\"Serhei\",\"orderId\":\"JN134173389\",\"deliveryAddress\":\"Dnepr, NP office №32\"}",
      "locator": "380501234567"
    }
  ],
  "email": false,
  "fromName": "V-COMP"
}

where the recipient’s phone number is in the locator field, and alpha-name is in the fromName field.

Prepare the SMS:

The message has the following look after data substitution:

It is not always practical to show all the content of an array in an SMS using foreach cycle, instead, it is possible to address a specific element of an array using orderData. 

In this example, the velocity structure looks as follows: $!data.get('orderData').get(0).get('name'), where the addressed element is the first one in an array (enumeration begins with 0).

5. Use Case for Viber Messages

The process of configuration setting is similar to the one for SMS. Define the data to be displayed in the Viber message. In contrast to SMS, a Viber message allows up to 1,000 symbols. It can display images and buttons with embedded links.

In such a case, the request body looks as follows:

{
    "recipients": [
        {
            "jsonParam": "{

\"firstName\":\"Serhii\",\"orderId\":\"JN134-173-389\",
\"deliveryAddress\":\"Dnepr, NP office №32\",
\"url\":\"https:\/\/example.com\/offers.html\",
\"imageUrl\":\"https:\/\/example.com\/apple_iphone_xs.jpg\"
}",
            "locator": "380501234567"
        }
    ],
    "email": false
}

where you have to indicate the recipient’s phone number in the locator field and include a link to the image in the imageUrl variable and a link for the button in the url variable.

Generate a Viber message:

This is how the message looks with the substituted data:

6. Use Case for Mob Push Notifications

To send a prepared single mobile push notification, the body of a request has to look like this:

{
    "recipients": [
        {
            "jsonParam": null,
            "contactId": 449790707
        }
    ],
    "email": false
}

Instead of contactId, use the locator parameter to identify a contact and transmit a token inside it.

The option to parametrize the content by transmitting data in the jsonParam field is available for mobile push notifications, as well as for other channels:

The Custom data field can contain data in JSON format and be a source of extra information. A mobile application shall support such an option of data use.

The following content is the result of substitution, the design of the notification may differ depending on the OS version:

7. Use Case for Web Push Notifications

Same as for the request for mob push notifications, use the locator parameter instead of contactId to identify a contact and transmit the token inside it.

{
    "recipients": [
        {
            "jsonParam": null,
            "contactId": 449790707
        }
    ],
    "email": false
}

You can insert dynamic content into a Web push notification. To do that, insert variables in the message editor in place of the logo, large image, and links:

In this case, the body of the request looks like this:

{
    "recipients": [
        {
            "jsonParam": "{
\"userName\":\"Aleksei\",\"productName\":\"Huawei Watch GT Black\",
\"price\":\"6999 UAH\",\"https:\/\/example.com\/huawei-watch-gt\/431369.html\",
\"imageUrl\":\"https:\/\/example.com\/gallery\/huawei-watch-gt.jpeg\",
\"logo\":\"https:\/\/example.com\/Your-Logo.jpeg\",
\"moreOffer\":\"https:\/\/example.com\/more-offer.html\"
}",
            "contactId": 380470486
       }
    ],
    "email": false
}

This is how a user sees the notification as the result of the data substitution from the request:

8. Conclusions

The application area for the Smartsend resource is the delivery of triggered messages, such as a password recovery email, message related to the order, abandoned browse or abandoned cart, a notification about the price change of an item the user was interested in.