Получить информацию о действиях подписчика

/v2/Api/Activities GET

Возвращает список определенных действий пользователя. Например, список кликов. Только для чтения.

Формат запроса

Параметры запроса:

Параметр Тип Описание
apiKey string Ваш API-key, необходимый для авторизации. Обязательный.
date date Дата. Обязательный. Формат — YYYY-MM-DD.
type string Тип требуемой активности. Обязательный.
columns string Возвращаемые столбцы, доступны следующие значения:
  • Standard (по умолчанию)
  • Extended (В CSV будут возвращены дополнительные столбцы, дополнительную информацию смотрите ниже)
returnTitle boolean Если true, то будет воозвращен дополнительный столбец с заголовком ссылки отправленного письма. Эта опция работает только для активности по кликам (Clicks)
returnGuid boolean Если true, то будет воозвращен дополнительный столбец с GUID Globally Unique Identifier отправленного письма. Эта опция не работает для активности по подпискам (Subscriptions) и подтверждениям подписки (Confirmations)

Поддерживаемые типы активностей:

Тип Описание
Subscriptions Новые подписчики в листах. Также содержит подписчиков, которые были импортированы, добавлены вручную ит.д.
Confirmations Подтвержденные подписчики.
Sends Отправленные подписчикам сообщения. Одному подписчику может быть отправлено несколько сообщений, и все они будут включены.
Opens Открытия сообщений. Если подписчик открыл сообщение несколько раз, все эти события будут включены.
Clicks Клики по ссылкам. Тоже самое.
Removals Отписавшиеся и вручную удаленные из листа подписчики.
Complaints Подписчики которые пожаловались на спам.
Bounces Bounces сообщения (Отказы)*.
Goals Достигнутые цели.

*Существуют разные типы Bounces:

  1. Hardbounce сразу добавляются в черные списки, и письма этим пользователям не отправляются.
  2. Softbounce (когда причинами ошибки являются не такие критичные вещи, как несуществование емейл-адреса, а, к примеру, переполнение ящика, временная блокировка пользователя, автоответчик, который пользователь поставил на время отпуска) — добавляются в черный список после отправления шести писем на такой ящик. Этот параметр можно изменить — сделать его меньше (меню «Настройки субаккаунта— Другое»).
    3. Также есть возможность работы с ошибками доставки (отчеты по ошибкам доставки): выгрузить те ошибки, причины которых вы считаете уж достаточными для того, чтобы добавить в черные списки — ну и, собственно, добавить в эти черные списки.
  3. Complaints (Жалобщики) (определенные с помощью FBL, который прописывали в настройках домена) — также добавляются в черные списки.
  4. GlobalBlackList. В системе имеется глобальный черный список, с которым происходит сверка на этапе загрузки базы в систему. Данные по этой загрузке можно посмотреть в меню «Отчеты»— по импорту листов.

Примеры: 

https://api.esv2.com/v2/Api/Activities?apiKey=Ваш_API-ключ&date=2011-11-25&type=Clicks
https://api.esv2.com/v2/Api/Activities?apiKey=Ваш_API-ключ&date=2011-11-26&type=Confirmations
https://api.esv2.com/v2/Api/Activities?apiKey=Ваш_API-ключ&date=2011-11-25&type=Sends&returnGuid=true

Ответ

Возвращает информацию по действиям подписчика в отправленном письме. Этот метод отличается от других тем, что возвращает ответ в CSV-формате, а не в XML. Сделано это потому, что иногда объем данных бывает очень большим. CSV позволяет проще парсить и обрабатывать данные.

