In order to save yourself time and to avoid common pitfalls, we have collected a number of important steps and top-level concepts that you should be aware of before you start using the Emarsys API. We strongly recommend that you read this article immediately and raise any questions with Emarsys Technical Support.
Our goal is to maintain the highest quality of service for all clients, across all our environments. For this reason we have set a limit of 200 requests per minute. If you require this limit must be set to a higher level, please contact us to discuss them and we can adjust our service according to your needs. Requests are associated with your API key.
If the rate limit is exceeded, we might block your requests depending on the load of our servers. To avoid this, you will need to implement error handling and monitoring for your client.
The Emarsys API server sets the following rate limiting related headers:
- X-RateLimit-Limit: Request limit per minute.
- X-Ratelimit-Remaining: The number of requests left for the time window.
- X-RateLimit-Reset: The time at which the current rate limit window resets. It is a unix timestamp.
Requests over the rate limit will be blocked with a 429 Too Many Requests status code according to the Additional HTTP Status Codes (RFC6585) standard. Please respect this message and monitor your API client for errors like this.
There is also a general 8MB limit for request payload size.
Request and response format
The Emarsys API is a JSON-based API. As a request, you have to provide the
Content-Type: application/json header in the
POST requests to the endpoints, together with the necessary variables in JSON format. As a response, you will receive a
HTTP Status, a
Content-Type parameter and, if applicable, a response body in JSON format.
Successful requests get the 200 OK HTTP Status, while in case of any errors, the response's HTTP Status will be in the 300, 400 or 500 region. For more information see the appendix on Error codes.