legacy.message_stats

‹ BACK TO API PAGE


Description

WARNING: This method cannot be combined with any other method call within the same POST command.

This method returns message delivery and response metrics. The elements to be included in the POST message enables the following selections:

  • Metrics for up to 1000 messages sent between (inclusive) a specified start and end date.
  • Metrics for up to 1000 messages sent on a specified date
  • Metrics for a specified message

In addition, the <last> element allows you to request the last N messages sent within the specified dates.

Arguments

Field Description Field Type Required Example
start_date The start of the date range of the messages' sending dates to be included in the response in YYYY-MM-DD format Date Conditional. If <end_date> is provided as an input parameter, then <start_date> is required. 2010-02-23
end_date The end of the date range of the messages' sending dates to be included in the response in YYYY-MM-DD format Date Conditional. If <start_date> is provided as an input parameter, then <end_date> is required. 2010-03-01
date The send date of the messages to be included in the response in YYYY-MM-DD format Date No 2010-07-04
mess_id The ID of the message to be included in the response. Integer No 2547173
last Include this element in the POST message when specifying a date or date range to select the last N messages sent. If not provided, then the default action is to return the last 100 messages sent. The value cannot exceed 1000. Integer No 10

Response

Field Description Example
message This element is the main "wrapper" for all delivery and response metrics for a given message. The ID attribute of this element references the message ID. 162224
message_subject Message subject line Eye on Innovation – 2010
message_name User-assigned message name  
date_sent Date the message was sent in YYYY-MM-DD HH:Min:SS format in US Pacific time zone 2010-06-23 12:29:28
message_notes Internal notes for extra message or campaign details Spring campaign
withheld_total Total number of subscribers included in the "excluded segments" of the message 100
globally_suppressed Total number of subscribers in the targeted message that were unmailable at the time of the send. 3
suppressed_total Withheld Total + Globally Suppressed 103
bill_codes User-defined alpha-numeric code abc123
sent_total Total number of emails sent 6392
sent_total_html Total number of HTML emails sent 6355
sent_total_plain Total number of plain-text emails sent 377
sent_rate_total Percentage of messages sent 100.00
sent_rate_html Percentage of html messages sent 99.91
sent_rate_plain Percentage of plain text messages sent 0.09
delivered_total Total number of emails sent in which BlueHornet received a code 250 back from the receiving SMTP server incidating a successful receipt. BlueHornet will automatically classify a sent email missing any response back from the receiving server (a.k.a. "missing" email) as an "other" bounce. Hence Delivered = Sent – Bounced 6016
delivered_html Total number of HTML emails delivered 5980
delivered_plain Total number of plain text emails delivered 36
delivered_rate_total Total Delivered / Total Sent 94.12
delivered_rate_html Total HTML Delivered / Total Sent 93.55
delivered_rate_plain Total Plain Delivered / Total Sent 0.56
bounced_total Hard bounce + Soft bounce + "Other" bounce 376
bounced_html Total bounced HTML emails 375
bounced_plain Total bounced plain text emails 1
bounced_rate_total Total Bounced / Total Sent 5.88
bounced_rate_html Total HTML Bounced / Total Sent 5.87
bounced_rate_plain Total Plain Bounced / Total Sent 0.02
invalid_total Total invalid emails 11
invalid_rate_total Total invalids / Total sent 0.09
has_dynamic_content Dynamic content is included in the message 0
has_delivery_report Domain delivery report was requested (no longer functional) 1
link_append_statement The text that is appended to all tracked links existing in the message. campaign_id=163697
timezone Timezone from which message is sent (if localized timezone feature is enabled)
ftf_forwarded Total messages forwarded to a friend 2
ftf_signups Total signups resulting from a forwarded message 1
ftf_conversion_rate Total ftf_signups / Total ftf_forwarded 50.00
optout_total Total unsubscribes coming from the Unsub link in the email 0
optout_rate_total Total Optouts / Total Delivered 0.00
opened_total Total HTML Opens (as identified by open tracking pixel) + Total Clicks from HTML emails (not otherwise identified by the tracking pixel). NOTE: BlueHornet does not include clicks on system links (e.g. unsubscribe, FTAF, view online, etc.) in this total 2144
opened_unique Total Unique HTML Opens + Total Unique HTML Clicks. (See above note) 1301
opened_rate_unique Total Unique HTML Opened / Total Delivered 21.63
opened_rate_aps Message opens, average per subscriber 5.49
clicked_total Total clicks in HTML and plain text emails. NOTE: BlueHornet does not include clicks on system links (e.g. unsubscribe, FTAF, view online, etc.) in this total 172
clicked_unique Total unique subscribers who clicked in the email. 141
clicked_rate_unique This metric is more commonly known as "Click-to-Open". Total Unique Subscriber Clicks / Total Unique Subscriber Opens 10.84
clicked_rate_aps Clicks, average per subscriber 0.00
campaign_name Name of the campaign this message was associated with Dialog – Eye On
campaign_id ID number of the associated campaign 123
campaign_type Displays the value 'R' if this message is a single send for a Recurring Message type. R
included_groups This element is a "wrapper" of the different static segments whose members were targeted by the message.
segment The name of the static segment. The ID attribute of this element references the static segment ID. Men's Apparel updates
included_smartlists This element is a "wrapper" of the different smart lists whose members were targeted by the message.
excluded_groups This element is a "wrapper" of the different static segments whose members were excluded from the message.
excluded_smartlists This element is a "wrapper" of the different smart lists whose members were excluded from the message.
attributes This element is a "wrapper" of the different message tags associated with this message.
attribute The name and value of the specific message tag. The "name" attribute is the friendly name of the message tag, the "ID" attribute is the system ID assigned to the tag. The value of this element is the specific value of the message tag associated with this message. Multi-value message tags will have each selected value separated by the pound "#" character. Monster Truck Rallies#Fine Dining
link This element is the "wrapper" for all click-through metrics associated with the message. The ID attribute references the link ID.
url The URL of a tracked link that exists within the message. http://www.company.com/moreinfo/productID=1234
url_name The name given to a tracked link. Signup Form
url_display If a URL name exists for a particular tracked link, that value is returned. If no URL name is provided for a tracked link, the URL value beginning with "https" or "http" is returned. Sign Up Form or http://example.com/sign-up-form
has_name Indicates whether a name was provided for a tracked link. If a URL name exists which does not begin with "http", a 1 is returned. If a URL name exists beginning with "http", the URL is considered not to have a name and a zero is returned. 0
clicked_unique_total Total unique subscribers who clicked the link. NOTE: BlueHornet does not include clicks on system links (e.g. unsubscribe, FTAF, view online, etc.) in this total 94
clicked_total_html Total clicks on this link as displayed within the HTML-formatted email 104
clicked_total_plain Total clicks on this link as displayed within the plain text-formatted email 0
clicked_unique_html Total unique subscribers who clicked this link within the HTML-formatted email 94
clicked_unique_plain Total unique subscribers who clicked this link within the plain text-formatted email 0
roi_conversions Total number of sales tied to the click on the link 2
roi_total ROI sales tied to the click on the link in USD $500.00
roi_average Total Sales / Total Conversions $250.00
binding This parameter returns the binding used for a message. Typically a well-known scientist name is used to name a binding echo

