Skip to end of metadata
Go to start of metadata

This page provides you information about how to get email statistics by message and by recipient.

Important

Icon

Email Statistics use a different "base URL" than methods that can be used to manage your console account resources. Caller application should handle three distinct base URL when working with REST API ("Console", "Statistics" and "Public")

Use of paging for email statistics is often enabled by default. It is strongly recommended to avoid removal of default paging because in some cases the size of returned data could be really big (i.e. caller applications may experience either response time that are longer than expected or errors that are related to maximum data size restrictions on the infrastructure that hosts the caller). By implementing paging, a developer is able to test the caller application in its edge cases, in such a way that even huge number of opens, delivered emails or clicks do not represent a problem.

Filtering does not apply to Count parameter

 

 

On this page:

 


Get Statistics by Message

This section enables you to get statistics of an email message by specifying its ID. You can get message IDs by using List Messages method. For each type of statistics by message both a "COUNT" method (only the total number) and a "LIST" method (all available details) are provided.

If you reuse a specified message and organize more campaigns with it, you should be aware that message statistics of a specific campaign cannot be handled separately from the statistics of the other campaigns made with the same message. If you need to separate the statistics of each campaign, it is recommended that you clone the message (i.e. make a copy) whenever you are planning a new campaign.

Read message recipients

Please note that the full list of message recipients is kept inside MailUp only for 15 days after message sending, after that period COUNT returns zero and LIST returns an empty array.

Description

Get recipients that received the specified message

HTTP Method

GET

URL

Get the number of recipients that received the specified message (COUNT)


Get a list of email addresses that received specified message (LIST, paging is set as default with pageSize=20)

JSON request (example)

none

JSON response (example)

COUNT method simply return the number of delivered messages (e.g. 103)

LIST method returns a paged list

 Click here to expand...

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Message/11826/List/Recipients?PageSize=10&PageNumber=1 (change page size to 10 and retreive the second page)

Read message opens

Full details about opens are kept for at least 90 days, this period is longer if your console account has activated the "Detailed Statistics Extension" option.

Description

Get opens for the specified message

HTTP Method

GET

URL

Get the number of opens for the specified message (COUNT)

 

Get a list of recipients that opened the specified message (LIST, paging is set as default with pageSize=20)

JSON request (example)

none

JSON response (example)

COUNT method simply return the number of opens (e.g. 13)

LIST method returns a list of recipients that opened the message (each recipient could have opened the message more than once, see "Count" parameter for each recipient). The list is paged by default if the number of returned items is higher than 20

 Click here to expand...

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Message/11826/List/Views?PageSize=5&PageNumber=1 (change page size to 5 and retreive the second page)

Read clicks by message

Full details about clicks are kept for at least 90 days, this period is longer if your console account has activated the "Detailed Statistics Extension" option.

Description

Get clicks for the specified message

HTTP Method

GET

URL

Get the number of clicks for the specified message (COUNT)

 

Get a list of recipients that clicked at least a link in the specified message (LIST, paging is set as default with pageSize=20)

JSON request (example)

none

JSON response (example)

COUNT method simply return the number of clicks (e.g. 13)

LIST method returns a list of recipients that clicked in the message (each recipient could have clicked the message more than once, see "Count" parameter for each recipient). The list is paged by default if the number of returned items is higher than 20

 Click here to expand...

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Message/11826/List/Clicks?PageSize=5&PageNumber=1 (change page size to 5 and retreive the second page)

Full details about clicks are kept for at least 90 days, this period is longer if your console account has activated the "Detailed Statistics Extension" option.

Description

Get distribution of clicks for the specified message

HTTP Method

GET

URL

Count the number of clicks on each link of specified message

 

Get a list of recipients that clicked at least a link in the specified message (LIST, paging is set as default with pageSize=20)

JSON request (example)

none

JSON response (example)

UrlClicks returns a paged list of message links with at least one click. For each link both the URL and the number of clicks are provided

 Click here to expand...

 

