Позволяет получить данные об открытиях писем по заданным параметрам. Результаты сортируются по полю ReceivedAt в порядке убывания. События открытия хранятся в течение установленного периода хранения данных, который по умолчанию составляет 45 дней (его можно изменить в диапазоне от 7 до 365 дней). События, произошедшие раньше этого периода, через API недоступны.
curl "https://api.haskimail.ru/messages/outbound/opens?recipient=john.doe@yahoo.com&tag=welcome-user&count=25&offset=0" \
-X GET \
-H "Accept: application/json" \
-H "X-Haskimail-Server-Token: server token"Данные об открытиях привязаны к серверам, поэтому для аутентификации и авторизации в запросах необходимо использовать заголовок X-Haskimail-Server-Token.
Имя и значение этого заголовка не чувствительны к регистру. Если вы выполните запрос с неверным или отсутствующим заголовком, то получите HTTP-ответ со статусом 401 (Unauthorized).
X-Haskimail-Server-Token: server token| count |
обязательный Количество возвращаемых записей об открытии в одном запросе (максимум 500). |
|---|---|
| offset |
обязательный Количество записей, которые нужно пропустить (используется для постраничной навигации). |
| recipient |
Фильтрация по адресу получателя (поля To, Cc или Bcc). |
| tag |
Фильтрация по тегу. |
| client_name |
Фильтрация по названию почтового клиента (например, Outlook, Gmail). |
| client_company |
Фильтрация по компании-разработчику клиента (например, Microsoft, Apple, Google). |
| client_family |
Фильтрация по семейству клиента (например, OS X, Chrome). |
| os_name |
Фильтрация по полному названию и версии ОС (например, OS X 10.9 Mavericks, Windows 7). |
| os_family |
Фильтрация по семейству ОС без указания версии (например, OS X, Windows). |
| os_company |
Фильтрация по компании-производителю ОС (например, Apple Computer, Inc., Microsoft Corporation). |
| platform |
Фильтрация по платформе (например, webmail, desktop, mobile). |
| country |
Фильтрация по стране, в которой было открыто письмо (например, Армения, Россия). |
| region |
Фильтрация по региону, в котором было открыто письмо (например, Санкт-Петербург, Московская область). |
| city |
Фильтрация по городу, в котором было открыто письмо (например, Новосибирск, Новосибирская область). |
При успешном выполнении запроса вы получите JSON-документ в формате, аналогичном примеру ниже.
Поля, всегда присутствующие в ответе
| TotalCount | integer |
Общее количество открытий, соответствующее заданным критериям поиска. Это число может быть больше, чем количество записей, возвращаемых в одном запросе. |
|---|---|---|
| Opens | array |
Массив объектов, где каждый объект описывает одно открытие письма. Обратите внимание: открытие уникально для каждого получателя. Поэтому, если одно и то же письмо было отправлено двум получателям и оба его открыли, в массиве будет две отдельные записи. |
| FirstOpen | boolean |
Показывает, является ли это открытие первым для уникальной пары «письмо-получатель». Все последующие открытия того же письма тем же получателем будут иметь в этом поле значение false. Haskimail сохраняет в своей базе данных только информацию о первых открытиях, тогда как данные обо всех открытиях доступны через вебхуки открытий. |
| UserAgent | string |
Полный заголовок User-Agent, переданный почтовым клиентом в Haskimail. На основе этих данных Haskimail заполняет поля Platform, Client и OS. |
| MessageID | string |
Уникальный идентификатор письма. |
HTTP/1.1 200 OK
Content-Type: application/json
{
"TotalCount": 1,
"Opens": [
{
"FirstOpen": true,
"Client": {
"Name": "Chrome 34.0.1847.131",
"Company": "Google Inc.",
"Family": "Chrome"
},
"OS": {
"Name": "OS X 10.7 Lion",
"Company": "Apple Computer, Inc.",
"Family": "OS X"
},
"Platform": "WebMail",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.131 Safari/537.36",
"Geo": {
"City": "St. Petersburg",
"Zip": "198205",
"Region": "St. Petersburg",
"RegionISOCode": "78",
"Country": "Russian Federation",
"CountryISOCode": "RU",
"IP": "50.31.208.163",
"Coords": "41.8776,-87.6272"
},
"MessageID": "927e56d4-dc66-4070-bbf0-1db76c2ae14b",
"ReceivedAt": "2014-04-30T05:04:23.8768746-04:00",
"Tag": "welcome-user",
"Recipient": "vasya.pupkin@mail.ru"
}
]
}При обработке полученного JSON-ответа учтите, что любое из следующих полей может отсутствовать. Если Haskimail не удалось получить какую-либо часть информации, соответствующее поле не будет включено в ответ.
| Client | object |
Объект с информацией о почтовом клиенте (или браузере), который использовался для открытия письма. Включает поля Name, company и family, описанные выше в параметрах запроса. |
|---|---|---|
| OS | object |
Объект с информацией об операционной системе, на которой было открыто письмо. |
| Platform | string |
Указывает, на какой платформе было открыто письмо. Возможные значения: WebMail (веб-интерфейс), Desktop (десктопный клиент), Mobile (мобильное устройство), Unknown (неизвестно). |
| Geo | object |
Объект, содержащий IP-адрес устройства получателя, на котором было открыто письмо, а также геолокационные данные, определенные по этому IP: координаты (Coords), страну (Country), регион (Region), город (City) и почтовый индекс (Zip). |
Получает все данные об открытиях для указанного письма. Результаты отсортированы по полю ReceivedAt в порядке убывания.
curl "https://api.haskimail.ru/messages/outbound/opens/:messageid?count=10&offset=0" \
-X GET \
-H "Accept: application/json" \
-H "X-Haskimail-Server-Token: server token"Данные об открытиях привязаны к серверам, поэтому для аутентификации и авторизации в запросах необходимо использовать заголовок X-Haskimail-Server-Token.
Имя и значение этого заголовка не чувствительны к регистру. Если вы выполните запрос с неверным или отсутствующим заголовком, то получите HTTP-ответ со статусом 401 (Unauthorized).
X-Haskimail-Server-Token: server token| count |
обязательный Ограничивает количество возвращаемых данных об открытиях на один запрос. Максимальное значение — 500. |
|---|---|
| offset |
обязательный Указывает, сколько записей об открытиях нужно пропустить (для пагинации). |
Формат ответа такой же, как и у запроса на поиск открытий. Для получения полной информации об этой конечной точке обратитесь к справочнику по API Сообщений.