sailthru-node-client

For installation instructions, documentation, and examples please visit: http://getstarted.sailthru.com/new-for-developers-overview/api-client-library/node-js-npm

A simple client library to remotely access the Sailthru REST API as per http://getstarted.sailthru.com/new-for-developers-overview/api/api-overview/

By default, it will make request in JSON format. XML format is not supported.

Installation

npm install sailthru-client --save

Examples

Initialization

var apiKey = '******',
    apiSecret = '*****',
    sailthru = require('sailthru-client').createSailthruClient(apiKey, apiSecret);

Configuration

By adding an object as the third parameter one can initialize with options. For example:

var ProxyAgent = require('proxy-agent');

var proxyUrl = process.env.http_proxy || 'http://168.63.43.102:3128';

var sailthru = require('sailthru-client').createSailthruClient(apiKey, apiSecret, {
  agent: new ProxyAgent(proxyUrl),
  apiUrl: 'api.example.com',
});

| Option | Default | Description | | -------------- | -------------------- | -------------------- | | agent | null | HTTP agent to be used when, for example, the application runs behind a proxy. | | apiUrl | 'api.sailthru.com' | Host to which requests are made |

Getting version

var version = require('sailthru-client').VERSION;

Enable / Disable Logging

sailthru.enableLogging();
sailthru.disableLogging();

Making POST Request

var data = {
    email: '[email protected]',
    lists: {
        'list-a': 1
    }
};
sailthru.apiPost('email', data, function(err, response) {
    if (!err) {
        console.log(response);
    } else {
        console.log('Error!');
        console.log(err);
    }
});

Making POST Request with multipart (Eg: Job API call with import type)

// Making import /job API POST call
// MUltipart call
var data = {
    job: 'import',
    list: 'test-list',
    file: './emails.txt'
};
var multipart_params = ['file']; // this is required to mark file as a multipart upload item'
sailthru.apiPost('job', data, multipart_params, function(err, response) {
   console.log(response);
});

Making GET Request

// Making /send API GET call
var send_id = 'TE8EZ3-LmosnAgAA';
sailthru.apiGet('send', {send_id: send_id}, function(err, response) {
    console.log(response);
});

Making DELETE Request

// /send API DELETE call
var send_id = 'TE8EZ3-LmosnAgAA';
sailthru.apiDelete('send', {send_id: send_id}, function(err, response) {
    console.log(response);
});

send

//send
var template = 'my-template',
    email = '[email protected]',
    options = {
        'vars': {
            'name': 'Foo Bar',
            'address': 'Queens, NY'
        },
        'options': {
            'test': 1,
            'replyto': '[email protected]'
        }
    };
sailthru.send(template, email, options, function(err, response) {
    if (err) {
        console.log("Status Code: " + err.statusCode);
        console.log("Error Code: " + err.error);
        console.log("Error Message: " + err.errormsg);
    } else {
        //process output
    }
});

//multi-send
var emails = ['[email protected]', '[email protected]', '[email protected]'],
    template = 'multi-template',
    options = {
        'options': {
            'test': 1
        }
    };
sailthru.multiSend(template, emails, options, function(err, response) {
    if (err) {
        //Process error
    } else {
        //process JSON output
    }
});

Rate Limit Information

The library allows inspection of the 'X-Rate-Limit-*' headers returned by the Sailthru API. The getLastRateLimitInfo(action, method) function allows you to retrieve the last known rate limit information for the given action / method combination. It must follow an API call. For example, if you do a /send POST, you can follow up with a call to getLastRateLimitInfo('send', 'POST') as shown below:

// make API call as normal
sailthru.apiPost('send', {'template': 'my template', 'email': '[email protected]'}, function(err, response) {
    if (!err) {
        console.log(response);
    } else {
        console.log('Error!');
        console.log(err);
    }
});

// check rate limit information
var rateLimitInfo = sailthru.getLastRateLimitInfo('send', 'POST');

The return type will be undefined if there is no rate limit information for the given action / method combination (e.g. if you have not yet made a request to that endpoint). Otherwise, it will be an object in the following format:

{
    limit: 1234, // <Number representing the limit of requests/minute for this action / method combination>
    remaining: 1230, // <Number representing how many requests remain in the current minute>
    reset: 1459381680 // <Number representing the UNIX epoch timestamp of when the next minute starts, and when the rate limit resets>
}

Development

npm install -g grunt-cli
npm install # to install dependencies locally
grunt # for running tests