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:
| Variable | Description |
|---|---|
| API_KEY | Used to authenticate requests. Set it to a valid API Key |
| BASE_URL | API 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"
}
]
}