SparkPost API

Welcome to the SparkPost API Reference. If you're new to SparkPost, create a free developer account (EU) and follow this guide to get started.

Endpoints

All calls to the API need to start with the appropriate base URL:

SparkPosthttps://api.sparkpost.com/api/v1
SparkPost EUhttps://api.eu.sparkpost.com/api/v1

For Enterprise accounts with their own endpoint, please contact your account manager for more information.

Authentication

Authenticate each request by setting the Authorization header with a valid API key. Create and manage your API Keys in the app (EU).

We accept just the API key:

"Authorization": "14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf"

or Basic type and the API key:

"Authorization": "Basic 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf"

Make sure to store your API keys somewhere secure and never share them publicly.

API Examples

cURL

If you are using cURL to call the API, you must include the resource URI in quotes when you pass in multiple query parameters separated by an &.

For example:

curl -v \
-H "Content-Type: application/json" \
-H "Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf" \
-X GET "https://api.sparkpost.com/api/v1/metrics/deliverability/aggregate?campaigns=testjob&from=2017-01-23T14:00&metrics=count_targeted,count_sent,count_accepted&timezone=America%2FNew_York&to=2017-06-23T15:50"

Using the -u flag for authentication:

curl -v \
-H "Content-Type: application/json" \
-u 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf: \
-X GET "https://api.sparkpost.com/api/v1/metrics/deliverability/aggregate?campaigns=testjob&from=2017-01-23T14:00&metrics=count_targeted,count_sent,count_accepted&timezone=America%2FNew_York&to=2017-06-23T15:50"

Postman

If you use Postman you can click the following button to import the SparkPost API as a collection:

Run in Postman

Environment Setup

Our collection is set up to expect two Postman variables:

VariableDescription
API_KEYUsed to authenticate requests. Set it to a valid API Key
BASE_URLAPI Hostname to be used.

More information on setting up Postman environments and variables can be found here.

Client Libraries

SparkPost has several official and community supported client libraries. Check out our Developer Hub or our GitHub for examples in your favorite language.

API Conventions

  • Trailing slashes are ignored: /transmissions is equivalent to /transmissions/.

  • URL paths, URL query parameter names, and JSON field names are case sensitive.

  • URL paths use lower case, with dashes separating words.

  • Query parameters and JSON fields use lower case, with underscores separating words.

  • The HTTP status indicates whether an operation failed or succeeded, with extra information included in the HTTP response body.

  • All APIs return standard HTTP error code formats. See Errors.

  • Unexpected query parameters and request body fields are ignored.

  • Our JSON number type is bounded to a signed 32-bit integer.

SparkPost EU

SparkPost EU is the full SparkPost service hosted in Western Europe. SparkPost and SparkPost EU accounts operate independently. An account created in SparkPost cannot be used in SparkPost EU, and vice-versa. You can create accounts in both regions. All documentation here works for both services. When relevant, EU specific links and information will be provided alongside general information.

Feature Availability

SparkPost presents a unified core API to all users with a few noted exceptions. This documentation is meant to serve as reference for all accounts, from Developer to Enterprise. Features that are limited to some accounts will be marked appropriately throughout as:

  • Not available on Enterprise

  • Enterprise only

Rate Limiting

To prevent abuse, our servers enforce request rate limiting, which may trigger responses with HTTP status code 429. The following endpoints are rate limited:

  • /api/v1/message-events

  • /api/v1/metrics/*

The limits are dynamic, but as a general rule, polling these endpoints more than once in 2 minutes may encounter rate limiting and a 429 status code.

Alternatives To Polling: For some common use cases, the API offers more efficient alternatives to polling, especially of the message events endpoint. For instance, A single call to the metrics deliverability summary endpoint offers a summary of deliveries, bounces, opens, clicks, and more for some time period. If your application requires low latency access to each message event, using a webhook-based process will be more efficient than polling message events and will avoid rate limiting.

Sandbox Domain Limits: The sandbox sending domain (sparkpostbox.com) is limited to 5 emails for the lifetime of your account.

Account Suspension

If your account has been suspended due to concern about a possible violation of our Messaging Policy, please reply to the email you should have received from compliance@sparkpost.com.

If you have not received this email, you can still contact the Compliance team directly through the app [EU].

Errors

When you make an API call you may receive an error message in response. Either there is something wrong with your request or something went wrong on our end. Errors respond with an error code and JSON that contains a more precise message, description and API code.

Example Error

422 Unprocessable Entity
{
  "errors": [
    {
      "message": "required field is missing",
      "description": "content object or template_id required",
      "code": "1400"
    }
  ]
}

Error Table

CodeStatus NameDescriptionSuggested Action
400Bad RequestThere is a problem with your request.Check your request follows the API documentation and uses correct syntax.
401UnauthorizedYou don't have the needed authorization to make the request.Make sure you are using a valid API key with the necessary permissions for your request.
403ForbiddenThe server understood the request but refused to fulfill it.See if your SparkPost plan includes the resource you are requesting and your API key has the necessary premissions.
404Not FoundThe server couldn't find the requested file.Change your request URL to match a valid API endpoint.
405Method Not AllowedThe resource does not have the specified method. (e.g. PUT on transmissions)Change the method to follow the documentation for the resource.
409ConflictA conflict arose from your request. (e.g. user already exists with that email)Modify the payload to clear the conflict.
415Unsupported Media TypeThe request is not in a supported format.Check that your Content-Type header is a supported type and that your request adheres to the documentation.
422Unprocessable EntityThe request was syntactically correct but failed due to semantic errors.Make sure that your request includes all of the required fields and your data is valid.
429Exceed Sending LimitYou sent too many requests in a given time period.Check that you are with in the limits of your SparkPost plan. If you are using the sandbox domain you'll need to add a sending domain to continue.
500Internal Server ErrorSomething went wrong on our end.Try the request again later. If the error does not resolve, check our status page for service updates. You can also contact Support from the app [ EU ] if your issue persists.
503Service UnavailableWe are experiencing higher than normal levels of traffic.Try the request again later.