Экспорт и миграция данных Brevo: как перенести данные в систему и из неё

Частота запросов вроде «brevo data export migration to another platform» объясняется одним опасением: что накопленные данные проще загрузить в систему, чем забрать обратно. Честный ответ по Brevo такой: большая часть выгружается чисто, часть выгружается в виде, который придётся пересобирать, а небольшая, но важная доля не переносится вообще.

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

Что действительно можно экспортировать из Brevo

Контакты и атрибуты

Путь в интерфейсе: CRM, затем «Контакты». Чтобы выгрузить всю базу, убедитесь, что не загружен ни список, ни сегмент и не применены фильтры. Чтобы выгрузить один список или сегмент, сначала нажмите «Загрузить список или сегмент» и выберите нужный.

Дальше вы отмечаете, какие стандартные и пользовательские атрибуты включить. EMAIL, дата последнего изменения и дата создания выбраны по умолчанию, остальное добавляете вы сами, и именно на этом шаге чаще всего ошибаются. Выберите разделитель полей CSV, точку с запятой или запятую, и при желании включите отправку экспорта по почте, чтобы ссылка на скачивание ушла на адрес владельца аккаунта. Нажмите «Начать экспорт», затем скачайте файл из колокольчика уведомлений рядом с именем аккаунта.

Списки и сегменты

Списки выгружаются как членство: сделайте по одному экспорту на список или включите метаданные _listIds в один полный экспорт и разделите файл потом. GET /v3/contacts/lists отдаёт названия списков, их идентификаторы и идентификаторы папок, чтобы вы могли воссоздать структуру на другой стороне.

С сегментами всё иначе, и это первый настоящий пробел. GET /v3/contacts/segments возвращает только id, segmentName, categoryName и updatedAt. Условия фильтра, которые определяют сегмент, не отдаются. Вы можете выгрузить участников сегмента на момент времени, но правило, которое их породило, придётся считывать с экрана и пересобирать вручную в новом инструменте. Сделайте скриншот каждого сегмента до закрытия аккаунта.

Статистика кампаний

Из отчёта по кампании данные можно выгрузить в CSV, а отчёты по email и SMS дополнительно предлагают версию в PDF для рассылки коллегам или печати. Для полной исторической выгрузки GET /v3/emailCampaigns принимает параметр statistics со значениями globalStats, linksStats или statsByDomain, а также пару startDate и endDate на диапазон до двух лет.

Транзакционные логи

Два пути с разными окнами.

GET /v3/smtp/statistics/events возвращает отдельные события с фильтром по типу (delivered, opened, clicks, hardBounces, spam, unsubscribed и другие). Диапазон дат не может превышать 90 дней, а по умолчанию берутся последние 30 дней, если не передан ни диапазон, ни параметр days.

Для массовой выгрузки POST /v3/webhooks/export создаёт задание экспорта за последние 7 дней сырых событий, с ограничением в 20 заданий на каждые 7 дней. Оно возвращает processId, вызывает ваш notify URL по завершении и отдаёт CSV со столбцами, включая date, email, event, message-id, reason, sending_ip, subject, tag и template_id. Большие объёмы приходят сжатым архивом из нескольких файлов CSV.

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

Что не поедет с вами

Эту часть большинство руководств по миграции пропускает.

• Структуры автоматизаций. API умеет запускать автоматизации через события, но документированного эндпоинта, который читает ветвления, задержки и условия сценария, нет. Каждый сценарий пересобирается на новой платформе вручную.
• Определения фильтров сегментов. Как сказано выше, доступны только названия и текущий состав участников.
• Полная история вовлечённости по каждому контакту. Вы можете выгрузить тех, кто открыл, кликнул, не открыл, отписался, а также жёсткие и мягкие отказы по конкретной кампании, используя customContactFilter на эндпоинте экспорта. Чего получить нельзя, так это единого аккуратного файла со всеми открытиями и кликами каждого контакта за всё время, потому что эндпоинты сырых событий ограничены 90 днями.
• Точность рендеринга шаблонов. htmlContent выгружается чисто, но drag-and-drop-блоки, синтаксис подстановочных тегов и плейсхолдеры ссылок отписки специфичны для платформы. Выгруженный HTML является отправной точкой, а не готовым шаблоном. Заложите время на повторное тестирование каждого шаблона в новом редакторе.
• Репутация доставляемости. Репутация отправителя живёт на отправляющих IP-адресах и аутентифицированном домене. Новая платформа, новый пул IP, новый прогрев. Сохранение того же домена и конфигурации DKIM сохраняет доменную часть репутации, и это действительно помогает, но сторону IP не переносит.
• Идентификаторы форм, лендингов и трекинга. У форм подписки, лендингов и скрипта отслеживания идентификаторы специфичны для платформы. Всё, что встроено на сайт, придётся заменить, а любая аналитика, привязанная к этим идентификаторам, ломается в момент переключения.

