邮件发送接口

用于实现通过配置的SMTP服务器发送邮件的功能，支持GET和POST两种请求方式。参数需根据应用“令牌启用状态”灵活选择验证方式（令牌或账号密码），appid（应用ID）、signature（应用签名）、mail（收件邮箱）、title（邮件标题）、content（邮件内容）为必填项，同时需通过签名校验、账号状态校验、邮箱配置校验等前置逻辑。

注意

1. 接口依赖标准邮件发送组件，需确保服务器环境支持邮件发送功能；
2. 邮件发送频率受会话限制，同一会话下需间隔60秒才能发起下一次请求；
3. 邮件发送结果（成功/失败）会自动记录到后台日志，可在后台查看发送记录。

请求地址 GET / POST

https://nobase.cn/api/mail/send

请求参数

参数名	位置	类型	必选	说明
appid	query	string	✅ 是	应用ID，填写从开发者中心获取的应用唯一标识
signature	query	string	✅ 是	应用签名，需与后台配置一致，用于校验请求合法性
mail	query	string	✅ 是	收件人邮箱，需符合标准邮箱格式（如xxx@xxx.com）
title	query	string	✅ 是	邮件标题，不可为空，建议控制在100字符内
content	query	string	✅ 是	邮件内容，支持HTML格式，纯文本内容需确保无HTML标签
token	query	string	条件必选	用户令牌，仅当令牌启用时需传递；需为登录后获取的有效令牌，用于验证用户身份
user	query	string	条件必选	用户账号，仅当令牌未启用时需传递；格式为纯数字（如手机号），需与应用内注册账号一致
pass	query	string	条件必选	用户密码，仅当令牌未启用时需传递；格式为字母+数字组合（不可含中文/符号），需与账号绑定的密码一致

返回示例

成功响应（邮件发送成功）

{
  "code": 200,
  "msg": "success",
  "data": "邮件发送成功"
}

失败响应（参数缺失）

{
  "code": 204,
  "msg": "fail",
  "data": "接口参数错误：缺少appid"
}

失败响应（令牌无效）

{
  "code": 401,
  "msg": "fail",
  "data": "token无效或已过期！"
}

失败响应（签名校验失败）

{
  "code": 402,
  "msg": "fail",
  "data": "用户访问被限制：签名校验失败！"
}

失败响应（账号格式错误）

{
  "code": 403,
  "msg": "fail",
  "data": "账号格式错误！仅支持数字账号！"
}

失败响应（状态异常）

{
  "code": 404,
  "msg": "fail",
  "data": "开发者账号已逾期(1天)，请缴费后重试！"
}

失败响应（请求频繁/发送失败）

{
  "code": 405,
  "msg": "fail",
  "data": "请求频繁：请于50秒后再添加任务！"
}

失败响应（应用配置缺失）

{
  "code": 407,
  "msg": "fail",
  "data": "应用配置不存在！"
}

返回数据结构

参数名	类型	说明
code	number	状态码：200=发送成功；204=参数缺失/错误；401=token无效；402=签名失败；403=账号格式错；404=状态异常（账号/应用/开发者）；405=请求频繁/发送失败；407=应用配置缺失
msg	string	状态描述：success=成功，fail=失败
data	string	响应数据：返回操作结果提示或错误原因，如“邮件发送成功”“请求频繁：请于50秒后再添加任务！”

代码示例

JavaScript (令牌启用)

// 1. 配置参数（令牌启用，需传有效token）
const appid = "your_app_id";
const signature = "signature_from_backend";
const mail = "recipient@example.com"; // 收件人邮箱
const title = "测试邮件标题";
const content = "<h1>这是测试邮件的HTML内容</h1>";
const token = "valid_user_token"; // 登录获取的有效令牌

// 2. 构造POST参数
const params = new URLSearchParams({
  appid,
  signature,
  mail,
  title,
  content,
  token
});

// 3. 发起POST请求
fetch("https://nobase.cn/api/mail/send", {
  method: "POST",
  body: params,
  headers: { "Content-Type": "application/x-www-form-urlencoded" }
})
.then(res => res.json())
.then(res => {
  res.code === 200 
    ? console.log("邮件发送结果：", res.data) 
    : console.error("邮件发送失败：", res.data);
})
.catch(err => console.error("请求异常：", err));

