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 data format
Request URL parameters:
| Element/attribute | Type | Notes |
|---|---|---|
| apiKey | string | Your API key, required for authentication. Required. |
| date | date | Date. Required, YYYY-MM-DD format. |
| channel | string | Limit 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. |
| type | string | Type of activity data to return. See below for all available options. Required. |
| columns | string | Returned columns. Optional. Can be one of the following: Standard (default value) Extended (additional columns are returned in the CSV – see below for details) |
| returnTitle | boolean | If set to true, additional column with link title will be returned. This option has no effect for activities other than Clicks. |
| returnGuid | boolean | If 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. |
| tags | string | Comma-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). |
| returnMessageContentId | boolean | If set to true, additional column with sent message content ID will be returned. This option has no effect for Subscriptions and Confirmations activity types. |
| returnSegmentId | boolean | If set to true, additional column with segment ID will be returned. This option has no effect for Subscriptions and Confirmations activity types. |
| returnActivityIp | boolean | If set to true, additional column with Activity Ip will be returned. This option has no effect for Subscriptions, Sends, Complaints and Bounces activity types. |
| returnDeliveryIp | boolean | If set to true, additional column with Delivery Ip will be returned. This option has no effect for Subscriptions, Complaints and Bounces activity types. |
Supported activity data types:
| Type | Returned data |
|---|---|
| Subscriptions | New subscriptions to lists. That also include subscribers that were imported, added manually etc. |
| Confirmations | Subscription confirmations. This only applies to double opt-in lists. |
| Sends | Sent messages to individual subscribers. A single subscriber can receive multiple messages and all those events will be included. |
| Opens | Message opens. If a subscriber opens a message multiple times (the same or different message) all events will be included. |
| Clicks | Link clicks. Same as above. |
| Complaints | Spam complaints. |
| Removals | Unsubscriptions and manual removal of subscribers from lists. |
| Bounces | Bounced messages. |
| Goals | Fulfilled 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:
| Name | Type | Notes |
|---|---|---|
| Date | datetime | Subscription date. YYYY-MM-DD HH:MM:SS format. |
| string | Subscriber’s email. | |
| Phone | int | Subscriber’s phone number. |
| ListId | int | List identifier. |
| ListName | string | List name. |
| CustomSubscriberId | string | Subscriber’s custom ID. |
| Channel | string | Channel to which the activity is connected.* |
* Returned only if channel option was set to All.
Columns for Confirmations activity:
| Name | Type | Notes |
|---|---|---|
| Date | datetime | Confirmation date. YYYY-MM-DD HH:MM:SS format. |
| string | Subscriber’s email. | |
| ListId | int | List identifier. |
| ListName | string | List name. |
| CustomSubscriberId | string | Subscriber’s custom ID. |
| ActivityIp | int | The IP of the subscriber’s activity.* |
| DeliveryIp | int | IP address from which the message was sent.** |
* Returned only if returnActivityIp option was set to true.
** Returned only if returnDeliveryIp option was set to true.
Columns for Sends activity:
| Name | Type | Notes |
|---|---|---|
| Date | datetime | Send date. YYYY-MM-DD HH:MM:SS format. |
| string | Subscriber’s email. | |
| Phone | int | Subscriber’s phone number. |
| MessageId | int | Identifier of sent message. |
| MessageSubject | string | Subject of sent message. |
| CustomSubscriberId | string | Subscriber’s custom ID. |
| Channel | string | Channel to which the activity is connected.* |
| ListId | int | List identifier.** |
| ListName | string | List name.** |
| MessageGuid | string | Sent message GUID.*** |
| MessageContentId | int | Identifier of opened message content.**** |
| SegmentId | int | Segment identifier.***** |
| DeliveryIp | int | IP address from which the message was sent.****** |
* 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.
****** Returned only if returnDeliveryIp option was set to true.
Columns for Opens activity:
| Name | Type | Notes |
|---|---|---|
| Date | datetime | Open date. YYYY-MM-DD HH:MM:SS format. |
| string | Subscriber’s email. | |
| MessageId | int | Identifier of opened message. |
| MessageSubject | string | Subject of opened message. |
| CustomSubscriberId | string | Subscriber’s custom ID. |
| ListId | int | List identifier.* |
| ListName | string | List name.* |
| MessageGuid | string | Sent message GUID.** |
| MessageContentId | int | Identifier of opened message content.*** |
| SegmentId | int | Segment identifier.***** |
| ActivityIp | int | The IP of the subscriber’s activity.****** |
| DeliveryIp | int | IP address from which the message was sent.******* |
* 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.
****** Returned only if returnActivityIp option was set to true.
******* Returned only if returnDeliveryIp option was set to true.
Columns for Clicks activity:
| Name | Type | Notes |
|---|---|---|
| Date | datetime | Click date. YYYY-MM-DD HH:MM:SS format. |
| string | Subscriber’s email. | |
| Phone | int | Subscriber’s phone number. |
| MessageId | int | Identifier of message containing clicked link. |
| MessageSubject | string | Subject of message containing clicked link. |
| Url | string | URL of clicked link (or URL template if link was personalized). |
| CustomSubscriberId | string | Subscriber’s custom ID. |
| Channel | string | Channel to which the activity is connected.* |
| Title | string | Title of clicked link (if “title” attribute was present in HTML). |
| ListId | int | List identifier.** |
| ListName | string | List name.** |
| MessageGuid | string | Sent message GUID.*** |
| MessageContentId | int | Identifier of message content containing clicked link.**** |
| SegmentId | int | Segment identifier.***** |
| ActivityIp | int | The IP of the subscriber’s activity.****** |
| DeliveryIp | int | IP address from which the message was sent.******* |
* 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.
****** Returned only if returnActivityIp option was set to true.
******* Returned only if returnDeliveryIp option was set to true.
Columns for Complaints activity:
| Name | Type | Notes |
|---|---|---|
| Date | datetime | Complaint date. YYYY-MM-DD HH:MM:SS format. |
| string | Subscriber’s email. | |
| MessageId | int | Identifier of message that caused complaint. |
| MessageSubject | string | Subject of message that caused complaint. |
| CustomSubscriberId | string | Subscriber’s custom ID. |
| ListId | int | List identifier.* |
| ListName | string | List name.* |
| MessageGuid | string | Sent message GUID.** |
| MessageContentId | int | Identifier of message content for message that caused complaint.*** |
| SegmentId | int | Segment 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:
| Name | Type | Notes |
|---|---|---|
| Date | datetime | Removal date. YYYY-MM-DD HH:MM:SS format. |
| string | Subscriber’s email. | |
| Phone | int | Subscriber’s phone number. |
| Reason | string | Removal reason. See below for all possible reasons. |
| MessageId | int | Identifier of message that caused removal. Optional (some removal reasons are not connected to sent messages). |
| MessageSubject | string | Subject of message that caused complaint. Optional. |
| CustomSubscriberId | string | Subscriber’s custom ID. |
| Channel | string | Channel to which the activity is connected.* |
| ListId | int | List identifier.** |
| ListName | string | List name.** |
| MessageGuid | string | Sent message GUID.*** |
| MessageContentId | int | Identifier of message content for message that caused removal. Optional (some removal reasons are not connected to sent messages).**** |
| SegmentId | int | Segment identifier.***** |
| ActivityIp | int | The IP of the subscriber’s activity.****** |
| DeliveryIp | int | IP address from which the message was sent.******* |
* 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.
****** Returned only if returnActivityIp option was set to true.
******* Returned only if returnDeliveryIp option was set to true.
Columns for Bounces activity:
| Name | Type | Notes |
|---|---|---|
| Date | datetime | Bounce date. YYYY-MM-DD HH:MM:SS format. |
| string | Subscriber’s email. | |
| Phone | int | Subscriber’s phone number. |
| Reason | string | Bounce reason. See below for all possible bounce reasons. |
| MessageId | int | Identifier of message that was bounced. |
| DiagnosticCode | strig | Bounce diagnostic code used to recognize bounce type. Optional (if bounce email did not contain diagnostic code). |
| CustomSubscriberId | string | Subscriber’s custom ID. |
| Channel | string | Channel to which the activity is connected.* |
| ListId | int | List identifier.** |
| ListName | string | List name.** |
| MessageGuid | string | Sent message GUID.*** |
| MessageContentId | int | Identifier of message content for message that was bounced.**** |
| SegmentId | int | Segment 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:
| Name | Type | Notes |
|---|---|---|
| Date | datetime | Goal fulfillment date. YYYY-MM-DD HH:MM:SS format. |
| string | Subscriber’s email. | |
| Phone | int | Subscriber’s phone number. |
| MessageId | int | Identifier of message that caused the goal to become fulfilled. |
| MessageSubject | string | Subject of message that caused the goal to become fulfilled. |
| GoalValue | int | Fulfilled goal value. Can be 0 if goal had no particular value assigned. |
| GoalId | int | Goal identifier. |
| CustomSubscriberId | string | Subscriber’s custom ID. |
| Channel | string | Channel to which the activity is connected.* |
| ListId | int | List identifier.** |
| ListName | string | List name.** |
| MessageGuid | string | Sent message GUID.*** |
| MessageContentId | int | Identifier of message content for message that caused the goal to become fulfilled.**** |
| SegmentId | int | Segment identifier.***** |
| ActivityIp | int | The IP of the subscriber’s activity.****** |
| DeliveryIp | int | IP address from which the message was sent.****** |
* 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.
****** Returned only if returnActivityIp option was set to true.
******* Returned only if returnDeliveryIp option was set to true.
Removal reasons:
| Name | Description |
|---|---|
| Subscriber | Subscriber has unsubscribed from link using an unsubscribe link or otherwise. |
| User | Subscriber was manually removed by user. |
| Bounce | Subscriber was automatically removed because of reaching bounce limit. |
| Spam | Subscriber was automatically removed after sending spam complaint. |
| UserUnknown | Subscriber was automatically removed because the email address does not exist (caused “user unknown” bounce). |
| Api | Subscriber was removed using API. |
Bounce reasons:
| Name | Description |
|---|---|
| UserUnknown | Email does not exist. |
| MailboxFull | Subscriber’s mailbox is full or otherwise temporary inaccessible. |
| Blocked | Sent message was blocked, possibly for spam-related reasons. |
| OutOfOffice | Mailbox returned automated “out of office” reply. |
| Unknown | Unknown reason. |
| Other | Other 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.comOK 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 subscriberRequest 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.comOK 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 listRequest 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.comOK 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-0000142e085dRequest 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.comOK 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,0Request 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.comOK 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 Request with Delivery Ip :
GET https://api.esv2.com/v2/Api/Activities/145408?apiKey=test_api_key1&date=2023-07-28&type=Opens&returnDeliveryIp=true HTTP/1.1
Accept-Encoding: gzip,deflate
User-Agent: Jakarta Commons-HttpClient/3.1
Host: api.esv2.comOK 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,DeliveryIp
2023-07-28 09:30:00,test1@yahoo.com,147849,Test preference center :),,666.666.666.666
2023-07-28 09:30:00,test2@yahoo.com,147849,Test preference center :),,666.666.666.666
2023-07-28 09:30:00,test3@yahoo.com,147849,Test preference center :),,666.666.666.666
2023-07-28 09:30:00,test4@yahoo.com,147849,Test preference center :),,666.666.666.666
2023-07-28 09:30:00,test5@yahoo.com,147849,Test preference center :),,666.666.666.666