Перейти к основному содержимому
Опубликовано: 

Управление стоп-листами через Sendsay API

Стоп-лист — это реестр контактов, который система автоматически исключает из рассылок. При выпуске рассылки CDP Sendsay проверяет каждый адрес по стоп-листу: если адрес найден, письмо ему не отправляется.

Стоп-листы

Параметр ignore_stoplist: 1 позволяет отправить письмо даже на адрес из стоп-листа. Это дополнительная возможность, которая используется для отправки обязательных уведомлений (подтверждение удаления аккаунта, юридически значимые уведомления). Для её подключения .

Типы записей стоп-листа​

Существует два типа записей:

  • Стоп-лист владельца (owner) — вы им полностью управляете. Соответствует стоп-листу Заблокированы вручную.
  • Стоп-лист получателя (member) — получатель вносит себя сам при отписке. Соответствует стоп-листу Отписались от всех рассылок.

Зоны действия записей​

  • Глобальная (по умолчанию) — запись исключает адрес из выпуска всегда.
  • По отправителю — запись содержит адрес отправителя и исключает адресата только из выпусков с этим же отправителем. Соответствует стоп-листу Отписки от отправителей. Это дополнительная услуга, для подключения .

Для одного адреса может одновременно существовать и глобальная запись, и записи по разным отправителям, для каждого типа (owner и member).

Стоп-лист по домену отправителя

Отдельного стоп-листа по домену нет, но если включена соответствующая настройка, проверки по отправителю будут положительными для любого отправителя с тем же доменом. Например, если есть отписка от news@myshop.ru, то promo@myshop.ru тоже будет заблокирован, а info@sale.myshop.ru — нет (домены разные).

Внести в стоп-лист — stoplist.add​

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

Параметры​

ПараметрОписание
typeТип стоп-листа: owner (по умолчанию) или member
senderАдрес отправителя. Если пуст или не указан — глобальный стоп-лист. Может быть массивом адресов

Способы указания получателей​

СпособОписаниеСинхронность по умолчанию
emailОдин адрес или телефонСинхронно
listМассив адресов/телефоновСинхронно
groupКод спискаАсинхронно
group.filterФильтр отбораАсинхронно
urlСсылка на файл со списком контактов (по одному на строке, возможен ZIP)Асинхронно
stat.uniВыборка из универсальной статистикиАсинхронно

Синхронность можно изменить параметром sync: 0|1. Одновременно может выполняться не более двух таких запросов.

Пример: добавление в глобальный стоп-лист​

{
  "apikey": "ваш-api-ключ",
  "action": "stoplist.add",
  "type": "owner",
  "email": "test@test.com"
}

Пример: добавление в стоп-лист по отправителю​

{
  "apikey": "ваш-api-ключ",
  "action": "stoplist.add",
  "type": "owner",
  "sender": "news@myshop.ru",
  "email": "test@test.com"
}

Пример: массовое добавление по списку​

{
  "apikey": "ваш-api-ключ",
  "action": "stoplist.add",
  "type": "owner",
  "list": ["test1@test.com", "test2@test.com", "test3@test.com"]
}

Ответ (синхронный)​

{
  "list": {
    "test1@test.com": 1,
    "test2@test.com": 1,
    "test3@test.com": 0
  }
}

Возможные значения:

  • 1 — внесён,
  • 0 — не внесён,
  • строка с кодом — синтаксическая ошибка в адресе.

Ответ (асинхронный)​

{
  "track.id": 12345
}
Важно

Если активна настройка stoplist.owner_to_member, то добавления с type: "owner" или type: "all" выполняются как type: "member".

Удалить из стоп-листа — stoplist.delete​

Вы можете удалить адрес из стоп-листа — он перестанет автоматически исключаться из рассылок (если нет других причин, например, стоп-лист получателя, ошибки доставки и т. д.).

Параметры​

ПараметрОписание
typeТип стоп-листа: owner (по умолчанию), member или all
senderАдрес отправителя. Если пуст — глобальный стоп-лист. Может быть массивом адресов

