发起邮箱变更

POST

/api/v1/auth/email-change/start

校验当前密码后创建 10 分钟邮箱变更挑战，并将验证码邮件写入 PostgreSQL
email_outbox。邮件 outbox 对 SMTP 外部副作用采用 at-least-once（至少一次）
语义：SMTP 调用成功但 processed_at 终结写入或事务提交结果不确定时，行会保留
待重试状态，恢复后可能再次发送同一封邮件。调用方不得把 202 解读为 SMTP 已
完成投递或最多只会收到一封邮件。

请求参数

Header 参数

Body 参数application/json必填

示例

{
    "new_email": "user@example.com",
    "current_password": "pa$$word"
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location '/api/v1/auth/email-change/start' \
--header 'X-CSRF-Token;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "new_email": "user@example.com",
    "current_password": "pa$$word"
}'

返回响应

🟢202成功

application/json

验证码已可靠排队发送

Bodyapplication/json

示例

{
    "challenge_id": "331c5928-fdd1-4016-9993-1395c38cce7b",
    "expires_at": "2019-08-24T14:15:22.123Z"
}

🟠400请求有误

🟠401没有权限

🟠403禁止访问

🟠429

🔴500服务器错误

🔴503服务器故障

修改于 2026-09-03 11:57:51

查询当前用户资料

确认邮箱变更