A Node.js client library for the Sailthru REST API.

Installation

npm install sailthru-client --save

Initialization

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

Standard Callback Function

Every function within the Node.js client library will execute asynchronously. Therefore, in order to receive and handle the response, you must provide a callback function. All of the client library functions have a parameter for the callback function, which by convention will be the last parameter. The callback function will receive two arguments: an error object, and a response object. The error object will be undefined if the API call was successful. The response object will include a Javascript object with the response from the API server.

Example:

sailthru.getUserByKey(test@example.com', 'email', function(err, response) {
    if (err) {
        // handle error
        return;
    }
    // handle response
});

Send API Helper Functions

send(template, email, options, callback) function

Send a single message to email, using the given template.

Parameters:

• template (required): Name of the template to use as the basis for the message content
• email (required): valid email address to send the message to
• options (optional): a Javascript object that can be used to specify any other valid API parameters for the send POST, the full list is available here
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: send POST

Examples:

send “Abandoned Cart Reminder” template to “example@example.com“

sailthru.send('Abandoned Cart Reminder', 'example@example.com', function(err, response) {
        // handle response
});

send “Welcome” template to “example@example.com“, using custom send vars, for a time in the future

var options = {vars: {color: 'blue'}, schedule_time: 'tomorrow 5pm'};
sailthru.send('Welcome', 'example@example.com', options, function(err, response) {
    // handle response
});

multiSend(template, emails, options, callback) function

Send a message to each of the “emails” specified, using the given “template”.

Parameters:

• template (required): Name of the template to use as the basis for the message content
• emails (required): valid email addresses to send the message to. This can be either a comma-separated String, or a Javascript Array.
• options (optional): a Javascript object that can be used to specify any other valid API parameters for the send POST, the full list is available here
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: send POST

Examples:

send “Abandoned Cart Reminder” template to “example1@example.com” and “example2@example.com**” (using delimited “emails” parameter)
**

sailthru.multiSend('Abandoned Cart Reminder', 'example1@example.com,example2@example.com', function(err, response) {
    // handle response
});

send “Welcome” template to “example1@example.com” and “example2@example.com” (using Array “emails” parameter) and evars

var emails= ['example1@example.com','example2@example.com'];
var options = { evars: {
    'example1@example.com': {color: 'blue'},
    'example2@example.com': {color: 'red'}
}};
sailthru.multiSend('Welcome', emails, options, function(err, response) {
    // handle response
});

getSend(send_id, callback) function

Looks up the delivery status of a particular send, by its “send_id”.

Parameters:

• send_id (required): the send ID which was in the response of a previous send call

Underlying Endpoint: send GET

Examples:

Look up a send by send_id

sailthru.getSend('V-WWJIO6iCcAi0Vo', function(e,r) {
    // handle response
});

cancelSend(send_id, callback) function

Cancels the scheduled send which is identified by “send_id”. Note that you can only cancel sends which were scheduled in the future with the “schedule_time” parameters.

Parameters:

• send_id (required): the send ID which was in the response of a previous send call

Underlying Endpoint: send DELETE

Examples:

Cancel a send by send_id

sailthru.cancelSend('V-WWJIO6iCcAi0Vo', function(e,r) {
    // handle response
});

Blast API Helper Functions

getBlast(blast_id, callback) function

Looks up the details about a particular campaign, using blast ID.

Parameters:

• blast_id (required): the blast ID which was in the response of a previous blast call
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: blast GET

Examples:

Look up a blast by blast_id

sailthru.getBlast(123, function(e,r) {
    // handle response
});

scheduleBlast(name, list, scheduleTime, fromName, fromEmail, subject, contentHtml, contentText, options, callback) function

Schedule a new campaign.

Parameters:

