Skip to content

Get subscriber activity

Activities collection allows retrieving a list of subscriber activity entries of specified kind. For example, a list of all clicks can be retrieved. This collection is, by its nature, read only. 

Request datformat

Request URL parameters:

Element/attributeTypeNotes
apiKeystringYour API key, required for authentication. Required.
datedateDate. Required, YYYY-MM-DD format.
channelstringLimit returned data to selected channel. Applicable only for the following activity types: Subscriptions, Sends, Clicks, Removals, Bounces, Goals. Optional. Defaults to Email. Valid values: All; Email; SmsMms.
typestringType of activity data to return. See below for all available options. Required.
columnsstringReturned columns. Optional. Can be one of the following:Standard (default value)Extended (additional columns are returned in the CSV – see below for details)
returnTitlebooleanIf set to true, additional column with link title will be returned. This option has no effect for activities other than Clicks.
returnGuidbooleanIf set to true, additional column with sent message GUID (globally unique identifier) will be returned. This option has no effect for Subscriptions and Confirmations activity types.
tagsstringComma-separated list of tags. Optional. If specified, only messages tagged with all provided tags will be returned. (Each comma works as AND operator. For OR operator, separate requests need to be created.) The parameter is only available for the following types: Sends, Opens, Clicks, Complaints, Removals, Bounces, Goals. System tags cannot be searched (API, D&D, A/B).
returnMessageContentIdbooleanIf set to true, additional column with sent message content ID will be returned. This option has no effect for Subscriptions and Confirmations activity types.
returnSegmentIdbooleanIf set to true, additional column with segment ID will be returned. This option has no effect for Subscriptions and Confirmations activity types.
returnActivityIpbooleanIf set to true, additional column with Activity Ip will be returned. This option has no effect for Subscriptions, Sends, Complaints and Bounces activity types.

Supported activity data types:

TypeReturned data
SubscriptionsNew subscriptions to lists. That also include subscribers that were imported, added manually etc.
ConfirmationsSubscription confirmations. This only applies to double opt-in lists.
SendsSent messages to individual subscribers. A single subscriber can receive multiple messages and all those events will be included.
OpensMessage opens. If a subscriber opens a message multiple times (the same or different message) all events will be included.
ClicksLink clicks. Same as above.
ComplaintsSpam complaints.
RemovalsUnsubscriptions and manual removal of subscribers from lists.
BouncesBounced messages.
GoalsFulfilled business goals.

URL examples:

https://api.esv2.com/v2/Api/Activities?apiKey=YOUR_API_KEY_HERE&date=2011-11-25&type=Clicks

https://api.esv2.com/v2/Api/Activities?apiKey=YOUR_API_KEY_HERE&date=2011-11-26&type=Subscriptions&channel=SmsMms

https://api.esv2.com/v2/Api/Activities?apiKey=YOUR_API_KEY_HERE&date=2011-11-25&type=Sends&returnGuid=true

https://api.esv2.com/v2/Api/Activities/145408?apiKey=test_api_key1&date=2023-07-28&type=Opens&returnActivityIp=true 

Response 

This method differs from other methods by returning the data in CSV format, rather than XML. This is because the amount of data will usually be larger. CSV allows for reducing the overhead and is generally easier to parse and manipulate.

Response content type will be “text/csv”. Returned data will contain a header with column names. CSV will be formatted using following settings:

  • Field separator: comma (,)
  • Quoting character: (“)
  • Escape character: (“)
  • Encoding: UTF-8 

Returned columns depend on requested activity type. See below for a complete listing of all columns for all available activity types.

Columns for Subscriptions activity:

NameTypeNotes
DatedatetimeSubscription date. YYYY-MM-DD HH:MM:SS format.
EmailstringSubscriber’s email.
PhoneintSubscriber’s phone number.
ListIdintList identifier.
ListNamestringList name.
CustomSubscriberIdstring    Subscriber’s custom ID. 
ChannelstringChannel to which the activity is connected.*  

* Returned only if channel option was set to All.

Columns for Confirmations activity:

NameTypeNotes
DatedatetimeConfirmation date. YYYY-MM-DD HH:MM:SS format.
EmailstringSubscriber’s email.
ListIdintList identifier.
ListNamestringList name.
CustomSubscriberIdstring    Subscriber’s custom ID.

Columns for Sends activity:

