Contents x
      transactional.getMessageContactActivity
      • 4 Minutes to read
      • Print
      • Dark
        Light
      Contents

      transactional.getMessageContactActivity

      • 4 Minutes to read
      • Print
      • Dark
        Light
      Article summary

      General Information

      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 subscriber's 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 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 the 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:

      <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


      The 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


      The 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>

      Was this article helpful?
      What's Next