welcome.messageStats

‹ 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 for welcome messages. The elements to be included in the POST message enables the following selections:

  • Metrics sent between (inclusive) a specified start and end date.
  • Metrics sent on a specified date
  • Metrics for a specified template

In addition, the <rollup_type> element allows you to specify how you want to aggregate the metrics requested. By default, metrics will be aggregated by template ID. Other options are Daily and Monthly.

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. 2020-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. 2020-03-01
date The send date of the messages to be included in the response in YYYY-MM-DD format Date No 2020-07-04
template_id The ID of the template to be included in the response. Integer No 2547173
rollup_type The method by which the date should be aggregated, either Daily, Monthly or Blank. If left blank, it will be aggregated by Template ID. If Monthly, the Date Sent value will be displayed as the Month/Year 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 template ID. 162224
date_sent Date the message was sent. Will be reported in YYYY-MM-DD format for Daily rollup, YYYY-MM for Monthly and omitted for default. All times are in US Pacific time zone. 2020-06-23
template_id ID of the Welcome Message template. 162224
message_subject Message subject line Eye on Innovation – 2020
message_notes Internal notes for extra message or campaign details Spring campaign
bill_codes User-defined alpha-numeric code abc123
binding This parameter returns the binding used for a message. Typically a well-known scientist name is used to name a binding echo
campaign_id ID number of the associated campaign 123
campaign_name Name of the campaign this message was associated with Dialog – Eye On
campaign_type Displays the value 'R' if this message is a single send for a Recurring Message type. R
link_append_statement The text that is appended to all tracked links existing in the message. campaign_id=163697
sent_total Total number of emails sent 6392
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
bounced_total Hard bounce + Soft bounce + "Other" bounce 376
invalid_total Total invalid emails 11
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
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

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 'template_id' is not an integer The value provided in the < template_id> element must be an integer.
407 'template_id' violates expression: 0<='template_id' The value provided in the < template_id> element must be an integer.
493 invalid rollup type The value provided in the element must be from one of these (monthly, daily, default)

Example Post

<methodCall>

<methodname>welcome.messageStats</methodname>

<date>2020-03-22</date>

<rollup_type>Daily</rollup_type>

</methodCall>

Example Response

<methodResponse>

<item>

<methodName>welcome.messageStats</methodName>

<responseData>

<message_data>

<message id='111111'>

<message_subject>Welcome to the family!</message_subject>

<message_notes/>

<bill_codes/>

<binding/>

<campaign_name/>

<campaign_id>0</campaign_id>

<campaign_type/>

<link_append_statement/>

<date_sent>2020-03-22</date_sent>

<sent_total>1133</sent_total>

<delivered_total>3</sent_total>

<bounced_total>0</sent_total>

<invalid_total>0</sent_total>

<opened_total>2</sent_total>

<opened_unique>1</sent_total>

<clicked_total>0</sent_total>

<clicked_unique>0</sent_total>

</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>welcome.messageStats</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