LianaMailer REST API documentation

Open source REST client can be found at github.

Most code examples use client for constructing the message including headers and authenticating.

Request rate

Max request rate is four per second. Exceeding this can result in 429 Too Many Requests -error.

Reserved property names

When creating or importing new data to LianaMailer, following names cannot be used for properties since they are reserved for system:

• admin
• archive
• delivery_id
• email
• id
• ip
• list_id
• list_name
• mail_id
• origin
• reason
• recipient_email
• recipient_sms
• scheduled
• sms
• subject
• tracking_id
• url
• useragent

Using these as property names will result in error or import failing.

Headers

Headers to include in request (case sensitive):

• Content-Type: application/json
• Content-MD5: md5-hash of json encoded content array (with GET method, this is made of empty string)
• Date: current timestamp i.e. '2020-01-20T12:30:10+03:00'
• Authorization: explained below

Authorization header

All requests must include HTTP Authorization header with correct signature. Authentication header is named Authorization and it should be structured as:

(API_REALM) (USER_ID):(HMAC-SIGNATURE)

Signing

HMAC-signature is generated with SHA256 algorithm using API secret as key with following strings in this specific order separated by newline (\n) in between, as data:

• API-method i.e. GET
• MD5-hash of content, as described above
• content-type as: application/json
• timestamp i.e. 2020-01-20T12:30:10+03:00
• json encoded content or empty string if sending GET request
• path to endpoint with possible URL parameters included i.e. /api/v3/events?type=mailopen&at_start=2020-01-10T12:00:00&at_end=2020-01-10T15:00:00

V1 Example

Example for sending "hello" to echoMessage API V1 endpoint.

Data being signed: POST\n1f0bf5038e61951a95c4a2a9db7c400a\napplication/json\n2020-01-15T12:00:00+03:00\n["hello"]\n/api/v1/echoMessage

Example signature generated using secret key 0123456789abcdef0123456789abcdef:
89b60df150aad61e42fef7d6a43883c83e642aef2f7f2338b971c681f9992c26

Example Authorization header for user ID 123 and realm EUR:
EUR 123:89b60df150aad61e42fef7d6a43883c83e642aef2f7f2338b971c681f9992c26

PHP code example on sending getRecipients request.

PHP code example on sending updateRecipient request using Liana rest-client.

V3 Example

Example for sending request to events API V3 endpoint.

Data being signed: GET\nd41d8cd98f00b204e9800998ecf8427e\napplication/json\n2020-01-15T12:00:00+03:00\n\n/api/v3/events?type=mailopen&at_start=2020-01-10T12:00:00&at_end=2020-01-10T15:00:00

Example signature generated using secret key 0123456789abcdef0123456789abcdef:
22404d156bd828b157c3e6e11f5b83943b00bc7b0029eceab304dae227ef7f03

Example Authorization header for user ID 123 and realm EUR:
EUR 123:22404d156bd828b157c3e6e11f5b83943b00bc7b0029eceab304dae227ef7f03

While making requests to different API versions it should be kept in mind that parameters work a bit differently in different versions.

V1

All root level parameters should be given in exact same order as they are mentioned in documentation. These parameters are identified by the order they are given in, rather than keys. Parameters themselves can contain tables with keys required. See PHP example. Optional parameters can be set null if not needed.

V2

Parameters are identified by keys so they are to be given as associative arrays.

V3

Since these are all GET requests, all parameters are given in url so content is left empty.

This is a collection of some common use cases and examples on how to complete them using LianaMailer REST API.

Send newsletter to imported list

In this case we have a list of contacts to which we want to send a newsletter.

1. Import contacts to Mailer

First we are going to create a new mailinglist and upload contacts with emails and some property values into it.

Endpoints used here:

• createMailingList
• importCSVToMailingList
• getImportStatus

<?php
/**
 * Mailing list import example
 *
 * This example uploads given recipients to LianaMailer™ and waits for the import to finish.
 *
 * Copyright: Liana Technologies Oy 2023
 *
 * Requirements:
 *      - This project/file needs to be UTF-8 formatted
 */

// Enter your API credentials below
$user_id = <id>;
$secret_key = <secret_key>;
$url = <api url>;
$realm = <realm>;

// Details for new list
$list_name = <string>;
$list_description = <string>;

// A ready made PHP client which handles the API communication
// @see https://github.com/LianaTech/rest-client
require_once 'rest-client/php/RestClient.php';

// We will be using v1 API
$apiv1 = new \LianaTech\RestClient($user_id, $secret_key, $url, 1, $realm);

// Create a mailinglist. Note that this will create a new one on every call!
// We use only first 2 parameters of endpoint.
$ret = $apiv1->call('createMailingList', array($list_name, $list_description));

