Description
Use this method to asynchronously retrieve message recipient response data for any given transactional message.
The process involves three steps:
- Initiate the request to retrieve recipient response data for a specific transactional message
- Query the job engine via utilities.getTasks to know when the response data is available for download
- Retrieve the response data via utilities.getFile
Transactional.getMessageContactActivity returns a task ID corresponding to the asynchronous job assigned to collect the message response data.
Query the job queue using the utilities.getTasks method call, passing in the task ID in the <task_id> input element and EXPORT_MESSAGE_CONTACTS in the <type> input element. This method will return the most current status of the specified job. When the returned status is COMPLETE, the method's <task_response> parameter will contain the file path to the message response data file.
When used with utilities.getFile, the resulting message response data file will be an XML-formatted file that contains the following information:
| Field | Description | Example |
|---|---|---|
| messagecontact | This element is the wrapper for all response information for a given message recipient. | |
| mes_cont_id | A unique ID that identifies the specific individual and the specific message that he was sent. | 186994297 |
| The recipient's email address | john_smith@example.com | |
| external_id | The message recipient's identifier defined within an external system. | ABC123DEF456 |
| salesforce_id | The recipient's external SalesForce ID. This value is only included in the data file if the <salesforce> parameter was set to '1'. | |
| current | a boolean value indicating whether or not the message recipient is an active subscriber or not where:
|
1 |
| sent | This node contains the date and time in US Pacific Time Zone that the message was sent to the individual. | |
| bounce | The node containing the date, time, and reason the message bounced when sent to the recipient. This element is only included if the message bounced during the specified date/time range. | |
| reason | This sub-element of the <bounce> element includes the code and description for why the message bounced when sent to the recipient | 5-Invalid Recipient |
| invalid | The node containing the date, time, and reason the recipient's contact record was marked permanently invalid. This element is only included if the recipient's contact record was marked invalid during the specified date/time range. | |
| opens | The node containing all dates and times that the recipient opened the email. This element is only included if the opens occurred within the specified date/time range. | |
| clicks | The node containing all the dates, times, and links that the recipient clicked. This element is only included if the clicks occurred within the specified date/time range. | |
| link_id | A system-generated unique number that identifies the specific link within the email. | 478193290 |
| optout | The date and time that the recipient unsubscribed directly from the specified message. This element is only included if the recipient opted out within the specified date/time range. | 2012-06-22 17:04:31 |
| date | This sub-element is always appears with the <bounce>, <invalid>, <opens>, and <clicks> elements whenever they are included within the data file. The date and time of the event in yyyy-mm-dd hh24:mi:ss format. | 2011-10-26 07:03:05 |
| roi | This element acts as a wrapper for each group of roi itEmpower returned in the method call. | |
| transaction | This sub-element of the wrapper element acts as a wrapper for each group of roi transaction data sets returned in the method call. | |
| link_id | Numerical string identifying the link. | 4266526 |
| amount | A numeric value containing the amount associated with the order in USD. This variable should not contain the dollar sign ($) or commas, and should have the format "dollars.cents", with cents only consisting of two digits. | 291.43 |
| orderid | String value for the order identification number. | A65487923 |
| datetime | Date the roi transaction was executed in yyyy-mm-dd hh:min:ss format in US Pacific time zone. | 2014-04-02 08:24:32 |
An example of the message's recipient response data would look similar to the following:
<?xml version="1.0" encoding="UTF-8"?>
<message_data>
<messagecontact>
<email>jsmith@example.com</email>
<mes_cont_id>619-295-1856</mes_cont_id>
<current>1</current>
<clicks>
<click>
<link_id>4266526</link_id>
<date>2011-10-26 08:00:52</date>
</click>
</clicks>
<opens>
<date>2011-10-26 08:00:36</date>
</opens>
<roi>
<transaction>
<link_id>38918752</link_id>
<amount>123.45</amount>
<order_id>M000001</order_id>
<date>2014-08-07 04:27:36</date>
</transaction>
</roi>
<sent>
<date>2011-10-26 07:00:36</date>
</sent>
</messagecontact>
<messagecontact>
<email>djones@example.com</email>
<mes_cont_id>619-295-1856</mes_cont_id>
<current>1</current>
<bounce>
<reason>5-Invalid Recipient</reason>
<date>2011-10-26 07:03:05</date>
</bounce>
<invalid>
<reason/>
<date>2011-10-26 07:03:05</date>
</invalid>
<sent>
<date>2011-10-26 07:00:36</date>
</sent>
</messagecontact>
<messagecontact>
<email>pbrown@example.com</email>
<mes_cont_id>619-295-1856</mes_cont_id>
<current>0</current>
<opens>
<date>2011-10-26 08:30:38</date>
<date>2011-10-26 10:30:45</date>
</opens>
<sent>
<date>2011-10-26 07:00:36</date>
</sent>
<optout>2011-10-26 10:32:38</optout>
</messagecontact>
</message_data>
Arguments
| Field | Description | Field Type | Required | Example |
|---|---|---|---|---|
| template_id | The template ID for the transactional message whose recipients' data is being retrieved | number | Yes | 1987294 |
| salesforce | A boolean value that when set to 1 will only return message contacts who have a Salesforce External ID. | boolean Default value is '0' |
No | 1 |
| When provided, this method will return only the specified subscriber's email response data. | string | No | john_smith@example.com | |
| external_id | A subscriber's identifier defined within an external system. This ID must be unique across all subscribers. | string 64 characters max. |
no | ABC123DEF456 |
| start_date | The starting date and time of the range to retrieve subscriber response data. | string Must be formatted as yyyy-mm-dd hh24:mi:ss |
No | 2011-12-31 23:59:59 |
| end_date | The ending date and time of the range to retrieve subscriber response data. | string Must be formatted as yyyy-mm-dd hh24:mi:ss |
No | 2012-06-03 12:00:00 |
| action_types | A comma-delimited list of subscriber actions being requested. Options include:
Default behavior is to return all action data (which will take longer to process) |
string | No | sent,open,click |
| roi | Specify if roi data is needed in the API output. This is a boolean value that when set to 0 will not return roi data | boolean Default value is '1' |
No | 0,1 |
Response
| Field | Description | Example |
|---|---|---|
| task_id | The job ID for the asynchronous task generating the recipient response behavior data file. This ID number is the input parameter to utilities.getTasks in order to check the status of the task. | 1153176 |
Response Codes
| Response Code | Response Text | Condition |
|---|---|---|
| 101 | background job submitted | The method call was successfully submitted, creating the task to generate the subscriber response behavior data file. |
| 504 | end_date occurs before start_date | The value passed for "end_date" occurs earlier than the value passed for "start_date" |
| 505 | start_date and end_date must both be passed together | Either "start_date" or "end_date" were passed, but the other was missing |
| 506 | invalid email format | The email address provided in the <email> parameter is not in a valid email format. (e.g. john_smith@example/com) |
| 507 | template_id parameter is required | The message ID was not provided. |
Example Post
<methodCall>
<methodName>transactional.getMessageContactActivity</methodName>
<template_id>1987294</template_id>
<salesforce>1</salesforce>
<start_date>2010-01-01 11:00:00</start_date>
<end_date>2010-01-01 13:00:00</end_date>
</methodCall>
Example Response
<methodResponse>
<item>
<methodName>transactional.getMessageContactActivity</methodName>
<responseCode>101</responseCode>
<responseText>background job submitted</responseText>
<responseData>
<task_id>1153175</task_id>
</responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>
Example Error
<methodResponse>
<item>
<methodName>transactional.getMessageContactActivity</methodName>
<responseCode>504</responseCode>
<responseText>end_date occurs before start_date</responseText>
<responseData></responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>