Upcoming API Transmission Endpoint Changes

Chris McFadden
Aug. 30, 2017 by Chris McFadden

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.

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 also continue to generate a rejection event for every suppressed email address which is 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 a rejection event for every suppressed email address, which is available via Webhooks or the Message Events API.

Preparing for the change

We plan to implement the first change related to suppression checks on or soon after November 1. 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, and will happen in the month of September.

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

5 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?

    Reply
  • 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.

    Reply
  • 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,

    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"
    }
    }

    Reply

Share your Thoughts

Your email address will not be published.

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