{"componentChunkName":"component---src-templates-api-js","path":"/api/","result":{"data":{"allApiBlueprint":{"edges":[{"node":{"meta":{"title":"A/B Testing API","label":"New"},"fields":{"path":"/api/ab-testing/","file":"ab-testing.apib"}}},{"node":{"meta":{"title":"Data Privacy API","label":"New"},"fields":{"path":"/api/data-privacy/","file":"data-privacy.apib"}}},{"node":{"meta":{"title":"Events API","label":null},"fields":{"path":"/api/events/","file":"events.apib"}}},{"node":{"meta":{"title":"Ingest API","label":"Private Access"},"fields":{"path":"/api/events-ingest/","file":"events-ingest.apib"}}},{"node":{"meta":{"title":"Inbound Domains API","label":null},"fields":{"path":"/api/inbound-domains/","file":"inbound-domains.apib"}}},{"node":{"meta":{"title":"Account API","label":null},"fields":{"path":"/api/account/","file":"account.apib"}}},{"node":{"meta":{"title":"API Overview","label":null},"fields":{"path":"/api/","file":"index.apib"}}},{"node":{"meta":{"title":"Automatic Inline Seeding","label":"Deliverability"},"fields":{"path":"/api/inline-seeds/","file":"inline-seeds.apib"}}},{"node":{"meta":{"title":"Labs APIs","label":null},"fields":{"path":"/api/labs/","file":"labs.apib"}}},{"node":{"meta":{"title":"Message Events API","label":null},"fields":{"path":"/api/message-events/","file":"message-events.apib"}}},{"node":{"meta":{"title":"Recipient Validation API","label":"New"},"fields":{"path":"/api/recipient-validation/","file":"recipient-validation.apib"}}},{"node":{"meta":{"title":"IP Pools API","label":null},"fields":{"path":"/api/ip-pools/","file":"ip-pools.apib"}}},{"node":{"meta":{"title":"Seed List API","label":"Deliverability"},"fields":{"path":"/api/seed-list/","file":"seed-list.apib"}}},{"node":{"meta":{"title":"Bounce Domains API","label":null},"fields":{"path":"/api/bounce-domains/","file":"bounce-domains.apib"}}},{"node":{"meta":{"title":"Recipient Lists API","label":null},"fields":{"path":"/api/recipient-lists/","file":"recipient-lists.apib"}}},{"node":{"meta":{"title":"Sending IPs API","label":null},"fields":{"path":"/api/sending-ips/","file":"sending-ips.apib"}}},{"node":{"meta":{"title":"Relay Webhooks API","label":null},"fields":{"path":"/api/relay-webhooks/","file":"relay-webhooks.apib"}}},{"node":{"meta":{"title":"SMTP API","label":null},"fields":{"path":"/api/smtp/","file":"smtp.apib"}}},{"node":{"meta":{"title":"Snippets API","label":"New"},"fields":{"path":"/api/snippets/","file":"snippets.apib"}}},{"node":{"meta":{"title":"Subaccounts API","label":null},"fields":{"path":"/api/subaccounts/","file":"subaccounts.apib"}}},{"node":{"meta":{"title":"Sending Domains API","label":null},"fields":{"path":"/api/sending-domains/","file":"sending-domains.apib"}}},{"node":{"meta":{"title":"Suppression List API","label":null},"fields":{"path":"/api/suppression-list/","file":"suppression-list.apib"}}},{"node":{"meta":{"title":"Template Language","label":null},"fields":{"path":"/api/template-language/","file":"template-language.apib"}}},{"node":{"meta":{"title":"Tracking Domains API","label":null},"fields":{"path":"/api/tracking-domains/","file":"tracking-domains.apib"}}},{"node":{"meta":{"title":"Templates API","label":null},"fields":{"path":"/api/templates/","file":"templates.apib"}}},{"node":{"meta":{"title":"Transmissions API","label":null},"fields":{"path":"/api/transmissions/","file":"transmissions.apib"}}},{"node":{"meta":{"title":"Event Webhooks API","label":null},"fields":{"path":"/api/webhooks/","file":"webhooks.apib"}}},{"node":{"meta":{"title":"Usage API","label":null},"fields":{"path":"/api/usage/","file":"usage.apib"}}},{"node":{"meta":{"title":"Metrics API","label":null},"fields":{"path":"/api/metrics/","file":"metrics.apib"}}}]},"apiBlueprint":{"ast":{"element":"parseResult","content":[{"element":"category","meta":{"classes":{"element":"array","content":[{"element":"string","content":"api"}]},"title":{"element":"string","content":"SparkPost API"}},"attributes":{"meta":{"element":"array","content":[{"element":"member","meta":{"classes":{"element":"array","content":[{"element":"string","content":"user"}]}},"content":{"key":{"element":"string","content":"FORMAT"},"value":{"element":"string","content":"1A"}}},{"element":"member","meta":{"classes":{"element":"array","content":[{"element":"string","content":"user"}]}},"content":{"key":{"element":"string","content":"title"},"value":{"element":"string","content":"API Overview"}}},{"element":"member","meta":{"classes":{"element":"array","content":[{"element":"string","content":"user"}]}},"content":{"key":{"element":"string","content":"description"},"value":{"element":"string","content":"Documentation for sending via SMTP or HTTP with the SparkPost API."}}},{"element":"member","meta":{"classes":{"element":"array","content":[{"element":"string","content":"user"}]}},"content":{"key":{"element":"string","content":"full"},"value":{"element":"string","content":"true"}}}]}},"content":[{"element":"copy","content":"Welcome to the SparkPost API Reference. If you're new to SparkPost, [create an account](https://app.sparkpost.com/join) ([EU](https://app.eu.sparkpost.com/join))\nand follow [this guide](https://www.sparkpost.com/docs/getting-started/getting-started-sparkpost/) to get started.\n\n## Endpoints\n\nAll calls to the API need to start with the appropriate base URL:\n\n| | |\n| ---------------------------------------- | ------------------------------------- |\n| **SparkPost** | `https://api.sparkpost.com/api/v1` |\n| **[SparkPost EU](#header-sparkpost-eu)** | `https://api.eu.sparkpost.com/api/v1` |\n\nFor Enterprise accounts with their own endpoint, please contact your account manager for more information.\n\n## Authentication\n\nAuthenticate each request by setting the \nAuthorization header with a valid API key. Create and manage your API Keys in the [app](https://app.sparkpost.com/account/api-keys) ([EU](https://app.eu.sparkpost.com/account/api-keys)).\n\nWe accept just the API key:\n\n```\n\"Authorization\": \"14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf\"\n```\n\nWe 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:`.\n\n```\n\"Authorization\": \"Basic MTRhYzU0OTljZmRkMmJiMjg1OWU0NDc2ZDJlNWIxZDJiYWQwNzliZjo=\"\n```\n\nMake sure to store your API keys somewhere secure and never share them publicly.\n\n## API Examples\n\n### cURL\n\nIf 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 `&`.\n\nFor example:\n\n```\ncurl -v \\\n-H \"Content-Type: application/json\" \\\n-H \"Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf\" \\\n-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\"\n```\n\nUsing the `-u` flag for Basic authentication:\n\n```\ncurl -v \\\n-H \"Content-Type: application/json\" \\\n-u 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf: \\\n-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\"\n```\n\n### Postman\n\nIf you use Postman you can click the following button to import the SparkPost API as a collection:\n\n[](https://god.postman.co/run-collection/ee44dcd644445e8bd864?action=collection%2Fimport)\n\n**Environment Setup**\n\nOur collection is set up to expect two Postman variables:\n\n| Variable | Description |\n| -------- | ---------------------------------------------------------------------------------- |\n| API_KEY | Used to [authenticate](#header-authentication) requests. Set it to a valid API Key |\n| BASE_URL | [API Hostname](#header-endpoints) to be used. |\n\nMore information on setting up Postman environments and variables can be found [here](https://learning.postman.com/docs/sending-requests/variables).\n\n### Client Libraries\n\nSparkPost has several official and community supported client libraries. Check out our [Developer Hub](https://developers.sparkpost.com) or our [GitHub](https://github.com/sparkpost) for examples in your favorite language.\n\n## API Conventions\n\n- Trailing slashes are ignored: /transmissions is equivalent to /transmissions/.\n\n- URL paths, URL query parameter names, and JSON field names are case sensitive.\n\n- URL paths use lower case, with dashes separating words.\n\n- Query parameters and JSON fields use lower case, with underscores separating words.\n\n- The HTTP status indicates whether an operation failed or succeeded, with extra information included in the HTTP response body.\n\n- All APIs return standard HTTP error code formats. See [Errors](#header-errors).\n\n- Unexpected query parameters and request body fields are ignored.\n\n- Our JSON number type is bounded to a signed 32-bit integer.\n\n## SparkPost EU\n\nSparkPost EU is the full SparkPost service hosted in Western Europe. [SparkPost](https://app.sparkpost.com/)\nand [SparkPost EU](https://app.eu.sparkpost.com/) accounts operate independently.\nAn account created in SparkPost cannot be used in SparkPost EU, and vice-versa.\nYou can create accounts in both regions. All documentation here works for both services.\nWhen relevant, EU specific links and information will be provided alongside general information.\n\n## Feature Availability\n\nSparkPost presents a unified core API to all users with a few noted exceptions.\nThis documentation is meant to serve as reference for all accounts, from Developer to Enterprise.\nFeatures that are limited to some accounts will be marked appropriately throughout as:\n\n- **Not available on Enterprise**\n\n- **Enterprise only**\n\n## Rate Limiting\n\nSparkPost 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.\n\nThe Transmissions API POSTs are not rate-limited in this way although DELETE requests are. Some customers may have daily or monthly [sending limits](https://developers.sparkpost.com/api/transmissions/#header-sending-limits) which may trigger a 420.\n\n### Alternatives To Polling\n\nFor 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](/api/metrics/#metrics-get-metrics-summary)\nendpoint offers a summary of deliveries, bounces, opens, clicks, and more for some time period.\nIf your application requires low latency access to each event, using a [webhook-based](/api/webhooks/)\nprocess will be more efficient than polling message events and avoids rate limiting.\n\n**Sandbox Domain Limits:** The sandbox sending domain (`sparkpostbox.com`) is limited to 5 emails for the lifetime of your account.\n\n## Account Suspension\n\nIf your account has been suspended due to concern about a possible violation of our [Messaging Policy](https://www.sparkpost.com/policies), please reply to the email you should have received from compliance@sparkpost.com.\n\nIf you have not received this email, you can still contact the Compliance team directly [through the app](https://app.sparkpost.com/?supportTicket=true&issueId=account_suspension) [\\[EU\\]](https://app.eu.sparkpost.com/?supportTicket=true&issueId=account_suspension).\n\n## Errors\n\nWhen 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.\n\n### Example Error\n\n```\n422 Unprocessable Entity\n```\n\n```\n{\n \"errors\": [\n {\n \"message\": \"required field is missing\",\n \"description\": \"content object or template_id required\",\n \"code\": \"1400\"\n }\n ]\n}\n```\n\n### Error Table\n\n| Code | Status Name | Description | Suggested Action |\n| ---- | ------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 400 | Bad Request | There is a problem with your request. | Check your request follows the API documentation and uses correct syntax. |\n| 401 | Unauthorized | You 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. |\n| 403 | Forbidden | The 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. |\n| 404 | Not Found | The server couldn't find the requested file. | Change your request URL to match a valid API endpoint. |\n| 405 | Method Not Allowed | The resource does not have the specified method. (e.g. PUT on transmissions) | Change the method to follow the documentation for the resource. |\n| 409 | Conflict | A conflict arose from your request. (e.g. user already exists with that email) | Modify the payload to clear the conflict. |\n| 413 | Request Entity Too Large | The size of the request exceeds the limit. | Check the documented limit for the API and reduce the size of the request. |\n| 415 | Unsupported Media Type | The 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. |\n| 420 | Exceed Sending Limit | You 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. |\n| 422 | Unprocessable Entity | The 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. |\n| 429 | Too Many Requests | You 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. |\n| 500 | Internal Server Error | Something went wrong on our end. | Try the request again later. If the error does not resolve, check [our status page](https://status.sparkpost.com/) for service updates. You can also contact Support [from the app](https://app.sparkpost.com/?supportTicket=true) \\[[EU](https://app.eu.sparkpost.com/?supportTicket=true)] if your issue persists. |\n| 503 | Service Unavailable | We are experiencing higher than normal levels of traffic. | Try the request again later. |"}]}]},"TableOfContents":[{"anchor":"#header-endpoints","title":"Endpoints"},{"anchor":"#header-authentication","title":"Authentication"},{"anchor":"#header-api-examples","title":"API Examples","children":[{"anchor":"#header-curl","title":"cURL"},{"anchor":"#header-postman","title":"Postman"},{"anchor":"#header-client-libraries","title":"Client Libraries"}]},{"anchor":"#header-api-conventions","title":"API Conventions"},{"anchor":"#header-sparkpost-eu","title":"SparkPost EU"},{"anchor":"#header-feature-availability","title":"Feature Availability"},{"anchor":"#header-rate-limiting","title":"Rate Limiting","children":[{"anchor":"#header-alternatives-to-polling","title":"Alternatives To Polling"}]},{"anchor":"#header-account-suspension","title":"Account Suspension"},{"anchor":"#header-errors","title":"Errors","children":[{"anchor":"#header-example-error","title":"Example Error"},{"anchor":"#header-error-table","title":"Error Table"}]}],"meta":{"title":"API Overview","description":"Documentation for sending via SMTP or HTTP with the SparkPost API.","full":true},"fields":{"path":"/api/"}}},"pageContext":{"file":"index.apib"}},"staticQueryHashes":["1319884646","1428769721","3859448388"]}