Skip to content

Get summary statistics

SummaryStatistics collection allows retrieving summary performance statistics of your messages. Statistics may be filtered and grouped by various parameters, exactly the same as using Reports->Summary page in ExpertSender Web Panel.

Request data format

Request URL parameters:

Element/attributeTypeNotes
apiKeystringYour API key, required for authentication. Required.
startDatedateStart date. Optional. If not specified, business unit creation date will be taken. YYYY-MM-DD format.
endDatedateEnd date. Optional. If not specified, current date will be taken. YYYY-MM-DD format.
scopestringFiltering scope. Optional. If not specified, no filtering will be applied (data for the whole business unit will be returned).
Available scopes are:
List – only results for specific subscriber listDomain – only results for specific domainDomainFamily – only results for specific domain family*MessageType – only results for specific message typeIp – only results for specific IP channelSegment – only results for specific subscriber segmentVendor – only results for specific vendorTag – only results for messages marked with a tagSendTimeOptimization – only results for messages with specific sending time optimization settings***TimeTravelOptimization – only results for messages with specific Time Travel settings****ReadingEnvironment – only results for messages opened/clicked in specific reading environment*****
scopeValuemixedFiltering scope value. Required if scope was specified. This is a mixed value, type depends on selected scope:
List – List ID, int, e.g. 123Domain – domain name, string, e.g. domain.comDomainFamily – domain family name, string, e.g. Gmail*MessageType – message type name, string, e.g. Newsletter**Ip – IP of channel, string, e.g. 11.22.33.44Segment – Segment ID, int, e.g. 123Vendor – vendor name, string, e.g. foobarTag – Tag name, e.g. holidaysSendTimeOptimization – only results for messages with specific sending time optimization settings***TimeTravelOptimization – only results for messages with specific Time Travel settings****ReadingEnvironment – only results for messages opened/clicked in specific reading environment*****
groupingstringResults grouping. Optional. If not specified, results will be grouped by whole business unit (one row of data will be returned with all values summed up).
Available groupings are:
DateMonthMessageMessageTypeListSegmentIpDomainDomainFamilyVendorTagSendTimeOptimization – only results for messages with specific sending time optimization settings***TimeTravelOptimization – only results for messages with specific Time Travel settings****ReadingEnvironment – only results for messages opened/clicked in specific reading environment*****OperatingSystemNOTE: It is impossible to filter and group by the same thing. scope parameter value must be different from grouping parameter value.
returnMessageTagsbooleanIf set to true and grouping set to Message, then Tags used in each message will be returned. Optional. Default set to false.

* Domain families are specific to each business unit and may be customized. Typical domain families that usually are used (but do not have to apply to your unit!) are: Yahoo, Outlook.com, Gmail, AOL, Other.
** Available message types: Newsletter, Autoresponder, Trigger, Transactional, Confirmation, Recurring, Test.
*** Possible SendTimeOptimization message settings: OptimizationNotUsed, TimeOptimized, TimeNotOptimized.
**** Possible TimeTravelOptimization message settings: OptimizationNotUsed, TimeOptimized, TimeNotOptimized.
***** Possible ReadingEnvironment values: Other, Desktop, Mobile, Webmail, NoActivity.

Examples:

https://api.esv2.com/v2/Api/SummaryStatistics?apiKey=YOUR_API_KEY_HERE

https://api.esv2.com/v2/Api/SummaryStatistics?apiKey=YOUR_API_KEY_HERE&startDate=2013-12-10&endDate=2013-12-31

https://api.esv2.com/v2/Api/SummaryStatistics?apiKey=YOUR_API_KEY_HERE&scope=List&scopeValue=123

https://api.esv2.com/v2/Api/SummaryStatistics?apiKey=YOUR_API_KEY_HERE&scope=MessageType&scopeValue=Autoresponder&grouping=Date

https://api.esv2.com/v2/Api/SummaryStatistics?apiKey=YOUR_API_KEY_HERE&startDate=2022-12-01&endDate=2022-12-31&scope=MessageType&scopeValue=Autoresponder&scope2=Segment&scopeValue2=13&grouping=Date

Response

Response Data element:

Element/attributeTypeNotes
SummaryStatisticsarray[complex]Array of SummaryStatistic elements.

SummaryStatistic element children:

Element/attributeTypeNotes
IsSummaryRowbooleanIf set to true, marks the summary row of statistic table (values are sums of all other rows).*
DatedateDate. Returned only if grouping by dates was requested.
MonthstringMonth represented as date period. Returned only if grouping by months was requested.
Example: 2010-01-01 : 2010-01-31
MessageIdint Message ID. Returned only if grouping by messages was requested.
MessageSubjectstringMessage subject. Returned only if grouping by messages was requested.
ListIdintSubscriber list ID. Returned only if grouping by lists was requested.
ListNamestringSubscriber list name. Returned only if grouping by lists was requested.
SegmentIdintSubscriber segment ID. Returned only if grouping by segments was requested and the row does not contain data about unsegmented subscribers.
SegmentNamestringSubscriber segment name. Returned only if grouping by segments as requested. If row contains data about unsegmented subscribers, it will return dash (“-“) as value.
IpstringChannel IP address. Returned only if grouping by IPs was requested.
DomainstringDomain name. Returned only if grouping by domains was requested. 
DomainFamilystringDomain family name. Returned only if grouping by domain families was requested.
VendorstringVendor name. Returned only if grouping by vendors was requested. If row contains data about subscribers with no vendor, dash (“-“) will be returned.
SendTimeOptimizationstringSend time optimization. Returned only if grouping by send time optimization was requested. One of: “OptimizationNotUsed”, “TimeOptimized”, “TimeNotOptimized” or dash “-” if does not apply.
TimeTravelOptimizationstringTime travel optimization. Returned only if grouping by time travel optimization was requested. One of: “OptimizationNotUsed”, “TimeOptimized”, “TimeNotOptimized” or dash “-” if does not apply.
ReadingEnvironmentstringReading environment. Returned only if grouping by reading environment was requested. One of: “Other”, “Desktop”, “Mobile”, “Webmail”, “NoActivity” or dash “-” if does not apply.
SentintNumber of sent emails.
BouncedintNumber of bounced emails.
DeliveredintNumber of delivered (sent – bounced) emails.
OpensintNumber of opened emails.
UniqueOpensintNumber of opened emails by unique subscribers.
ClicksintNumber of link clicks.
UniqueClicksintNumber of link clicks by unique subscribers.
ClickersintNumber of unique subscribers that clicked any link.
ComplaintsintNumber of spam complaints.
UnsubscribesintNumber of “unsubscribe” link clicks.
GoalsintNumber of achieved business goals. 
GoalsValueintValue of achieved business goals.
BccintNumber of BCC emails sent. Available only for units with BCC feature enabled. **

