SparkPost API

Welcome to the SparkPost API Reference. If you're new to SparkPost, create an 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"

We also support Basic authentication where the username is the API key and the password is an empty string. For instance, the Authorization header's value is the word Basic followed by the base64-encoded string 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf:.

"Authorization": "Basic MTRhYzU0OTljZmRkMmJiMjg1OWU0NDc2ZDJlNWIxZDJiYWQwNzliZjo="

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?campaigns=testjob&from=2022-02-01T14:00&metrics=count_targeted,count_sent,count_accepted&timezone=America%2FNew_York&to=2022-02-02T15:50"

Using the -u flag for Basic authentication:

curl -v \
-H "Content-Type: application/json" \
-u 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf: \
-X GET "https://api.sparkpost.com/api/v1/metrics/deliverability?campaigns=testjob&from=2022-02-01T14:00&metrics=count_targeted,count_sent,count_accepted&timezone=America%2FNew_York&to=2022-02-02T15: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

SparkPost APIs are rate limited, which limits how often each user can call the API, in order to protect the service from inadvertent or malicious overuse. If you exceed the limits for an API you will receive an HTTP status code 429. These limits are dynamic, but as a general rule, wait 1 to 5 seconds after receiving a 429 response before requesting again. Heavier usage patterns may require a more sophisticated and incremental backoff strategy.

The Transmissions API POSTs are not rate-limited in this way although DELETE requests are. Some customers may have daily or monthly sending limits which may trigger a 420.

Alternatives To Polling

For some common use cases, the API offers more efficient alternatives to polling, especially of the Events endpoint. For example, 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 event, using a webhook-based process will be more efficient than polling message events and avoids 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.
413Request Entity Too LargeThe size of the request exceeds the limit.Check the documented limit for the API and reduce the size of the request.
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.
420Exceed Sending LimitYou exceeded your daily, monthly, or sandbox sending limit.Check that you are within the limits of your SparkPost plan. If you are using the sandbox domain, then you'll need to add a sending domain to continue.
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.
429Too Many RequestsYou sent too many requests in a given time period.Wait 1 to 5 seconds before making another request. Heavier usage patterns may require a more sophisticated and incremental backoff strategy.
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.