Перейти к основному содержимому

Как получить статистику через API

Sendsay API позволяет получить статистику о результатах доставки отправленных выпусков. Это реализуется через возвращаемые значения.

Отправка через API-консоль в Sendsay​

Для тестирования воспользуемся сервисом Webhook.site:

  1. Перейдите на Webhook.site и скопируйте URL для возвращаемых значений:

    Unique url

  2. В Sendsay перейдите в раздел API → API-консоль и вставьте запрос:

    {
       "action": "stat.uni",
       "select": [
           "issue.id",
           "issue.name"
       ],
       "result": [
           {
               "type": "url_file",
               "to": "ВАШ URL ДЛЯ ВОЗВРАЩАЕМЫХ ЗНАЧЕНИЙ (КОЛЛБЭКОВ)",
               "format": "json"
           }
       ]
    }

    где ВАШ URL ДЛЯ ВОЗВРАЩАЕМЫХ ЗНАЧЕНИЙ (КОЛЛБЭКОВ) — скопированный ранее URL для возвращаемых значений.

  3. Нажмите «Выполнить» и посмотрите результат на Webhook.site. Примерный результат должен выглядеть так:

    Request details

    Нажмите на ссылку «Download», чтобы скачать JSON-архив с данными статистики.

Отправка через Postman​

Протестируйте отправку запроса через Postman. Для этого вам потребуется уникальный API-ключ.

Как получить API-ключ

  1. Переходите в Postman и авторизуйтесь, либо зарегистрируйте новый аккаунт. Затем перейдите в раздел My Workspace, нажмите «New» и выберите HTTP — чтобы создать новый HTTP-запрос.

    Postman

  2. В параметрах запроса выберите метод POST. Затем выберите вкладку body и укажите raw, в раскрывающемся меню выберите JSON.

    Postman

  3. В поле URL вставьте https://api.sendsay.ru/general/api/v100/json/Ваш_логин_Sendsay. Вместо Ваш_логин_Sendsay необходимо добавить ваш логин, его можно скопировать в меню аккаунта:

Login

  1. В поле ниже вставьте запрос:

    {
       "apikey": "ВАШ API КЛЮЧ",
       "action": "stat.uni",
       "select": [
           "issue.id",
           "issue.name"
       ],
       "result": [
           {
               "type": "url_file",
               "to": "ВАШ URL ДЛЯ ВОЗВРАЩАЕМЫХ ЗНАЧЕНИЙ (КОЛЛБЭКОВ)",
               "format": "json"
           }
       ]
    }

    где ВАШ API КЛЮЧ — ваш API-ключ, сгенерированный в п.4; ВАШ URL ДЛЯ ВОЗВРАЩАЕМЫХ ЗНАЧЕНИЙ (КОЛЛБЭКОВ) — URL, скопированный в п.1.

    Postman

    Затем нажмите «Send».

    После отправки запроса должен прийти похожий ответ:

    Postman

    А на Webhook.site вы получите JSON-файл со статистикой:

    Webhook-site

    Это значит, что запрос выполнился успешно — и теперь вы можете получать данные статистики.

Базовые представления о получении статистики через stat.uni​

Универсальная статистика позволяет получить информацию про переходы, открытия писем, тиражи выпусков и результаты доставки выпусков рассылок. Все представленные ниже примеры вы можете проверить самостоятельно в API-консоли, при необходимости изменив под ваши конкретные нужды.

Статистика по выпуску​

Статистика по выпуску, которую вы видите в веб-интерфейсе Sendsay, получена из кэшированных данных — поэтому вы получаете эти сведения моментально.

Рассмотрим получение данных со всей базовой информацией по отправленным email-выпускам — например, за декабрь 2022 года:

{
    "action": "stat.uni",
    "result": "response",
    "select": ["issue.id", "issue.name", "issue.subject", "issue.dt:Ys", "issue.group.gid", "issue.group.name", "issue.members", "issue.deliv_ok", "issue.deliv_bad", "issue.readed", "issue.u_readed", "issue.clicked", "issue.u_clicked", "issue.unsubed"],
    "filter": [{
        "a": "issue.dt:Ys",
        "op": ">=",
        "v": "2022-12-01 00:00:00"
    }, {
        "a": "issue.dt:Ys",
        "op": "<=",
        "v": "2022-04-31 23:59:59"
    }, {
        "a": "issue.format",
        "op": "==",
        "v": "e"
    }],
    "order": ["-issue.dt:Ys"]
}

