Intro to Node.js

As a Developer Advocate for SparkPost, I write a lot of sample applications. My background is mostly front-end development, therefore my strongest language is JavaScript. Thanks to Node.js, I’m a decent backend developer as well. Does this mean I’m a full stack developer now? Anyway, it was important for me that we had an awesome SparkPost client library for Node.js. So, I dove right in and became a contributor (even before I was hired).

Allow me to help you get started sending emails with SparkPost on your Node.js project.

Installing & Setup

I’m going to assume that you have Node.js installed. Because we follow the Node.js Long Term Support (LTS) schedule, you’ll need to be running version 4 or higher. You can see which version you’re running using the node --version command in your terminal window.

Let’s create a new npm project. If you already have one, you can skip this part.

This will create a new project and accept all the defaults. You can also instead run npm init and answer all the prompts.

Now we can install node-sparkpost:

Once installed you can import and create an instance of the SparkPost class:

It’s good practice to avoid putting your API key in code. We highly recommend storing it outside your code, so we set up the client library to detect the SPARKPOST_API_KEY  environment variable.

Sending Email

Now that you have a SparkPost instance, you’re ready to send. There are quite a few options available for sending, but let’s start with a simple example. Here’s how you send an email to a single recipient, specifying inline content:

Note: This example uses Promises, but don’t worry. We also support callback functions.

There are more options available with transmissions, including specifying stored templates or recipient lists, cc and bcc, adding attachments, specifying a campaign, using substitution data, and much more. Check out the examples, docs for the Transmissions resource, and the Transmissions API documentation for more info.

Bonus: Sending Email with Nodemailer

Nodemailer is a popular library for Node.js that make sending email “easy as cake.” For those of you choosing to use this library, we created a SparkPost transport for Nodemailer. You’ll need to install the nodemailer  and nodemailer-sparkpost-transport packages in your project.

Now you can create a nodemailer transport instance:


Notice how I am reading the API Key from an environment variable. It’s still a best practice to never put that directly in your code.

There are several options that can passed into the SparkPost transport, like campaign id and whether or not the message is transactional. Take a look at the for all the options.

Here’s how you’d send the same message above using Nodemailer:

Double Bonus: Sending Email with

We all know that email is king of communication but sometimes you want to be able to reach people via multiple channels. is a Node.js library for sending all kinds of transactional messages. Whether you want to send an email, sms, push, or webpushes, you can do it with ease. It also has built in fall and round robin strategies for multiple providers. We recently worked with the creators to build a SparkPost provider. You’ll need to install the notifme-sdk package in your project.

You can now create a notifme instance with the SparkPost provider:

Again, we are pulling the API Key from an environment variable. We’ve said it three times — it’s that important. 🙂

Now let’s repeat this same example, this time using

It’s really easy to use and I recommend looking at the other features.

There’s no wrong way to Node

When it comes to sending email using Node.js, you have many options. We’ve worked hard to help make it as painless as possible. If you run into any issues or have any questions, feel free to submit an issue on our node-sparkpost or nodemailer-sparkpost-transport github repos or join us on our community Slack team in the #node channel. I look forward to hearing from you.

— Aydrian Howard

Dev Survival Guide Blog Footer

Abbreviations For Code

One of SparkPost’s taglines is “robust cloud email API,” so it probably doesn’t surprise you that our service has an awesome API that makes it really easy to send email. Our API also enables certain types of account configuration, which you usually don’t need to call in an automated way. For instance, the simplest way to set up a relay webhook is by writing a cURL command and sending it off to the API.

Another good example is adding an inbound domain. Using cURL, here’s how you’d write out this relatively tame beast.

Game Of Thrones GIF - Find & Share on GIPHY

Pretty straightforward, right? But as Larry Wall, the creator of Perl, once quipped, laziness is a virtue in programmers. That’s why we build tools and automate tasks. Consider the example above. Most of the data in that request will be repeated in every SparkPost API call. Plus, doing it this way means you have to store your API key somewhere easily accessible. So how do we make this easier? Why, a command line interface!

Opening The Black Box

We recently refactored some of our client libraries to be very thin wrappers on top of our API. This makes maintaining them much easier, while still providing a common interface between the different languages.

With this mindset we wanted to build something that would be both configurable, mirror the SparkPost API, and require relatively little maintenance. To achieve this, we generated the SparkPost CLI from our node library, which has resource wrapper objects to improve the user experience.

Next, we set up a configuration file and merged it with the configuration that we generated from the library. Lastly, we handed the combined configuration off to yargs, a powerful library for writing CLIs in node.

