Adapty Mail APIを使うと、Adapty SDKを経由せずに、サーバーから直接Adapty Mailにユーザープロファイルとトランザクションを送信できます。以下のような場合に活用してください：

• 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} の形式でキーを指定してください。

ユーザープロファイルを送信する

プロファイルには、ユーザーのメールアドレスと属性が含まれます。プロファイルを作成または更新するには、/api/v1/profile/save/ にPOSTリクエストを送信します。

以下の3つのフィールドが必須です：

• アプリまたはバックエンドが管理する安定した external_profile_id
• Adapty Mailがキャンペーンを配信する email
• ユーザー作成日時を示す external_created_at（セグメントで使用可能）

同じユーザーが別のエントリーポイントから Adapty Mail にアクセスする場合は、customer_user_id — そのソースが送信するものと同じユーザー ID — を送信してください。Adapty SDK の場合は Adapty.identify() に渡す値です。FunnelFox は自身が保持している値を送信します。これはどのプロファイルに紐付けられるかを決定するものではなく、メールアドレスがそれを担います。customer_user_id が追加するのは、プロファイルを見つけるための第二の手段です。それを含むトランザクションイベントはメールアドレスがなくても解決でき、削除時にはアドレスの代わりにこの ID を指定できます。

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	はい	はい	Adapty Mail はこれを使って、ローカライズされたキャンペーンのどの翻訳を送信するかを決定します。ロケールが未設定のユーザーには英語でメールが送信されます。
app_version	はい	はい	バージョン順で比較されるため、1.10.0 は 1.9.0 より上位になります。
timezone	はい	いいえ	ユーザーがメールを受信する時刻を設定します。未設定の場合、Adapty Mail はそのユーザーを UTC として扱うため、08:00〜21:00 の送信ウィンドウはユーザー自身の時刻ではなく UTC に従います。

Save profile リファレンスで利用可能なすべてのフィールドを確認してください。

トランザクションイベントを送信する

一度も購入していないフローを除くすべてのフローは、購入履歴によって動作します。購入、更新、キャンセルを処理する際にトランザクションイベントを送信することで、Adapty Mailはプロファイルを適切なフローに振り分けられます。トランザクションイベントは収益アトリビューションにも活用されます。一度も購入していないキャンペーンのみを実施する場合は省略できます。

トランザクションを記録するには、/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"
  }'

Save transaction event リファレンスで利用可能なすべてのフィールドを確認できます。

プロファイルが存在する前にトランザクションを送信することもできます。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 でプロファイルを特定します。少なくとも1つを送信してください。Adapty Mail は保存されたデータを削除しますが、そのアドレスをブロックするわけではありません。ソースが再度データを送信すると、履歴のない新しいプロファイルが作成されます。永続的に除外するには、ソースがそのユーザーのデータを送信しないようにしてください。

削除リクエストがタイムアウトした場合、リクエストが届いたかどうか不明なため、再度送信することになります。external_profile_id または customer_user_id でプロファイルを指定している場合、この2回目の呼び出しは安全です。成功し、何も変更されません。一方、email のみを指定した2回目の呼び出しは 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	買い切り購入が返金されたとき	返金済み