---
title: "Sending Transactional Messages (API)"
slug: "send-transactional-messages-api"
updated: 2025-05-26T14:11:45Z
published: 2025-05-26T14:11:45Z
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 messages using the Mapp Engage API with unique tracking per contact.

## Workflow Options

Transactional messages in Mapp Engage require a Transactional Message ID (TMID) to track each message per contact. There are two supported workflows depending on where the TMID comes from:

| Workflow | When to Use | Group Setting | API Method | TMID Handling |
| --- | --- | --- | --- | --- |
| **TMID from an external system** | Your CRM or backend system can generate a unique TMID per message | *Transactional Message Mode = Off* | `messageSendTransactional` or `/message/sendTransactionalWithEventDetails` | TMID is passed in the API call from your external system |
| **TMID generated by Mapp Engage** | Your system cannot generate TMIDs | *Transactional Message Mode = On* | `messageSendSingle` | Mapp Engage creates the TMID based on personalization rules |

> [!NOTE]
> Note on Compliance
> 
> Often, transactional recipients have not opted in to receive marketing emails. To stay compliant, manage these contacts in a dedicated group that is kept separate from marketing or newsletter subscribers.

---

## Procedure

#### Step 1: Create an API User Account​

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

For more information on creating an API user account, see [Create Mapp Engage System User](/v1/docs/create-mapp-engage-system-user).

#### Step 2: Create a Group for Transactional Message Sendout​

Set up a new group to manage recipients of transactional messages. This group serves as a container and keeps transactional message recipients separate from other users in the system.

> [!NOTE]
> **Note**: When Mapp Engage sends a transactional message to a contact who is not already in the group, it automatically adds that contact to the group.

1. Navigate to ​*Audience* *> Group Management >* *Groups*.
2. Create a group.
3. In **Sendout Options**, set *Transactional Message Mode* to:
  1. **Off** - if your external system can create the TMID
  2. **On** - if you want Mapp Engage to generate the TMID.
4. If the *Transactional Message Mode* is set to **On**, you must define a personalization pattern that generates TMIDs.

For more information, see [Add a TMID to Messages](/v1/docs/add-a-tmid-to-messages).

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

Create a prepared message that you can use as a transactional message template.

1. In the main navigation, click *Create New > Message* *> Email Message > HTML Email*.
2. In the **Message Name** field, enter a name (e.g., *Transactional Message Template*), then click **Create**.
3. Paste your HTML content into the message editor (see sample below).
4. Click **Prepare Sendout**.
5. From the *Group* drop-down, select the group you created earlier.
6. Select **Saved as Prepared Message**.
7. Click **Check Message**.

The message will appear in the *Prepared Messages Overview*.

This sample HTML includes placeholders for a standard attribute, a custom attribute, and a parameter for inserting data from the connected system.

```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>
```

For more information on new message creation, see [Create an Email Message​](/v1/docs/create-an-email-message).

#### Step 4: Call the API Method

Use the appropriate API method depending on your system setup to send the prepared message.

Your external system must:

1. Include the recipient data (create or look up contact).
2. Provide the TMID (if externally generated) as a parameter.
3. Send any required personalization data or parameters.
4. Reference the prepared message.
5. Trigger the transactional message sendout.

> [!NOTE]
> If using older integrations, refer to their specific configurations. For API 1.0, use `sendParametrizedSingleMessageToUser` and pass the TMID as a parameter with a placeholder in group settings: `&lt;%parameter.YourParameterName%&gt;`