Скриптовый экспорт для крупных аккаунтов

Примерно от 100 000 контактов экспорт через интерфейс становится медленным и неудобным, да и повторяемое задание вам всё равно нужно. Эндпоинт экспорта контактов асинхронный: он принимает фильтр, возвращает идентификатор процесса и отдаёт CSV по завершении.

curl --request POST \
  --url https://api.brevo.com/v3/contacts/export \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'api-key: YOUR_API_KEY' \
  --data '{
    "customContactFilter": { "actionForContacts": "allContacts" },
    "exportMandatoryAttributes": true,
    "exportAttributes": ["FIRSTNAME", "LASTNAME", "SMS", "COUNTRY"],
    "exportMetadata": ["_listIds", "ADDED_TIME", "MODIFIED_TIME"],
    "exportSubscriptionStatus": ["email_marketing", "sms_marketing"],
    "exportDateInUTC": true,
    "notifyUrl": "https://example.com/hooks/brevo-export"
  }'

Успешный вызов возвращает HTTP 202 и тело с processId. exportMandatoryAttributes по умолчанию равен true и покрывает EMAIL, ADDED_TIME и MODIFIED_TIME, поэтому свои пользовательские поля вы перечисляете в exportAttributes. Именно exportSubscriptionStatus кладёт в файл состояние маркетингового согласия по email и SMS, и его пропуск является самым частым способом получить экспорт, бесполезный для законной миграции.

Если вы предпочитаете обходить записи постранично, а не ждать задание, GET /v3/contacts принимает limit до 1000 вместе с offset, плюс modifiedSince и createdSince для инкрементальных выгрузок. Каждый контакт возвращается с полями emailBlacklisted, smsBlacklisted, listIds, listUnsubscribed и consentGroups, а это всё, что нужно для восстановления состояния согласий.

Следите за лимитами, когда пишете такой скрипт. Эндпоинты контактов допускают 36 000 запросов в час и 10 в секунду на стандартных тарифах, вдвое больше на Professional и Enterprise, тогда как большинство остальных эндпоинтов ограничены 100 запросами в час. Обход миллиона контактов по 1000 на страницу это 1000 запросов, что комфортно укладывается в бюджет контактов, а вот долбить в цикле эндпоинты кампаний или шаблонов уже нельзя.

Почему список подавления нужно переносить первым

Переносите отказы раньше всего остального.

Юридический аргумент прост. Контакт, который отписался, отозвал согласие у вашего бренда. Этот отзыв не обнуляется от того, что вы сменили подрядчика. По GDPR запись о согласии и его отзыве является вашей обязанностью как контролёра, а по CAN-SPAM отказ должен быть исполнен в течение десяти рабочих дней и действует бессрочно. Потеря списка при миграции не является технической случайностью, это нарушение комплаенса с документальным следом, ведущим к вам.

Аргумент про доставляемость на практике ещё жёстче. Среди подавленных адресов непропорционально много тех, кто жаловался, дал жёсткий отказ или активно хотел уйти. Рассылка им с нового IP без репутации является самым известным способом получить троттлинг или блокировку новой отправки на первой же неделе. Несколько тысяч переработанных спам-ловушек и жалобщиков сводят на нет месяц аккуратного прогрева.

Поэтому выгружайте подавленные когорты явно, а не надейтесь, что они подразумеваются. На эндпоинте экспорта actionForContacts принимает unsubscribed для контактов, заблокированных любым способом, и unsubscribedPerList для отказавшихся от одного конкретного списка. Отдельным проходом соберите hardBounces по каждой кампании. На входе в новую платформу импортируйте этот файл в её список подавления, а не в рассылаемый список.

