Logo Help Portal
  • Getting Started

    Introduction

    • Onboarding overview
    • Project Initiation
    • Email compliance
    • Account Administration

    Data

    • Data exchange
    • Data onboarding
    • Web data collection
    • Strategic Platform Integrations

    Channels

    • Email onboarding
    • Smart Insight
    • Predict
  • Training

    Resources

    • Introduction
    • Online Self-learning
    • Onboarding Videos

    Events

    • Instructor-led Training
    • Webinars
    • Seminars
    • Training Calendar
  • User Guides

    Strategy

    • Personalization
    • Automation
    • Data Monitoring

    Channels

    • Email
    • Mobile Apps
    • Web
    • Ads
    • SMS

    Add-ons

    • Smart Insight
    • Predict
    • Incentive Recommendation
    • AIM
    • Relational Data
  • News & Support
    Forrester Wave CCCM (Independent Platforms) Report Q4 2019

    News

    • What’s New in the Emarsys Platform
    • Updates from the CSA
    • Pilot-Features
    • Articles on Data Protection and GDPR

    Support

    • Help and Support at Emarsys
    • Managing your user profile
    • Preparing for Black Friday 2019
    • Black Friday 2019 - Best practices
  • |
  • Partners

    Enhance Partners

    • Getting Started as an Emarsys Partner
    • The Emarsys Integration Platform
    • Automation Center Integrations
  • Developers
  • System Status
Need help?
English Deutsch Español Français Русский Türkçe 简体中文 Test New Chat
Sign in
  • Getting Started
  • Preparing for Integration
  • 0 Getting Started Preparing for Integration

In this section:

  • Data exchange resources
  • Strategic platform integrations
  • Preparing your product data file
  • Preparing your sales data file
  • Using the Google Product Feed format
  • Migrating your first email campaigns
  • Preparing your account assets
  • Migrating your brand assets
  • Introduction to the Emarsys API
EDIT
Expand all

Introduction to the Emarsys API

Updated: June 14, 2019 09:39

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.

Contents:

  • About the Emarsys Developer Hub
  • Before You Start
  • Resources
  • Interactive Demo Options
    • Emarsys Developer Hub
    • Postman Collection
    • The API Demo Page
    • Command Line

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 Admin > Security Settings. For details, see API Users.

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
  • Email status and error codes
  • Conditional placeholders
  • Personalization placeholders
  • System fields
Response Codes
  • Emarsys response codes
Glossary
  • Common terminology
Appendix
  • Language codes
  • Timezones
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).

  1. Select the endpoint you want to test.
  2. Click Try it out.
  3. Fill in your authentication information in the navigation bar.
  4. Provide the required parameters.
  5. 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
  • Something is wrong with your connection.
  • The API URL is invalid.
  • The Emarsys API is not available.
  • Check with your IT support why you cannot reach the API (e.g. if the traffic is blocked by your firewall.)
  • Check your access information again.
  • Please try again later.

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

For the traditionalists among you, we recommend using HTTPie with our WSSE plugin for HTTPie that you can clone from GitHub.

Was this article helpful?

Have more questions? Submit a request
Return to top

Emarsys is a Leader

You may also be interested in:

Related articles

  • List of all public API endpoints
  • Overview:: Data Import - Overview
  • Overview:: Triggered Email - Overview
  • Preparing your sales data file
  • Strategic platform integrations
Copyright © 2019 Emarsys eMarketing Systems. All rights reserved
Legal Notice Privacy Policy Master Services Agreement Anti-spam Policy