Description
Use this method to asynchronously retrieve subscriber response data for any given promotional message.
The process involves three steps:
- Initiate the request to retrieve subscriber response data for a specific promotional 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
Statistics.getMessageSubscriberData 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 |
|---|---|---|
| contact | The main node containing each message recipient's response data from the specified message | |
| The recipient's email address | john_smith@example.com | |
| mes_cont_id | A unique ID that identifies the specific subscriber and the specific message that he was sent. | 186994297 |
| external_id | The message recipient's identifier defined within an external system. | ABC123DEF456 |
| current | a boolean value indicating whether or not the subscriber is active or not where:
|
1 |
| salesforce_id | The subscriber's external SalesForce ID. This value is only included in the data file if the <salesforce> parameter was set to '1'. | |
| sent | A boolean value indicating if the contact was sent the message within the specified date/time range. | 1 |
| bounce | The node containing the date, time, and reason the message bounced when sent to the subscriber. 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 subscriber was marked permanently invalid. This element is only included if the subscriber was marked invalid during the specified date/time range. | |
| opens | The node containing all dates and times that the subscriber 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 subscriber 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 subscriber unsubscribed directly from the specified message. This element is only included if the subscriber opted out within the specified date/time range. | 2012-06-22 17:04:31 |
| date | This sub-element 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:min: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 subscriber response data would look similar to the following:
<?xml version="1.0" encoding="UTF-8"?>
<message_data>
<contact>
<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>1</sent>
</contact>
<contact>
<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>1</sent>
</contact>
<contact>
<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>1</sent>
<optout>2011-10-26 10:32:38</optout>
</contact>
</message_data>
Arguments
| Field | Description | Field Type | Required | Example |
|---|---|---|---|---|
| mess_id | The message ID for the 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 NOTE: Default behavior is to return all action data. If start and end date parameters are not provided then all data will be returned. |
boolean Default value is '1' |
No | 0,1 |
Response
| Field | Description | Example |
|---|---|---|
| task_id | The job ID for the asynchronous task generating the subscriber 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 | mess_id parameter is required | The message ID was not provided. |
Example Post
<methodCall>
<methodName>statistics.getMessageSubscriberData</methodName>
<mess_id>1987294</mess_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>statistics.getMessageSubscriberData</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>statistics.getMessageSubscriberData</methodName>
<responseCode>504</responseCode>
<responseText>end_date occurs before start_date</responseText>
<responseData></responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>