* Summary rows do not contain grouping columns (e.g. Date, Month).
** Bcc will be displayed only there is no scope or MessageType scope used. Furthermore, if there is no or grouping other than Date, Month, Message or MessageType is used then Bcc number will be displayed only in first returned SummaryStatistic element (which is a summary row). Otherwise, when one of those four grouping options is used then Bcc will also be added to each SummaryStatistic element.

Examples

Statistics grouped by domain from a certain period of time:

Request (ungrouped statistics):

GET https://api.esv2.com/v2/Api/SummaryStatistics?apiKey=test_api_key1&startDate=2010-01-01&endDate=2012-01-01&grouping=Domain 
HTTP/1.1
Accept-Encoding: gzip,deflate
User-Agent: Jakarta Commons-HttpClient/3.1
Host: api.esv2.com

OK response: 

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 5.0
X-AspNet-Version: 4.0.30319
Set-Cookie: TEMP_DATA=209ffb47-7020-4508-99dc-8f7083928452; path=/
X-Powered-By: ASP.NET
Date: Wed, 11 Dec 2013 14:51:50 GMT
Content-Length: 97229

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Data>
    <SummaryStatistics>
      <SummaryStatistic>
        <IsSummaryRow>true</IsSummaryRow>
        <Sent>3656424</Sent>
        <Bounced>478621</Bounced>
        <Delivered>3177803</Delivered>
        <Opens>356783</Opens>
        <UniqueOpens>243556</UniqueOpens>
        <Clicks>145664</Clicks>
        <UniqueClicks>113442</UniqueClicks>
        <Clickers>98761</Clickers>
        <Complaints>3452</Complaints>
        <Unsubscribes>34211</Unsubscribes>
        <Goals>12344</Goals>
        <GoalsValue>123440</GoalsValue>
      </SummaryStatistic>
      <SummaryStatistic>
        <Domain>yahoo.com</Domain>
        <Sent>1262372</Sent>
        <Bounced>144511</Bounced>
        <Delivered>1117861</Delivered>
        <Opens>345112</Opens>
        <UniqueOpens>245218</UniqueOpens>
        <Clicks>83445</Clicks>
        <UniqueClicks>63443</UniqueClicks>
        <Clickers>34552</Clickers>
        <Complaints>2231</Complaints>
        <Unsubscribes>56775</Unsubscribes>
        <Goals>3345</Goals>
        <GoalsValue>33450</GoalsValue>
      </SummaryStatistic>
      
      ...
      
    </SummaryStatistics>
  </Data>
</ApiResponse>

Statistics filtered by message type and grouped by IP:

Request (ungrouped statistics):

GET https://api.esv2.com/v2/Api/SummaryStatistics?apiKey=test_api_key1&scope=MessageType&scopeValue=Newsletter&grouping=Ip 
HTTP/1.1
Accept-Encoding: gzip,deflate
User-Agent: Jakarta Commons-HttpClient/3.1
Host: api.esv2.com

OK response: 

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 5.0
X-AspNet-Version: 4.0.30319
Set-Cookie: TEMP_DATA=90015733-b2c3-4a23-93ac-b9bce60ab8af; path=/
X-Powered-By: ASP.NET
Date: Wed, 11 Dec 2013 15:04:03 GMT
Content-Length: 5655

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Data>
    <SummaryStatistics>
      <SummaryStatistic>
        <IsSummaryRow>true</IsSummaryRow>
        <Sent>21256701</Sent>
        <Bounced>6136556</Bounced>
        <Delivered>15120145</Delivered>
        <Opens>198540</Opens>
        <UniqueOpens>163857</UniqueOpens>
        <Clicks>17264</Clicks>
        <UniqueClicks>15689</UniqueClicks>
        <Clickers>12326</Clickers>
        <Complaints>2106</Complaints>
        <Unsubscribes>3351</Unsubscribes>
        <Goals>0</Goals>
        <GoalsValue>0</GoalsValue>
      </SummaryStatistic>
      <SummaryStatistic>
        <Ip>11.22.33.44</Ip>
        <Sent>5051025</Sent>
        <Bounced>1814659</Bounced>
        <Delivered>3236366</Delivered>
        <Opens>45737</Opens>
        <UniqueOpens>37578</UniqueOpens>
        <Clicks>4194</Clicks>
        <UniqueClicks>3640</UniqueClicks>
        <Clickers>2887</Clickers>
        <Complaints>465</Complaints>
        <Unsubscribes>799</Unsubscribes>
        <Goals>0</Goals>
        <GoalsValue>0</GoalsValue>
      </SummaryStatistic>
      ...
    </SummaryStatistics>
  </Data>
</ApiResponse>
On this page
To top