Mail 模块

Mail 模块为 XScript 提供完整的电子邮件收发功能，支持 SMTP 协议发送邮件、IMAP 协议接收和管理邮件。

功能特性

发送功能

SMTP 支持 - 标准 SMTP 协议发送邮件

HTML 邮件 - 发送富文本邮件

附件支持 - 添加文件附件

多收件人 - 支持多个收件人、抄送、密送

邮件模板 - 使用模板生成邮件

SSL/TLS - 安全连接支持

嵌入图片 - 在 HTML 中嵌入图片

接收与管理功能

IMAP 支持 - 标准 IMAP 协议接收邮件

连接管理 - 持久化连接管理

文件夹操作 - 列出、选择邮件文件夹

邮件列表 - 获取邮件列表（支持筛选）

邮件搜索 - 按条件搜索邮件（发件人、收件人、时间段、已读/未读等）

邮件标记 - 标记邮件为已读/未读

邮件删除 - 删除邮件

邮件移动 - 在文件夹间移动邮件

邮件转发 - 转发邮件给其他人

基本使用

引入模块

发送邮件

配置 SMTP

发送简单邮件

发送 HTML 邮件

发送附件

多收件人

嵌入图片

接收与管理邮件

连接到邮件服务器

列出文件夹

选择文件夹

列出邮件

搜索邮件

获取完整邮件内容

标记邮件

删除邮件

移动邮件

转发邮件

断开连接

API 参考

发送相关

`mail.config(options)`

配置 SMTP 服务器。

参数:

options.host (string) - SMTP 服务器地址

options.port (number) - 端口号(25/465/587)

options.secure (boolean) - 是否使用 SSL/TLS

options.auth (object) - 认证信息

user (string) - 用户名

pass (string) - 密码

`mail.send(options)`

发送邮件。

参数:

options.from (string) - 发件人邮箱

options.to (string|Array) - 收件人

options.cc (string|Array) - 抄送

options.bcc (string|Array) - 密送

options.subject (string) - 主题

options.text (string) - 纯文本正文

options.html (string) - HTML 正文

options.attachments (Array) - 附件列表

filename (string) - 文件名

path (string) - 文件路径

content (Buffer|string) - 文件内容

cid (string) - 内容ID（用于嵌入图片）

返回: (boolean) 发送结果

接收与管理相关

`mail.connect(options)`

连接到邮件服务器。

参数:

options.protocol (string) - 协议类型，目前仅支持 'imap'

options.account (string) - 邮箱账户

options.password (string) - 邮箱密码

options.server (string) - 服务器地址（如 imap.example.com:993）

options.useTLS (boolean) - 是否使用 TLS 连接

返回: (string) 连接ID

`mail.disconnect(connectionId)`

断开连接。

参数:

connectionId (string) - 连接ID

返回: (boolean) 操作结果

`mail.listFolders(connectionId)`

列出所有邮件文件夹。

参数:

connectionId (string) - 连接ID

返回: (Array) 文件夹列表

name (string) - 文件夹名称

delimiter (string) - 分隔符

attributes (Array) - 属性列表

`mail.selectFolder(connectionId, folderName)`

选择邮件文件夹。

参数:

connectionId (string) - 连接ID

folderName (string) - 文件夹名称

返回: (Object) 文件夹信息

name (string) - 文件夹名称

messages (number) - 邮件总数

recent (number) - 最近邮件数

unseen (number) - 未读邮件数

`mail.listMessages(connectionId, options)`

列出邮件。

参数:

connectionId (string) - 连接ID

options (Object) - 可选筛选条件

unread (boolean) - 仅未读邮件

read (boolean) - 仅已读邮件

since (string) - 起始时间（RFC3339格式）

before (string) - 结束时间（RFC3339格式）

from (string) - 发件人过滤

to (string) - 收件人过滤

subject (string) - 主题过滤

返回: (Array) 邮件列表

uid (number) - 邮件UID

from (string) - 发件人

to (string) - 收件人

subject (string) - 主题

date (string) - 日期

flags (Array) - 标记列表

`mail.searchMessages(connectionId, options)`

搜索邮件。

参数:

connectionId (string) - 连接ID

options (Object) - 搜索条件（同listMessages）

返回: (Array) 邮件UID列表

`mail.getMessage(connectionId, uid)`

获取完整邮件内容。

参数:

connectionId (string) - 连接ID

uid (number) - 邮件UID

返回: (Object) 完整邮件信息

uid (number) - 邮件UID

from (string) - 发件人

to (string) - 收件人

cc (string) - 抄送

bcc (string) - 密送

subject (string) - 主题

date (string) - 日期

content (string) - 邮件内容

content-type (string) - 内容类型

flags (Array) - 标记列表

`mail.markAsRead(connectionId, uid)`

标记邮件为已读。

参数:

connectionId (string) - 连接ID

uid (number) - 邮件UID

返回: (boolean) 操作结果

`mail.markAsUnread(connectionId, uid)`

标记邮件为未读。

参数:

connectionId (string) - 连接ID

uid (number) - 邮件UID

返回: (boolean) 操作结果

`mail.deleteMessage(connectionId, uid)`

删除邮件。

参数:

connectionId (string) - 连接ID

uid (number) - 邮件UID

返回: (boolean) 操作结果

`mail.moveMessage(connectionId, uid, destFolder)`

移动邮件到指定文件夹。

参数:

connectionId (string) - 连接ID

uid (number) - 邮件UID

destFolder (string) - 目标文件夹名称

返回: (boolean) 操作结果

`mail.forwardMessage(connectionId, uid, options)`

