Get Mailing Summaries

Return a summary for the given mailings, including most common KPIs. If no mailing ID is given, the summaries of all mailings in your account are returned, page by page.

GET https://api.maileon.com/1.0/reports/mailing_summaries

Note: the two-year limit for report data does not apply to this resource. Summaries are available for mailings of any age, including archived mailings (see the field archived below).

Attributes

All parameters are optional query parameters.

Parameter	Default	Description
mailing_id	none	The Maileon mailing id. Multivalued parameter, use …mailing_id=1&mailing_id=2 Type: integer. If omitted, the summaries of all mailings in your account are returned. Mailing IDs that do not exist or that belong to another account are ignored: they are left out of the response, and no error is returned.
include_mailings_without_response	false	Type: boolean (true or false). By default, only mailings that already have reporting data (typically mailings that have been sent) are returned. With true, all mailings of the account except drafts are returned; values without data are returned as 0 (archived: false).
page_index	1	Type: integer, 1 to 1,000,000. The page to return. The first page is 1.
page_size	100	Type: integer, 1 to 1,000. The number of mailing summaries per page.

Pagination

The results are sorted by mailing ID in ascending order and returned in pages of page_size items. Each response contains these headers:

Header	Description
X-Items	Total number of mailing summaries that match the request.
X-Pages	Total number of pages for the given page_size.
Link	URLs of the first page (rel=“start“), the previous page (rel=“prev“, not on the first page) and the next page (rel=“next“, not on the last page). Each URL is sent in its own Link header.

Limitation: the URLs in the Link headers contain only the parameters mailing_id, page_index and page_size. If you use include_mailings_without_response=true, add this parameter yourself when you request the next or previous page; otherwise the following pages are returned without it.

Response fields

The response contains one mailing summary per mailing. The field names in JSON differ from XML for three fields only (mailingId, opensUnique, clicksUnique).

XML	JSON	Description
mailing_id	mailingId	ID of the mailing.
recipients	recipients	Number of emails Maileon sent for this mailing. This is not the number of delivered emails: bounces are not subtracted.
opens	opens	Total number of opens, including repeated opens by the same contact.
opens_unique	opensUnique	Number of contacts who opened the mailing at least once.
clicks	clicks	Total number of clicks, including repeated clicks by the same contact.
clicks_unique	clicksUnique	Number of contacts who clicked in the mailing at least once.
bounces	bounces	Total number of bounces, hard and soft bounces combined. A contact can bounce more than once, so this value can be higher than the number of bounced contacts.
unsubscriptions	unsubscriptions	Number of unsubscriptions attributed to this mailing.
replies	replies	Total number of replies to this mailing, including several replies from the same contact.
archived	archived	true if the detailed response data of this mailing (individual opens, clicks, bounces and replies) has been deleted because the retention period for response data in your account has passed. The summary values above remain available, but reports with individual responses no longer return data for this mailing. Otherwise false.

Example

GET https://api.maileon.com/1.0/reports/mailing_summaries?mailing_id=103
Authorization: Basic <base64-encoded API key>
Accept: application/vnd.maileon.api+xml; charset=utf-8

Response:

Status: 200 OK
Content-Type: application/vnd.maileon.api+xml
X-Items: 1
X-Pages: 1
Link: <https://api.maileon.com/1.0/reports/mailing_summaries?page_index=1&mailing_id=103&page_size=100>; rel="start"

<mailing_summaries>
    <mailing_summary>
        <mailing_id>103</mailing_id>
        <recipients>452057</recipients>
        <opens>337082</opens>
        <opens_unique>174205</opens_unique>
        <clicks>26697</clicks>
        <clicks_unique>13502</clicks_unique>
        <bounces>1183</bounces>
        <unsubscriptions>624</unsubscriptions>
        <replies>2896</replies>
        <archived>false</archived>
    </mailing_summary>
</mailing_summaries>

JSON-Output

The function also supports JSON-output. Send the header Accept: application/json to receive JSON. If you send no Accept header or application/vnd.maileon.api+xml, the response is XML.

Example output:

GET https://api.maileon.com/1.0/reports/mailing_summaries?mailing_id=103
Authorization: Basic <base64-encoded API key>
Accept: application/json

Status: 200 OK
Content-Type: application/json
X-Items: 1
X-Pages: 1

[
  {
    "mailingId": 103,
    "recipients": 452057,
    "opens": 337082,
    "opensUnique": 174205,
    "clicks": 26697,
    "clicksUnique": 13502,
    "bounces": 1183,
    "unsubscriptions": 624,
    "replies": 2896,
    "archived": false
  }
]

The order of the fields in a JSON object is not fixed.

Count mailing summaries

Returns the number of mailing summaries for the given filters, without the summaries themselves. It accepts the parameters mailing_id and include_mailings_without_response, with the same meaning and defaults as above; there is no pagination.

GET https://api.maileon.com/1.0/reports/mailing_summaries/count

Example:

GET https://api.maileon.com/1.0/reports/mailing_summaries/count?mailing_id=103&mailing_id=104
Authorization: Basic <base64-encoded API key>
Accept: application/vnd.maileon.api+xml; charset=utf-8

Status: 200 OK
<count>2</count>

With Accept: application/json the response is: {„count“:2}

Error codes

Error responses contain an XML body of the form <error><message>…</message></error>, also when JSON was requested.

Status code	Description
400 Bad Request	page_index or page_size is outside the allowed range.
401 Unauthorized	The Authorization header is missing, sent more than once or badly formatted; or the API key does not exist, is not active, has expired or may not be used from your IP address; or the account is not active.
403 Forbidden	The API key has no read permission, or the request was sent over HTTP instead of HTTPS.
404 Not Found	A parameter value is not a number (for example mailing_id=abc). Note: unknown mailing IDs do not cause 404; they are left out of the response.
406 Not Acceptable	The Accept header requests a format other than XML or JSON.
429 Too Many Requests
500 Internal Server Error	An unexpected error occurred. Please retry later or contact Maileon support.

Authentication

Requests are authenticated with HTTP Basic authentication: send the header Authorization: Basic followed by your Base64-encoded API key, and use HTTPS. The API key needs read permission, which is required for all GET requests. No further permission is needed for this resource. Each API key only returns the mailings of its own account.