通过 Adapty Mail API 发送邮件和交易数据

Adapty Mail API 让你无需通过 Adapty SDK 中转，直接从服务器向 Adapty Mail 发送用户画像和交易数据。以下场景适合使用它：

在 Adapty Mail 中尚未有用户列表时添加订阅者。
复用来自其他应用的订阅者列表。
以你的后端作为数据源，通过服务器到服务器的方式向 Adapty Mail 推送数据。

用 API 还是 SDK？ 大多数应用通过 Adapty SDK 向 Adapty Mail 发送数据，SDK 会自动收集邮箱和购买信息。如果你的应用没有集成 Adapty SDK、数据已存储在服务器上，或者需要从其他来源导入订阅者，请选择 API 方式。

开始之前

在发送数据之前，请先完成 Adapty Mail 的配置——包括创建营销活动、市场细分（如有需要）、网页付费墙以及已上线的流程。Adapty Mail 仅向配置完成后创建的用户画像发送邮件；此前已发送的用户画像不会收到任何邮件。请先参阅Adapty Mail 入门指南完成配置，再回到此处继续操作。

你还需要准备好 API 密钥和基础 URL：

Secret API key（密钥）：在 Adapty Mail 中，进入 Settings 并复制你的 Secret API key。该密钥与项目绑定，API 通过它识别数据所属的项目。
Base URL：所有请求均发送至 https://api-mail.adapty.io。
Authentication（身份验证）：在 Authorization 请求头中以 Bearer {your_secret_api_key} 的格式传入密钥。

在收集用户邮箱并将其发送至 Adapty Mail 之前，请务必获得用户的明确授权。您有责任遵守 GDPR、CAN-SPAM 及所在市场的其他相关法规。

发送用户画像

用户画像包含用户的邮箱和属性。要创建或更新用户画像，请向 /api/v1/profile/save/ 发送 POST 请求。

以下三个字段为必填项：

由你的应用或后端维护的稳定 external_profile_id
Adapty Mail 用于发送营销活动邮件的 email
external_created_at —— 用户创建时间，可用于市场细分

请始终传入稳定的 external_profile_id，不要使用匿名 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"
    }
  }'

请参阅保存用户画像参考文档，了解所有可用字段。

发送交易事件

拥有邮箱的用户画像即可进入 never purchased 流程。其他所有流程还需要交易事件。

除 never purchased 之外的所有流程都依赖购买历史。在处理购买、续订和取消订阅时，同步发送用户画像的交易事件，这样 Adapty Mail 才能将其归入正确的流程。交易事件同时也支持收入归因。只有在你仅运行 never purchased 营销活动时，才可以跳过这一步。要记录一笔交易，请向 /api/v1/profile/transaction-event/save/ 发送 POST 请求。使用与用户画像相同的 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`	一次性购买已退款。	已退款