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 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 an API user and matching secret key under Management > Security Settings. For details, see API Users.
- Make sure that your API user has all of the necessary access privileges. Access privileges can be granted in the Security setting page. API users 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.
Resources
Go to the developer hub directly to find endpoint specifications and definitions.
All endpoint specifications are provided in OpenAPI 2.0 (Swagger) and RAML 0.8 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 with your real data right here on the Developer Hub.
Proceed with care, this functionality is not a sandbox! Any changes to contact or campaign data will have a real effect on your account (i.e. if you test Delete a Contact, the contact you use for the test will be deleted).
- Select the endpoint you want to test.
- Click Try it out.
- Fill in your authentication information in the navigation bar.
- Provide the required parameters.
- Click Send request.
Your request is sent to our servers and returns real data.
Code samples and specifications are also at your fingertips. Go to the Code Generation tab at the endpoint page to find production-ready code samples for each endpoint in multiple languages. You can insert it into your code with a simple copy and paste.
Curl commands are also available in the code samples.
Postman Collection
If you prefer Postman, download our categorized libraries that contain all endpoints with examples.
You must compute the WSSE header value manually when using Postman and insert it into the X-WSSE header.
The API Demo Page
We provide a demo page where you can experiment with the API capabilities. This has a graphical user interface allowing experimentation with API requests and their parameters. The responses are then displayed so users can see what to expect.
- To access the demo environment, visit https://api.emarsys.net/api-demo.
- To check whether the access data is valid, make a test request to see what languages are available. For this, go to the Contact Fields tab. Leave the Language code field empty and click OK. The response will appear on the right of the same page, including some information about the request. The following table shows the possible responses and the reasons for failure.
| Response (replyCode, replyText) |
Possible Reason |
Suggested Solution |
|---|---|---|
| 0, OK |
You succeeded, and your credentials were accepted. |
You should see the list of the languages. |
| 1, Unauthorized |
Something is wrong with your credentials. |
Check your access information again. |
| No response at all |
|
|
The response of your request always appears in the top right of the page so, after sending a request, don’t forget that you might need to scroll up to see the response.
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 mutliple calls simultaneously.