Client Libraries

The Bananatag's API libraries for Java, Node, PHP and Python allow you to be up and running and interacting with our REST API in minutes.

Libraries

Java Client Library

Download the library from the GitHub project site.


Configuration

Import the java.util.HashMap package and create your api object using your authentication credentials.

                            
import java.util.HashMap;
import java.util.concurrent.TimeUnit;
import org.json.simple.JSONObject;

BtagAPI btag = new BtagAPI("Your AuthID", "Your Access Key");
                            
                        
Making A Request

To make a request you must call the request method passing in the desired endpoint and a HashMap object containing all request parameters. The library will handle creating the authentication header provided both a valid authID and access key.

                            
// build parameters to map
HashMap<String, Object> params = new HashMap<String, Object>();
JSONObject result = new JSONObject();

params.put("rtn", "json");
params.put("start", "2015-01-01");
params.put("end", "2015-01-30");
params.put("isOpened", true);

do {
    result = btag.request("tags", params);
    System.out.println(result);
    TimeUnit.SECONDS.sleep(1);
} while (!result.isEmpty());
                            
                        
Full Example

In this example we will retrieve and list aggregated stats for all tags sent in January of 2015.

                            
import java.util.HashMap;
import java.util.concurrent.TimeUnit;
import org.json.simple.JSONObject;

public class Example {

    public static void main(String[] args) throws Exception {
        BtagAPI btag = new BtagAPI("Your AuthID", "Your Access Key");
        HashMap<String, Object> params = new HashMap<String, Object>();
        JSONObject result = new JSONObject();

        // build parameters to map
        params.put("rtn", "json");
        params.put("start", "2015-01-01");
        params.put("end", "2015-01-30");
        params.put("aggregateData", true);

        do {
            result = btag.request("stats", params);
            System.out.println(result);
            TimeUnit.SECONDS.sleep(1);
        } while (!result.isEmpty());
    }
}

                            
                        

Node Client Library

Download the library from the GitHub project site.


Installation
                            
$ npm install bananatag-api
                            
                        
Configuration

Require the ../lib/btag.js file and create your api object using your authentication credentials.

                            
var BtagAPI = require('bananatag-api.js');
var credentials = {
    authID: 'Your AuthID',
    key: 'Your Access Key'
};

var btag = new BTagAPI(credentials.authID, credentials.key);
                            
                        
Making A Request

To make a request you must call the request method passing in the desired endpoint and an object of request parameters. The library will handle creating the authentication header provided both a valid authID and access key.

                            
btag.request('tags', {start : '2015-01-01', end : '2015-02-01'}, function (err, data) {
    if (!err) {
        console.log(data);
    }
});
                            
                        
Full Example

In this example we will retrieve and list aggregated stats for all tags sent in January of 2015.

                            
var BtagAPI = require('bananatag-api.js');
var credentials = {
    authID: 'Your AuthID',
    key: 'Your Access Key'
};

var btag = new BTagAPI(credentials.authID, credentials.key);
var params = {
    start : '2015-01-01',
    end : '2015-02-01',
    aggregateData : true
};

// Results are returned paginated, automatically get all results by passing
// in an options parameter with getAllResults set to true.
btag.request('stats', params, {getAllResults: true},function (err, data) {
    if (err) {
        throw err;
    }

    console.log("Total Sent: " + data[0].totalSent);
    console.log("Total Opens: " + data[0].totalOpens);
    console.log("Total Clicks: " + data[0].totalClicks);
    console.log("Unique Opens: " + data[0].uniqueOpens);
    console.log("Unique Clicks: " + data[0].uniqueClicks);
    console.log("Date Last Sent: " + data[0].dateLastSent);
});
                            
                        

PHP Client Library

Download the library from the GitHub project site.


Installation
                            
composer require bananatag/bananatag-api-php
                            
                        
Configuration