Способы указания получателей — аналогичны stoplist.add. Запрос с list всегда асинхронный.

Удаление из стоп-листа получателя (type: "member") работает только в пределах месячного лимита, который составляет 0,1% от размера вашей базы по тарифу, но не более 1 тыс. контактов.

Важно

Для тарифов без ограничений на размер базы, лимит на удаление из стоп-листа — 100 контактов в месяц.

Пример: удаление из глобального стоп-листа владельца​

{
  "apikey": "ваш-api-ключ",
  "action": "stoplist.delete",
  "type": "owner",
  "email": "test@test.com"
}

Пример: удаление из стоп-листа по отправителю​

{
  "apikey": "ваш-api-ключ",
  "action": "stoplist.delete",
  "type": "owner",
  "sender": "news@myshop.ru",
  "email": "test@test.com"
}

Пример: удаление по группе​

{
  "apikey": "ваш-api-ключ",
  "action": "stoplist.delete",
  "type": "owner",
  "group": "reactivated_users"
}

Чтение записей стоп-листа — stoplist.get​

Вы можете посмотреть записи стоп-листа, используя вызов stoplist.get.

Важно

Альтернативный способ посмотреть записи стоп-листа — использовать stat.uni. Этот способ позволяет быстрее загружать информацию, использовать фильтры и сохранять результат в файл или прислать по почте.

Параметры​

ПараметрОписание
typeТип стоп-листа: all (по умолчанию), owner или member. Рекомендуется указывать явно, чтобы избежать получения лишних данных
senderАдрес отправителя. Если пуст — глобальный стоп-лист
listМассив интересующих адресов. Если не указан — возвращаются все записи

Пример: проверка конкретных адресов​

{
  "apikey": "ваш-api-ключ",
  "action": "stoplist.get",
  "type": "all",
  "list": ["client1@test.com", "client2@test.com"]
}

Ответ​

{
  "list": {
    "client1@test.com": {
      "owner": 1,
      "member": 1
    },
    "client2@test.com": {
      "owner": 1
    }
  }
}

В ответе присутствуют только адреса, найденные в стоп-листе.

Очистить стоп-лист — stoplist.erase​

Используя вызов stoplist.erase вы можете удалить все записи из стоп-листа. Вызов асинхронный.

Важно

Операция очистки стоп-листа необратима.

Параметры​

ПараметрОписание
typeТип стоп-листа: owner (по умолчанию), member или all
senderАдрес отправителя. Если пуст — очищается глобальный стоп-лист. Специальное значение " ALL " (с пробелами) — удаляет записи и из глобального, и из всех стоп-листов по отправителям

Пример: очистить глобальный стоп-лист владельца​

{
  "apikey": "ваш-api-ключ",
  "action": "stoplist.erase",
  "type": "owner"
}

Пример: очистить всё​

{
  "apikey": "ваш-api-ключ",
  "action": "stoplist.erase",
  "type": "owner",
  "sender": " ALL "
}

Ответ​

{
  "track.id": 12345
}

Стоп-лист в статистике​

Запрос позволяет выгружать историю внесения адресов в стоп-лист. Данные о стоп-листе доступны через stat.uni:

{
  "apikey": "ваш-api-ключ",
  "action": "stat.uni",
  "select": ["stoplist.email", "stoplist.dt"],
  "filter": [{ "a": "stoplist.dt:YM", "op": ">=", "v": "2026-01-01" }],
  "order": ["-stoplist.dt"],
  "limit": 100
}

Особенности работы со стоп-листами через Sendsay API​

  • Контакт в стоп-листе остаётся в базе — его данные не удаляются. Он просто не получает рассылки.
  • Вызовы завершатся ошибкой при попытке управлять стоп-листом получателя (type: "member") без полученного разрешения или при достижении месячного лимита.
  • Стоп-листом по отправителю можно управлять, но он игнорируется при выпуске, если не получено соответствующее разрешение.
  • member.sendconfirm с параметром unsubcancel: 1 или unsubsendercancel: 1 позволяет отправить контакту ссылку для самостоятельного удаления из стоп-листа.