LIST method returns a list of recipients that clicked in the message (each recipient could have clicked the message more than once, see "Count" parameter for each recipient). The list is paged by default if the number of returned items is higher than 20

 Click here to expand...

For sake of simplicity we consider a message with only one clicked link and with the page size that is reduced to 2 items per page

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Message/11826/List/UrlClickDetails?PageSize=5&PageNumber=1 (change page size to 5 and retreive the second page)

Read bounces by message

Description

Get recipients for whom a bounce occurred when the specified message was sent

HTTP Method

GET

URL

Get the number of bounces related to the specified message (COUNT)

 

Get a list of email addresses that originated a bounce when the specified message was sent (LIST, paging is set as default with pageSize=20)

JSON request (example)

none

JSON response (example)

COUNT method simply return the number of bounces (e.g. 103)

LIST method returns a paged list

 Click here to expand...

Disclaimer: addresses used in the example here below have been invented as examples of wrong emails, it is not guaranteed that they actually match with the bounce "Type" that is specified for each of them

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Message/11826/List/Bounces?PageSize=10&PageNumber=1 (change page size to 10 and retreive the second page)

Read unsubscribed recipients by message

This feature allows to extract either the number or the full list of the recipients whose unsubscription is related to specified message.

Description

Get recipients whose unsubscription is related to the specified message

HTTP Method

GET

URL

Get the number of unsubscribed (COUNT)

 

Get a detailed list of unsubscribed (LIST, paging is set as default with pageSize=20).

JSON request (example)

none

JSON response (example)

COUNT method simply return the number of unsubscribed recipients (e.g. 103)

LIST method returns a paged list

 Click here to expand...

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Message/11826/List/Unsubscriptions?PageSize=10&PageNumber=1 (change page size to 10 and retreive the second page)

 


Get Statistics by Recipient

This section enables you to get statistics related to a recipient by specifying its ID. You can get recipient ID by using "Check if a subscriber exists" method. For each type of statistics by message both a "COUNT" method (only the total number) and a "LIST" method (all available details) are provided.

Read delivered messages by recipient

Please note that delivery details are kept inside MailUp only for 15 days, after that period COUNT returns zero and LIST returns an empty array.

Description

Get the email messages received by the specified recipient

HTTP Method

GET

URL

Get the email messages received by the specified recipient (COUNT)

 

Get the email messages received by the specified recipient (LIST, paging is set as default with pageSize=20)

JSON request (example)

none

JSON response (example)

COUNT method simply return the number of delivered messages (e.g. 2)

LIST method returns a paged list (default page size = 20)

 Click here to expand...

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Recipient/1378914/List/Deliveries?PageSize=10&PageNumber=1 (change page size to 10 and retreive the second page)

