Introduction

What is the Mapp Engage API?

An API (application programming interface) is used to share data between your information system and Mapp Engage. The Mapp Engage web services API connects any program to your marketing platform. You can use the API to send messages, update your blacklist, anonymize contacts, and much more!

We offer and support access via both SOAP (Simple Object Access Protocol) and REST(REpresentational State Transfer) APIs. There are some general differences; which one you use will depend on your preferences. If you have a large amount of data to send, you may wish to use Control XML (CXML). It is a SOAP document with an authentication header and a comprehensive body. In addition to the XML, large attachments with recipient lists can be uploaded.

What can I do with the Engage API?

Lots! For example, you can send messages and create or update contact profiles. Please see our Use Cases for ideas to get you started, or check out the Call for a complete list of available calls.

Watch this video for more details.

What is a REST API?

REST (Representational State Transfer) 

REST often transfers values to the API as key-value pairs in a URL, similar to using a web browser. However, you may need to make more checks on the responses as these are not as strictly described as in SOAP, and there is no absolute enforcement of the required method arguments and endpoints as there is with SOAP.

Request

The requests you send to the API will need to have the following parts:

URL

• https://yourdomain.com/api/rest/v19

  • The URL includes the Domain, version, and should include the method name.

• If the URL contains a reserved character, it must be encoded. Check Percent encoding for more information.

Headers

• Authorization header

• "Accept" header - set desired response format to "application/json" or application/xml"

• "Content-Type" header - set to "application/json" or "application/xml" (POST method only)

Body

(POST method only)

• The content syntax must match the selected content type

• The body syntax can be validated at jsonlint.com

Postman example

In the example below, a POST call is being used to get a specified user by email. Please note that application/JSON is required for both the content type and the accept header.

RESTED example

Rested is another common API tool. The POST call below is adding a user to a group. Like in the Postman example above, the Accept and content-type headers are required.

Responses

When using Mapp Engage REST 2.0 web services, you must check the HTTP header returned to check the status of your request. A response status code may only be set in the header, given that some requests do not send a response back to the client in the HTML body. Please be aware that expected responses and examples can be found in the Swagger for each call.