Response Codes

Response Code Response Text Description
201 Success A successful retrieval of message statistics
402 invalid usage case An error was encountered with the data parameters provided.
403 malformed 'start_date' parameter; must be a valid date in YYYY-MM-DD format The value provided in the <start_date> element is not properly date-formatted
404 malformed 'end_date' parameter; must be a valid date in YYYY-MM-DD format The value provided in the <end_date> element is not properly date-formatted
405 malformed 'date' parameter; must be a valid date in YYYY-MM-DD format The value provided in the <date> element is not properly date-formatted
406 'last' is not an integer The value provided in the <last> element must be an integer between 1 and 1000.
407 'last' violates expression: 0<= 'last' The value provided in the <last> element must be an integer between 1 and 1000.

Example Post

<methodCall>

<methodname>legacy.message_stats</methodname>

<start_date>2011-09-03</start_date>

<end_date>2011-09-13</end_date>

</methodCall>

Example Response

<methodResponse>

<item>

<methodName>legacy.message_stats</methodName>

<responseData>

<message_data>

<message id='111111'>

<message_subject>Hurry! Free shipping ends today!</message_subject>

<message_name>Fall Savings - Free Shipping</message_name>

<date_sent>2011-09-13 10:13:27</date_sent>

<message_notes/>

<withheld_total>0</withheld_total>

<globally_suppressed/>

<suppressed_total/>

<bill_codes/>

<sent_total>1133</sent_total>