If you want to retreive only the messages that are related to a particular list you can specify the "FilterBy" option (e.g. only messages that belong to list 51

  • /Recipient/1378914/List/Deliveries?filterby="IdList+%3d%3d+51"

Read opens by recipient

Full details about opens are kept for at least 90 days, this period is longer if your console account has activated the "Detailed Statistics Extension" option.

Description

Get opens for the specified recipient

HTTP Method

GET

URL

Get the number of opens for the specified recipient (COUNT)

 

Get a list of messages that were opened by the specified recipient (LIST, paging is set as default with pageSize=20)

JSON request (example)

none

JSON response (example)

COUNT method simply return the number of opens (e.g. 13)

LIST method returns a detailed list of opened messages (each message could have been opened the message more than once by the same recipient, see "Count" parameter for each recipient). The list is paged by default if the number of returned items is higher than 20

 Click here to expand...

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Recipient/300501/List/Views?PageSize=5&PageNumber=1 (change page size to 5 and retreive the second page)

If you want to retreive only the messages that are related to a particular list you can specify the "FilterBy" option (e.g. only messages that belong to list 51)

  • /Recipient/300501/List/Views?filterby="IdList+%3d%3d+51"

If you want to retreive only the messages that have been opened more than once by specified recipient you can specify the "FilterBy" option (e.g. Count >=2)

Read clicks by recipient

Full details about clicks are kept for at least 90 days, this period is longer if your console account has activated the "Detailed Statistics Extension" option.

Description

Get clicks performed by the specified recipient

HTTP Method

GET

URL

Get the number of clicks for the specified message (COUNT)

 

Get a list messages in which the specified recipients has performed at least one click (LIST, paging is set as default with pageSize=20)

JSON request (example)

none

JSON response (example)

COUNT method simply return the number of clicks (e.g. 13)

LIST method returns a list of clicked messages (the specified recipient could have clicked the message more than once, see "Count" parameter for each message). The list is paged by default if the number of returned items is higher than 20

 Click here to expand...

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Recipient/300501/List/Clicks?PageSize=5&PageNumber=1 (change page size to 5 and retreive the second page)

Full details about clicks are kept for at least 90 days, this period is longer if your console account has activated the "Detailed Statistics Extension" option.

Description

Get the distribution of clicks done by the specified recipient

HTTP Method

GET

URL

Get a list of links, grouped by message, that the specified recipient has clicked (LIST, paging is set as default with pageSize=20). For each link a click counter is provided.

JSON request (example)

none

JSON response (example)

ClicksDetails returns a paged list of message links with at least one click. For each message both the clicked URL and the number of clicks are provided. The list is paged by default if the number of returned items is higher than 20

 Click here to expand...

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Recipient/300501/List/ClicksDetails?PageSize=5&PageNumber=1 (change page size to 5 and retreive the second page)

Read bounces by recipient

Description

Get bounces that have been reported for the specified recipient

HTTP Method

GET

URL

Get the number of bounces related to the specified recipient (COUNT)

 

Get a list of messages in which a bounce condition occurred for specified recipient (LIST, paging is set as default with pageSize=20)

 

Get a detailed list of messages in which a bounce condition occurred for specified recipient (DETAILED LIST, paging is set as default with pageSize=20)


JSON request (example)

none

JSON response (example)

COUNT method simply return the number of bounces (e.g. 4)

LIST method returns a paged list

 Click here to expand...

DETAILED LIST method returns a paged list that includes also the message details (subject and notes)

 Click here to expand...


Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Recipient/1419659/List/Bounces?PageSize=10&PageNumber=1 (change page size to 10 and retreive the second page)

Read clicks on unsubscription link by recipient

This feature allows to extract either the unsubscriptions made by specified recipient

Description

Get information about the unsubscriptions by the specified recipient

HTTP Method

GET

URL

Get the number of clicks on any "Unsubscribe" link by the specified recipient (COUNT)

 

Get a detailed list of clicks on "Unsubscribe" link by the specified recipient (LIST, paging is set as default with pageSize=20).

JSON request (example)

none

JSON response (example)

COUNT method simply return the number of recipients who clicked on Unsubsribe link (e.g. 1)

LIST method returns a paged list

 Click here to expand...

In this example recipient unsubscribed by means of unsubscription link of message 11775 on list 1 

Paging and filtering (example)

If you want to change the paging size you can take advantage of the "PageSize" option.

  • /Recipient/1419828/List/Unsubscriptions?PageSize=10&PageNumber=1 (change page size to 10 and retreive the second page)

Access to built-in pages for email statistics

MailUp also provides some public pages that display some of the available statistics. These pages do not provide all the details you can obtain by properly combining the methods listed above, but in some cases it could be an acceptable tradeoff. (Note: you may also use the returned URL to extract the account URL)

Description

Get a list of public pages

HTTP Method

GET

URL

Get a list of URLs

JSON request (example)

none

JSON response (example)

 Click here to get the list of available pages...
  • Overall report by message
  • Login page ("console" URL)
  • Click trend
  • Opens by message
  • Link tracking by message
  • Readers by message
  • Mailings by message ("sent" report)
  • Clicks split by filters
  • Opens split by filters
 Click here to expand...

This is an example provided when requesting pages related to message with ID=11118 (on list 67) for the account with URL=example.mailup.com

Paging and filtering (example)

 

 

message

  • No labels