• name (required): the name for the campaign, which will be used to identify it in Campaign Reporting
• list (required): the target list for the campaign
• scheduleTime (required): when the campaign should be sent
• fromName (required): the from name for the email campaign
• fromEmail (required): the from email for the email campaign
• subject (required): the email subject line for the campaign
• contentHtml (required): the content of the email body, for the HTML version of the campaign
• contentText (required): the content of the email body, for the Text version of the campaign
• options (optional): provide additional blast API options, as outlined in the blast POST documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: blast POST

Examples:

Schedule a campaign without using the optional options object

var name = 'my campaign';
var list = 'clicked';
var scheduleTime = '+2 hours';
var fromName = 'Example User';
var fromEmail = example@example.com';
var subject = 'my test send';
var contentHtml = '<p>This is a test</p>{beacon}';
var contentText = 'this is a test';
sailthru.scheduleBlast(name, list, scheduleTime, fromName, fromEmail, subject, contentHtml, contentText, function(err, response) {
    // Handle response
});

Schedule a campaign using the options object

var name = 'my campaign';
var list = 'clicked';
var scheduleTime = '+2 hours';
var fromName = 'Example User';
var fromEmail = example@example.com';
var subject = 'my test send';
var contentHtml = '<p>This is a test</p>{beacon}';
var contentText = 'this is a test';
var options = {
    suppress_list: ['100users', 'domain']
}
sailthru.scheduleBlast(name, list, scheduleTime, fromName, fromEmail, subject, contentHtml, contentText, options, function(err, response) {
    // Handle response
});

scheduleBlastFromBlast(blastId, scheduleTime, options, callback) function

Schedule an existing campaign which was previously in draft status, or change the schedule time of a scheduled campaign.

Parameters:

• blast_id (required): the blast ID which was in the response of a previous blast call
• scheduleTime (required): when the campaign should be sent
• options (optional): provide additional blast API options, as outlined in the blast POST documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: blast POST

Examples:

Schedule an existing campaign to send now

sailthru.scheduleBlastFromBlast(123, 'now', function(err, response) {
    // Handle response
});

Schedule a campaign to send now while also setting the suppress_list using options object

var options = {
    suppress_list: ['100users', 'domain']
}
sailthru.scheduleBlastFromBlast(123, 'now', options, function(err, response) {
    // Handle response
});

scheduleBlastFromTemplate(blastId, template, list, scheduleTime, options, callback) function

Modify an existing campaign by copying data into it from a Template, and then scheduling it.

Parameters:

• blast_id (required): the blast ID which was in the response of a previous blast call
• template (required): the name of a template to copy from, as the basis for this campaign
• list (required): the target list for the campaign
• scheduleTime (required): when the campaign should be sent
• options (optional): provide additional blast API options, as outlined in the blast POST documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: blast POST

Examples:

Modify a campaign with data copied from “Welcome” template and send in 2 hours

var list = 'clicked';
sailthru.scheduleBlastFromTemplate(123, 'Welcome', list, '+2 hours', function(err, response) {
    // Handle response
});

Modify a campaign with data copied from “Welcome” template and send in 2 hours, while also setting a report email

var list = 'clicked';
var options = {
    report_email: 'example@example.com'
}
sailthru.scheduleBlastFromTemplate(123, 'Welcome', list, '+2 hours', options, function(err, response) {
    // Handle response
});

updateBlast(blastId, options, callback) function

Modify an existing campaign by setting any field.

Parameters:

• blast_id (required): the blast ID which was in the response of a previous blast call
• options (required): provide additional blast API options, as outlined in the blast POST documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: blast POST

Examples:

Enable link tracking on a campaign

var options = {
    is_link_tracking: 1
}
sailthru.updateBlast(123, options, function(err, response) {
    // Handle response
});

unscheduleBlast(blast_id, callback) function

Unschedule a previously scheduled campaign, by blast ID.

Parameters:

• blast_id (required): the blast ID which was in the response of a previous blast call
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: blast POST

Examples:

Unschedule a previously scheduled blast by blast_id

sailthru.unscheduleBlast(123, function(e,r) {
    // handle response
});

deleteBlast(blast_id, callback) function

Delete a previously created campaign, by blast ID. This cannot be undone.

