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

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.


C# library community feature

The community of developers working with SparkPost really has stepped up in the last few months: submitting pull requests, writing new client libraries, finding bugs, and helping each other out in our community Slack. They say you are the company you keep—well, if even a small bit of your collective awesomeness rubs off on us, we’ll know we’ve made it. 🙂

We’d like to show a little bit of love in return by highlighting some of the community members who’ve helped raise the bar for SparkPost and our tools. Today, I’ll start with Darren Cauthon, who contributed the SparkPost C# client library. I asked Darren to share a little bit of his point of view.

How long have you been a developer and what got you started in the tech world?

I’ve been a developer for over 15 years. I got started with tech in my sophomore year, right around the time my college forces students to pick a major. I thought about being a music teacher or going for a general “business” degree, but I remembered that programming in QA Basic in junior high was fun. So I signed up for my first C++ class and never looked back.

What do you like most about being a developer?

Working with all types of people to solve new problems. The tech is fun, but using it to solve actual problems that exist in reality makes it very fulfilling.

What led you to contribute to open source projects?

Two things. First, I got over the fear that my code wasn’t good enough. Second, I’ve found it’s hard to grow as a developer when I’m limited to solving the problems that my business has. Open source provides the opportunity to solve problems that I’d otherwise never think to solve, and it provides a chance to work with developers I’d otherwise never know.

How did you find SparkPost?

My company was about to deploy a new Mandrill solution when their big shakeup occurred. We looked for alternatives, and my boss noticed SparkPost due to your relationship with Port25 (which we used for other solutions).

What prompted you to create the C# client library for us?

I saw there wasn’t one, and I wanted the experience of writing the library. I’ve learned a lot about email processing and C# features while working on the library, and that’s knowledge I’d never have gained otherwise. I’ll be able to apply that knowledge to many more things than just this library.

What’s the hardest thing about contributing to an open source project?

Saying “no” to contributors. Sometimes someone may offer a pull request with a feature or change that doesn’t fit. I hate having to say “no” and reject what another developer has spent time writing. But luckily I haven’t had that problem with this library, as we’ve had a great group of developers contribute new features—and every contribution has fit.

What are you passionate about outside of work?

I have a great family, and raising kids is fun. I’ve been a tuba player for over twenty years, and I’m slowly working towards a black-belt in Tae Kwon Do. I have a 2016 resolution to beat Ninja Gaiden without dying, so I like older console gaming. But my first passion is still programming.

I was really glad to have a chance to talk with Darren and learn more about his point of view. His project really has been a great addition to the ways folks can use SparkPost. Thanks, Darren!

Do you have an idea or project to contribute to this great community of developers? Give us a shout on the SparkPost community Slack, and you might wind up in our new community features series.


p.s. you can check out another one of Darren’s C# libraries here.