Sending Transactional Messages (API)

  • 2 minute(s) read
Prev Next

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

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

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.

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

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.

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