Аккаунт
Выйти

Обзор

Интеграции

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

Справочник API

Вебхуки

Возвраты

Возвраты — письма, которые сервер получателя не принял. Серверный ключ видит возвраты только своего сервера, ключ аккаунта — всех серверов; сузить выборку до канала можно фильтром messagestream.

Статистика по доставке #

get

/deliverystats

Количество возвратов сервера ключа за последние 45 дней по типам. Первая запись (Name: All, без Type) — все возвраты вместе.

Заголовки запроса

Accept обязательный

application/json
X-Haskimail-Server-Token обязательный

Серверный API-ключ. Он есть в настройках сервера на вкладке «API-ключи».

Ответ

Bounces array

Количество возвратов по типам.
Bounces[].Type string

Тип возврата: HardBounce, SoftBounce, BulkBounce или SpamBlock. В списке возвратов BulkBounce называется BlkBounce, а SpamBlock — SpmBounce. У записи All типа нет.
Bounces[].Name string

Название типа.
Bounces[].Count integer

Количество возвратов.

Пример запроса с curl

curl "https://api.haskimail.ru/deliverystats" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Haskimail-Server-Token: server token"

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Bounces": [
    {
      "Name": "All",
      "Count": 253
    },
    {
      "Type": "HardBounce",
      "Name": "Hard bounce",
      "Count": 195
    },
    {
      "Type": "BulkBounce",
      "Name": "Bulk bounce",
      "Count": 12
    },
    {
      "Type": "SoftBounce",
      "Name": "Soft bounce",
      "Count": 38
    },
    {
      "Type": "SpamBlock",
      "Name": "Spam block",
      "Count": 8
    }
  ]
}

Получение списка возвратов #

get

/bounces

Возвращает возвраты сервера ключа, новые первыми.

Заголовки запроса

Accept обязательный

application/json
X-Haskimail-Server-Token обязательный

Серверный API-ключ. Он есть в настройках сервера на вкладке «API-ключи».

Параметры строки запроса

count

Количество возвратов в ответе. По умолчанию 500.
offset

Сколько возвратов пропустить. По умолчанию 0.
type

Тип возврата: HardBounce, SoftBounce, BlkBounce или SpmBounce. Принимаются и названия из статистики по доставке: BulkBounce вместо BlkBounce, SpamBlock вместо SpmBounce.
emailFilter

Email получателя, точное совпадение.
tag

Тег письма.
messageID

ID письма.
messagestream

ID канала.
fromdate

Начало периода, дата 2026-10-01, МСК. По умолчанию — месяц назад.
todate

Конец периода включительно, дата. По умолчанию — сегодня.

Ответ

TotalCount integer

Сколько всего возвратов подходит под фильтры запроса — без учета count и offset.
Bounces array

Возвраты.
Bounces[].Type string

Тип возврата: HardBounce, SoftBounce, BlkBounce или SpmBounce. В статистике по доставке два из них называются иначе: BulkBounce и SpamBlock.
Bounces[].Name string

Название типа.
Bounces[].Email string

Email получателя, которому не доставлено письмо.
Bounces[].RecordType string

Всегда Bounce.
Bounces[].MessageID string

ID письма.
Bounces[].ServerID integer

ID сервера.
Bounces[].MessageStream string

ID канала.
Bounces[].Description string

Причина возврата — ответ сервера получателя.
Bounces[].BouncedAt string

Время возврата, YYYY-MM-DD HH:MM:SS, МСК.
Bounces[].TypeCode string

Код причины возврата.
Bounces[].Subject string

Тема письма.
Bounces[].Tag string

Тег письма.

Пример запроса с curl

curl "https://api.haskimail.ru/bounces?count=50&offset=0" \
  -X GET \
  -H "Accept: application/json" \
  -H "X-Haskimail-Server-Token: server token"

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "TotalCount": 1,
  "Bounces": [
    {
      "Type": "HardBounce",
      "Name": "Hard bounce",
      "Email": "old-address@example.com",
      "RecordType": "Bounce",
      "MessageID": "a41d7c9e2b6f4e0d8c3b5a1f9e7d2c60",
      "ServerID": 11834,
      "MessageStream": "2081",
      "Description": "550 5.1.1 The email account that you tried to reach does not exist",
      "BouncedAt": "2026-10-07 14:30:15",
      "TypeCode": "550",
      "Subject": "Ваш заказ №1042 оформлен",
      "Tag": "orders"
    }
  ]
}

Типы возвратов #

Тип возврата в поле Type и в фильтре type. Два типа называются по-разному в разных методах: список возвратов отдает BlkBounce и SpmBounce, а статистика по доставке — BulkBounce и SpamBlock. Это одни и те же типы, и фильтр type принимает оба названия. Если сравниваете или фильтруете типы у себя, учитывайте оба.

HardBounceHardBounce

Жесткий возврат: адреса нет или ящик недоступен навсегда.

SoftBounceSoftBounce

Мягкий возврат: временная проблема — ящик переполнен, сервер получателя недоступен.

BlkBounceBulkBounce

Блокировка: сервер получателя отклонил письмо по своей политике или из-за репутации отправителя.

SpmBounceSpamBlock

Письмо отклонено как спам.

Первое название — в списке возвратов, второе — в статистике по доставке.