transactional.getMessageContactActivity

‹ BACK TO API PAGE


Description

Use this method to asynchronously retrieve message recipient response data for any given transactional message.
The process involves three steps:

  1. Initiate the request to retrieve recipient response data for a specific transactional message
  2. Query the job engine via utilities.getTasks to know when the response data is available for download
  3. 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
email 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:
  • 0 – indicates that the subscriber record is deleted, unsubscribed or otherwise opted out
  • 1 – indicates that the subscriber is currently in the active subscribers list
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 items 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
email 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:
  • sent
  • open
  • click
  • bounce
  • invalid
  • optout

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>


Back to API Reference Guide