1) User Creation

If you do not have an API (Or hybrid) User account, one must be created. Any user who has user creation permission can create an API user account. 

  1. In Mapp Engage, select User Management > System User > System User
  2. In the System Users Screen, Select Create
  3. Under the Type drop-down, select API User
  4. Enter your API user's contact details, and make sure the Role is set to Client Administrator
  5. Select Save

Please note, that while hybrid users can be used for API accounts, we do not recommend this approach. The separation of API and User Interface users and their activities in your company's account makes it much easier to see who exactly made the changes. 


For more information on this, please see New System User.

2) Sending A Request

Authorization & Permissions

Both SOAP and REST API use HTTP basic authentication method that does not require cookies or session tokens. For this reason, there are no explicit login and logout methods.
Instead, the authorization header (encoded in Base64) must be included in each API request. You can create this yourself based on the username and password of the API User in your specific platform.

The example header for 'j.mcexample@example.com' user and 'ThisizAstr0ngPswrd!!_' password is the following:

Authorization: Basic ai5tY2V4YW1wbGVAZXhhbXBsZS5jb20gcHc6IFRoaXNpekFzdHIwbmdQc3dyZCEhXw==
CODE

Only API and Hybrid user credentials can be used to build this Basic Auth Header to be used in the API call. 

Host header

Users connecting to the Mapp Engage API should ensure that their web service clients correctly add or include the Host header in the HTTP header. The domain name sent in the HTTP header must be identical to the web service URL you are connecting to. Our web services require that the host header value be set as this will be used along and in parallel with the requested URL when connecting to our servers.

Host: yourdomain.com
CODE

Without this host header, there could be issues when connecting to the correct service and server, and it could also trip our anti-intrusion systems.

In the example below, not only is the HTTP REST request being requested by GET to the domain cook.shortest-route.com but in the HTTP header, the corresponding virtual host is also specified in the "Host" field.

GET https://yourdomain.com/api/rest/v9/contact/anonymize?contactId=12345678901┬ČificationRecipient=system.user@example.tld HTTP/1.1
Host: yousdomain.com.com
User-Agent: Rest Webservice Test Client 1.0
Accept: application/json
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate, br
Content-Type: application/json
Authorization: Basic QXNJZklXb3VsZFB1dEFSZWFsVXNlcm5hbWVIZXJlOlRoaXNJc05vdEFQYXNzd29yZA==
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
JS

Domains

API calls are grouped within functional test domains. A full list of domains and calls can be found in our Swagger documentation. You can also find the domains below. 

 Click here to expand...

REST

SOAP

Description

async

async

Contains methods for response queue.

automation

automation

Contains methods for automation in Mapp Engage.

blacklist

blacklist

Contains methods to manage the system and group blacklists.

cms

cms

Contains methods to manage messages stored in the CMS.

contact

contact

Contains methods for contact management.

user

user

Contains more methods for contact management.

content

content

Contains methods to manage elements in the Content Store.

draftmessage

draftmessage

Contains methods for working with messages saved as a draft.

group

group

Contains all group-related methods.

landingpage

landingpage

Contains methods to manage landing pages.

membership

membership

Contains methods to manage group memberships.

message

message

Contains methods to manage email and SMS messages.

meta

meta

Contains methods that define your system.

mobile

n/a

The mobile domain contains methods to manage approx properties

preparedmessage

preparedmessage

A prepared message is a saved message assigned to a group.

process

process

Contains methods to interact with a process in Mapp Engage.

relatedData

relateddata

Contains methods to manage records stored in Related Data.

system

system

Contains methods about the current version of the system.

systemuser

systemuser

Contains methods related to the system user.

usagestatistics

usagestatistics

Contains methods pertaining to usage statistics.

Versioning

Contact Mapp Technical Support to confirm if you have the latest version. At the moment this is v19.


3) Testing

Here are some outside tools which may help you get started using API:

ToolLink
SoapUI

An open-source web service testing tool

Download and install

PostmanDownload and install
To setup REST projectExample REST project
To setup SOAP projectExample SOAP project
To setup Control XML projectExample Control XML project
To setup SOAP 1.0 (deprecated)Example SOAP 1.0


Related Topics

Engage API implementation and error-handling recommendations

Use Cases

Soap vs Rest

Rest Documentation

SOAP UI