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

• 在 Adapty Mail 中尚未建立用户群时添加订阅者。
• 复用其他应用中已有的订阅者群体。
• 以后端作为数据来源，通过服务端对服务端的方式向 Adapty Mail 推送数据。

开始之前

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

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

发送用户画像

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

以下三个字段为必填项：

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

如果同一用户还通过另一个入口点接入 Adapty Mail，请发送 customer_user_id——与该来源发送的用户 ID 相同。对于 Adapty SDK，这是你传给 Adapty.identify() 的值；FunnelFox 则发送它自己持有的那个。它不决定用户最终落到哪个用户画像上，邮箱地址才是决定因素。它的作用是提供第二种查找用户画像的方式：携带它的交易事件无需邮箱即可完成解析，删除操作也可以用它来代替邮箱地址进行指定。

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 营销活动时，才可以跳过这一步。

要记录一笔交易，请向 /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"
  }'

请参阅 保存交易事件 参考文档，了解所有可用字段。

您可以在用户画像创建之前发送交易记录。Adapty Mail 会暂时保存该事件，待下次包含相同 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，因为第一次删除操作已清除了原本可匹配的邮箱地址。删除用户画像 参考文档列出了所有响应状态码。

将事件映射到流程

发送与实际发生情况对应的 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	一次性购买已退款。	已退款