ユーザーに未検証のセカンダリメールアドレスを追加

POST /v1/users/{user_id}/emails · 権限 users:write

ユーザーに未検証のセカンダリメールアドレスを追加します。アドレスは保存前に正規化されます。ユーザーが同じアドレスをすでに持っている場合は、行は書き込まれず、既存の行（検証済みやプライマリの場合もあります）が返されます。そのため、リクエストを繰り返しても安全です。新しい行は、アクターを API キーとして user.email_added の名前で管理監査ログに記録されます。アドレス自体は監査記録には書き込まれません。アドレスを検証するには、POST /v1/users/{user_id}/emails/{email_id}:send-verification で確認メールを送信するか、:verify で検証済みとしてマークしてください。

リクエスト

パラメータ 指定場所 必須 説明
user_id path はい ユーザー ID。接頭辞は usr_ です。
フィールド 型 必須 説明
email string はい メールアドレス。320 文字以内。

レスポンス

メール行を含む 201 Created が返されます。users:read_pii 権限がない場合、アドレスはマスクされます（a***@e***.com）。

{
  "id": "0191f0a0-3333-7444-8555-666666666666",
  "email": "ada@example.com",
  "verified": false,
  "primary": false,
  "created_at": "2026-01-15T09:30:00Z"
}

エラー

すべてのエラーは、安定した code を含む application/problem+json ボディで返されます。

HTTP code 発生条件
400 malformed_request、unknown_field ボディが有効な JSON ではないか、未知のフィールドが含まれています。
409 conflict このアドレスは、この環境の別のユーザーで検証済みです（errors[]：/email、email_taken）。
409 email_limit_reached ユーザーがすでに 10 件のアドレスを持っています。
415 unsupported_media_type Content-Type: application/json を指定せずにボディが送信されました。
422 validation_failed email が未指定、空、320 文字を超える、有効なアドレスではない、または型が不正です。
404 not_found この環境にユーザーが存在しないか、削除中であるか、ID の形式が不正です。
401 unauthenticated API キーが指定されていないか、不正であるか、取り消されています。
403 insufficient_permissions このキーには users:write 権限がありません。
429 rate_limited レート制限を超えました。Retry-After に従ってください。
503 service_unavailable 依存先が一時的に利用できません。しばらくしてから再試行してください。

例

curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/emails \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.com"}'

個人データ

このエンドポイントは個人データ（エンドユーザーのプロフィール）を扱います。KeenAuth API における個人データでは、保存される内容、保存期間、削除方法について説明しています。いずれのフィールドにも、特別な種類の個人データ（健康、生体情報、宗教、政治的意見、性的指向）を送信しないでください。