What is the Emarsys API?
The Emarsys API provides programmatic access to the Emarsys Marketing Cloud. The Emarsys API provides a lot of functionality, but most of our customers use it in the following main areas:
The Emarsys API offers a wide range of functions for creating, retrieving, updating and deleting contacts, which can be used to perform ad hoc actions or set up an automated synchronization process.
Pass content for use in email campaigns without having to log in to Emarsys. The API lets you create and save HTML content for emails as well as include files retrieved from the Media Database.
Once the content for an email has been finalized, use the API to launch, schedule and test email campaigns.
Data export and reporting
Keep track of all new contact registrations and follow the response rates for individual campaigns and contacts. These can then be used in an external tool to cross-reference with other statistics, for example web analytics.
Sending transactional messages
Send transactional (real-time) messages by triggering external events associated with an email.
Using the Automation Center
Alternatively, you can also set up Automation Center programs with entry points that are triggered by API calls. A number of different API calls can be used, depending on the desired workflow, e.g. New Contact, Data Change, External Event, etc.
When using the API to launch emails created in the Emarsys application, all links in the HTML and text sources are still automatically tracked. There is no need for an explicit API call for this. Furthermore, you can define the name of the link and its category as special attributes of the HTML tag.
How does it work?
The Emarsys API is available in the api.emarsys.net domain. For each API request, you need your
secret for the API. Ask your Account Owner to create these for you. For more information, see: Security Settings.
If you have already connected successfully to the API, you might want to move straight to the Use Cases, where we show a number of typical scenarios that can be automated via the API.
Every call to the API must be authenticated, which must be done by adding a custom HTTP header (X-WSSE) with your API user name and secret.
In order to keep your API secure, Account Owners can create new API users and matching secret keys regularly in the Security Settings page of the Admin menu.
Here are a few code samples in different languages that you can use to test the authentication:
The header has the following format, usually a single HTTP header line which we have broken down into multiple lines for easier readability:
X-WSSE: UsernameToken Username="customer001", PasswordDigest="ZmI2ZmQ0MDIxYmQwNjcxNDkxY2RjNDNiMWExNjFkZA==", Nonce="d36e316282959a9ed4c89851497a717f", Created="2014-03-20T12:51:45Z"
- X-WSSE - The name of the HTTP header we use for authenticating the request.
UsernameToken - The authentication method, and must contain a
UsernameTokenas we only support token-based authentication.
- Username - This field contains the username you were provided during onboarding. It is usually in the following format: account_name00X, where X is a digit.
- PasswordDigest - This field contains the hashed token which will prove the authenticity of your request. It is essential that you recompute this hash for every request as a hash is only valid for a certain period of time, and then it expires. You can read more about how to compute below.
- Nonce - A random value used to make your request unique so it cannot be replicated by any other unknown party. This string is always 16 bytes long and should be represented as a 32 characters long hexadecimal value.
- Created - This field contains the current UTC, GMT, ZULU timestamp (YYYY-MM-DDTHH:MM:SS) according to the ISO8601 format, e.g. `2014-03-20T12:51:45+01:00`. You can use any timezone you want as long as it is defined in the timestamp, but recommend that you use UTC time as this is the global Emarsys standard.
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.
The list of available endpoints can be found here.
The API demo page
We also 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.
The list of possible error codes and their explanation can be found in the Appendix.