Upcoming SparkPost API Transmission Endpoint Changes

Marc Chidester
Jan. 27, 2017 by Marc Chidester

***Updated on 5/10/2017***

Back in January, we posted details of an upcoming change to the SparkPost API transmissions capability on this page. Given all the great feedback we received after publishing this post, we decided to hold off on those changes until we have a strong alternative in place.

That means the SparkPost transmissions API endpoint still supports GET requests for listing and retrieving your scheduled transmissions.

We do still want to evolve our API towards more scalable transmission management. Once we put that plan in place, we’ll publish those changes ahead of time as usual.

You can read all about the transmissions endpoint in our API documentation and you’ll also find our regular changelog announcements in this support article and we’re always open for your feedback and chat on Slack.

We’re constantly using community feedback and evaluating usage patterns against performance goals to improve our service. As part of a swath of performance and service improvements, we’d like to announce some upcoming SparkPost API transmission endpoint changes that may affect a very small percentage of users.

What’s Changing

Listing Transmissions: GET /api/v1/transmissions
At present, when you make a GET request to the /api/v1/transmissions endpoint, you receive a list of all multi-recipient in-progress and completed transmissions from the last 24 hours as well as any upcoming scheduled transmissions.

After this change, GET requests to /api/v1/transmissions will return a 405 status code.

Retrieving A Transmission: GET /api/v1/transmissions/{id}
At present, you can retrieve details of a single transmission by making a GET  request to /api/v1/transmissions/{id} , where {id} is the numeric identifier of your transmission.

After this change, transmission details will no longer be available and will return a 404 status code.

Note: POST requests to /api/v1/transmissions are not affected, so this change will not impact your current email sending flow.

The transmission API endpoint’s functionality is documented here in our API documentation, which has been updated to reflect the upcoming change.

Why We Are Making This Change

The main benefit of running GET on the transmissions endpoint was easy access to a historical summary of recent transmission requests. However, the current user experience is inconsistent since some transmissions can be retrieved with the GET while others cannot. Additionally, to allow GETting transmission details for some types of transmissions, each newly-created transmission is held in temporary storage for later retrieval and then passed on to our generation and delivery infrastructure. This storage and retrieval step has a cost in both end-to-end delivery performance and in responsiveness of the transmissions endpoint itself.

To realize these improvements, we’ll be removing the temporary storage step and passing new transmissions directly through to our generation and delivery services. As part of that work, we’ll also have to remove the retrieval capabilities of the transmission endpoint.

Who Is Affected

A quick look at our API usage shows that around 2% of our users are making GET requests to the transmissions endpoint. That is a not insignificant portion of our user base so we’ll be reaching out to those we have identified to help with their transition.

How To Tell If You’re Affected

If your app makes GET requests to /api/v1/transmissions either to list historical or pending transmissions or to retrieve single immediate transmission details, you will be affected by this change and should check out the Alternative Solutions section below for options.

Alternative Solutions

If you currently use the transmissions endpoint as a keep-alive mechanism, you can easily make GET requests to an alternate endpoint such as /api/v1/sending-domains  or /api/v1/templates.

The most obvious and recommended alternative to transmissions listing and retrieval is the metrics summary endpoint. This endpoint provides generalised metrics such as count_injected, count_rejected and count_delivered that you can filter by time, campaign ID, template, sending domain, subaccount, and numerous other fields. However, metrics cannot be filtered by transmission ID. To allow easy metrics reporting by transmission, one could set a unique campaign ID for each transmission.

If filtering by transmission ID, another option is to use message events or webhooks to track each event relating to a campaign ID, template, time window or transmission ID.

Finally, when you schedule a transmission, you can save the identifier returned by your POST request to /api/v1/transmissions  for use if you need to cancel it. You can cancel scheduled transmissions in the normal manner with a DELETE call to /api/v1/transmissions/{id}.

What Happens Next

We will be in touch with those affected to raise awareness and help you prepare. Closer to the time, we’ll update this post to include a deployment date for this change. We’ll also send a follow-up email closer to the change-over but before the change goes live.

In the meantime, you can read the current transmission endpoint API docs and come find us on Slack if you’d like to talk through the details of this transition.

— Marc Chidester
Engineering Manager

Big Rewards Blog Footer

Share your Thoughts

Your email address will not be published.

Related Content

Community Spotlight: Rise And Shine With This Alexa Skill

Getting out of bed in the morning is easier with coffee and your new favorite Alexa skill: MyMorning.Online, our winners from the recent AngelHack.

read more

Our Top 5 Email Template Hacks

From creating standards that can apply to many templates to design hints on validating your data, here are our top 5 email template hacks.

read more

PHP Frameworks In The Wild: A Closer Look at the PHP Ecosystem

For those looking to go beyond the basics with PHP, explore some PHP frameworks and tools in the wild and learn how they interact with SparkPost.

read more

Start sending email in minutes!

The world’s most powerful email delivery solution is now yours in a developer-friendly, quick to set up cloud service. Open a SparkPost account today!

Get Started

Send this to a friend