UPDATED OCT 30 2017

We are constantly looking for ways to improve the performance and reliability of our email API. We know how important it is that when you call the Transmissions API endpoint, we are able to accept your request quickly and return a response. In the past months we encountered some situations where our API did not respond quickly due to the dependence on an underlying component, subsystem, or database that had degraded performance. Two upcoming changes will eliminate these dependencies and improve the consistency of our API response times.

The key takeaway of the changes is that we will no longer do in-line rejection of suppressed recipients.  Instead there will be an injection event followed by a bounce event when a recipient is suppressed. The changes will take effect soon after the start of the new year in January 2018 to give customers time to prepare.

Improving Transmissions API performance

The first change to the Transmissions API endpoint is that it will no longer perform a synchronous suppression check on single recipient transmissions.  What this means to users is that the Transmissions API will no longer return a HTTP response of 400 if the address is suppressed, but instead will return a 200.  We will continue to check against the suppression list but we will do it asynchronously.  We will no longer generate a rejection event but will instead generate an injection event followed by a bounce event.  These events will be available via webhooks or the Message Events API.  By making this change we will be able to speed up our API and ensure more consistent performance.

The second change to the Transmissions API endpoint is that we will only track and return a status for scheduled transmissions when calling the GET method. For all other Transmissions, including multi-recipient transmissions, a transmission record will not be returned when you call the GET /api/v1/transmissions endpoint. Instead, the API will return a 404, not found, error. In order to keep track of your transmissions, we recommend using the Metrics API, Message Events API, or Webhooks.

SMTPAPI change

The SMTPAPI will also no longer perform the synchronous suppression checks. The SMTPAPI will no longer return a 554 error when an address is suppressed. All valid messages will be accepted and the API will return a 250 OK. As with the Transmissions API, we will continue to check the suppression list asynchronously and generate an injection event and a bounce event for every suppressed email address, which is available via Webhooks or the Message Events API.

Preparing for the change

These changes will be made in the next couple months.  The first change related to suppression checks will be implemented on or soon after January 2nd 2018.  We recommend that you continue to handle the current inline suppression response returned by the Transmissions API endpoint and SMTPAPI, but put in place measures to begin using the Webhook or Message Event API data.  This will ensure a smooth transition.  The scheduled transmissions change to the GET method will affect very few people in a material way will happen in November.

Summary of the current and future behavior

The following is a summary of the current and future behavior for when a recipient is suppressed

SMTP

  • Current: return a ‘250 Ok’ and ‘policy rejection’ event (no injection event)
  • Future: return a ‘250 Ok’ with ‘injection’ event followed by a ‘bounce’ event

REST API

Single recipient transmission

  • Current: return a 400 with special error message, followed by a ‘generation rejection’ event
  • Future: return a 200 with an ‘injection’ event followed by a ‘bounce’ event

Multiple recipient transmission

  • Current: return a 200 followed by a ‘generation rejection’ event (no injection event)
  • Future: return a 200 with an ‘injection’ event followed by a ‘bounce’ event

When a bounce is generated due to suppression the webhook will have bounce_class of “25” and an error_code of “554” and reason of “Recipient address was suppressed due to customer policy” or “Recipient address was suppressed due to system policy

Making a tough decision

At SparkPost, we take backwards-compatibility very seriously. We don’t make these types of changes lightly and appreciate that our customers have code in production using our API. We also take our reliability and performance very seriously and know that is one of the primary reasons why developers and enterprises choose SparkPost. As a result, taking all of the above feedback and issues into account, we believe the updates will provide a much better experience for our customers.

Finally, if you’d like to discuss this update, or anything SparkPost related, please feel free to join us in our community Slack channel or reach out to us on Twitter.

Chris McFadden
VP Engineering and Cloud Operations

Dev Survival Guide Blog Footer