Getting Started with Engage API

This guide walks you through making your first authenticated call to the Mapp Engage REST API.

1. Create an API user

If you do not have an API (or hybrid) user account, one must be created. Any user with user-creation permission can create an API user account.

In Mapp Engage, go to User Management > System User > System User.
On the System Users screen, select Create.
Under the Type drop-down, select API User.
Enter the API user's contact details and set the Role to Client Administrator.
Select Save.

While hybrid users can be used for API accounts, we do not recommend this in production environments for security reasons. Separating API users from UI users makes it much easier to see who made which changes. For more information, see New System User.

2. Authenticate

Both the REST and SOAP APIs use HTTP Basic authentication, which does not use cookies or session tokens. There are no explicit login or logout methods; instead, include an Authorization header in every request. Only system users with the API or Hybrid role can be used.

Build the header from the system user's email address and password, separated by a colon:

j.mcexample@example.com:ThisizAstr0ngPswrd!!_

Base64-encode that string:

ai5tY2V4YW1wbGVAZXhhbXBsZS5jb206VGhpc2l6QXN0cjBuZ1Bzd3JkISFf

The final header is:

Authorization: Basic ai5tY2V4YW1wbGVAZXhhbXBsZS5jb206VGhpc2l6QXN0cjBuZ1Bzd3JkISFf

3. Base URL

The Engage API runs on the same host as your Engage system. To find your base URL, take the URL you use to log in to Engage, drop the page path (such as /home or /login.jsp), and append /api/rest/v19.

For example, if you log in at https://email.yourdomain.com/home/login.jsp, your base URL is https://email.yourdomain.com/api/rest/v19. All endpoints in this documentation are appended to this base URL.

If a URL contains a reserved character, it must be percent-encoded (see Percent-encoding).

4. Request headers

Every request must include these four headers:

Header	Description
`Host`	Your Engage domain hosting the API. It must match the host in the request URL; without it, the request may fail to route correctly or trip our anti-intrusion systems.
`Accept`	The format you want the response in: `application/json` or `application/xml`.
`Content-Type`	The format of the body you send (POST only): `application/json` or `application/xml`.
`Authorization`	`Basic <base64-encoded credentials>` — see step 2.

For POST requests, the request body must match the Content-Type you set. You can validate JSON at jsonlint.com.

5. Example call

Combining the endpoint and headers produces a request like this:

POST https://subdomain.yourdomain.com/api/rest/v19/membership/subscribeByEmail?email=user@example.com&groupId=987654321&subscriptionMode=OPT_IN HTTP/1.1
Host: subdomain.yourdomain.com
Accept: application/json
Content-Type: application/json
Authorization: Basic ai5tY2V4YW1wbGVAZXhhbXBsZS5jb206VGhpc2l6QXN0cjBuZ1Bzd3JkISFf

6. Response codes

The API uses standard HTTP status codes. Two codes indicate success: 200 (success, with data in the response body) and 204 (success, no body returned). For the full list of codes and recommended actions, see Error Handling.

7. Testing

These external tools can help you get started:

Tool	Details
SoapUI	An open-source web service testing tool. Download and install.
Postman	Download and install.
Postman collection	See Use Cases for sample Postman collections.
Example REST project	Example REST project.

Documentation Index