API для данных об открытиях

Поиск данных об открытиях #

get

/messages/outbound/opens

Позволяет получить данные об открытиях писем по заданным параметрам. Результаты сортируются по полю ReceivedAt в порядке убывания. События открытия хранятся в течение установленного периода хранения данных, который по умолчанию составляет 45 дней (его можно изменить в диапазоне от 7 до 365 дней). События, произошедшие раньше этого периода, через API недоступны.

Пример запроса с помощью curl

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

Параметры запроса (querystring)

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).

Данные об открытиях для одного письма #

get

/messages/outbound/opens/{messageid}

Получает все данные об открытиях для указанного письма. Результаты отсортированы по полю ReceivedAt в порядке убывания.

Пример запроса с помощью curl

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

Параметры запроса (querystring)

count	обязательный Ограничивает количество возвращаемых данных об открытиях на один запрос. Максимальное значение — 500.
offset	обязательный Указывает, сколько записей об открытиях нужно пропустить (для пагинации).

Формат ответа такой же, как и у запроса на поиск открытий. Для получения полной информации об этой конечной точке обратитесь к справочнику по API Сообщений.

Обзор

Интеграции

Руководство пользователя

Справочник API

Вебхуки

API для данных об открытиях

Поиск данных об открытиях #

/messages/outbound/opens

Пример запроса с помощью curl

Заголовки для аутентификации

Пример заголовка

Параметры запроса (querystring)

Ответ

Обязательные поля

Пример ответа

Дополнительные поля в ответе

Данные об открытиях для одного письма #

/messages/outbound/opens/{messageid}

Пример запроса с помощью curl

Заголовки для аутентификации

Пример заголовка

Параметры запроса (querystring)