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 Mapp received a code 250 back from the receiving SMTP server incidating a successful receipt. Mapp 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: Mapp 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: Mapp 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: Mapp 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 |
| message_type | This parameter returns the message type (standard, recurring) | standard |
| from_email | This parameter returns the value of the From Email address that is used to send the message | email@example.com |
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>