Get summary statistics - ExpertSender Help Center

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/attribute	Type	Notes
apiKey	string	Your API key, required for authentication. Required.
startDate	date	Start date. Optional. If not specified, business unit creation date will be taken. YYYY-MM-DD format.
endDate	date	End date. Optional. If not specified, current date will be taken. YYYY-MM-DD format.
scope	string	Filtering 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 list Domain – only results for specific domain DomainFamily – only results for specific domain family* MessageType – only results for specific message type Ip – only results for specific IP channel Segment – only results for specific subscriber segment Vendor – only results for specific vendor Tag – only results for messages marked with a tag SendTimeOptimization – 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***
scopeValue	mixed	Filtering scope value. Required if scope was specified. This is a mixed value, type depends on selected scope: List – List ID, int, e.g. 123 Domain – domain name, string, e.g. domain.com DomainFamily – 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.44 Segment – Segment ID, int, e.g. 123 Vendor – vendor name, string, e.g. foobar Tag – Tag name, e.g. holidays SendTimeOptimization – 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***
grouping	string	Results 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: Date Month Message MessageType List Segment Ip Domain DomainFamily Vendor Tag SendTimeOptimization – 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*** OperatingSystem NOTE: It is impossible to filter and group by the same thing. `scope` parameter value must be different from `grouping` parameter value.
returnMessageTags	boolean	If 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/attribute	Type	Notes
SummaryStatistics	array[complex]	Array of SummaryStatistic elements.

SummaryStatistic element children:

Element/attribute	Type	Notes
IsSummaryRow	boolean	If set to true, marks the summary row of statistic table (values are sums of all other rows).*
Date	date	Date. Returned only if grouping by dates was requested.
Month	string	Month represented as date period. Returned only if grouping by months was requested. Example: 2010-01-01 : 2010-01-31
MessageId	int	Message ID. Returned only if grouping by messages was requested.
MessageSubject	string	Message subject. Returned only if grouping by messages was requested.
ListId	int	Subscriber list ID. Returned only if grouping by lists was requested.
ListName	string	Subscriber list name. Returned only if grouping by lists was requested.
SegmentId	int	Subscriber segment ID. Returned only if grouping by segments was requested and the row does not contain data about unsegmented subscribers.
SegmentName	string	Subscriber segment name. Returned only if grouping by segments as requested. If row contains data about unsegmented subscribers, it will return dash („-„) as value.
Ip	string	Channel IP address. Returned only if grouping by IPs was requested.
Domain	string	Domain name. Returned only if grouping by domains was requested.
DomainFamily	string	Domain family name. Returned only if grouping by domain families was requested.
Vendor	string	Vendor name. Returned only if grouping by vendors was requested. If row contains data about subscribers with no vendor, dash („-„) will be returned.
SendTimeOptimization	string	Send time optimization. Returned only if grouping by send time optimization was requested. One of: „OptimizationNotUsed”, „TimeOptimized”, „TimeNotOptimized” or dash „-” if does not apply.
TimeTravelOptimization	string	Time travel optimization. Returned only if grouping by time travel optimization was requested. One of: „OptimizationNotUsed”, „TimeOptimized”, „TimeNotOptimized” or dash „-” if does not apply.
ReadingEnvironment	string	Reading environment. Returned only if grouping by reading environment was requested. One of: „Other”, „Desktop”, „Mobile”, „Webmail”, „NoActivity” or dash „-” if does not apply.
Sent	int	Number of sent emails.
Bounced	int	Number of bounced emails.
Delivered	int	Number of delivered (sent – bounced) emails.
Opens	int	Number of opened emails.
UniqueOpens	int	Number of opened emails by unique subscribers.
Clicks	int	Number of link clicks.
UniqueClicks	int	Number of link clicks by unique subscribers.
Clickers	int	Number of unique subscribers that clicked any link.
Complaints	int	Number of spam complaints.
Unsubscribes	int	Number of “unsubscribe” link clicks.
Goals	int	Number of achieved business goals.
GoalsValue	int	Value of achieved business goals.
Bcc	int	Number 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>