JavaScript (令牌未启用)

// 1. 配置参数（令牌未启用，需传user和pass）
const appid = "your_app_id";
const signature = "signature_from_backend";
const mail = "recipient@example.com";
const title = "测试邮件标题";
const content = "这是测试邮件的纯文本内容";
const user = "13800138000"; // 纯数字账号
const pass = "UserPass123"; // 字母+数字密码

// 2. 拼接GET参数
const params = new URLSearchParams({ appid, signature, mail, title, content, user, pass });
const requestUrl = `https://nobase.cn/api/mail/send?${params.toString()}`;

// 3. 发起GET请求
fetch(requestUrl)
.then(res => res.json())
.then(res => {
  res.code === 200 
    ? console.log("邮件发送结果：", res.data) 
    : console.error("邮件发送失败：", res.data);
})
.catch(err => console.error("请求异常：", err));

Python (令牌启用)

import requests

# 1. 配置参数
params = {
    "appid": "your_app_id",
    "signature": "signature_from_backend",
    "mail": "recipient@example.com",
    "title": "测试邮件标题",
    "content": "<h1>这是测试邮件的HTML内容</h1>",
    "token": "valid_user_token"
}

# 2. 发起POST请求
url = "https://nobase.cn/api/mail/send"
try:
    res_data = requests.post(url, data=params, timeout=10).json()
    print(f"邮件发送结果：{res_data['data']}")
except requests.exceptions.RequestException as e:
    print(f"请求异常：{str(e)}")

Python (令牌未启用)

import requests

# 1. 配置参数
params = {
    "appid": "your_app_id",
    "signature": "signature_from_backend",
    "mail": "recipient@example.com",
    "title": "测试邮件标题",
    "content": "这是测试邮件的纯文本内容",
    "user": "13900139000",
    "pass": "UserPass456"
}

# 2. 发起GET请求
url = "https://nobase.cn/api/mail/send"
try:
    res_data = requests.get(url, params=params, timeout=10).json()
    print(f"邮件发送结果：{res_data['data']}")
except requests.exceptions.RequestException as e:
    print(f"请求异常：{str(e)}")

注意事项

1. 参数选择规则

   • 令牌启用：仅需传递appid、signature、mail、title、content、token，无需传user和pass，避免敏感信息暴露；
   • 令牌未启用：必须传递appid、signature、mail、title、content、user、pass，不可同时传递token和user/pass，否则会导致参数冲突。

2. 邮箱格式与内容要求

   • 收件人邮箱需符合标准格式（如xxx@xxx.com），否则返回“邮箱格式错误！”；
   • 邮件内容支持HTML格式，若需发送纯文本，需确保content中无HTML标签，接口会自动生成纯文本备用内容；
   • 邮件标题和内容不可为空，为空会直接返回“接口参数错误：缺少title”或“接口参数错误：缺少content”。

3. 核心校验逻辑
   接口会自动校验以下内容，异常时返回对应提示，需提前确保：

   • 开发者账号未逾期且状态正常（非禁用）；
   • 应用处于“正常状态”（非审核中、非停用）；
   • 用户账号已注册、状态正常，且账号长度符合应用配置（最短/最长字符限制）；
   • 邮箱服务器配置存在且有效（含SMTP地址、端口、账号、密钥）；
   • 签名（signature）与后台配置一致，否则会返回“用户访问被限制：签名校验失败！”。

4. 频率限制与日志记录

   • 同一会话下，邮件发送请求需间隔60秒，频繁请求会返回“请求频繁：请于XX秒后再添加任务！”；
   • 无论发送成功或失败，都会记录到后台日志，包含应用ID、收件邮箱、标题、发送时间、IP、状态，便于排查问题。

5. 安全与体验建议

   • 令牌未启用时，pass以明文传递，生产环境必须使用HTTPS协议，防止密码泄露；
   • 优先推荐启用令牌验证，减少账号密码传递频率，提升接口安全性；
   • 前端可提前通过正则（/^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)+$/）校验邮箱格式，减少无效请求；
   • 若邮件发送失败，可先检查SMTP配置（地址、端口、密钥是否正确），再通过后台日志获取详细异常信息。