<sent_total_html>1132</sent_total_html>

<sent_total_plain>1</sent_total_plain>

<sent_rate_total>100.00</sent_rate_total>

<sent_rate_html>99.91</sent_rate_html>

<sent_rate_plain>0.09</sent_rate_plain>

<delivered_total>1130</delivered_total>

<delivered_html>1129</delivered_html>

<delivered_plain>1</delivered_plain>

<delivered_rate_total>99.74</delivered_rate_total>

<delivered_rate_html>99.73</delivered_rate_html>

<delivered_rate_plain>100.00</delivered_rate_plain>

<bounced_total>3</bounced_total>

<bounced_html>3</bounced_html>

<bounced_plain>0</bounced_plain>

<bounced_rate_total>0.26</bounced_rate_total>

<bounced_rate_html>0.27</bounced_rate_html>

<bounced_rate_plain>0.00</bounced_rate_plain>

<invalid_total>1</invalid_total>

<invalid_rate_total>0.09</invalid_rate_total>

<has_dynamic_content>0</has_dynamic_content>

<has_delivery_report>0</has_delivery_report>

<link_append_statement/>

<timezone/>

<ftf_forwarded>0</ftf_forwarded>

<ftf_signups>0</ftf_signups>

<ftf_conversion_rate>0.00</ftf_conversion_rate>

<optout_total>0</optout_total>

<optout_rate_total>0.00</optout_rate_total>

<clicked_total>0</clicked_total>

<clicked_unique>0</clicked_unique>

<clicked_rate_unique>0.00</clicked_rate_unique>

<clicked_rate_aps>0.00</clicked_rate_aps>

<opened_total>1862</opened_total>

<opened_unique>339</opened_unique>

<opened_rate_unique>30.03</opened_rate_unique>

<opened_rate_aps>5.49</opened_rate_aps>

<campaign_name/>

<campaign_id>0</campaign_id>

<campaign_type/>

<included_groups>

<segment id='1119440'><![CDATA[Men's Apparel updates]]></segment>

<segment id='1119445'><![CDATA[All Apparel updates]]></segment>

</included_groups>

<included_smartlists>

<segment id='1470975'>Purchased Men's Apparel within 12 months</segment>

</included_smartlists>

<excluded_groups>

<segment id='1119435'><![CDATA[Inactive as of 011713]]></segment>

</excluded_groups>

<excluded_smartlists></excluded_smartlists>

<attributes>

<attribute name='Personal Interests' id='3785'>

<![CDATA[Monster Truck Rallies#Fine Dining#Watching The Voice on TV#Outdoor Activities]]>

</attribute>

<attribute name='Winks' id='2924'>

<![CDATA[Seeking F]]>

</attribute>

</attributes>

<link id='28643696'>

<url>http://www.example.com</url>

<url_name><![CDATA[]]></url_name>

<url_display><![CDATA[http://www.example.com]]></url_display>

<has_name>0</has_name>

<clicked_unique_total>1592</clicked_unique_total>

<clicked_total_plain>0</clicked_total_plain>

<clicked_unique_plain>0</clicked_unique_plain>

<clicked_total_html>1839</clicked_total_html>

<clicked_unique_html>1592</clicked_unique_html>

<roi_conversions>0</roi_conversions>

<roi_total>0.00</roi_total>

<roi_average>0.00</roi_average>

</link>

<link id='28643695'>

<url>http://www.example.com/blog-article/news/586</url>

<url_name><![CDATA[Latest News Update]]></url_name>

<url_display><![CDATA[http://www.example.com/blog-article/news/586]]></url_display>

<has_name>0</has_name>

<clicked_unique_total>3640</clicked_unique_total>

<clicked_total_plain>0</clicked_total_plain>

<clicked_unique_plain>0</clicked_unique_plain>

<clicked_total_html>4215</clicked_total_html>

<clicked_unique_html>3640</clicked_unique_html>

<roi_conversions>112</roi_conversions>

<roi_total>3870.72</roi_total>

<roi_average>34.56</roi_average>

</link>

</message>

<message id='888888'>

... more message data ...

</message>

<message id='999999'>

... more message data ...

</message>

</message_data>

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>

Example Error

<methodResponse>

<item>

<methodName>legacy.message_stats</methodName>

<responseData>

message=2&reason=malformed 'start_date' parameter; must be a valid date in YYYY-MM-DD format

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>


Back to API Reference Guide