Content-type ответа — «text/csv». Данные содержат строку заголовков. CSV формируется, используя следующие настройки:

  • разделитель полей: запятая (,)
  • ограничитель: двойная кавычка (")
  • кодировка: UTF-8

От типа запрошенной активности зависит то, какие колонки вернутся в CSV. Ниже смотрите список колонок для каждого типа активности.

Колонки для подписчика (Subscriptions):

Имя Тип Описание
Date datetime Дата подписки. YYYY-MM-DD HH:MM:SS.
Email string Емейл подписчика.
ListId int Идентификатор листа.
ListName string Имя листа.

Колонки для подтвержденных подписчиков (Confirmations):

Имя Тип Описание
Date datetime Дата подтверждения. YYYY-MM-DD HH:MM:SS.
Email string Емейл подписчика.
ListId int Идентификатор листа.
ListName string Имя листа.

Колонки для отправленных писем подписчику (Sends):

Имя Тип Описание
Date datetime Дата отправки. YYYY-MM-DD HH:MM:SS.
Email string Емейл подписчика.
MessageId int Идентификатор отправленного сообщения.
MessageSubject string Тема отправленного сообщения.
ListId int Идентификатор листа.*
ListName string Имя листа.*
MessageGuid string GUID отправленного письма.**
*Дополнительные столбцы.
**Возвращается только если параметр returnGuid установлен в true.

Колонки для открытых писем подписчиком (Opens):

Имя Тип Описание
Date datetime Дата открытия. YYYY-MM-DD HH:MM:SS.
Email string Емейл подписчика.
MessageId int Идентификатор открытого сообщения.
MessageSubject string Тема открытого сообщения.
ListId int Идентификатор листа.*
ListName string Имя листа.*
MessageGuid string GUID отправленного письма.**
*Дополнительные столбцы.
**Возвращается только если параметр returnGuid установлен в true.

Колонки для кликов в письмах подписчиком (Clicks):

Имя Тип Описание
Date datetime Дата клика. YYYY-MM-DD HH:MM:SS.
Email string Емейл подписчика.
MessageId int Идентификатор сообщения, содержащего ссылку, по которой кликнули.
MessageSubject string Тема сообщения, содержащего ссылку, по которой кликнули.
Url String URL ссылки (или ее шаблон, если ссылка персонализированная).
ListId int Идентификатор листа.*
ListName string Имя листа.*
MessageGuid string GUID отправленного письма.**
*Дополнительные столбцы.
**Возвращается только если параметр returnGuid установлен в true.

Колонки жалоб подписчика (Complaints):

Имя Тип Описание
Date datetime Дата жалобы. YYYY-MM-DD HH:MM:SS.
Email string Емейл подписчика.
MessageId int Идентификатор сообщения, на которое пожаловались.
MessageSubject string Тема сообщения, на которое пожаловались.
ListId int Идентификатор листа.*
ListName string Имя листа.*
MessageGuid string GUID отправленного письма.**
*Дополнительные столбцы.
**Возвращается только если параметр returnGuid установлен в true.

Колонки ошибок доставки подписичика (Bounces):

Имя Тип Описание
Date datetime Дата жалобы. YYYY-MM-DD HH:MM:SS.
Email string Емейл подписчика.
Reason string Причина ошибки. Дополнительную информацию смотрите ниже.
MessageId int Идентификатор сообщения, при отправке которого в ответе вернулась ошибка
DiagnosticCode string Диагностический код ошибки, описывающий тип ошибки. Не обязательное (если email не содержит диагностический код ошибки).
ListId int Идентификатор листа.*
ListName string Имя листа.*
MessageGuid string GUID отправленного письма.**
*Дополнительные столбцы.
**Возвращается только если параметр returnGuid установлен в true.

Колонки целей подписчика (Goals):

Имя Тип Описание
Date datetime Дата удаления. YYYY-MM-DD HH:MM:SS.
Email string Емейл подписчика.
MessageId int Идентификатор сообщения из которого была достигнута цель.
MessageSubject string Тема сообщения из которого была достигнута цель.
GoalValue int Значение достигнутой цели. Может быть равно 0, если значение цели не задано.
ListId int Идентификатор листа.*
ListName string Имя листа.*
MessageGuid string GUID отправленного письма.**
*Дополнительные столбцы.
**Возвращается только если параметр returnGuid установлен в true.

Колонки удаленного подписчика (Removals):

Имя Тип Описание
Date datetime Дата удаления. YYYY-MM-DD HH:MM:SS.
Email string Емейл подписчика.
Reason string Причина удаления. Смотрите ниже все возможные причины.
MessageId int Идентификатор сообщения, которое вызвало удаление. Необязательный (некоторые причины
удаления не связаны с сообщениями).
MessageSubject string Тема сообщения, которое вызвало удаление. Необязательный.
ListId int Идентификатор листа.*
ListName string Имя листа.*
MessageGuid string GUID отправленного письма.**
*Дополнительные столбцы.
**Возвращается только если параметр returnGuid установлен в true.

Причины удаления (Removals):

Имя Описание
Subscriber Подписчик отписался от рассылки, используя ссылку отписки, или иным способом.
User Подписчик был вручную удален из листа в веб-интерфейсе.
Bounce Подписчик был автоматически удален, так как исчерпал предел bounce.
Spam Подписчик был автоматически удален после жалобы на спам.
UserUnknown Подписчик был автоматически удален, потому что емейл не существует (был bounce “userunknown”).
Api Подписчик был удален через API.

Причины ошибок (Bounce):

Имя Описание
UserUnknown Емейл не существует.
MailboxFull Почтовый ящик подписчика заполнен или временно недоступен по другой причине.
Blocked Отправленное сообщение было заблокировано, возможно, по причине спама.
OutOfOffice Почтовый ящик автоматически ответил «outofoffice».
Unknown Неизвестная причина.
Other Другая причина. Сюда входят ошибки доставки, баги mail-сервера и т. д.

Примеры

Запрос: 

GET https://api.esv2.com/v2/Api/Activities?date=2010-10-01&apiKey=Ваш_API-ключ&type=Sends HTTP/1.1 
Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com

Ответ: 

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

Запрос с дополнительными колонками: 

GET https://api.esv2.com/v2/Api/Activities?date=2010-10-01&apiKey=Ваш_API-ключ&type=Sends&columns=Extended HTTP/1.1 
Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com

Ответ: 

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

Запрос с информацией о кликах: 

https://api.esv2.com/v2/Api/Activities?apiKey=Ваш_API-ключ&date=2010-10-01&type=Clicks&returnTitle=true

Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com

Ответ: 

Date,Email,MessageId,MessageSubject,URL,Title
2010-10-01 17:10:00,test1@yahoo.com,1168,Welcome on board,https://www.google.ru,123,header
2010-10-01 17:10:00,test2@yahoo.com,1168,Welcome on board,https://www.google.ru,main_CTA
2010-10-01 17:11:00,test3@yahoo.com,1168,Welcome on board,https://www.google.ru,footer