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

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

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

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

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

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

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

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

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

Если тот же пользователь попадает в Adapty Mail через другую точку входа, передавайте customer_user_id — тот же идентификатор пользователя, который отправляет источник. Для Adapty SDK это значение, которое вы передаёте в Adapty.identify(); FunnelFox передаёт тот, что хранит у себя. Этот параметр не определяет, на какой профиль попадёт пользователь — это делает адрес электронной почты. Но он добавляет второй способ найти профиль: событие транзакции, содержащее его, обрабатывается без email, а удаление может указывать его вместо адреса.

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": "jane@example.com",
    "country": "US",
    "custom_attributes": {
      "plan": "trial"
    }
  }'

device_info описывает устройство пользователя. Объект необязателен, но platform должен присутствовать всякий раз, когда вы его передаёте.

Поле	Опционально	Фильтр сегмента	Примечания
platform	Нет	Да
device	Да	Да	Модель устройства.
os	Да	Да
locale	Да	Да
app_version	Да	Да	Сравнивается в порядке версий, поэтому 1.10.0 выше 1.9.0.
timezone	Да	Нет	Определяет, когда пользователь получает письма. Без него Adapty Mail считает часовой пояс UTC, и окно отправки 08:00–21:00 будет следовать UTC, а не локальному времени пользователя.

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

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

Все флоу, кроме 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"
  }'

See the Save transaction event reference for every available field.

You can send a transaction before the profile exists. Adapty Mail keeps the event unattached, then links it to the profile on the next save that includes the same external_profile_id.

Удаление профиля

Чтобы выполнить запрос на удаление данных, отправьте идентификаторы профиля на /api/v1/profile/delete/. Adapty Mail удалит персональные данные профиля и отменит его запланированные письма.

curl --request POST \
  --url 'https://api-mail.adapty.io/api/v1/profile/delete/' \
  --header 'Authorization: Bearer {your_secret_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_profile_id": "user_12345"
  }'

Идентифицируйте профиль по external_profile_id, customer_user_id или email — укажите хотя бы один параметр. Adapty Mail удаляет сохранённые данные, но не блокирует адрес: если источник снова пришлёт его, появится новый профиль без истории. Чтобы навсегда исключить пользователя, нужно остановить источник, который передаёт его данные.

Запрос на удаление, который завис по таймауту, оставляет вас в неопределённости — дошёл ли он до сервера, — и вы отправляете его повторно. Повторный вызов безопасен, если вы идентифицируете профиль по external_profile_id или customer_user_id: он завершится успешно и ничего не изменит. Повторный вызов, содержащий только email, вернёт 404, поскольку первое удаление очистило адрес, по которому произошло бы совпадение. Все коды ответов перечислены в справочнике Delete profile.

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

Отправляйте 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	Разовая покупка возвращается.	Возврат