# プロファイルを保存する

> Adapty Mail にプロファイルを作成または更新します。プロファイルには、Adapty Mail が受信者を識別し[セグメント](/docs/mail-segments)を構築するために使用する、ユーザーのメールアドレスと属性が含まれます。
>
> 各ユーザーを安定した `external_profile_id` で識別してください。同じ `external_profile_id` を再度送信すると、重複を作成するのではなく、既存のプロファイルが更新されます。

## OpenAPI

```yaml
/api-specs/adapty-mail-api.yaml post /api/v1/profile/save/
openapi: 3.1.0
info:
  title: Adapty Mail API
  version: 1.0.0
  description: |
    Adapty Mail API を使用すると、Adapty SDK を経由せずに、サーバーから直接ユーザーのプロファイルとトランザクションイベントを Adapty Mail に送信できます。

    用途:

    - Adapty Mail にまだベースがない場合にサブスクライバーを追加する。
    - 他のアプリのサブスクライバーベースを再利用する。
    - バックエンドをデータの信頼できる情報源として、Adapty Mail をサーバー間で連携させる。

    メールアドレスを持つプロファイルは **never purchased** フローに対して十分です。その他のフロー（renewal cancelled、billing issue、expired、refunded）は購入履歴によって駆動されるため、それらのプロファイルには適切なフローに配置されるためのトランザクションイベントも必要です。

    手順のウォークスルーについては、[Adapty Mail API 経由でメールとトランザクションを送信する](/docs/mail-send-data-via-api) を参照してください。
servers:
  - url: https://api-mail.adapty.io
    description: 本番サーバー
paths:
  /api/v1/profile/save/:
    post:
      summary: プロファイルを保存する
      description: |
        Adapty Mail にプロファイルを作成または更新します。プロファイルには、Adapty Mail が受信者を識別し[セグメント](/docs/mail-segments)を構築するために使用する、ユーザーのメールアドレスと属性が含まれます。

        各ユーザーを安定した `external_profile_id` で識別してください。同じ `external_profile_id` を再度送信すると、重複を作成するのではなく、既存のプロファイルが更新されます。
      operationId: saveProfile
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProfileDTO"
            examples:
              basic:
                summary: メールアドレスを持ち、"never purchased" フローに対応したプロファイル
                value:
                  external_profile_id: user_12345
                  external_created_at: "2026-06-01T10:30:00Z"
                  email: jane@example.com
                  country: US
                  custom_attributes:
                    plan: trial
      responses:
        "200":
          description: プロファイルが正常に保存されました。レスポンスボディは空のオブジェクトです。
          content:
            application/json:
              schema:
                type: object
              examples:
                default:
                  value: {}
        "400":
          description: バリデーションに失敗しました — 必須フィールドが不足しているか無効です。`field_name` にどのフィールドかが表示されます。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
              examples:
                default:
                  value:
                    errors:
                      - message: Field required
                        error_code: base_error
                        status_code: 400
                        field_name: email
        "403":
          description: シークレット API キーが不足しているか無効です。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
              examples:
                default:
                  value:
                    errors:
                      - message: Secret key doesn't exist
                        error_code: secret_key_does_not_exist_error
                        status_code: 403
                        field_name: null
components:
  schemas:
    ProfileDTO:
      type: object
      required:
        - external_profile_id
        - external_created_at
        - email
      properties:
        external_profile_id:
          type: string
          description: |
            アプリまたはバックエンドが所有するユーザーの安定した識別子です。Adapty Mail がメール、クリック、購入を一つのプロファイルに紐付けられるよう、リクエスト間で同じ値を再利用してください。匿名識別子やインストールごとの識別子は使用しないでください。
        external_created_at:
          type: string
          format: date-time
          description: |
            ISO 8601 形式（例: `"2026-06-01T10:30:00Z"`）のユーザー作成日時です。この日付はセグメントで使用できます。
        email:
          type: string
          format: email
          description: ユーザーのメールアドレスです。Adapty Mail はこのアドレスにキャンペーンを配信します。
        first_name:
          type: string
          description: ユーザーの名前（名）です。
        last_name:
          type: string
          description: ユーザーの名前（姓）です。
        gender:
          type: string
          description: ユーザーの性別です。
        birthday:
          type: string
          format: date
          description: "ISO 8601 形式（例: `\"1990-05-21\"`）のユーザーの生年月日です。"
        country:
          type: string
          description: "ユーザーの国を表す ISO 3166-1 alpha-2 の2文字大文字コードです（例: `US`）。"
        store_country:
          type: string
          description: "ユーザーのストアリージョンを表す ISO 3166-1 alpha-2 の2文字大文字コードです（例: `US`）。"
        custom_attributes:
          type: object
          description: |
            プロファイルに付加する任意のキーと値のペア（文字列または数値）です。[セグメント](/docs/mail-segments)の構築に使用します（例: `plan`、`signup_source`、`trial_days`）。
        device_info:
          $ref: "#/components/schemas/DeviceInfoDTO"
    Errors:
      type: object
      description: 標準エラーレスポンスです。すべての失敗はこの形式で 4XX ステータスを返します。
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: エラーの人間が読める説明です。
              error_code:
                type: string
                description: マシンが読み取り可能なエラー識別子です。
              status_code:
                type: integer
                description: このエラーの HTTP ステータスコードです。
              field_name:
                type: string
                description: エラーの原因となったリクエストフィールド、またはエラーがフィールド固有でない場合は `null` です。
    DeviceInfoDTO:
      type: object
      required:
        - platform
      properties:
        platform:
          type: string
          description: "ユーザーが使用しているプラットフォームです（例: `iOS` または `Android`）。"
        device:
          type: string
          description: "デバイスのモデルです（例: `iPhone15,2`）。"
        os:
          type: string
          description: "オペレーティングシステムのバージョンです（例: `17.5`）。"
        locale:
          type: string
          description: "ユーザーのロケールです（例: `en-US`）。"
        timezone:
          type: string
          description: "ユーザーのタイムゾーンです（例: `America/New_York`）。"
        app_version:
          type: string
          description: "ユーザーが実行しているアプリのバージョンです（例: `3.1.0`）。"
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        すべてのリクエストを Adapty Mail のシークレット API キーで認証してください。キーは **Authorization** ヘッダーに `Bearer {your_secret_api_key}` の形式（例: `Bearer secret_live_...`）で送信します。

        このキーは Adapty Mail の **Settings** で確認できます。キーはプロジェクト固有であり、データが属するプロジェクトを識別するため、プロファイルエンドポイントとトランザクションエンドポイントにはプロジェクト ID は不要です。
```