NameTypeNotes
DatedatetimeSend date. YYYY-MM-DD HH:MM:SS format.
EmailstringSubscriber’s email.
PhoneintSubscriber’s phone number.
MessageIdintIdentifier of sent message.
MessageSubjectstringSubject of sent message.
CustomSubscriberIdstring    Subscriber’s custom ID. 
Channelstring    Channel to which the activity is connected.*
ListIdintList identifier.**
ListNamestringList name.**
MessageGuidstringSent message GUID.*** 
MessageContentId   intIdentifier of opened message content.****
SegmentIdintSegment identifier.*****

* Returned only if channel option was set to All.
** Extended columns.
*** Returned only if returnGuid option was set to true.
**** Returned only if returnMessageContentId option was set to true.
***** Returned only if returnSegmentId option was set to true. If only a list was used then it will return 0.

Columns for Opens activity:

NameTypeNotes
DatedatetimeOpen date. YYYY-MM-DD HH:MM:SS format.
EmailstringSubscriber’s email.
MessageIdintIdentifier of opened message.
MessageSubjectstringSubject of opened message.
CustomSubscriberIdstring    Subscriber’s custom ID. 
ListIdintList identifier.*
ListNamestringList name.*
MessageGuidstringSent message GUID.**
MessageContentIdintIdentifier of opened message content.***
SegmentIdintSegment identifier.*****

* Extended columns.
** Returned only if returnGuid option was set to true.
*** Returned only if returnMessageContentId option was set to true
***** Returned only if returnSegmentId option was set to true. If only a list was used then it will return 0.

Columns for Clicks activity:

NameTypeNotes
DatedatetimeClick date. YYYY-MM-DD HH:MM:SS format.
EmailstringSubscriber’s email.
PhoneintSubscriber’s phone number.
MessageIdintIdentifier of message containing clicked link.
MessageSubjectstringSubject of message containing clicked link.
UrlstringURL of clicked link (or URL template if link was personalized).
CustomSubscriberIdstring    Subscriber’s custom ID. 
Channelstring    Channel to which the activity is connected.*
TitlestringTitle of clicked link (if “title” attribute was present in HTML).
ListIdintList identifier.**
ListNamestringList name.**
MessageGuidstringSent message GUID.***
MessageContentIdintIdentifier of message content containing clicked link.****
SegmentIdintSegment identifier.*****

* Returned only if channel option was set to All.
** Extended columns.
*** Returned only if returnGuid option was set to true.
**** Returned only if returnMessageContentId option was set to true.
***** Returned only if returnSegmentId option was set to true. If only a list was used then it will return 0.

Columns for Complaints activity:

NameTypeNotes
DatedatetimeComplaint date. YYYY-MM-DD HH:MM:SS format.
EmailstringSubscriber’s email.
MessageIdintIdentifier of message that caused complaint.
MessageSubjectstringSubject of message that caused complaint.
CustomSubscriberIdstring    Subscriber’s custom ID. 
ListIdintList identifier.*
ListNamestringList name.*
MessageGuidstringSent message GUID.**
MessageContentIdintIdentifier of message content for message that caused complaint.***
SegmentIdintSegment identifier.*****

* Extended columns.
** Returned only if returnGuid option was set to true.
*** Returned only if returnMessageContentId option was set to true.
***** Returned only if returnSegmentId option was set to true. If only a list was used then it will return 0.

Columns for Removals activity:

NameTypeNotes
DatedatetimeRemoval date. YYYY-MM-DD HH:MM:SS format.
EmailstringSubscriber’s email.
PhoneintSubscriber’s phone number.
ReasonstringRemoval reason. See below for all possible reasons.
MessageIdintIdentifier of message that caused removal. Optional (some removal reasons are not connected to sent messages).
MessageSubjectstringSubject of message that caused complaint. Optional.
CustomSubscriberIdstring    Subscriber’s custom ID. 
Channelstring    Channel to which the activity is connected.*
ListIdintList identifier.**
ListNamestringList name.**
MessageGuidstringSent message GUID.***
MessageContentIdintIdentifier of message content for message that caused removal. Optional (some removal reasons are not connected to sent messages).****
SegmentIdintSegment identifier.*****

* Returned only if channel option was set to All.
** Extended columns.
*** Returned only if returnGuid option was set to true.
**** Returned only if returnMessageContentId option was set to true.
***** Returned only if returnSegmentId option was set to true. If only a list was used then it will return 0.