Parameters:

• blast_id (required): the blast ID which was in the response of a previous blast call
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: blast DELETE

Examples:

Delete a previously created blast by blast_id

sailthru.deleteBlast(123, function(e,r) {
    // handle response
});

pauseBlast(blast_id, callback) function

Pause a currently sending created campaign, by blast ID.

Parameters:

• blast_id (required): the blast ID which was in the response of a previous blast call
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: blast POST

Examples:

Pause a currently sending campaign by blast_id

sailthru.pauseBlast(123, function(e,r) {
    // handle response
});

resumeBlast(blast_id, callback) function

Resume a previously paused campaign, by blast ID.

Parameters:

• blast_id (required): the blast ID which was in the response of a previous blast call
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: blast POST

Examples:

Resume a previously paused campaign by blast_id

sailthru.resumeBlast(123, function(e,r) {
    // handle response
});

cancelBlast(blast_id, callback) function

Cancel a campaign which is currently sending, by blast ID. This cannot be undone.

Parameters:

• blast_id (required): the blast ID which was in the response of a previous blast call
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: blast POST

Examples:

Cancel a sending blast by blast_id

sailthru.cancelBlast(123, function(e,r) {
    // handle response
});

Templates API Helper Functions

getTemplates(callback) function

Return a list of all the templates in your account.

Parameters:

• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: template GET

Examples:

Return all templates in your account

sailthru.getTemplates(function(e,r) {
    // handle response
});

getTemplate(template, callback) function

Return details about a named template in your account.

Parameters:

• template (required): the name of the template to fetch
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: template GET

Examples:

Return information about the “Welcome” template in your account

sailthru.getTemplate('Welcome', function(e,r) {
    // handle response
});

getTemplateFromRevision(revision_id, callback) function

Return details about a template in your account, using revision_id to look it up

Parameters:

• revision_id (required): the revision_id of the template to fetch
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: template GET

Examples:

Return information about the 1234 template revision in your account

sailthru.getTemplateFromRevision(1234, function(e,r) {
    // handle response
});

saveTemplate(template, options, callback) function

Create or update a template with the given name

Parameters:

• template (required): the name of the template
• options (required): any template API options, as outlined in the template POST documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: template POST

Examples:

Create a new template with a welcome message

var options = {
    content_html: '<p>Welcome</p>{beacon}',
    subject: 'Welcome'
};
sailthru.saveTemplate('New Template', options, function(err, response) {
    // handle response
});

saveTemplateFromRevision(template, revision_id, callback) function

Revert a template to one of its previous revisions.

Parameters:

• template (required): the name of the template
• revision_id (required): a revision_id of the template
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: template POST

Examples:

Revert the “Welcome” template to a revision with id 1234

sailthru.saveTemplateFromRevision('Welcome', 1234, function(e,r) {
    // handle response
});

deleteTemplate(template, callback) function

Delete a template from your account. This cannot be undone.

Parameters:

• template (required): the name of the template
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: template DELETE

Examples:

Delete a template called “test template”

sailthru.deleteTemplate('test template', function(e,r) {
    // handle response
});

List API Helper Functions

getLists(callback) function

Return a list of all the lists in your account.

Parameters:

• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: list GET

Examples:

Return all lists in your account

sailthru.getLists(function(e,r) {
    // handle response
});

deleteList(list, callback) function

Delete a list from your account, and remove all record of it from your user profiles. This cannot be undone.

Parameters:

• list (required): the name of an existing list in your account
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: list DELETE

Examples:

Delete a list called “test list”

sailthru.deleteList('test list', function(e,r) {
    // handle response
});

Content API Helper Function

pushContent(title, url, options, callback) function

Create a new content item.

Parameters:

• title (required): the name of the content item being created
• url (required): the URL of the content item, which will be used as its unique identifier
• options (optional): provide additional content API options, as outlined in the content POST documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: content POST

Examples:

Create a new content item