if (empty($ret['succeed']) || empty($ret['result'])) {
    die('unexpected response for createMailingList: ' . json_encode($ret));
}

$mailinglist_id = $ret['result'];

// Lets form the recipient list and their properties
$recipients_csv =<<<EOF
"email";"firstname";"lastname"
"recipient+1@example.com";"John1";"Doe1"
"recipient+2@example.com";"John2";"Doe2"
"recipient+3@example.com";"John3";"Doe3"
"recipient+4@example.com";"John4";"Doe4"
"recipient+5@example.com";"John5";"Doe5"
"recipient+6@example.com";"John6";"Doe6"
"recipient+7@example.com";"John7";"Doe7"
"recipient+8@example.com";"John8";"Doe8"
"recipient+9@example.com";"John9";"Doe9"
"recipient+10@example.com";"John10";"Doe10"
EOF;

// Upload that CSV into the mailinglist
$ret = $apiv1->call('importCSVToMailingList', array(
    $mailinglist_id,
    null, // a deprecated param
    base64_encode($recipients_csv),
    null, // deprecated param, set to null
    true, // base64 encoded data
    true, // truncate the mailinglist first
));

if (empty($ret['succeed'])) {
    die('unexpected response for importCSVToMailingList: ' . json_encode($ret));
}

// Wait for the list import to finish
$start = time();
$import_success = false;
$wait = 600; // seconds, increase if you are using huge lists

while (time() < $start + $wait) {
    sleep(1);
    $ret = $apiv1->call('getImportStatus', array($mailinglist_id));

    if (isset($ret['result']) && $ret['result'] === -1) {
        $import_success = true;
        break; // import finished
    }
}

if (! $import_success) {
    die('mailinglist import never finished. last output: ' . json_encode($ret));
}

echo "All done!\n";

2. Send newsletter to list

Next we are going to send a newsletter built in LianaMailer UI, to a list uploaded earlier using batch-send endpoint.

<?php

/**
 * Sending newsletter using batch-send
 *
 * This example setups a newsletter for sending via REST API
 *
 * Copyright: Liana Technologies Oy 2023
 *
 * Requirements:
 *      - This project/file needs to be UTF-8 formatted
 *      - Draft used in this example is created beforehand in LianaMailer UI
 */

// Enter your API credentials below
$user_id = <id>;
$secret_key = <secret_key>;
$url = <api url>;
$realm = <realm>;

// A ready made PHP client which handles the API communication
// @see https://github.com/LianaTech/rest-client
require_once 'rest-client/php/RestClient.php';

// We will be using v2 API
$apiv2 = new \LianaTech\RestClient($user_id, $secret_key, $url, 2, $realm);

// Array of target list ids. Like one uploaded in previous example can also be used.
$lists = array(12345);

// We need to define letter to be used. Type should be 'draft' and id should refer to draft created in LianaMailer UI.
$letter = array(
  'type' => 'draft',
  'id' => 95
);

$params = array(
  'letter' => $letter,
  'lists' => $lists
);

$ret = $apiv2->call(
  'deliveries/batch-send',
  $params,
  'POST'
);

if (empty($ret['succeed']) || empty($ret['result'])) {
    die('unexpected response for deliveries/batch-send: ' . json_encode($ret));
}

Notice that you can also give recipients with necessary properties manually by inserting them into recipients array. This can be used with or without lists param:

$recipients = array(
  array(
    'email' => 'recipient1@example.com',
    'firstname' => 'John'
  ),
  array(
    'email' => 'recipient2@example.com',
    'firstname' => 'Jane'
  )
);
$params = array(
  'letter' => $letter,
  'lists' => $lists,
  'recipients' => $recipients
);

It is also possible to modify content of message by using optional fields in letter as explained in event-send example.

Fetch events

In this example we fetch tracking events from v3/events endpoint.

Parameters used here are:

• event type is mailopen
• fetch only events dated between 2020-01-30T12:00:00 and 2020-01-31T12:00:00
• fetch results in pages of 100 events
• results are sorted by event time in descending order

<?php

/**
 * Event fetch example
 *
 * This example gets events from v3/events endpoint with specific conditions.
 *
 * Copyright: Liana Technologies Oy 2023
 *
 * Requirements:
 *      - This project/file needs to be UTF-8 formatted
 */

// Enter your API credentials below
$user_id = <id>;
$secret_key = <secret_key>;
$url = <api url>;
$realm = <realm>;

// A ready made PHP client which handles the API communication
// @see https://github.com/LianaTech/rest-client
require_once 'rest-client/php/RestClient.php';

