Отримання активності контактів через API

Ресурс Get contacts activity повертає записи активності за повідомленнями, надісланими вашим контактам, за вказаний період. Кожен запис у відповіді містить статус — DELIVERED, UNDELIVERED, READ, CLICKED, UNSUBSCRIBED, SUBSCRIPTION_CHANGED або SPAM, — час події, а також повідомлення й контакт, яких вона стосується. Для UNDELIVERED повертається ще й причина.

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

Get contacts activity повертає окремі події активності за період і охоплює багатьох контактів одразу; нові події можуть зʼявлятися із затримкою в кілька хвилин.

Get contact's message history повертає історію повідомлень одного контакту, ідентифікатор якого потрібно передати в запиті, та відображає факт надсилання одразу. Тому використовуйте цей ресурс для перевірки перед повторним надсиланням. Повне порівняння методів отримання активності контактів, разом із вебхуками та експортом, — у розділі 6.

1. Запит

GET https://esputnik.com/api/v2/contacts/activity

Запити авторизуються через Basic HTTP Authentication, де паролем є API-ключ. API-ключі >

Обовʼязкові лише dateFrom і dateTo. Усі інші параметри — фільтри, які звужують вибірку.

Приклад запиту за одним контактом за два тижні:

curl --request GET \
  --url 'https://esputnik.com/api/v2/contacts/activity?dateFrom=2026-08-01T00:00:00&dateTo=2026-08-14T23:59:59&[email protected]&maxrows=25000' \
  --user 'YOUR_LOGIN:YOUR_API_KEY'

2. Період

• Значення без часу означає північ цієї дати за UTC. Щоб отримати активність за поточний день, вказуйте час у форматі ISO 8601 — наприклад, dateTo=2026-08-14T10:59:59.
• Активність зберігається 90 діб. Якщо dateFrom вказує на ранішу дату, записи за межами цього періоду не потраплять до відповіді. Для довготривалого зберігання отримуйте нові події вебхуками або експортуйте їх до BigQuery.

3. Посторінкове читання

За один запит повертається не більше maxrows записів. Для наступної сторінки надішліть той самий запит, передавши значення offset останнього отриманого запису. Продовжуйте, доки кількість отриманих записів не стане меншою за maxrows.

GET .../activity?dateFrom=...&dateTo=...&maxrows=25000
GET .../activity?dateFrom=...&dateTo=...&maxrows=25000&offset={last_offset}

Не змінюйте фільтри між сторінками: значення offset діє лише в межах початкової вибірки.

4. Відповідь

Відповідь — масив, у якому кожен запис описує одну подію активності за одним повідомленням. Кожен запис також містить значення offset для продовження читання.

Повідомлення

Контакт

Активність

Джерело повідомлення

Приклад запису:

[
  {
    "iid": "3f9a1c20-7624-11f1-a0dc-000000000000",
    "externalRequestId": "zamovlennya-48219",
    "contactId": 451677871,
    "externalCustomerId": "48219",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 3045908,
    "messageInstanceId": 6694763,
    "messageName": "Pidtverdzhennya zamovlennya",
    "messageLanguageCode": "uk",
    "activityDateTime": "2026-08-14T14:41:54",
    "imid": 29055000426,
    "offset": "MjAyNi0wOC0xNFQxNDo0MTo1NA"
  }
]

5. Типові задачі

5.1 Зіставити активність із власним запитом на надсилання

Це працює лише для повідомлень, надісланих ресурсом, який приймає externalRequestId: Send prepared message — окреме значення для кожного одержувача, а також Send email message, Send SMS message і Send Viber message — одне значення на весь запит. Повідомлення, надіслані сценарієм, масовою розсилкою або подією, цього поля не мають.

Передайте власний externalRequestId під час надсилання, а потім знайдіть його у відповіді про активність — він звʼязує активність із вашим запитом на надсилання. Один запит може містити кількох одержувачів з однаковим externalRequestId, тому для визначення окремого повідомлення додатково зіставляйте contactId, адресу або iid. Використання API-ресурсу Send prepared message >

externalRequestId не є параметром фільтра цього ресурсу — його потрібно шукати у вже отриманій відповіді.

5.2 Отримати дані про недоставлені повідомлення

Запитайте записи з activityStatus=UNDELIVERED і згрупуйте значення statusDescription, щоб виявити некоректні адреси, блокування на стороні серверів-одержувачів або системні проблеми з доставленням. Процес контролю доставлення >

6. Що обрати: активність, історію повідомлень, вебхуки чи експорт

Повʼязані статті

• Get contacts activity — повний перелік параметрів і полів
• Get contact's message history — історія повідомлень окремого контакту
• Використання API-ресурсу Send prepared message — відправка з власним externalRequestId
• Вебхуки — отримання активності в момент її появи
• Інтеграція eSputnik і Google BigQuery — експорт активності для аналітики