Updating the SparkPost Postman Collection

One nice thing about SparkPost API documentation is the easy access to a “Postman collection”, which we’ve made available since March 2016. Whether you are just starting out with APIs, or if you are an experienced hand, Postman enables you to get started easily and be immediately productive with your SparkPost based development project.

Spring is in the Air

Jump forward to March 2018, and our collection was in need of spring cleaning, reflecting the numerous API improvements we’ve made (while avoiding breaking changes). We’ve just done that, bringing it into line with current API features and documentation.

Here’s what EUve been Waiting For

With the launch of our public sign-up SparkPost EU service, with API running on https://api.eu.sparkpost.com, we need a flexible solution to support varying URLs.

We also have many SparkPost Enterprise customers with distinct URLs, across three different AWS regions – for example https://customername.api.e.sparkpost.com. Our advice on this in the docs was:

.. seems like we should be a bit more helpful, given the collection contains 100+ requests! Bringing us to:

Postman Collection Variables

Postman has a great feature which we have used to solve this problem – variables can now be of varying scope:

*(from Postman documentation)

This is a really well-thought-out feature from Postman. We can:

  • Replace the hard-wired address in our published collection with {{BASE_URL}} ;
  • Define it inside the collection, preset to the standard sparkpost.com service value, so the collection still “just works” out-of-the-box;
  • .. yet anyone can change it at environment scope if they need to (taking precedence).

When you hover your mouse over the placeholder variable in each call, Postman shows you the current value, along with the scope it’s defined in. Here’s how our collection looks in plain-vanilla form:

If you want to override that value, just create an Environment variable named {{BASE_URL}} and set it to your specific URL, along with your API key. For example, to access our new EU endpoint:

When you hover over the call, you will see the value and scope:

Note the little red square “E” (environment scope) has replaced the orange square “C” (collection scope).

It’s easy to switch between your environments using the Postman drop-down settings on the top right:

Open-sourcing the Collection

The collection itself is hosted via a link to Postman’s own site. That makes it really easy to get started, as your browser knows which app open for you. However, we wanted to go one step further and host the collection source (which is just a big JSON file) on Github, so that you can easily notify us of issues and propose changes or improvements directly.

The Last Post

So, that’s pretty much all there is to it. The collection is now nice and fresh, and you can easily use it with Enterprise and EU endpoints.

If you have any comments, improvements or other suggestions on our Postman collection, please get in touch via Community Slack or direct on Github.



In case you missed the announcement last month, our SparkPost API documentation now comes with a “Run in Postman” button:


What Does That Mean?

Cool! We’ve got a nifty new button. But what does that mean? And how do I know whether or not I’ll need (or want) it?
Here are the basics:

  • Are you (or one of your other developers) digging into the SparkPost API yourself, in addition to using the automated systems built around it?
  • Are you a little uncomfortable with the details of HTTP requests?
  • Do you have a hard time remembering what particular cURL command to use?

Postman to the rescue! It parses your API request and response and displays them in more manageable formats. It also simplifies the creation of API requests, which means you’re off the hook for finding the arcane syntax that will pull the precise information you’re in search of.

As Dave mentions in his blog post:

Postman gives less-technical users a way to make arbitrary HTTP requests using a point and click user interface. Collections make it easy to organize your requests and, to a point, share them. Environments make it easy to switch authentication keys and make other things configurable without editing each request.

Is your interest piqued? Good! Then without further ado, let’s dive in…

Getting Started

So what do you need to do to start using this?

Firstly, when you click this button, you’ll be directed to open this collection with your installed Postman app.

You will then see the “SparkPost API” collection show up in the left-side pane, and you can expand the various folders in the collection.


There are currently 76 different request types in the collection; we’ll be adding more as the API becomes even richer.

You can try running these right away – for example Message Events / Get Samples.  You’ll see results come right back in the Response window.


This particular request works straight away, because just getting samples back doesn’t require authorization.

Setting up Authorization

If you try most of the other requests – such as “List All Sending Domains” – you’ll get a message saying

because each account’s data is private. You’ll need an API key set up to access this information.


Here’s where a neat feature of Postman comes in. The Environments collection is set up to look for a Postman variable called {{API_KEY}}.  You can see this by viewing the request headers.


If you don’t have an API key yet, you’ll want to create one.

Once you have your API key in hand, go to “Manage Environments.”


Choose Add, and type a name, e.g. “My SparkPost setup.”  Then add your key and value.

Key should be just the words API_KEY  (without the curly braces this time), and the value is your specific hex string.


Hit Add.  Choose “My SparkPost Setup” from your drop-down list of environments in Postman.


Re-run your API request, and your authorization will be used for each of the collection’s requests without any further editing.

Here’s what I get back from “List all Sending Domains” — I can see my domain is set up and ready to go.


Now you’re set to explore the other requests in this collection.  Happy exploring!

postman and sparkpost

Run in Postman

Run SparkPost in Postman

SparkPost is an API-first service, targeting developers. What this means in practice is that we build our APIs (you guessed it) first, and then build our UI using those same API calls. We also have quite a few human users of our APIs, in addition to the automated systems we’ve built around them. Some of these users aren’t comfortable enough on the command line, or with the details of HTTP, to use cURL to build their API requests. This is where Postman comes in, turning the API request and response into something much more human-readable.

There’s a UI for That

Postman gives less-technical users a way to make arbitrary HTTP requests using a point and click user interface. Collections make it easy to organize your requests and, to a point, share them. Environments make it easy to switch authentication keys and make other things configurable without editing each request.

The new Run in Postman button makes it much easier to share collections. Since we already use Postman internally, and for demos, it was a no brainer for us to get the button set up, using examples from our API documentation.

Roll Your Own

There are lots of things you can do with the SparkPost API, and now, more easily, with Postman. For example, you could send quick, one-off test messages, or experiment with some of our more complex templating features.

When it’s time to do some data analysis, our API gives you lots of options about what kinds of metrics you’d like to see, what period of time you’d like to see data for, and how to group the data that’s returned. The examples that we’ve provided are organized by endpoint, so they’re really showing you what types of questions can be answered.

Customizing these queries so they answer the sorts of questions you have about what you’re sending is where things start to get interesting. Show us how you’re using our collection and get your questions answered on SlackTwitter or good ole’ email.