var title = 'my new content';
var url = 'http://test.com/my-new-content';
sailthru.pushContent(title, url, function(err, response) {
    // handle response
});

Create a new content item with certain tags

var title = 'my new content';
var url = 'http://test.com/my-new-content';
var options = {
    tags: ['new', 'exciting', 'shoes']
}
sailthru.pushContent(title, url, options, function(err, response) {
    // handle response
});

Purchase API Helper Function

purchase(email, items, options, callback) function

Record a purchase into the Sailthru system.

Parameters:

• email (required): the email of the user who made the purchase
• items (required): a description of what items the user purchased. See the examples on the main Purchase API page
• options (optional): provide additional purchase API options, as outlined in the purchase POST documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: purchase POST

Examples:

Register a purchase for a single product, without any extra options

var items = [
    {
        "qty": 1,
        "title": "product1",
        "url": "https://www.example.com/product1",
        "price": 10000,
        "id": "id1"
    }
];
sailthru.purchase('example@example.com', items, function (err, response) {
    // handle response
});

Register a purchase for two products, including a coupon code var

var items = [
    {
        "qty": 2,
        "title": "Water Bottle",
        "price": 1099,
        "id": 1234,
        "url": "https://example.com/1234/water_bottle"
    },
    {
        "qty": 1,
        "title": "product1",
        "url": "https://www.example.com/product1",
        "price": 10000,
        "id": "id1"
    }
];
var options = {
    vars: { coupon_code: 'xyz' }
};
sailthru.purchase('example@example.com', items, options, function (err, response) {
    // handle response
});

Stats API Helper Functions

stats(data, callback) function

Fetch stats for any part of Sailthru.

Parameters:

• data (required): provide stats API options, as outlined in the stats GET documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: stats GET

Examples:

Get stats for the performance of the “Welcome” template over a certain month

var data = {
    stat: 'send',
    template: 'Welcome',
    start_date: '2016-10-01',
    end_date: '2016-10-31'
};
sailthru.stats(data, function(err, response) {
    console.log(response);
});

statsList(options, callback) function

Fetch stats for a List within Sailthru.

Parameters:

• options (required): provide stats API options, as outlined in the stats GET documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: stats GET

Examples:

Get stats for the performance of the “clicked” list on a certain day

var options = {date: '2016-04-15', list: 'clicked'};
sailthru.statsList(options, function(err, response) {
    // handle response
});

statsBlast(options, callback) function

Fetch stats for a campaign send, or aggregate campaign data over a time period.

Parameters:

• options (required): provide stats API options, as outlined in the stats GET documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: stats GET

Examples:

Get stats for the engagement level performance of campaigns over a certain month

var options = {start_date: '-3 months', end_date: 'today', engagement: 1};
sailthru.statsBlast(options, function(err, response) {
    // handle response
});

Get subject line performance for a particular campaign

var options = {blast_id: 225, subject: 1};
sailthru.statsBlast(options, function(err, response) {
    console.log(err);
    console.log(response);
});

Job API Helper Functions

getJobStatus(job_id, callback) function

Fetch the status of a job.

Parameters:

• job_id (required): the job ID which was returned from a previous job POST
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: job GET

Examples:

Get status of a particular job

sailthru.getJobStatus('575b100f83ba8830008b4568', function(err, response) {
    // handle response
});

processJob(job, options, report_email, postback_url, binary_data_params, callback) function

Create a new job with specific options.

Parameters:

• job (required): the name of the job to create
• options (optional): provide additional job API options, as outlined in the job POST documentation
• report_email (optional): the email address that will be emailed when the job completes or fails
• postback_url (optional): the URL which will receive postback data when the job completes or fails
• binary_data_params (optional): used to specify file upload details. Should be an array which includes strings, corresponding to fields in the “options” parameter that should be read in as files.
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: job POST

Examples:

Export the list “VIP Users” to a CSV file

var options = { list: 'VIP Users' };
sailthru.processJob('export_list_data', options, function(err, response) {
    // handle response
});

