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

reporting with sparkpost using node.js

SparkPost is the world’s most powerful email platform. Our engineering team takes advantage of this fact by using SparkPost to power several pieces of functionality within SparkPost itself. One of the areas we use SparkPost is to power our internal reporting. In this post I’ll demonstrate how we use SparkPost to build an email report.

We’re going to build what we refer to as our sending domains report. This report goes to our deliverability team, which ensures we follow best practices to help our customers succeed. We’ll use Node.js, demonstrate some queries in Cassandra, which is where our customer data lives, and pull it all together with the templates and transmissions capabilities of SparkPost.

The content of the email will be a simple heading and table with a row for each record in the data we retrieve from Cassandra. Here we create a template that makes use of the SparkPost template substitution data:

We’ll create a new template with the ID sending-domains-report by going to the SparkPost Templates UI and pasting the HTML content into our template editor:


Let’s break down what we’re doing in the template:

First, we have a heading and an if statement. We use this statement to see if the domains variable is empty (we’ll show you where that comes from later). If it is, the template will just show a friendly message.

If the domains variable is not empty we create a table with a heading row:

And finally we loop through each item in the domains variable and render some data:

Now that we have our template, we need to create a Node.js script that queries our Cassandra database and uses node-sparkpost to send the email.

First we have to require some libraries:

Next we create the functions for retrieving data from our sending domains and accounts tables. Note that we created our own wrapper around cassandra-driver to promisify the batch/execute methods and add an executeByStream function that allowed us to stream back more than 5,000 results:

We have to do some processing on the data returned from the queries to merge them together:

This function is responsible for sending our message through SparkPost using the node-sparkpost library. We use the config library to set up our connection to Sparkpost, prepare the message meta and substitution data and deliver the message:

Finally we pull it all together into a promise chain and log out the results:

You can view the code in full as a Gist on Github. The end result an email report that looks like this:


Internal reporting is only a small sample of how we use SparkPost at SparkPost. In a future post we will dig into how we use SparkPost to power the various emails that are sent to users of SparkPost.


Dev Survival Guide Blog Footer

Nodejs SDKThere are few – if any – apps today that could get away without utilizing email sending capabilities. At the very least, web and mobile applications need the capability to promptly send password reset links when a user forgets his or her password. Additionally, of course, users who buy something these days expect an email receipt. These transactional emails should be sent within a minute – at most. Otherwise, you risk losing users when they tire of repeatedly hitting the refresh button on their email client.

You may already know that SparkPost gives companies of all sizes the ability to send fast and dependable email. But we don’t stop there because it’s not enough to have access to the best market-leading email service if you have to become an expert to use it. We want you to be able to integrate our email service easily and efficiently, so you can get back to working on your app’s key functionality. That’s why we’ve made it our mission to make it as easy as possible for developers to integrate SparkPost into their web or mobile apps. To that end, we most recently released an SDK for Node.js.

The SparkPost team is always looking to see what SDKs would benefit our user community. Node.js has become a popular language for developers building scalable enterprise web applications, so we’ve provided a little syntactic sugar for the Node.js crowd. Using our APIs or SDKs, developers typically get up and running with SparkPost in 30 minutes or so.

Developers primarily use SparkPost SDKs to send a transmission, but we’ve included additional capabilities in the Node.js SDK:

  • Recipient lists
  • Sending domains
  • Suppression list
  • Templates
  • Transmissions
  • Webhooks

These capabilities will soon be added to our PHP and Python SDKs as well. All of our SDKs are provided as open source through Github, and more will be added in the future. Send me a tweet @aydrianh if you have any new suggestions about SDKs you’d like to see.

Here at Message Systems, we’re always looking for opportunities to give back to the local community. We donate to Feeding America every year in support of the cause to alleviate poverty and our employees are regular participants in Oxfam Trailwalker Japan, a challenging endurance fundraising event that supports worldwide economic empowerment programs.

So of course, when the opportunity came up to get involved in a way that would positively impact our local community and industry, it was hard to say no. Especially since we were being called upon for our technical expertise – finally a chance to do some social good while sharing our coding skills!

And that’s the story of how Message Systems became an official sponsor of the Baltimore NodeSchool.

What is the NodeSchool?

First, a little background: the NodeSchool is a fully community-driven effort that is 100% open source. It comprises a series of self-directed programs or adventure-style lessons to learn different aspects of node.js, which is written in Javascript. According to Wikipedia:

Node.js is a software platform for scalable server-side and networking applications. Node.js applications are designed to maximize throughput and efficiency, using non-blocking I/O and asynchronous events.”

The Baltimore NodeSchool was inspired by and follows in the fine tradition of NodeSchool. Think of it as the local chapter in Baltimore. For this first event, the Baltimore NodeSchool decided to focus on the introductory lessons in the Learn You Node workshop by NodeSchool.

Aside from keeping participants fed and watered, Message Systems also provided mentors for the event: our very own Bob Evans, Software Engineering Manager and Jessica Martin, Software Engineer!


Jessica and Bob were among the 7-8 mentors volunteering for the event, which saw 50 students in attendance. The mentors went around answering questions students had about problems, or teased out answers with hints to the solutions. While having a basic knowledge of Javascript was beneficial, the registration for the event was open to all. The students were rated on a scale of 1 to 3 and the mentors discovered a wide range of skill sets among the students.


“It was fun for us to demonstrate the knowledge we had of node.js in developing the Momentum product,” said Bob. “We want to get more involved in the Javascript community in the Baltimore/DC area. I saw this as a great opportunity to get the ball rolling.”

The next Baltimore NodeSchool event is scheduled to be conducted in July, and it will be geared towards students that have some intermediate knowledge of node.js or just Javascript in general. Once again, Message Systems is thrilled to announce that we are an official sponsor!

In the words of Jessica, “I really enjoyed mentoring at this event, it was really interesting to see the wide range of abilities in the students, and their enthusiasm for not only learning, but sharing their knowledge with their peers. I was sad to see the end of the event, but am definitely enthusiastic for an even better one in July!”

Looking to embark on a fulfilling engineering career? Not a problem. With Message Systems, you can! Find out more about what we do and read our white paper, What Sets Momentum Apart.