Heads Up: Changes to Error Handling in Transmissions API

Isaac Kim
Oct. 3, 2018 by Isaac Kim

SparkPost’s Transmissions API is among the most heavily used features of the SparkPost service. We know how critical this endpoint is to how our customers integrate email into their applications.

That’s why we’re continuously looking for ways to further strengthen its reliability, maximize its performance, and improve the developer experience. It’s also why we’re very careful about making any changes that might impact how our customers use the Transmissions API in their production code.

Usually, those objectives are completely aligned, but there are times when the strategic goals do require an unavoidable breaking change to the API. In January, we will be deploying one of those changes. Read on for the details.

Summary of Changes to the Transmissions API Coming in January 2019

On January 12, 2019, we will be making three changes related to how the SparkPost’s Transmissions API handles errors:

  • Single-recipient message generation will become an asynchronous, rather than synchronous, operation.
  • All inline template syntax validation will become asynchronous. This will affect both single- and multi-recipient transmissions.
  • Extended error codes will no longer be returned in Transmission API responses.

Each of these changes affects error cases; they will not change the result of any successful (HTTP 200 response) API request.

Making Single-Recipient Transmissions Asynchronous

SparkPost will no longer perform synchronous template validation and message generation on single recipient transmissions.

This means that the Transmissions API will no longer return an HTTP response of 4xx if there is a problem with the template syntax or substitution data.

Instead, the Transmissions API will return a 200 response, and then a subsequent “Generation Failure” webhook event that will provide details on the failure. These events will be available via webhooks, the Message Events API, and as Message Events in the SparkPost app. This behavior for single recipient transmissions will be the same as the current behavior for multi-recipient transmissions.

Making Inline Template Syntax Validation Asynchronous

The second change to the Transmissions API endpoint is that inline template syntax validation will no longer be performed synchronously.

For both single and multi-recipient transmissions, the syntax validation will be done asynchronously, with an HTTP response of 4xx no longer returned for syntax error on inline templates.

Instead, the API will return a 200 response, and then a subsequent “Generation Failure” webhook event that will provide details on the failure. It is recommended that developers utilize the preview capability of the Templates API before injecting with an inline template.

Removing Extended Error Codes for API Responses

Finally, we are removing extended error codes from the HTTP response from several APIs. Note that these extended error codes will remain available via webhooks.

Several API endpoints, including Transmissions, Templates, Sending Domains, Inbound Domains, Relay Webhooks, and Tracking Domains, currently return extended descriptions and codes in the body of their response.

Instead, API error responses will return a 400 HTTP status code and single message field in the response body.

For example, a Transmissions API error currently looks like this:

With the changes coming in January, we will return just the HTTP status code and the optional error message. There will no longer be a code or description field returned, but the content of the old description field will be returned in the message field.

This change will eliminate redundant information from these API endpoint responses and make error responses consistent across all of our API endpoints.

Preparing for these Changes

If you have any code that is currently looking at the API error response for code, message, or description you will need to update those systems.

To prepare for these changes, we recommend that you begin using webhooks or the Message Events API to capture detailed error codes rather than relying on the now-deprecated Transmissions API response. This will ensure a smooth transition on January 12.

As mentioned above, to validate a template before using it in a transmission, the best option is the use the Templates API preview endpoint, or to preview the template within the SparkPost web app.

Careful Consideration of Changes—and Future Capabilities

We understand that this breaking change to the Transmissions API may affect some customers’ production code. We apologize for the inconvenience this change may cause.

We take reliability, performance, and usability very seriously and know these are among the primary reasons you’ve chosen SparkPost. Thank you for that confidence. These updates will allow us to continue to provide great services and enable future capabilities.

Please do not hesitate to reach out to us with any questions or feedback. You can ping us on Twitter or email your primary SparkPost contact.

—Isaac Kim
Technical Product Manager

Related Content

Upcoming API Transmission Endpoint Changes

We’re making some API Transmission Endpoint changes. Learn how the changes will improve performance and optimize end-to-end delivery latency.

read more

Support for Google AMP for Email in SparkPost Coming Soon

We’re working with Google to add support for Accelerated Mobile Pages (AMP) for Email to the SparkPost service. Here’s a preview of how it works.

read more

How to Get Started with A/B Testing in SparkPost

Learn how to get started with SparkPost’s new A/B Testing feature that's been optimized for transactional email and other app-generated notifications.

read more

Get started and start sending

Try SparkPost and see how easy it is to deliver your app’s email on time and to the inbox.

Try Free

Send this to a friend