// We will be using v3 API
$apiv3 = new \LianaTech\RestClient($user_id, $secret_key, $url, 3, $realm);

// Define paginating values
$page_size = 100; // Results per page
$offset = 0;
$page_num = 0;

// Array to gather all results into
$results_array = array();

// Iterate thru results using pagination
do {
  // Additional delay to ensure we are not sending requests too frequently.
  sleep(1);

  $offset = $page_size * $page_num;
  $page_num++;

  // It is recommended to give params to limit the amount of data to be fetched at once.
  $params = array(
    'type' => 'mailopen', // Event type we are looking for
    'at_start' => '2020-01-30T12:00:00', // Find events after x
    'at_end' => '2020-01-31T12:00:00', // Find events before x
    'limit' => $page_size, // Amount of results we want to fetch at time
    'offset' => $offset, // Skip amount of results
    'sort' => '-at' // Sorting by time, descending
  );

  $ret = $apiv3->call(
    'events?' . http_build_query($params),
    array(),
    'GET'
  );

  $results_array = array_merge($results_array, $ret['items']);

} while (count($ret['items']) == $page_size);

Sending transactional mail

Sending a transactional, or other more recipient specific mail can be done using v3/event-send endpoint.

  <?php

  /**
   * Sending event mail using event-send
   *
   * This example builds a transactional message for sending via REST API
   *
   * Copyright: Liana Technologies Oy 2023
   *
   * Requirements:
   *      - This project/file needs to be UTF-8 formatted
   *      - Draft used in this example is created beforehand in LianaMailer UI
   */

  // Enter your API credentials below
  $user_id = <id>;
  $secret_key = <secret_key>;
  $url = <api url>;
  $realm = <realm>;

  // A ready made PHP client which handles the API communication
  // @see https://github.com/LianaTech/rest-client
  require_once 'rest-client/php/RestClient.php';

  // We will be using v2 API
  $apiv2 = new \LianaTech\RestClient($user_id, $secret_key, $url, 2, $realm);

  // Define recipient(s) and their properties
  $recipients = array(
    array(
      'email' => 'recipient@mail.com',
      'firstname' => 'John',
      'lastname' => 'Doe',
      'order_num' => 1234
    )
  );

  // We need to define letter to be used. Type should be 'draft' and id should refer to draft created in LianaMailer UI.
  $letter = array(
    'type' => 'draft',
    'id' => 95,
    'recipients_reset' => true, // Set this to true if it should be possible for same recipient to receive this message multiple times
  );

  $params = array(
    'letter' => $letter,
    'recipients' => $recipients
  );

  $ret = $apiv2->call(
    'deliveries/event-send',
    $params,
    'POST'
  );

  if (empty($ret['succeed']) || empty($ret['result'])) {
    die('unexpected response for deliveries/event-send: ' . json_encode($ret));
  }

Notice that in this case we use a ready made draft containing all the content and placeholders for properties (i.e. $order_num$ etc.).

Overwriting message content of base draft

We might also want to overwrite entire content of draft being used. In that case draft used should be made of source template.

  $letter = array(
    'type' => 'draft',
    'id' => 95,
    'recipients_reset' => true,
    'subject' => 'Order received',
    'html' => '<p>Thank you for your order $firstname$ $lastname$. Order number $order_num$ has been received.</p>'
  );

Personalized HTML blocks

We might also want to use more recipient specific HTML blocks in our message. This can be done using raw type properties. Such property must be created using createCustomerProperty endpoint.

Notice that this only has to be done one time only. After that the property can be used in all future deliveries.

  $params = array(
    'ordered_items_html', // wanted name for the new property
    'FI', // property language, use `FI`
    'raw' // property type, raw allows HTML content
  );
  $apiv1->call('createCustomerProperty', $params, 'POST');

Now that we have a property which can contain custom HTML we can use it in message. NOHTMLENCODE: prefix is required for HTML content to work.

  $recipients = array(
    array(
      'email' => 'recipient@mail.com',
      'firstname' => 'John',
      'lastname' => 'Doe',
      'order_num' => 1234,
      'ordered_items_html' => 'NOHTMLENCODE:
        <table border=1>
          <tr>
            <td>ordered item</td>
            <td>amount</td>
          </tr>
          <tr>
            <td>Foo bar</td>
            <td>2</td>
          </tr>
        </table>'
    )
  );

  $letter = array(
    'type' => 'draft',
    'id' => 95,
    'recipients_reset' => true,
    'subject' => 'Order received',
    'html' => '<p>Thank you for your order $firstname$ $lastname$. Order number $order_num$ has been received:</p> $ordered_items_html$',
  );