Brevo обрабатывает и обратный случай: он поддерживает импорт списка заблокированных контактов, а API импорта принимает булевы emailBlacklist и smsBlacklist, поэтому загруженный файл попадает в подавление. Обратите внимание на асимметрию, которую Brevo правильно делает обязательной: контакты нельзя разблокировать массово, потому что массовая повторная подписка того, кто просил его не трогать, была бы незаконной. Подавление легко добавить и намеренно трудно снять. Считайте это правильным поведением, а не препятствием.

Чек-лист миграции из Brevo

1. Аудит. Посчитайте контакты, списки, сегменты, активные автоматизации, шаблоны и интеграции. Запишите, какие интеграции пишут данные в Brevo, потому что именно эти трубы придётся перенаправлять.
2. Экспорт. Контакты со всеми атрибутами плюс статус подписки, по файлу на список или один файл с _listIds, когорты подавления отдельными файлами, статистика кампаний, транзакционные события настолько глубоко, насколько позволяет окно в 90 дней, и HTML шаблонов.
3. Заархивируйте то, что истекает. Всё, что ограничено по времени (сырые события, логи), исчезает, когда окно сдвигается. Сложите это в собственное хранилище или объектное хранилище прямо сейчас.
4. Почистите и сопоставьте. Уберите дубликаты, приведите к единому виду форматы дат и телефонов и напишите явное сопоставление столбцов с полями новой платформы. Это же естественный момент, чтобы удалить адреса без активности за год, что дешевле, чем платить за прогрев мёртвого груза. Пороговые значения разбирает наше руководство по очистке списка рассылки.
5. Сначала загрузите подавление. Импортируйте отказы и жёсткие отказы в список подавления новой платформы, сверьте, что количества совпадают с экспортом, и только потом загружайте рассылаемые контакты.
6. Прогрев. Начните с самого вовлечённого сегмента, наращивайте объём постепенно и ежедневно следите за долей отказов и жалоб. Подробную последовательность даёт наше руководство по доставляемости писем.
7. Поработайте параллельно. Оставьте Brevo включённым и отправляющим критичную транзакционную почту, пока новая платформа берёт на себя растущую долю маркетинговых рассылок. Не переключайте оба потока сразу.
8. Проверьте. Сверьте количество контактов, выборочно проверьте двадцать контактов поле за полем, убедитесь пробной отправкой, что подавленные контакты действительно подавлены, и сравните неделю объёма отправки со старой платформой.
9. Переключитесь и сохраните откат. Меняйте DNS и эндпоинты интеграций в окно, когда за этим кто-то наблюдает. Держите аккаунт Brevo живым и оплаченным как минимум один полный биллинговый цикл после переключения, а выгруженные файлы храните вне обеих платформ. Именно это, а не обещание вендора, является вашим настоящим планом отката.

Миграция в Brevo с другой платформы

Тот же чек-лист выполняется в обратную сторону, с тремя замечаниями, специфичными для Brevo.

Получите настоящий экспорт у прежнего вендора. Большинство платформ отдают контакты и их пользовательские поля в CSV. Отдельно запросите список подавления и список отказов: они часто лежат в отдельной выгрузке, о которой забывают. Если вы переходите с модели оплаты за контакт, сравните, сколько вы реально заплатите на входе, с помощью нашего руководства по тарифам Brevo.

Сопоставьте поля до загрузки. У атрибутов Brevo есть типы (текст, число, дата, булев, категория), и дата, попавшая в текстовый атрибут, позже не будет фильтроваться. Сначала создайте атрибуты с правильными типами, потом импортируйте.

Импортируйте через API всё сколько-нибудь крупное. POST /v3/contacts/import принимает встроенный CSV в fileBody, массив JSON в jsonBody, оба с ограничением около 10 МБ, либо удалённый файл через fileUrl, а также listIds или объект newList. updateExistingContacts по умолчанию равен true и сопоставляет записи по email. Сделайте один импорт с emailBlacklist в true для файла подавления, затем второй импорт для рассылаемых контактов. Полные рабочие скрипты есть в нашем руководстве по импорту контактов из CSV в Brevo скриптом.

Затем пересоберите то, что не перенеслось: автоматизации, сегменты, формы и шаблоны. Отправьте тестовое письмо на несколько почтовых провайдеров, прежде чем писать реальным людям.

Не превращайте следующую миграцию в обрыв

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

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

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