转发邮件。

参数:

connectionId (string) - 连接ID

uid (number) - 邮件UID

options (Object) - 转发选项

to (string|Array) - 收件人

from (string) - 发件人（可选）

返回: (boolean) 操作结果

实际应用场景

邮件客户端

自动回复机器人

邮件归档系统

邮件转发规则

邮件统计分析

常用邮件服务器配置

Gmail

SMTP 发送:

IMAP 接收:

163邮箱

SMTP 发送:

IMAP 接收:

QQ邮箱

SMTP 发送:

IMAP 接收:

最佳实践

发送邮件

使用授权码 - 不要使用邮箱登录密码

速率限制 - 批量发送时控制频率

错误处理 - 捕获发送失败并重试

模板化 - 使用邮件模板提高可维护性

测试环境 - 开发时使用测试邮箱

日志记录 - 记录邮件发送日志

内容审查 - 避免触发垃圾邮件过滤器

接收与管理邮件

连接管理 - 及时断开不用的连接

批量操作 - 尽量批量处理邮件以提高效率

错误恢复 - 网络中断时自动重连

文件夹整理 - 定期归档旧邮件

搜索优化 - 使用精确的搜索条件减少数据传输

定时任务 - 使用定时任务自动处理邮件

安全性 - 妥善保管连接凭证

注意事项

发送相关

SPF/DKIM - 配置域名认证提高送达率

退订链接 - 营销邮件提供退订选项

隐私保护 - 使用密送保护收件人隐私

附件大小 - 注意附件大小限制(通常10-25MB)

HTML 兼容性 - 使用简单的 HTML 标签

接收相关

连接超时 - IMAP连接可能超时，需要处理重连

UID 变化 - 邮件UID在某些操作后可能改变

文件夹命名 - 不同服务器的特殊文件夹名称可能不同（如INBOX、Sent、Trash等）

并发限制 - 某些服务器限制同时连接数

存储配额 - 注意邮箱存储空间限制

兼容旧API

为保持向后兼容，保留了原有的 receive() 方法：

注意: 旧方法会自动将邮件标记为已读。推荐使用新的连接管理API以获得更多控制。

错误处理示例

性能优化建议

复用连接 - 多个操作使用同一个连接

批量获取 - 一次获取多封邮件而非逐个获取

选择性加载 - 列表时不加载完整内容，需要时再获取

索引搜索 - 使用服务器端搜索而非客户端过滤

异步处理 - 耗时操作使用异步方式

缓存结果 - 适当缓存文件夹列表等不常变化的数据

完整示例

完整的邮件客户端示例，包含发送和接收功能：

mail

Mail 模块#

功能特性#

发送功能#

接收与管理功能#

基本使用#

引入模块#

发送邮件#

配置 SMTP#

发送简单邮件#

发送 HTML 邮件#

发送附件#

多收件人#

嵌入图片#

接收与管理邮件#

连接到邮件服务器#

列出文件夹#

选择文件夹#

列出邮件#

搜索邮件#

获取完整邮件内容#

标记邮件#

删除邮件#

移动邮件#

转发邮件#

断开连接#

API 参考#

发送相关#

mail.config(options)#

mail.send(options)#

接收与管理相关#

mail.connect(options)#

mail.disconnect(connectionId)#

mail.listFolders(connectionId)#

mail.selectFolder(connectionId, folderName)#

mail.listMessages(connectionId, options)#

mail.searchMessages(connectionId, options)#

mail.getMessage(connectionId, uid)#

mail.markAsRead(connectionId, uid)#

mail.markAsUnread(connectionId, uid)#

mail.deleteMessage(connectionId, uid)#

mail.moveMessage(connectionId, uid, destFolder)#

mail.forwardMessage(connectionId, uid, options)#

实际应用场景#

邮件客户端#

自动回复机器人#

邮件归档系统#

邮件转发规则#

邮件统计分析#

常用邮件服务器配置#

Gmail#

163邮箱#

QQ邮箱#

最佳实践#

发送邮件#

接收与管理邮件#

注意事项#

发送相关#

接收相关#

兼容旧API#

相关模块#

错误处理示例#

性能优化建议#

完整示例#

Mail 模块

功能特性

发送功能

接收与管理功能

基本使用

引入模块

发送邮件

配置 SMTP

发送简单邮件

发送 HTML 邮件

发送附件

多收件人

嵌入图片

接收与管理邮件

连接到邮件服务器

列出文件夹

选择文件夹

列出邮件

搜索邮件

获取完整邮件内容

标记邮件

删除邮件

移动邮件

转发邮件

断开连接

API 参考

发送相关

`mail.config(options)`

`mail.send(options)`

接收与管理相关

`mail.connect(options)`

`mail.disconnect(connectionId)`

`mail.listFolders(connectionId)`

`mail.selectFolder(connectionId, folderName)`

`mail.listMessages(connectionId, options)`

`mail.searchMessages(connectionId, options)`

`mail.getMessage(connectionId, uid)`

`mail.markAsRead(connectionId, uid)`

`mail.markAsUnread(connectionId, uid)`

`mail.deleteMessage(connectionId, uid)`

`mail.moveMessage(connectionId, uid, destFolder)`

`mail.forwardMessage(connectionId, uid, options)`

实际应用场景

邮件客户端

自动回复机器人

邮件归档系统

邮件转发规则

邮件统计分析

常用邮件服务器配置

Gmail

163邮箱

QQ邮箱

最佳实践

发送邮件

接收与管理邮件

注意事项

发送相关

接收相关

兼容旧API

相关模块

错误处理示例

性能优化建议

完整示例