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.

Avi
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.

–Aydrian