---
title: "Sending Transactional Messages (API)"
slug: "send-transactional-messages-api"
updated: 2025-05-26T14:11:45Z
published: 2025-05-26T14:11:45Z
---
> ## 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
Hi <%${user['FirstName']}%>,
The item you requested has been ordered for delivery to our
<%${user['CustomAttribute['DeliveryLocation']']}%>.
Product name: <%${parameter['productName']}%>
We will send you a notification when the item is available for pickup.
Best regards,
Your Company
```
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: `<%parameter.YourParameterName%>`