Статистика по выпускам заранее посчитана — и при необходимости вы можете запросить данные по всем отправленным выпускам за весь срок жизни вашего аккаунта.

А чтобы, например, узнать количество отправленных писем с PDF-вложениями за конкретный период, можно получить количество отправленных писем с разбивкой по значению поля issue.features:

{
    "action": "stat.uni",
    "select": [
        "issue.features",
        "sum(issue.members)"
    ],
    "filter": [
        {
            "a": "issue.dt:YM",
            "op": "==",
            "v": "2022-12"
        },
        {
            "a": "issue.format",
            "op": "==",
            "v": "e"
        }
    ]
}

С помощью этого запроса вы получите количество отправленных email-выпусков за декабрь 2022 года. Полный набор и описание полей, описывающих выпуск рассылки issue.*, есть в документации.

Статистика для конкретного получателя​

В отличие от статистики по выпуску, данные по конкретному получателю рассылок собираются и отдаются «на лету» — в момент выполнения запроса.

Данные о каждом типе событий хранятся каждая в своей области:

Нельзя в одном запросе добавить в select параметры, описывающие разные события.

Далее приведём примеры.

Все выпуски, отправленные за сегодня для конкретного емейла​

{
    "action": "stat.uni",
    "result": "response",
    "select": [
        "deliv.member.email",
        "deliv.issue.id",
        "deliv.issue.name",
        "deliv.issue.dt",
        "deliv.status"
    ],
    "filter": [
        {
            "a": "deliv.member.email",
            "op": "==",
            "v": "my@secret.email"
        },
        {
            "a": "deliv.issue.dt:YD",
            "op": "==",
            "v": "CURRENT"
        }
    ]
}

Количество кликов по каждой ссылке за сегодня для конкретного емейла​

{
    "action": "stat.uni",
    "result": "response",
    "select": [
        "click.member.email",
        "click.issue.id",
        "click.link.url",
        "count(*)"
    ],
    "filter": [
        {
            "a": "click.member.email",
            "op": "==",
            "v": "my@secret.email"
        },
        {
            "a": "click.issue.dt:YD",
            "op": "==",
            "v": "CURRENT"
        }
    ]
}

Если убрать из массива filter запроса объект, ограничивающий результаты конкретным емейлом, то в результате будут выведены все адреса, попадающие под оставшиеся условия запроса.

Важно

Общее количество строк в результате выполнения запроса не лимитируется, однако отправляемые запросы должны соответствовать базовым лимитам.

Вывод результата запроса​

Результат запроса к stat.uni вы можете получить синхронно — в ответе на сам запрос, а также ассинхронно, — сохранив результат в файле.

Выбранный способ вывода зависит от предполагаемого времени выполнения запроса и количества строк в результате. В целом, ничего не мешает вывести в браузере сотню тысяч строк результата, но жизнь брокера будет зависеть только от мощности вашего компьютера.

За результат выполнения запроса отвечает параметр result. В примерах выше ожидается синхронный ответ, и при выполнении запроса в API-консоли вы увидите результат на экране.

Если же вы трезво оцениваете сложность запроса и решили сохранить результат в файле, то вам стоит воспользоваться возможностями настройки параметра result API-запроса.

Сохранить в Файлы -> Отчеты -> stat.uni​

"result": "save"

Сохранить результат запроса на внешний FTP в utf8​

"result": [{
    "to": "ftp://login:password@ftp.yourserver/path/",
    "filename": "Clients",
    "format": "csv",
    "type": "url_file",
    "utf8": "1"
}]

Последовательность работы запроса stat.uni​

  1. Сервер находит все строки, подходящие под условия, указанные в filter.
  2. Если указан order, то найденные строки сортируются по указанному правилу. Если порядок не указан, то данные выведутся без сортировки, каждый раз по-разному.
  3. Если указан skip, то из вывода исключается указанное количество найденных строк.
  4. Если указан first, то выводится указанное количество строк; если не указан — выводятся все найденные строки.