接口使用说明

📋 接口概述

自动根据订单号匹配邮箱和业务规则
智能过滤发件人，只返回符合规则的邮件
自动提取邮件中的验证码（4-8位数字）
支持多种返回格式（JSON、HTML、验证码）
内置缓存机制，提升响应速度
自动验证订单有效期

📝 请求参数

参数名	类型	必填	说明
orderNo	String	必填	订单号，用于查找对应的邮箱和业务规则
type	String	可选	返回格式：`json`（默认）、`html`、`code`

💡 提示： type 参数不传时默认返回 JSON 格式，三种格式都会自动提取验证码。

📤 返回格式说明

1️⃣ JSON 格式（type=json 或不传）

返回结构化的 JSON 数据，适合程序调用。

[
  {
    "send": "noreply@example.com",
    "subject": "您的验证码",
    "text": "您的验证码是：123456，请在10分钟内使用。",
    "verification_code": "123456",
    "date": "2026-01-26T10:30:00.000Z"
  }
]

2️⃣ HTML 格式（type=html）

返回可直接在浏览器展示的 HTML 页面，包含完整的邮件内容和样式。

✅ 适用场景： 需要在浏览器中直接查看邮件内容，或用于邮件预览功能。

3️⃣ 验证码格式（type=code）

返回 JSON 格式，但重点突出验证码字段，便于快速获取。

[
  {
    "send": "noreply@example.com",
    "subject": "您的验证码",
    "text": "您的验证码是：123456",
    "verification_code": "123456",
    "date": "2026-01-26T10:30:00.000Z"
  }
]

🚀 使用示例

示例 1：获取 JSON 格式邮件

GET /key?orderNo=ORDER123456

示例 2：获取 HTML 格式邮件

GET /key?orderNo=ORDER123456&type=html

示例 3：仅获取验证码

GET /key?orderNo=ORDER123456&type=code

示例 4：JavaScript 调用

// 使用 Fetch API
fetch('/key?orderNo=ORDER123456')
  .then(response => response.json())
  .then(data => {
    console.log('邮件内容:', data[0]);
    console.log('验证码:', data[0].verification_code);
  })
  .catch(error => console.error('错误:', error));

// 使用 Axios
axios.get('/key', {
  params: { orderNo: 'ORDER123456' }
})
  .then(response => {
    console.log('验证码:', response.data[0].verification_code);
  });

📊 响应字段说明

字段名	类型	说明
send	String	发件人邮箱地址
subject	String	邮件主题
text	String	邮件纯文本内容
verification_code	String	自动提取的验证码（4-8位数字），如果没有则为空字符串
date	String	邮件接收日期（ISO 8601 格式）

⚠️ 错误码说明

状态码	错误信息	说明
400	orderNo参数不能为空	未提供 orderNo 参数
400	orderNo参数错误	orderNo 格式不正确或无效
401	邮箱认证失败	邮箱 token 失效或配置错误
404	未找到符合规则的邮件	邮箱中没有符合业务规则的邮件
404	邮箱不存在或已禁用	对应的邮箱已被删除或禁用
410	订单已过期	orderNo 对应的订单已超过有效期
500	服务器错误	服务器内部错误

⚡ 注意事项

🔔 重要提示：

系统仅返回 2天内 收到的邮件，超过时间范围的邮件不会被检索
接口会自动过滤发件人，只返回符合业务规则的邮件
验证码识别支持 4-8 位数字，支持中英文验证码关键词
系统内置缓存机制（30秒），相同请求会直接返回缓存结果
建议使用 HTTPS 协议保护数据传输安全

🎯 最佳实践：

在发送验证码邮件后等待 3-5 秒再调用接口，确保邮件已到达
如果需要频繁获取同一邮箱的邮件，利用缓存机制减少请求
处理错误响应，根据不同的状态码进行相应的业务处理
对于高频调用场景，建议在客户端实现请求去重

🔧 技术特性

🚀 性能优化

三级缓存机制（订单映射、邮箱信息、邮件内容）
请求去重处理，并发相同请求自动合并
智能选择 Graph API 或 IMAP 协议
异步并发读取收件箱和垃圾邮件箱

🔒 安全保障

订单有效期自动验证
邮箱状态实时检查
超时保护机制（60秒）
详细的错误日志记录

🎨 智能识别

多种验证码关键词识别（中英文）
自动从纯文本和 HTML 中提取验证码
支持 4-8 位数字验证码
发件人邮箱地址智能提取

❓ 常见问题

Q1: 为什么接口返回"未找到符合规则的邮件"？

A: 可能的原因包括：

邮件发件人不符合业务规则中设置的发件人模式
邮件接收时间超过 2 天
邮箱中确实没有邮件

Q2: 验证码字段为什么是空的？

A: 系统会尝试自动识别 4-8 位数字验证码，如果邮件内容中没有符合条件的数字串，该字段将为空。您可以从 text 字段中手动提取。

Q3: 接口响应速度如何？

A: 首次请求通常需要 2-5 秒（取决于邮箱中的邮件数量），缓存生效后响应时间可降至 50-200 毫秒。

Q4: 如何调试接口？

A: 建议使用 type=html 参数，直接在浏览器中查看返回的邮件内容，便于排查问题。

📧 接口使用说明