Как вернуть статусы писем Unisender Go в CRM

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

Unisender Go — сервис отправки email. API — интерфейс обмена данными — позволяет системе запросить отправку, а webhook — получить уведомление о последующем событии на свой сервер. Это два направления обмена, и успешность первого не подтверждает успешность второго.

Задача интеграции — связать статус с конкретной отправкой, сохранить его смысл и выполнить нужное бизнес-действие один раз. Ниже — контракт обработки, предлагаемый CRM Lab. Имена полей поставщика сверены со справочником Web API.

Сохраните связь с отправкой

В ответе email/send возвращается job_id — идентификатор задания. Webhook передаёт события пакетами; у события transactional_email_status могут присутствовать job_id, email, status, event_time и metadata. Метаданные помогают вернуть ваш контекст отправки.

До обращения к сервису создайте собственный message_id. Это идентификатор бизнес-отправки внутри CRM, а не попытки сетевого запроса. Сохраните получателя, сценарий, версию шаблона и основание сообщения. После ответа добавьте идентификатор задания поставщика. Если в задании несколько адресатов, одного job_id недостаточно для различения получателей.

Не связывайте ответ только по текущему email клиента. К моменту получения webhook адрес в профиле мог измениться. Нужна связь с адресом именно той отправки и постоянным клиентским ID. В metadata передавайте минимальные технические ключи; полный состав заказа или персональные сведения для сопоставления обычно не нужны.

Разделите состояния доставки и реакции

В справочнике Go accepted означает приём сообщения, sent — отправку без подтверждённой доставки, delivered — доставку. Отдельные статусы сообщают об открытиях, кликах, отписке и жалобе. В event_time используется время UTC без смещения на местный часовой пояс.

Для CRM удобно хранить несколько независимых признаков: результат доставки, зарегистрированную реакцию и запрет дальнейших маркетинговых коммуникаций. Одно поле «последний статус» теряет смысл. Если после отписки пришло запоздавшее уведомление о доставке, оно не должно восстановить разрешение писать.

Доставка не подтверждает попадание во входящие или чтение человеком. Открытие и клик также могут содержать автоматические действия почтовых систем. В отчёте называйте наблюдаемый факт точно: «зарегистрирован переход», а не «клиент заинтересовался предложением».

Обрабатывайте webhook как отдельный процесс

Проверьте подлинность уведомления предусмотренным Go способом через поле auth; алгоритм описан в справочнике. Разбирайте все события внутри пакета, а не только первый элемент. Проверку подлинности выполняйте до применения статусов к клиентским записям.

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

Нужна защита от повторных событий: повтор webhook не должен повторно начислять бонус, отправлять сообщение менеджеру или увеличивать число уникальных доставок. При этом два настоящих клика по одной ссылке не обязательно являются дублем. Заранее определите идентичность события и отдельно — уникальность бизнес-действия, которое оно вызывает.

Проверьте порядок получения событий

Условный пример. Письмо доставлено в 10:00, клиент отписался в 10:05. Из-за задержки обработчика CRM сначала получила отписку, затем доставку. Если система просто заменяет статус последним пришедшим значением, профиль ошибочно вернётся в разрешённую аудиторию.

Правильная модель сохранит оба факта с временем события и временем получения. Доставка дополнит историю письма, а отписка останется отдельным ограничением. Повторное согласие, если оно появится, обрабатывается по собственному подтверждённому основанию. Оно не выводится из технического статуса старого сообщения.

Проверьте также неизвестный job_id, отсутствие необязательного поля, уведомление, не прошедшее проверку подлинности, повтор целого пакета и временную недоступность CRM. Для неизвестной отправки сохраните событие в очередь разбора: причина может быть в том, что webhook пришёл раньше завершения записи ответа API.

Настройте сверку и восстановление

Следите за задержкой обратных статусов и долей отправок, для которых долго нет ожидаемого результата. Порог выбирайте с учётом очередей и допустимого времени доставки. Отсутствие webhook не равно недоставке: возможен сбой самого обратного канала.

Предусмотрите сверку с доступной статистикой сервиса и повторную обработку сохранённых уведомлений. Повторная обработка статуса не должна повторять первоначальную отправку письма. Для восстановления задайте период, набор отправок и критерий завершения сверки.

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

Источники

Unisender Go. Справочник Web API. Документация Unisender Go. Проверено 23.09.2026.