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:

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:

Environment Setup

Our collection is set up to expect two Postman variables:

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

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:

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