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.

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.

Go to User Management > System Users > System Users.
Click Create.
Enter the required user information.
Click Save.

For details, see 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.

Go to Audience > Group Management > Groups.
Create a group.
In Sendout Options, set Transactional Message Mode to the mode you chose above.
If you chose On or Optional, define the TMID pattern. See Set Up a TMID for Transactional Messages.

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 and Create an HTML 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):

<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. To pass order data, such as the products of an order, with the message, see Injection of Transactional Data into Mapp Engage.

Note
For older integrations based on API 1.0, use sendParametrizedSingleMessageToUser. Pass the TMID as a parameter and use the placeholder <%parameter.YourParameterName%> as the TMID pattern of the group.