Sign up for a SparkPost account and visit our Developer Hub for even more content.
The official Node.js binding for your favorite SparkPost APIs!
Before using this library, you must have:
npm install sparkpost
Note: Node.js versions 0.10 and 0.12 are no longer supported.
new SparkPost(apiKey[, options]) - Initialization
apiKey
SPARKPOST_API_KEY
environment variable)String
options.origin
or options.endpoint
String
https://api.sparkpost.com:443
https://api.eu.sparkpost.com:443
.options.apiVersion
String
v1
options.stackIdentity
String
product/1.0.0
options.headers
Object
options.debug
Boolean
false
debug
when true
for debugging purposesNote: All methods return promises and accept an optional last argument callback. Read about how we handle callbacks and promises.
options
- see request modules optionsoptions.uri
- can either be a full url or a path that is appended to options.origin
used at initialization (url.resolve)options.debug
- setting to true
includes full response from request client for debugging purposesoptions
- see request optionsPassing in an API key
const SparkPost = require('sparkpost');
const client = new SparkPost('YOUR_API_KEY');
Using an API key stored in an environment variable
//Create an env var as SPARKPOST_API_KEY
const SparkPost = require('sparkpost');
const client = new SparkPost();
Specifying non-default options
const SparkPost = require('sparkpost');
const options = {
endpoint: 'https://dev.sparkpost.com:443'
};
const client = new SparkPost('YOUR_API_KEY', options);
We may not wrap every resource available in the SparkPost Client Library, for example the Node Client Library does not wrap the Metrics resource, but you can use the Node Client Library 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.
const options = {
uri: 'metrics/domains'
};
client.get(options)
.then(data => {
console.log(data);
})
.catch(err => {
console.log(err);
});
Below is an example of how to send a simple email. Sending an email is known as a transmission. By using the send method on the transmissions service that's available from the SparkPost object you instantiate, you can pass in an object with all the transmission attributes relevant to the email being sent. The send method will return a promise that will let you know if the email was sent successful and if not information about the error that occurred. If a callback is passed, it will be executed.
const SparkPost = require('sparkpost');
const client = new SparkPost('<YOUR API KEY>');
// If you have a SparkPost EU account you will need to pass a different `origin` via the options parameter:
// const euClient = new SparkPost('<YOUR API KEY>', { origin: 'https://api.eu.sparkpost.com:443' });
client.transmissions.send({
options: {
sandbox: true
},
content: {
from: 'testing@sparkpostbox.com',
subject: 'Hello, World!',
html:'<html><body><p>Testing SparkPost - the world\'s most awesomest email service!</p></body></html>'
},
recipients: [
{address: '<YOUR EMAIL ADDRESS>'}
]
})
.then(data => {
console.log('Woohoo! You just sent your first mailing!');
console.log(data);
})
.catch(err => {
console.log('Whoops! Something went wrong');
console.log(err);
});
Click on the desired API to see usage and more information
client.inboundDomains
(examples)client.messageEvents
(examples)client.events
(examples)client.recipientLists
(examples)client.relayWebhooks
(examples)client.sendingDomains
(examples)client.subaccounts
(examples)client.suppressionList
(examples)client.templates
(examples)client.transmissions
(examples)client.webhooks
(examples)Run npm install
inside the repository to install all the dev dependencies.
Once all the dependencies are installed, you can execute the unit tests using npm test