Goal

To send transactional messages with the Mapp Engage API.

Background Information​

A transactional message includes a unique ID for every contact. This ID is called a transactional message ID (TMID). This ID allows you to track every message individually and to confirm that the contact receives and opens the message.

The API method that is used here is messageSendTransactional.

This setup assumes that your external tool generates a unique ID for every message. This setup also assumes that your tool sends this ID to Mapp Engage as a parameter in the API call.

If your external tool does not generate this ID, Mapp Engage can generate unique IDs for you. Use the API method messageSendSingle instead of messageSendTransactional. Set the ​Transactional Message Mode​ in the group settings to ​On​. Use the ​Personalization​ window to create a pattern that generates a unique TMID for every sendout.

Example

u=<%${user['PK']}%>m=<%${message['PK']}%>t=<%${ecx:formatDate(ecm:addInterval(date.today, '-0d'), 'yyyy-MM-dd\'T\'HH:mm:ss.SSS\'Z\'', ecm:timeZone('UTC'), '', false)}%>
When Mapp Engage sends the single messages, the system assigns a unique TMID to every message. For more information, see ​Add a TMID to Messages​.

When Mapp Engage sends a transactional message to a contact who is not in the group, Mapp Engage adds the contact to the group.

Procedure

A) Create an API User Account​

  1. In the ​Main Navigation​, click ​User Management​ > ​System Users > System Users​.
    ⇒  The ​System User Overview​ window opens.
  2. Click the ​New​ button.
    ⇒  The ​New System User​ window opens.

For more information on API user account creation, see Table.

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

When Mapp Engage sends a transactional message to a contact who is not in the group, Mapp Engage adds the contact to the group.

Often, the recipients of a transactional message have not completed the opt-in process for your newsletter. Manage these addresses separately to prevent accidentally contacting these addresses with marketing promotions to which they have not agreed.

  1. In the ​Main Navigation​, click ​Audience >Groups​.
    ⇒  The ​Group Overview ​window opens.
  2. Click Create.
    ⇒  The ​Group Details​ window opens.
  3. In the ​Name​ input field, enter a name that distinguishes this group from other groups that are already stored in the system.
    In the ​Email​ input field, enter the email address to be used for transactional message sendout.
  4. Click Create.
    ⇒  A window opens to the ​General Settings ​tab.
  5. Open the ​Sendout Options​ tab and scroll down to the ​Transactional Messages​ area.
  6. Set the ​Transactional Message Mode​ in the group settings to ​Off​.
    This setting tells Mapp Engage not to generate an additional TMID for each sendout.

C) Create the Transactional Message as a Prepared Message​

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

For more information on new message creation, see Create an Email Message​.

The 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><!--Standard attribute placeholders insert data stored in the user profile in Mapp Engage.--> 
		<p>The item you requested has been ordered for delivery to our <%user.CustomAttribute['Local store purchase']%> store:</p><!--Custom attribute placeholders insert data stored in custom attributes.-->
		<p><%parameter.productName%></p><!--This placeholder inserts data from the connected system. The property reference should match the column name in the external data set.--> 
		<p>We will send you notification when the item is available for pickup.</p> <p>Best Regards,</p> 
	</body> 
</html>
XML
  1. In the ​Main Navigation​, click ​+ ​​Create > ​New Message​.
  2. In the ​Message Name​ input field, enter a name for the message. For example, ​Transactional Message Template​.
    Click ​Create​.
  3. Copy the sample HTML and paste this code into the content area.
  4. Click ​Prepare Sendout​.
  5. In the ​Group​ drop-down list, select the group that was created in the previous task.
  6. In the options for ​Message will be​ options, select ​Saved as Prepared Message​.
  7. Click ​Check Message​.
    ⇒  The message is created and displayed in the ​Prepared Messages Overview​ window.

D) Build the API Solution​

Transactional events that initiate message sendout must be sent to Mapp Engage via API. The API solution can be set up to perform any of the following actions:

  • Lookup or create the recipient user account in Mapp Engage.

  • Update the user profile.

  • Deliver message content including attachments.

  • Deliver data that is used to trace the transaction in Mapp Engage.

  • Send the transactional message.

  • Transmit the message content.

This setup is specific to API 2.0. Some systems with standard integrations use an older version of the API (for example, Magento or Demandware). These integrations have different configurations for transactional messages.

API 1.0 uses the soap call sendParametrizedSingleMessageToUser. You can transfer the TMID from an external system as one of the parameters. In this case, you must add a placeholder to the group settings in the Transactional Messages area of the ​Sendout Options​ tab. The placeholder has the following format: <%parameter.YourParameterName%>.

E) Track Transactional Messages​

Mapp Engage offers the following possibilities to track transactional messages.

  • View whether an individual contact received and opened a transactional message in the ​Message History​ window. For more information, see ​Message History (window)​.

  • View a summary of the statistics for all sendouts of the prepared message in the ​Statistics​ area. For more information, see ​Single Message Statistics Overview (window)​.

  • Export data about transactional messages with a ​Raw Data Export​. For more information, see Raw Data Exports​. You can upload this data in your CRM or BI tool for further analysis.

  • Retrieve information from the Mapp Engage result queue with the API call asyncPoll (see http://developers.mapp.com/#poll). A Mapp administrator must set up how to put response data into the response queue for your Mapp Engage system. This option is not active by default for Mapp Engage standalone systems. This option is active by default for CIM/CEP integrated systems.

Related Topics​

Transactional Messages​
Add a TMID to Messages​
API documentation