---
title: "Getting Started with Engage API"
slug: "getting-started-with-engage-api"
updated: 2026-07-31T08:01:22Z
published: 2026-07-31T08:01:22Z
canonical: "docs.mapp.com/getting-started-with-engage-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

1. In Mapp Engage, go to *User Management > System User > System User*.
2. On the System Users screen, select **Create**.
3. Under the **Type** drop-down, select **API User**.
4. Enter the API user's contact details and set the **Role** to **Client Administrator**.
5. 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](https://docs.mapp.com/docs/new-system-user-window).

## 2. Authenticate

Both the REST and SOAP APIs use [HTTP Basic authentication](https://en.wikipedia.org/wiki/Basic_access_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:

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

Base64-encode that string:

```plaintext
ai5tY2V4YW1wbGVAZXhhbXBsZS5jb206VGhpc2l6QXN0cjBuZ1Bzd3JkISFf
```

The final header is:

```plaintext
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](https://en.wikipedia.org/wiki/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](https://jsonlint.com/).

## 5. Example call

Combining the endpoint and headers produces a request like this:

```plaintext
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](/v1-api/apidocs/engage-api-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](https://www.soapui.org/). |
| **Postman** | [Download and install](https://www.getpostman.com/). |
| **Postman collection** | See [Use Cases](/v1-api/apidocs/use-cases-engage-api) for sample Postman collections. |
| **Example REST project** | [Example REST project](https://documentation.mapp.com/download/attachments/36145917/rest-v19-soapui-project.xml?version=1&modificationDate=1662640985000&api=v2). |