Отправка писем и транзакций через Adapty Mail API

Adapty Mail API позволяет отправлять профили пользователей и транзакции в Adapty Mail напрямую с вашего сервера, минуя SDK Adapty. Используйте его, если вы хотите:

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

API или SDK? Большинство приложений передают данные в Adapty Mail через Adapty SDK, который автоматически собирает email-адреса и покупки. Выбирайте API, если в вашем приложении нет Adapty SDK, если данные уже хранятся на вашем сервере или если вы импортируете подписчиков из другого источника.

Перед началом работы

Завершите настройку Adapty Mail до отправки данных — это значит создать кампанию, сегменты (если нужны), веб-пейвол и запустить флоу. Adapty Mail отправляет письма только профилям, созданным после завершения этой настройки; профили, добавленные раньше, не получат никаких писем. Сначала пройдите Начало работы с Adapty Mail, а затем возвращайтесь сюда.

Вам также понадобятся API-ключ и базовый URL:

Секретный API-ключ: В Adapty Mail перейдите в Settings и скопируйте секретный API-ключ. Ключ привязан к конкретному проекту, поэтому API знает, к какому проекту относятся данные.
Базовый URL: Все запросы отправляются на https://api-mail.adapty.io.
Аутентификация: Передавайте ключ в заголовке Authorization в формате Bearer {your_secret_api_key}.

Перед сбором email-адресов и их передачей в Adapty Mail получите явное согласие пользователей. Вы несёте ответственность за соответствие требованиям GDPR, CAN-SPAM и аналогичных законодательных актов в ваших регионах.

Отправка профилей пользователей

Профиль содержит email пользователя и его атрибуты. Чтобы создать или обновить профиль, отправьте POST-запрос на /api/v1/profile/save/.

Обязательные поля:

Стабильный external_profile_id, которым владеет ваше приложение или бэкенд
email — адрес, на который Adapty Mail доставляет кампании
external_created_at — время создания пользователя, которое можно использовать в сегментах

Всегда передавайте стабильный external_profile_id — никогда анонимный или привязанный к конкретной установке. Adapty Mail использует его, чтобы связывать письма, клики и покупки с одним профилем.

curl --request POST \
  --url 'https://api-mail.adapty.io/api/v1/profile/save/' \
  --header 'Authorization: Bearer {your_secret_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_profile_id": "user_12345",
    "external_created_at": "2026-06-01T10:30:00Z",
    "email": "[email protected]",
    "country": "US",
    "custom_attributes": {
      "plan": "trial"
    }
  }'

Полное описание всех доступных полей см. в справочнике Save profile.

Отправка событий транзакций

Для охвата пользователей во флоу never purchased достаточно профиля с email. Пользователям во всех остальных флоу также нужны события транзакций.

Все флоу, кроме never purchased, формируются на основе истории покупок. Отправляйте события транзакций профиля при обработке покупок, продлений и отмен — так Adapty Mail правильно определит, в какой флоу попадёт пользователь. События транзакций также обеспечивают атрибуцию выручки. Пропускайте их только в том случае, если вы запускаете исключительно кампании never purchased. Чтобы зафиксировать транзакцию, отправьте POST-запрос на /api/v1/profile/transaction-event/save/. Используйте тот же external_profile_id, что вы отправляли вместе с профилем, — так Adapty Mail свяжет транзакцию с нужным пользователем.

curl --request POST \
  --url 'https://api-mail.adapty.io/api/v1/profile/transaction-event/save/' \
  --header 'Authorization: Bearer {your_secret_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_type": "subscription_started",
    "event_id": "evt_abc123",
    "event_datetime": "2026-06-10T14:20:05Z",
    "external_profile_id": "user_12345",
    "store": "app_store",
    "store_product_id": "premium_monthly",
    "store_transaction_id": "1000000123456789",
    "store_original_transaction_id": "1000000123456789",
    "purchased_at": "2026-06-10T14:20:00Z",
    "originally_purchased_at": "2026-06-10T14:20:00Z",
    "price_usd": "9.99"
  }'

Список всех доступных полей см. в справочнике события сохранения транзакции.

Привяжите события к флоу

Отправляйте event_type, соответствующий произошедшему событию. Adapty Mail определяет состояние профиля на основе истории событий и направляет его в подходящее флоу.

`event_type`	Когда отправлять	Флоу
`subscription_started`	Пользователь оформляет новую подписку.	Активна — без флоу повторного вовлечения
`subscription_renewed`	Подписка автоматически продлевается.	Активна — без флоу повторного вовлечения
`subscription_renewal_reactivated`	Пользователь снова включает автопродление.	Активна — без флоу повторного вовлечения
`non_subscription_purchase`	Пользователь совершает разовую покупку.	Активна — без флоу повторного вовлечения
`subscription_renewal_cancelled`	Пользователь отключает автопродление (подписка остаётся активной до истечения срока).	Отмена продления
`billing_issue_detected`	Платёж за продление не проходит.	Проблема с оплатой
`entered_grace_period`	Платёж не прошёл, но пользователь находится в льготном периоде.	Проблема с оплатой
`subscription_expired`	Подписка истекает и доступ заканчивается.	Истекла
`subscription_refunded`	Покупка подписки возвращается.	Возврат
`non_subscription_purchase_refunded`	Разовая покупка возвращается.	Возврат