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

`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`）。

```json
{
  "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` | 依存先が一時的に利用できません。しばらくしてから再試行してください。 |

## 例

```bash
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 における個人データ](/docs/policies/personal-data)では、保存される内容、保存期間、削除方法について説明しています。いずれのフィールドにも、特別な種類の個人データ（健康、生体情報、宗教、政治的意見、性的指向）を送信しないでください。