邮箱验证码API服务 API 文档

使用 LaunchAlways 发送一次性验证码邮件，并通过发送接口返回的 ID 校验用户提交的验证码或查询发送记录。

outgoing_mail

1. 发送验证码邮件

创建一条已发送邮件记录，发送固定验证码邮件模板，并返回可查询的记录 ID。

LaunchAlways 使用固定验证码邮件模板。请求只能包含收件邮箱、验证码、过期时间窗口和语言；自定义主题、纯文本、HTML 或内容字段都会被拒绝。

POST/api/v1/email-verifications/send

请求头

Authorization: Bearer la_your_api_key_here
Content-Type: application/json

请求体

字段	类型	必填	可为空	约束	说明
`email`	string	是	否	有效邮箱地址	收件人邮箱地址。会去除首尾空格并统一转为小写。
`code`	string	是	否	1-8 个字符	由你的应用提供的验证码。长度必须为 1-8 个字符。
`expiresInMs`	number	是	否	整数，1000-86400000	过期时间窗口，单位毫秒。允许范围为 1000-86400000。
`language`	string	否	否	枚举： `en`, `zh-CN`, `zh-TW`, `es`, `fr`, `ja`, `ko`, `de`, `hi`, `ar`, `bn`, `pt`, `id`, `ur`	邮件模板语言。省略时默认使用 en。

支持语言

取值	邮件语言
`en`	English
`zh-CN`	中文
`zh-TW`	中文繁體
`es`	Español
`fr`	Français
`ja`	日本語
`ko`	한국어
`de`	Deutsch
`hi`	हिन्दी
`ar`	العربية
`bn`	বাংলা
`pt`	Português
`id`	Bahasa Indonesia
`ur`	اردو

示例

curl -X POST https://launchalways.com/api/v1/email-verifications/send \
  -H "Authorization: Bearer la_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "482913",
    "expiresInMs": 300000,
    "language": "zh-CN"
  }'

成功响应

{
  "ok": true,
  "emailId": "b7e4f7a3-0000-4000-9000-123456789abc",
  "language": "zh-CN",
  "expiresAt": "2026-06-08T12:34:56.789Z",
  "createdAt": "2026-06-08T12:29:56.789Z"
}

成功响应字段

字段	类型	必填	可为空	约束	说明
`ok`	boolean	是	否	成功时恒为 true	表示发送请求已成功完成。
`emailId`	uuid	是	否	UUID 字符串	用于查询这条已发送邮件记录的唯一 ID。
`language`	string	是	否	支持语言枚举值之一	用于渲染并发送这封验证码邮件的语言。
`expiresAt`	ISO datetime	是	否	ISO 8601 时间戳	根据 expiresInMs 计算得到的绝对过期时间。
`createdAt`	ISO datetime	是	否	ISO 8601 时间戳	LaunchAlways 创建这条已发送邮件记录的时间。

错误响应

状态码	响应体	触发场景
`400`	`{"error":"<validation message>"}`	邮箱无效、验证码长度无效、过期时间无效、语言不支持、JSON 格式错误，或提交了被拒绝的自定义内容字段。
`401`	`{"error":"Invalid or missing API key."}`	Bearer Token 缺失、格式错误或不存在。
`402`	`{"error":"Email verifications quota reached for the Free plan."}`	账户已用完当前月度发送额度。新的邮件发送会被阻止，但已有验证码记录仍可查询。
`503`	`{"error":"RESEND_API_KEY is not configured."}`	邮件服务商尚未配置。
`500`	`{"error":"<provider or server message>"}`	通过校验和额度检查后，服务商请求或数据库写入失败。

fact_check

2. 校验验证码

根据提交的收件邮箱和验证码，与系统内保存的 hash 进行比对，并返回校验结果、邮件记录 ID、记录状态和结果原因。

只有邮箱和验证码匹配该记录且记录未过期时，valid 才是 true；验证码不匹配、邮箱不匹配或记录已过期时，valid 都是 false。API key 只能访问本项目创建的邮件记录；如果使用其他项目的 emailId，会返回 404 和 {"error":"Email record not found."}。

POST/api/v1/email-verifications/{emailId}

请求头

Authorization: Bearer la_your_api_key_here
Content-Type: application/json

请求体

字段	类型	必填	可为空	约束	说明
`email`	string	是	否	有效邮箱地址	收件人邮箱地址。会去除首尾空格并统一转为小写。
`code`	string	是	否	1-8 个字符	由你的应用提供的验证码。长度必须为 1-8 个字符。

