Sign up for a SparkPost account and visit our Developer Hub for even more content.

Node.js SDK

The official Node.js binding for your favorite SparkPost APIs!

Prerequisites

Before using this library, you must have:

• A shiny new SparkPost Account, sign up for a new account or login to SparkPost
• A valid SparkPost API Key. Check out our Support Center for information on how to create API keys

Installation

npm install sparkpost

Initialization

new SparkPost(apiKey, options) - Initialization

• apiKey
  • Required: yes (unless key is stored in SPARKPOST_API_KEY environment variable)
  • Type: String
  • a passed in apiKey will take precedence over an environment variable
• options.origin or options.endpoint
  • Required: no
  • Type: String
  • Default: https://api.sparkpost.com:443
• options.apiVersion
  • Required: no
  • Type: String
  • Default: v1
• options.headers
  • Required: no
  • Type: Object
  • set headers that apply to all requests

Methods

• request(options, callback)
  • options - see request modules options
  • options.uri - can either be a full url or a path that is appended to options.origin used at initialization (url.resolve)
  • callback - executed after task is completed. required
    • standard callback(err, data)
    • err - any error that occurred
    • data.res - full response from request client
    • data.body - payload from response
• get | post | put | delete(options, callback)
  • options - see request options
  • callback - see request options
  • Request method will be overwritten and set to the same value as the name of these methods.

Creating a SparkPost Client

Passing in an API key

var SparkPost = require('sparkpost');
var client = new SparkPost('YOUR_API_KEY');

Using an API key stored in an environment variable

//Create an env var as SPARKPOST_API_KEY
var SparkPost = require('sparkpost');
var client = new SparkPost();

Specifying non-default options

var SparkPost = require('sparkpost');
var options = {
  endpoint: 'https://dev.sparkpost.com:443'
};
var client = new SparkPost('YOUR_API_KEY', options);

Using the Node SDK Base Object

We may not wrap every resource available in the SparkPost SDK, for example the Node SDK does not wrap the Metrics resource, but you can use the Node SDK Base Object to form requests to these unwrapped resources. Here is an example request using the base object to make requests to the Metrics resource. Here is an example request using the base object to make requests to the Metrics resource.

// Get a list of domains that the Metrics API contains data on.
var options = {
  uri: 'metrics/domains'
};

client.get(options, function(err, data) {
  if(err) {
    console.log(err);
    return;
  }

  console.log(data.body);
});

SparkPost API Resources Supported in Node SDK

Click on the desired API to see usage and more information

• Recipient Lists - client.recipientLists (examples)
• Sending Domains - client.sendingDomains (examples)
• Suppression List - client.suppressionList (examples)
• Templates - client.templates (examples)
• Transmissions - client.transmissions (examples)
• Webhooks - client.webhooks (examples)

Development

Setup

We use Grunt for our task runner, so you will also have to install Grunt globally npm install -g grunt-cli

Run npm install inside the repository to install all the dev dependencies.

Testing

Once all the dependencies are installed, you can execute the unit tests using grunt test

Contributing

Guidelines for adding issues

Our coding standards

Submitting pull requests

ChangeLog

See ChangeLog here