- 4 Minutes to read
- Print
- DarkLight
Send Transactional Messages (API)
- 4 Minutes to read
- Print
- DarkLight
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
In the Main Navigation, click User Management > System Users > System Users.
⇒ The System User Overview window opens.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.
In the Main Navigation, click Audience >Groups.
⇒ The Group Overview window opens.Click Create.
⇒ The Group Details window opens.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.Click Create.
⇒ A window opens to the General Settings tab.Open the Sendout Options tab and scroll down to the Transactional Messages area.
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>
In the Main Navigation, click + Create > New Message.
In the Message Name input field, enter a name for the message. For example, Transactional Message Template.
Click Create.Copy the sample HTML and paste this code into the content area.
Click Prepare Sendout.
In the Group drop-down list, select the group that was created in the previous task.
In the options for Message will be options, select Saved as Prepared Message.
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