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.

we love developers