SMTP邮件发送API文档

基本信息

端点
GET|POST /send_smtp_email/v1 或 /send_smtp_email/v2
HTTP方法
GET（查询参数）或 POST（请求体）
版本说明
- v1：标准模式
- v2：支持对mail_body字段进行Base64编码（自动解码）

请求参数

1. 通用参数

参数名	必填	说明	示例值
`smtp_user`	是	SMTP用户名	`user@example.com`
`smtp_host`	是	SMTP服务器地址	`smtp.example.com`
`smtp_password`	是	SMTP密码	`your_password`
`smtp_port`	是	SMTP端口（需为数字）	`465`
`smtp_secure`	是	是否启用TLS（仅接受`"true"`或`"false"`）	`"true"`
`to_email`	是	收件人邮箱	`recipient@abc.com`
`mail_subject`	是	邮件主题	`测试邮件`
`mail_body`	是	邮件正文（v2需Base64编码）	`Hello World`
`to_email_cc`	否	抄送邮箱（多个用逗号分隔）	`cc1@x.com,cc2@y.com`
`to_email_bcc`	否	密送邮箱（多个用逗号分隔）	`bcc@z.com`
`token`	条件	若环境变量`token_enable=true`或`1`时必填，需与`TOKEN`环境变量一致	`your_token`

2. 模式切换参数

参数名	必填	说明
`type`	否	值为`post`时，强制从请求体解析参数（默认从查询参数解析）

请求示例

1. GET请求（查询参数）

curl "https://api.example.com/send_smtp_email/v1?smtp_user=user@example.com&smtp_host=smtp.example.com&smtp_password=***&smtp_port=465&smtp_secure=true&to_email=recipient@abc.com&mail_subject=测试邮件&mail_body=HelloWorld"

2. POST请求（JSON格式）

curl -X POST "https://api.example.com/send_smtp_email/v2?type=post" \
  -H "Content-Type: application/json" \
  -d '{
    "smtp_user": "user@example.com",
    "smtp_host": "smtp.example.com",
    "smtp_password": "***",
    "smtp_port": 465,
    "smtp_secure": "true",
    "to_email": "recipient@abc.com",
    "mail_subject": "测试邮件",
    "mail_body": "SGVsbG8gV29ybGQ="  # v2需Base64编码
  }'

环境变量配置

变量名	必填	说明
`TOKEN`	条件	若启用Token验证，需与请求中的`token`一致
`token_enable`	否	设为`true`或`1`时强制校验Token

响应结构

成功响应

{
  "success": true,
  "message": "邮件发送成功",
  "debug": {
    "requestId": "123456",
    "timestamp": "2023-10-01T12:00:00Z",
    "params": { /* 过滤敏感字段后的参数 */ },
    "mailInfo": {
      "messageId": "<xxx@example.com>",
      "accepted": ["recipient@abc.com"],
      "rejected": []
    },
    "smtpLog": [ /* 结构化日志条目 */ ]
  }
}

错误响应

{
  "success": false,
  "error": "错误类型描述",
  "debug": {
    "requestId": "123456",
    "timestamp": "2023-10-01T12:00:00Z",
    "errorDetails": { /* 错误详情 */ },
    "smtpLog": [ /* 结构化日志条目 */ ]
  }
}

错误代码

错误码	含义	常见原因
`401`	认证失败	Token缺失或不匹配
`400`	参数校验失败	参数缺失、类型错误或格式无效
`400`	请求体解析失败	POST请求体格式错误
`502`	SMTP服务器连接失败	服务器地址、端口或认证信息错误
`500`	服务器内部错误	未捕获的异常（开发环境下返回堆栈信息）

注意事项

敏感字段过滤
smtp_password和token在日志中自动替换为******。
SMTP日志
响应中的smtpLog字段包含详细的SMTP交互日志，可用于调试。
开发模式
设置环境变量NODE_ENV=development时，错误响应包含堆栈信息。
性能建议
- 启用Token验证以提高安全性。
- 使用v2版本传输长文本邮件内容时，建议Base64编码。