Import a CSV file into a new list called “New List”

var options = { list: 'New List', file: '/path/to/new_users.csv' };
var report_email = 'report@example.com';
var postback_url = 'http://example.com/postback.php';
var binary_data_params = ['file'];
sailthru.processJob('import', options, report_email, postback_url, binary_data_params, function(err, response) {
    // handle response
});

User API Helper Functions

getUserBySid(sid, callback) function

Return a user profile by looking up via a Sailthru ID (sid).

Parameters:

• sid (required): the sailthru id for a given user
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: user GET

Examples:

Return the user profile for a given user

sailthru.getUserBySid('57e54ddc83ba8895008b4567', function(e,r) {
    // handle response
});

getUserByKey(id, key, fields, callback) function

Return a user profile by looking up via a given key and ID.

Parameters:

• id (required): the id for a given user
• key (required): specify which type of key was provided in the “id” parameter
• fields (options): specify which fields to return. Options are documented here
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: user GET

Examples:

Return the user profile for a given email address

sailthru.getUserByKey('example@example.com', 'email', function(e,r) {
    // handle response
});

Return the lists that a user is on

var fields = {lists: 1};
sailthru.getUserByKey('example@example.com', 'email', fields, function(err, response) {
    // handle response
});

saveUserBySid(sid, options, callback) function

Update a user profile.

Parameters:

• sid (required): the sailthru id for a given user
• options (required): provide user API options, as outlined in the user POST documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: user POST

Examples:

Add a var to a user profile

var data = {vars: {def: 123}};
sailthru.saveUserBySid('57e54ddc83ba8895008b4567', data, function(err, response) {
    // handle response
});

saveUserByKey(id, key, options, callback) function

Update a user profile.

Parameters:

• id (required): the id for a given user
• key (required): specify which type of key was provided in the “id” parameter
• options (required): provide user API options, as outlined in the user POST documentation
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: user POST

Examples:

Add a var to a user profile

var data = {vars: {abc: 456}};
sailthru.saveUserByKey('example@example.com', 'email', data, function(err, response) {
    // handle response
});

Low Level Functions

Sometimes the helper functions do not give the options you need. In this case, you can always specify a raw API GET, POST, or DELETE call using these low level functions.

apiGet(action, data, callback) function

Perform an arbitrary API GET request to Sailthru.

Parameters:

• action (required): the API endpoint to send a request to
• data (required): provide the API options, as outlined in the GET section of the documentation for that endpoint
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: any GET

Examples:

Fetch details about a purchase, using a purchase_id

sailthru.apiGet('purchase', {
    purchase_id: '5520b3b39759105e4aa4e69f',
    purchase_key: 'sid'
}, function(err, response) {
    // handle response
});

apiPost(action, data, callback) function

Perform an arbitrary API POST request to Sailthru.

Parameters:

• action (required): the API endpoint to send a request to
• data (required): provide the API options, as outlined in the POST section of the documentation for that endpoint
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: any POST

Examples:

Copy a blast, saving under a new name

sailthru.apiPost('blast', {
    copy_blast: 123,
    name: 'my copy'
}, function(err, response) {
    // handle response
});

apiDelete(action, data, callback) function

Perform an arbitrary API DELETE request to Sailthru.

Parameters:

• action (required): the API endpoint to send a request to
• data (required): provide the API options, as outlined in the DELETE section of the documentation for that endpoint
• callback (required): a standard callback function which will be invoked after the API server responds

Underlying Endpoint: any DELETE

Examples:

Delete a feed by its id

var data = {
    "id": "559a8fc63c8aa934460f227d"
};
sailthru.apiDelete('feed', data, function(err, response) {
    // handle response
});

Library Utility Functions

Get Version

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

Enable / Disable Logging

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

When you’re logging to a specific file, the script must include the [file] parameter after the options object. This is required by the node library to process file uploads.

sailthru.apiPost(endpoint, data, ['file'], callback)

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': 'foo@example.com'}, 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>
}