---
title: "Sending Transactional Messages (API)"
slug: "send-transactional-messages-api"
description: "Send transactional emails from an external system through the Mapp Engage API, with a unique TMID for each message and optional order data."
status: "update"
updated: 2026-11-06T16:02:29Z
published: 2026-11-06T16:02:29Z
canonical: "docs.mapp.com/send-transactional-messages-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.

# Sending Transactional Messages (API)

## Goal

Send transactional email messages from an external system, such as a web shop or a CRM, through the Mapp Engage API. Each message gets a unique TMID, so you can track it individually.

For the concept and the TMID modes, see [Transactional Messages](/v1/docs/transactional-messages).

---

## Choose Where the TMID Comes From

Decide first whether your external system or Mapp Engage creates the TMID. Your choice determines the group setting and the API call.

| Your setup | Transactional Message Mode | API call |
| --- | --- | --- |
| Your external system creates a unique TMID for each message. | **Off** | Pass the TMID in the call, for example with `messageSendTransactional` or `/message/sendTransactionalWithEventDetails`. |
| Mapp Engage creates the TMID. | **On** | Send the call without a TMID, for example with `messageSendSingle`. Mapp Engage creates the TMID from the pattern of the group. |
| Some calls contain a TMID, others do not. | **Optional** | Pass the TMID where you have one. Mapp Engage creates a TMID for calls without one. |

---

## Procedure

### Step 1: Create a System User for the API

Your external system needs a system user to call the API.

1. Go to *User Management > System Users > System Users*.
2. Click **Create**.
3. Enter the required user information.
4. Click **Save**.

For details, see [Create Mapp Engage System User](/v1/docs/create-mapp-engage-system-user).

### Step 2: Create a Group for Transactional Messages

Create a separate group for the recipients of transactional messages. This keeps them apart from your marketing and newsletter subscribers, who have given a different consent.

1. Go to *Audience > Group Management > Groups*.
2. Create a group.
3. In **Sendout Options**, set **Transactional Message Mode** to the mode you chose above.
4. If you chose **On** or **Optional**, define the TMID pattern. See [Set Up a TMID for Transactional Messages](/v1/docs/add-a-tmid-to-messages).

> [!NOTE]
> Note
> 
> If you send a transactional message to a contact who is not a member of the group, Mapp Engage adds the contact to the group.

### Step 3: Create the Message as a Prepared Message

Create an email message with the content of your transactional message. Save it as a prepared message in the group from step 2. For the steps, see [Create a Prepared Message](/v1/docs/save-draft-as-prepared-message) and [Create an HTML Email Message](/v1/docs/create-an-email-message).

The following sample uses a standard attribute (`FirstName`), a custom attribute (`DeliveryLocation`), and a parameter that the external system sends with the API call (`productName`):

```xml
<html>
  <body>
    <p>Hi <%${user['FirstName']}%>,</p>

    <p>The item you requested has been ordered for delivery to our
    <%${user.CustomAttribute['DeliveryLocation']}%>.</p>

    <p>Product name: <%${parameter['productName']}%></p>

    <p>We will send you a notification when the item is available for pickup.</p>

    <p>Best regards,<br/>Your Company</p>
  </body>
</html>
```

### Step 4: Call the API

Your external system calls the API method that matches your mode. The call must:

- identify the contact, or create the contact if it does not exist,
- reference the prepared message,
- contain the TMID, if your system creates it,
- contain the parameters that the message uses.

For the API methods and their parameters, see [Engage API](/v1/docs/engage-api). To pass order data, such as the products of an order, with the message, see [Injection of Transactional Data into Mapp Engage](/v1/docs/injection-of-transactional-data-into-mapp-engage).

> [!NOTE]
> Note
> 
> For older integrations based on API 1.0, use `sendParametrizedSingleMessageToUser`. Pass the TMID as a parameter and use the placeholder `&lt;%parameter.YourParameterName%&gt;` as the TMID pattern of the group.