Columns for Bounces activity:

NameTypeNotes
DatedatetimeBounce date. YYYY-MM-DD HH:MM:SS format.
EmailstringSubscriber’s email.
PhoneintSubscriber’s phone number.
ReasonstringBounce reason. See below for all possible bounce reasons.
MessageIdintIdentifier of message that was bounced.
DiagnosticCodestrigBounce diagnostic code used to recognize bounce type. Optional (if bounce email did not contain diagnostic code).
CustomSubscriberIdstring    Subscriber’s custom ID. 
Channelstring    Channel to which the activity is connected.*
ListIdintList identifier.**
ListNamestringList name.**
MessageGuidstringSent message GUID.***
MessageContentIdintIdentifier of message content for message that was bounced.****
SegmentIdintSegment identifier.*****

* Returned only if channel option was set to All.
** Extended columns.
*** Returned only if returnGuid option was set to true.
**** Returned only if returnMessageContentId option was set to true.
***** Returned only if returnSegmentId option was set to true. If only a list was used then it will return 0.

Columns for Goals activity: 

NameTypeNotes
DatedatetimeGoal fulfillment date. YYYY-MM-DD HH:MM:SS format.
EmailstringSubscriber’s email.
PhoneintSubscriber’s phone number.
MessageIdintIdentifier of message that caused the goal to become fulfilled.
MessageSubjectstringSubject of message that caused the goal to become fulfilled.
GoalValueintFulfilled goal value. Can be 0 if goal had no particular value assigned. 
GoalIdint Goal identifier. 
CustomSubscriberIdstringSubscriber’s custom ID. 
ChannelstringChannel to which the activity is connected.*
ListIdintList identifier.**
ListNamestringList name.**
MessageGuidstringSent message GUID.***
MessageContentIdintIdentifier of message content for message that caused the goal to become fulfilled.****
SegmentIdintSegment identifier.*****

* Returned only if channel option was set to All.
** Extended columns.
*** Returned only if returnGuid option was set to true.
**** Returned only if returnMessageContentId option was set to true.
***** Returned only if returnSegmentId option was set to true. If only a list was used then it will return 0.

Removal reasons:

NameDescription
SubscriberSubscriber has unsubscribed from link using an unsubscribe link or otherwise.
UserSubscriber was manually removed by user.
BounceSubscriber was automatically removed because of reaching bounce limit.
SpamSubscriber was automatically removed after sending spam complaint.
UserUnknownSubscriber was automatically removed because the email address does not exist (caused “user unknown” bounce).
ApiSubscriber was removed using API.

Bounce reasons: 

NameDescription
UserUnknownEmail does not exist.
MailboxFullSubscriber’s mailbox is full or otherwise temporary inaccessible.
BlockedSent message was blocked, possibly for spam-related reasons.
OutOfOfficeMailbox returned automated “out of office” reply.
UnknownUnknown reason.
OtherOther bounce reason. This category contains transport-related issues, mail server bugs etc.

Examples

Request:

GET https://api.esv2.com/v2/Api/Activities?date=2010-10-01&apiKey=test_api_key1&type=Sends 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/csv; charset=utf-8 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 2.0 
X-AspNet-Version: 2.0.50727 
Set-Cookie: TIMEZONE=Central European Standard Time; path=/ 
X-Powered-By: ASP.NET 
Date: Thu, 08 Dec 2011 12:02:14 GMT 
Content-Length: 463  

 
Date,Email,MessageId,MessageSubject 
2010-10-01 17:10:00,test1@yahoo.com,1168,some test subject 
2010-10-01 17:10:00,test2@yahoo.com,1168,some test subject 
2010-10-01 17:11:00,test3@yahoo.com,1168,some test subject 
2010-10-01 17:11:00,test4@yahoo.com,1168,some test subject 
2010-10-01 19:20:00,john.doe@gmail.com,1170,Hello dear subscriber

Request with extended columns:

GET https://api.esv2.com/v2/Api/Activities?date=2010-10-01&apiKey=test_api_key1&type=Sends&columns=Extended 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/csv; charset=utf-8 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 2.0 
X-AspNet-Version: 2.0.50727 
Set-Cookie: TIMEZONE=Central European Standard Time; path=/ 
X-Powered-By: ASP.NET 
Date: Thu, 08 Dec 2011 12:02:14 GMT 
Content-Length: 523  
 

