The Emarsys API provides programmatic access to most functions of the Emarsys Marketing Platform, giving you the tools to integrate with us and automate your marketing campaigns.
- Integration enables you to access most functionalities of the Emarsys Platform directly from your own application.
- Automation provides a way to set up complex marketing campaigns that run without the need for any human interaction on your side.
About the Emarsys Developer Hub
We do have a List of all public API endpoints on this Help Portal, but the bulk of our technical content is on our Developer Hub.
This resource features guides, resources, use cases and interactive reference that helps you integrate with the Emarsys Marketing Platform to deliver personal customer interactions across email, mobile, social, SMS and web.
Ready to jump in? Continue on the Emarsys Developer Hub.
Before You Start
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.
Don't worry, you will make your first successful API call in a couple of minutes. But there are a couple of housekeeping items you need to do first:
- Your company has completed the relevant parts of your onboarding journey: data onboarding and activation of the channels you will be using.
- You have read the Before You Start section and got familiar with the basics of how our RESTful API works and what it has to offer.
- Your account owner has set up API Credentials and matching secret key under Management > Security Settings. For details, see API Credentials.
- Make sure that your API Credentials are accompanied by the necessary access privileges. Access privileges can be granted in the Security setting page. API endpoints do not have all privilege enabled by default. If privileges are not set up right, certain functions of the API are not usable, the call results in a
403 Forbiddenerror. See API permission system for details.
Before using our API, we strongly recommend that you read the following guides to learn about concepts, architecture and best practices.
- Learn the basics - Learn the core Emarsys concepts and how our RESTful API is designed, including authentication, rate limiting, and request structures.
- Take the first steps - Follow our guide to get up an running in a heartbeat.
After completing the first steps, visit the endpoint reference to see and test available endpoints in real-time with your own data. We also provide code samples, a comprehensive Postman collection as well as specification in OpenAPI and RAML formats on the developer hub.
Configuration and usage of OpenID Connect
Our OpenID Connect solution is based on OAuth 2.0 and JWT technology. For more information, see RFC6749 and RFC7519.
Here are the steps to configure your API setup and to make your first call:
- On the Security Settings page, create your API credentials by selecting OpenID Connect.
Make sure to note down the API Client Secret value, as this is the only time it is displayed. Make also note of your Client ID and the Token Endpoint values.
- Acquire your JSON Web Token (JWT) using the OAuth 2.0 client credentials grant. Here is an example call for that. Replace
locationvalue, as well asclientIdandclientSecretwith the values obtained in the previous step:
curl -i -X POST --location https://auth.emarsys.net/oauth2/token \
-H 'Authorization: Basic base64(clientId:clientSecret)' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-d 'grant_type=client_credentials'
- With the JWT, you can make your first call:
curl --location 'https://api.emarsys.net/api/v3/settings' \
-H 'Authorization: Bearer JWT'
Make sure to use v3 in the URL for the location.
For more information, visit our Developer Portal.
Resources
Go to the developer hub directly to find endpoint specifications and definitions.
All endpoint specifications are provided in JSON and YAML formats as well as a Postman collection on the developer hub.
| Section | Contents |
|---|---|
| Before You Start | Learn the core Emarsys concepts and how our RESTful API is designed. |
| First Steps | Follow our step-by-step guide if you are new to the platform. |
| Endpoints | Check out available endpoints, and test them on the fly with your own data. |
| Personalization |
|
| Response Codes |
|
| Appendix |
|
| Changelog | See release notes and follow the changes related to the Emarsys API and the Developer Hub. |
Interactive Demo Options
Experiment before you code! To help you build your integration, we offer multiple options for testing your implementation.
Emarsys Developer Hub
You can test every endpoint by using mock servers provided by the host of the Developer Hub.
You can try the endpoints with mock data and look for static or dynamic acknowledgements or error messages.
Curl commands and other languages are also available in the code samples.
Postman Collection
If you prefer using Postman, feel free to visit our guide on its usage in our public repository in GitHub.
Bruno
As a free alternative to Postman collection, you can install Bruno locally and add the necessary files, as described in our guide.
Command Line
API retries
It is a good idea to include retry mechanisms in workflows that use API calls.
Error messages after an unsuccessful API call attempt may result from either local or global temporary network connection issues. Various errors and outages that affect the success of our communication may occur outside our systems. In this case, the problem can often be fixed by a simple retry.
A good example for a workflow where a retry mechanism can help is when you receive "HTTP 503 / The system is overloaded for this resource." responses to your call.
Time the retry, make sure that it is not done straight after the receiving the HTTP 503 error. Delay the API retry attempt with 3-4 minutes, or schedule it to a period that is surely inactive on your side so you are not sending multiple calls simultaneously.