Upcoming API Transmission Endpoint Changes

Chris McFadden
Aug. 30, 2017 by Chris McFadden

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

17 Comments

  • “…our API did not respond quickly due to the dependence on an underlying component, subsystem, or database that had degraded performance”

    Umm… what? Instead of breaking backwards compatibility, why not just improve the performance of the “underlying component, subsystem or database?

  • Thanks for your question, Andrew. Performance and reliability are paramount for the SparkPost service. Our technical decisions are guided by a hierarchy of priorities for the Transmission and SMTP API endpoints. The first and most important thing for us is to never lose a message once we have taken responsibility for it. Once we accept it we ensure it either gets delivered or eventually bounces. Secondly, we must always accept messages from our customers. While transient errors or timeouts can be reasonably expected and handled by our customers, sustained email API slowness or complete outage for more than a few minutes has widespread impacts since our customers generally do not queue and retry messages for any significant period of time. Third, we try to make the first attempt at delivery within the first few seconds and if that is not possible then as soon as possible.
    Our decision to move the suppression checks to asynchronous will ensure we fulfill our second priority. While we continue to improve our underlying components and databases involved in the email processing flow, the more dependencies there are in a synchronous API call the lower the overall reliability. I am confident that the overall benefit to our users and community far outweigh the negative aspect of this change.

  • Hello,

    Why I am getting below error.

    We’re sorry but your account has been suspended due to potential fraudulent activity. Please contact support

    Can you explain

  • Hi Vinay,

    Be sure to open a ticket with our support team (support@sparkpost.com) and they can help out!

    Thanks,

    Jen

  • Hi Chris, I totally agree with you, but if someone (like me) is using the APIs in a synchronous manner, and for example giving a synchronous feedback to a frontend web page, this is a breaking change.
    Now I give an immediate feedback like “Your message has been sent”, tomorrow I can only give a feedback like “Maybe your message has been sent, I don’t know!” 🙂

  • Email is by it’s nature asynchronous. It might not be delivered for a number of reasons and end up bouncing. I recommend treating these as infrequent exceptions in a similar way. Perhaps you have some way of notifying a customer when there is a problem, either in your app or send them an email.

  • Hi Chris,

    Nothing’s changed for email sending, right? You’ll still return an id on POST /api/v1/transmissions?


    {
    "results": {
    "total_rejected_recipients": 0,
    "total_accepted_recipients": 2,
    "id": "11668787493850529"
    }
    }

  • Correct, the Transmission API POST will still have the same response body.

  • Fine, but January 2nd when lots of people are still on holiday? I am not looking forward to being called in the first week of the year for unexpected breakage that could easily be pushed a few weeks further? TIP: Some of us in the Southern Hemisphere may not go back to work a couple of weeks into January.

  • This will not take place Jan 2nd, likely later that week or the next. Keep in mind that your emails will continue to be accepted with no change on your end. This will only affect cases where a recipient is suppressed. If you care about that you should add webhook call back handling in advance. Otherwise no change is needed on your end.

  • Will the elixir client library continue to behave as expected without change?

  • Yes, it will continue to work the same way. You should get set up to receive webhook call backs if you aren’t already.

  • How will this affect callbacks of nodemailer-sparkpost-transport – https://github.com/SparkPost/nodemailer-sparkpost-transport?

  • Instead of getting a rejection call back you will get a bounce call back.

  • I would recommend not rolling out on Jan 2nd, the day many people return from holiday. It’s a hectic enough time without returning to for nd your injection engine stops working. Also is there beta access we can test to see if our changes are working properly before the rollout?

  • Hi Rich, it will not be Jan 2nd for that very reason, but will be some time in early January.

  • We have an application using Laravel 5.2.4 and their standard integration with SparkPost. Do you know if this will be affected by the coming changes?

Related Content

Our DevOps Journey

Switching from on-premises to a cloud-first company is no small feat. Here’s our journey to continuous deployment and improvement over the past few years.

read more

RESTful API Versioning Best Practices: Why v1 is #1

Breaking changes can result in frustration and loss of trust between an API provider and their users. API versioning is one way to avoid that frustration.

read more

Configuration Management and Provisioning in AWS with CloudFormation, Ansible, and Puppet

Experimenting with various configuration management and provisioning tools taught our teams how important it is to not get too attached to specific tools.

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 and get started for free.

Get Started

Send this to a friend