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 |
| message_type | This parameter returns the message type (welcome) | welcome |
| 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 | '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 |
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>