Contents x
      Sending Transactional Messages (API)
      • 2 Minutes to read
      • Print
      • Dark
        Light
      Contents

      Sending Transactional Messages (API)

      • 2 Minutes to read
      • Print
      • Dark
        Light
      Article summary

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

      Was this article helpful?
      What's Next
      ESC

      AI Assistant, facilitating knowledge discovery through conversational intelligence