Date,Email,MessageId,MessageSubject,ListId,ListName 
2010-10-01 17:10:00,test1@yahoo.com,1168,some test subject,123,some list name 
2010-10-01 17:10:00,test2@yahoo.com,1168,some test subject,123,some list name  
2010-10-01 17:11:00,test3@yahoo.com,1168,some test subject,123,some list name   
2010-10-01 17:11:00,test4@yahoo.com,1168,some test subject,123,some list name   
2010-10-01 19:20:00,john.doe@gmail.com,1170,Hello dear subscriber,456,other list

Request with GUID:

GET https://api.esv2.com/v2/Api/Activities?date=2010-10-01&apiKey=test_api_key1&type=Sends&returnGuid=true 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/csv; charset=utf-8 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 2.0 
X-AspNet-Version: 2.0.50727 
Set-Cookie: TIMEZONE=Central European Standard Time; path=/ 
X-Powered-By: ASP.NET 
Date: Thu, 08 Dec 2011 12:02:14 GMT 
Content-Length: 523  
 

Date,Email,MessageId,MessageSubject,MessageGuid 
2010-10-01 17:10:00,test1@yahoo.com,1168,some test subject,c7015756-95f3-4509-8c6c-759feec48f91 
2010-10-01 17:10:00,test2@yahoo.com,1168,some test subject,f1184a56-86d5-461e-ac1b-0000040bb27b
2010-10-01 17:11:00,test3@yahoo.com,1168,some test subject,d56a7c29-885f-4fcc-8f85-00001392908b
2010-10-01 17:11:00,test4@yahoo.com,1168,some test subject,180668e3-7ea1-4f12-83b3-000004f11566
2010-10-01 19:20:00,john.doe@gmail.com,1170,Hello dear subscriber,a01b5b76-c61d-4533-bc3f-0000142e085d

Request with message content id and segment id:

GET https://api.esv2.com/v2/Api/Activities?date=2010-10-01&apiKey=test_api_key1&type=Opens&returnMessageContentId=true&returnSegmentId=true 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/csv; charset=utf-8 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 2.0 
X-AspNet-Version: 2.0.50727 
Set-Cookie: TIMEZONE=Central European Standard Time; path=/ 
X-Powered-By: ASP.NET 
Date: Thu, 08 Dec 2011 12:02:14 GMT 
Content-Length: 523  
 

Date,Email,MessageId,MessageSubject,CustomSubscriberId,MessageContentId,SegmentId
2010-10-01 17:10:00,test1@yahoo.com,1168,some test subject,c7015756-95f3-4509-8c6c-759feec48f91,,1222,34
2010-10-01 17:10:00,test2@yahoo.com,1168,some test subject,f1184a56-86d5-461e-ac1b-0000040bb27b,,1222,34
2010-10-01 17:11:00,test3@yahoo.com,1168,some test subject,d56a7c29-885f-4fcc-8f85-00001392908b,,1222,34
2010-10-01 17:11:00,test4@yahoo.com,1168,some test subject,180668e3-7ea1-4f12-83b3-000004f11566,,1222,34
2010-10-01 19:20:00,john.doe@gmail.com,1170,Hello dear subscriber,a01b5b76-c61d-4533-bc3f-0000142e085d,,1224,0

Request with Activity Ip :

GET https://api.esv2.com/v2/Api/Activities/145408?apiKey=test_api_key1&date=2023-07-28&type=Opens&returnActivityIp=true  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/csv; charset=utf-8 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 2.0 
X-AspNet-Version: 2.0.50727 
Set-Cookie: TIMEZONE=Central European Standard Time; path=/ 
X-Powered-By: ASP.NET 
Date: Thu, 08 Dec 2011 12:02:14 GMT 
Content-Length: 523  
 

Date,Email,MessageId,MessageSubject,CustomSubscriberId,ActivityIp 
2023-07-28 09:30:00,test1@yahoo.com,147849,Test preference center :),,127.0.0.1 
2023-07-28 09:30:00,test2@yahoo.com,147849,Test preference center :),,127.0.0.1 
2023-07-28 09:30:00,test3@yahoo.com,147849,Test preference center :),,127.0.0.1 
2023-07-28 09:30:00,test4@yahoo.com,147849,Test preference center :),,127.0.0.1 
2023-07-28 09:30:00,test5@yahoo.com,147849,Test preference center :),,127.0.0.1 
On this page
To top