Including the package (use Bananatag\Api) and create your api object using your authentication credentials.

                            
use Bananatag\Api;

// Create Api class instance
$btag = new Api('AuthID', 'Access Key');
                            
                        
Making A Request

Making a request is as easy as calling the request function passing in the desired endpoint and an array of request parameters. The library will handle creating the authentication header provided both a valid authID and access key.

                            
/* make request for all tags in date range */
$results = $btag->request("tags", ['start'=>'2015-01-01', 'end'=>'2015-02-01']);
                            
                        
Pagination

The result set is separated into pages, each with a max size of 250 records. Each time a request is made with the same parameters, the library will retrieve the next page of data until no more pages are remaining. In this example, we will recursively call getTags to retrieve the entire dataset.

                            
use Bananatag\Api;

$btag = new Api('AuthID', 'Access Key');

function getTags(&$btag) {
    $results = $btag->request("tags", []);

    echo $results['paging']['cursors']['next'];

    if ($results['paging']['cursors']['next'] < $results['paging']['cursors']['total']) {
        sleep(1);
        getTags($btag);
    }
}

getTags($btag);
                            
                        

Or you can manually choose a page.

                            
// Page 1
$results = $btag->request("tags", ['page'=>1]);
// Page 3
$results = $btag->request("tags", ['page'=>3]);
// Page 2
$results = $btag->request("tags", ['page'=>2]);
                            
                        
Full Example

In this example we will retrieve and list all data for all tags sent in January of 2015.

                            
use Bananatag\Api;

// Create Api class instance
$btag = new Api('AuthID', 'Access Key');

/* make request for tags in date range */
$results = $btag->request("tags", ['start'=>'2015-01-01', 'end'=>'2015-02-01', 'page'=>1]);

/* print list of tags */
echo "Total Tags: " . sizeOf($results) . '<br><hr><br>';
foreach ($results as $tag) {
    $recipients = [];
    foreach ($tag['recipients'] as $recipient) {
        $recipients[] = $recipient['name'] . " ({$recipient['email']})";
    }

    echo "Tag ID: " . $tag['id'];
    echo "<br>Subject: " . $tag['subject'];
    echo "<br>Recipients: " . implode(", ", $recipients);
    echo "<br>Total Opens: " . $tag['data']['totalOpens'];
    echo "<br>Unique Opens: " . $tag['data']['uniqueOpens'];
    echo "<br>Desktop Opens: " . $tag['data']['desktopOpens'];
    echo "<br>Mobile Opens: " . $tag['data']['mobileOpens'];
    echo "<br>Total Clicks: " . $tag['data']['totalClicks'];
    echo "<br>Unique Clicks: " . $tag['data']['uniqueClicks'];
    echo "<br>Desktop Clicks: " . $tag['data']['desktopClicks'];
    echo "<br>Mobile Clicks: " . $tag['data']['mobileClicks'];
    echo "<br>Date Sent: " . $tag['dateSent'];
    echo "<br><br><hr><br>";
}
                            
                        

Python Client Library

Download the library from the GitHub project site.


Installation
                            
pip install bananatag-api
                            
                        
Configuration

Import the lib.btapi file and create your api object using your authentication credentials.

                            
from lib.btapi import BTagAPI

btag = BTagAPI('Your AuthID', 'Your Access Key', False);
                            
                        
Making A Request

To make a request you must call the request method passing in the desired endpoint and an dictionary of request parameters. The library will handle creating the authentication header provided both a valid authID and access key.

                            
# make request for all tags in date range
data = btag.request('tags', {'start':'2015-01-01', 'end':'2015-01-30'})
                            
                        
Full Example

In this example we will retrieve all opens on emails in January of 2015.

                            
from lib.btapi import BTagAPI

btag = BTagAPI('Your AuthID', 'Your Access Key', False);

params = {'start':'2015-01-01', 'end':'2015-01-30'}

data = btag.request('opens', params)

print data;