示例

curl -X POST https://launchalways.com/api/v1/email-verifications/b7e4f7a3-0000-4000-9000-123456789abc \
  -H "Authorization: Bearer la_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "482913"
  }'

成功响应

{
  "valid": true,
  "emailId": "b7e4f7a3-0000-4000-9000-123456789abc",
  "status": "sent",
  "reason": "matched"
}

成功响应字段

字段	类型	必填	可为空	约束	说明
`valid`	boolean	是	否	true 或 false	只有提交的邮箱和验证码匹配该记录，且记录尚未过期时为 true；验证码不匹配、邮箱不匹配或记录已过期时为 false。
`emailId`	uuid	是	否	UUID 字符串	已发送邮件记录 ID。
`status`	`sent` \| `expired`	是	否	枚举：sent、expired	过期前为 sent，超过过期时间后为 expired。
`reason`	string	是	否	枚举：matched、expired、email_mismatch、code_mismatch	本次校验结果原因：matched、expired、email_mismatch 或 code_mismatch。

错误响应

状态码	响应体	触发场景
`400`	`{"error":"<validation message>"}`	邮箱无效、验证码长度无效、过期时间无效、语言不支持、JSON 格式错误，或提交了被拒绝的自定义内容字段。
`401`	`{"error":"Invalid or missing API key."}`	Bearer Token 缺失、格式错误或不存在。
`404`	`{"error":"Email record not found."}`	查询 ID 无效、缺失，或属于其他项目。
`500`	`{"error":"Could not verify email code."}`	记录存在，但因服务端错误无法加载。

manage_search

3. 查询已发送记录

返回收件邮箱、有效期窗口、语言、状态和时间戳。

该接口不会返回验证码、验证码 hash、服务商消息 ID、主题、HTML 或纯文本正文。API key 只能访问本项目创建的邮件记录；如果使用其他项目的 emailId，会返回 404 和 {"error":"Email record not found."}。

GET/api/v1/email-verifications/{emailId}

请求头

Authorization: Bearer la_your_api_key_here

路径参数

字段	类型	必填	可为空	约束	说明
`emailId`	uuid	是	否	UUID 字符串	发送接口返回的记录 ID。

示例

curl https://launchalways.com/api/v1/email-verifications/b7e4f7a3-0000-4000-9000-123456789abc \
  -H "Authorization: Bearer la_your_api_key_here"

成功响应

{
  "emailId": "b7e4f7a3-0000-4000-9000-123456789abc",
  "email": "user@example.com",
  "expiresInMs": 300000,
  "language": "zh-CN",
  "status": "sent",
  "expiresAt": "2026-06-08T12:34:56.789Z",
  "createdAt": "2026-06-08T12:29:56.789Z"
}

成功响应字段

字段	类型	必填	可为空	约束	说明
`emailId`	uuid	是	否	UUID 字符串	已发送邮件记录 ID。
`email`	string	是	否	规范化后的邮箱地址	收件人邮箱地址。
`expiresInMs`	number \| null	是	是	存在时为整数，1000-86400000	发送接口中提交的原始有效期窗口。
`language`	string	是	否	支持语言枚举值之一	用于渲染并发送邮件的语言。
`status`	`sent` \| `expired`	是	否	枚举：sent、expired	过期前为 sent，超过过期时间后为 expired。
`expiresAt`	ISO datetime	是	否	ISO 8601 时间戳	这封邮件中验证码的绝对过期时间。
`createdAt`	ISO datetime	是	否	ISO 8601 时间戳	LaunchAlways 创建这条已发送邮件记录的时间。

错误响应

状态码	响应体	触发场景
`401`	`{"error":"Invalid or missing API key."}`	Bearer Token 缺失、格式错误或不存在。
`404`	`{"error":"Email record not found."}`	查询 ID 无效、缺失，或属于其他项目。
`500`	`{"error":"Could not load email record."}`	记录存在，但因服务端错误无法加载。

security

安全说明

API Key 和验证码校验接口都应只在可信服务端环境调用。LaunchAlways 只保存带服务端 pepper 的不可逆验证码 hash。

data_object

标准错误对象

上方列出的错误响应均使用下面的 JSON 对象结构。

{
  "error": "Invalid or missing API key."
}

字段	类型	必填	可为空	约束	说明
`error`	string	是	否	可读错误信息	说明请求失败的原因。