Take The SparkPost CLI For A Spin

Grab the SparkPost CLI from NPM and configure it with your API key.

Now to add an inbound domain, run the following command, which is substantially more tame, and significantly less boilerplate-y than our earlier, verbose cURL example.

Happy GIF - Find & Share on GIPHY

Releasing It To You


Our hope is that this tool will make our API easier to use for the more mundane, ad hoc tasks like creating a webhook or grabbing data from the Message Events API. Right now the SparkPost CLI has support for 7 of our API endpoints, and there are more coming soon.

Give it a try and let us know what you think! We live for community feedback. If you’re really into it, dig around the code and maybe even make a pull request. Then hop on over to Slack or Twitter and let us know what you think.

Software Engineer

node.js client library

Developing our Node.js Client Library

On Feb 6, 2015, my first pull request (PR) to the Node.js Client Library for SparkPost was accepted. The library was in its infancy and only included support for sending an email using the Transmissions Resource. My contribution expanded its capabilities to add support for the Sending Domains Resource. You might be thinking, “No big deal! You work at SparkPost, and are on the team that works on these libraries.” But this particular PR occurred a full month before I joined the SparkPost team as a Developer Advocate. Little did I know, I would soon become the maintainer of this codebase.

We’ve come a long way since that PR. Last month, we released the next major version of the node.js client library, node-sparkpost 2.0.0. This was our opportunity to step back and look at how the library was being used, remove what didn’t work or was holding us back, and improve the overall user experience. So we broke it down and built it back on top of a stronger foundation. We hope you like it.

Remember, this release has breaking changes, so you’ll need to consult our new Keep A Changelog inspired changelog, but I’ll highlight some of the changes and features below.

It’s so hard to say goodbye to yesterday

Sometimes in order to move forward, you have to let some things go. Starting with the 2.0.0 release, we will be following the Node.js Long Term Support Schedule and removing support for v0.10 and v0.12. This will allow us to take advantage of new features without having to worry about supporting versions of Node.js that are no longer maintained.

For those of you still on versions < v4, you can continue using the latest 1.x version of our client library using  `npm install sparkpost@1`.

Half the fat, just as filling

SparkPost is constantly growing and releasing new functionality. In order to keep up with the progress, we’ve switched the client library to be a thin wrapper. This ensures that new functionality will be exposed without the need for a new release and it helps simplify documentation. Everything you see in the API Documentation is now available in the client library. You can access every resource via the base object. Many resource wrapper objects have been included to provide syntactic sugar to improve the user experience.

For those of you moving from 1.x to 2.0, check to make sure all properties are passed in snake case (e.g. `campaign_id`). We have removed support for camel case (e.g. `campaignId`). If you are using any of the resource wrappers, be sure to consult the documentation because the method names and signatures could have changed.

Keep it simple

The data being returned has been simplified. In previous versions, we returned the full response. Now we are just returning the body of the response parsed as a JSON object. This cuts out the extra unneeded data and quickly gets you the results you need. We’ve added a debug option on initialization that will deliver the full response in a debug property should you still need it.

If you are migrating from v1.x to v2.0, `data.body` is now simply `data`.

Promises, Promises

We now support both of your favorite async strategies. All methods now return a promise, but we’ve also provided you the ability to continue passing callbacks. Want to know more about how we handle callbacks and promises? Check out the documentation.

So how do you send an email now?

Since the majority of developers use the sending functionality of the client library, let’s see what it looks like using node-sparkpost 2.0.0:

For those of you migrating from 1.x to 2.0, you’ll notice that the transmissionBody property has been promoted to the first argument and it aligns with the Transmissions Attributes. We have also moved any query string parameters to an optional second argument. For this example, we are using promises, but you can still opt to pass a function as the last argument to continue using the callback async strategy.

Additionally, as mentioned above, we’ve worked hard to make this version of the library get out of your way as much as possible. If you’d like to do the same transmissions call using our generic base object, this is what that would look like:

We’re very excited about this release and hope you all are as well. Thanks to our user-agent reporting, we are already starting to see adoption of our node.js client library.

graph: adoption of node.js client library

Are you currently using our node.js client library? Then pop over to our community slack and let us know what you think in our #node channel. You can also create an issue if you’ve found a bug or have a great idea for an enhancement. You can even submit a pull request and fix or add a feature yourself to our node.js client library. I welcome your feedback. Let’s improve the SparkPost experience for Node.js developers together.