IMAP 邮件管理库 · 深度分析报告

基于 Go 封装的高性能 IMAP 客户端，支持 TLS、代理、流式解析，专为邮件批量处理与安全通信设计。

当前版本

v2.4

最后更新 2026-08-01 · 流程优化

安全特性

TLS 1.2+

S5代理 · 超时控制 · 授权码登录

核心能力

邮件管理

列表 · 信息 · 附件 · 删除 · 已读状态

附加特性

ID标识

兼容网易等强制上报服务器

功能特性

完整 IMAP 命令集 — 登录、退出、文件夹列表、选择文件夹、邮件搜索（按日期/主题/发件人）、获取邮件详情、删除、标记已读/未读。
支持 SSL/TLS 加密 — 默认端口 993，提供 DialTLS 安全连接，同时兼容非加密 143 端口。
SOCKS5 代理 — 支持通过代理访问邮件服务器，适用于内网穿透或跨国服务。
灵活的超时控制 — 连接超时、文件夹列表超时、邮件获取超时可独立设置，防止网络卡死。
附件大小限制 — 默认限制 5MB，可通过 setMaxAttachSize() 调整，避免内存暴涨。
智能邮件解析 — 返回结构化 JSON，包含 ReplyTo、Sender、InReplyTo、MessageId 等关键字段，并支持降级处理（FallbackMode）。
网易等特殊服务器兼容 — 提供 setID() 设置客户端标识，规避网易 IMAP 强制“不安全登录”阻断。
延迟加载附件 — 获取邮件时可选择不下载附件内容（仅名称/类型），按需下载 base64 数据，节省带宽与内存。

核心优点

高安全性高性能 Go 底层资源可控简洁 API 生产级容错

安全第一： 支持 TLS 加密、代理隧道、超时熔断，密码/授权码不落地，登录失败自动清理连接。
内存友好： 附件大小限制、延迟加载、大邮件超时断开，防止 OOM 与服务雪崩。
开发效率： 单行创建客户端，链式调用，错误信息详细，支持 Intellisense 智能提示。
健壮性： 针对网易、QQ 等主流服务商特殊 header 兼容，解析失败自动降级，返回原始数据。
可运维： 支持设置客户端 ID（RFC 2971），适应不同服务器策略，日志友好。

API 快速索引

logout()退出登录，释放会话

close()关闭管理器，释放资源

setID()设置客户端名称/版本 (网易强制)

getDirList()获取所有文件夹名称数组

selectDir()打开文件夹，返回邮件总数

getMailList()按条件搜索邮件 UID 列表

getMailInfo()获取邮件完整信息 (含附件)

delMail()删除指定 UID 邮件

setReadState()标记已读 / 未读

setMaxAttachSize()调整附件下载大小限制

典型用法

        // 创建客户端 (SSL + 代理)
        imap = godking.imap("imap.example.com", 993, true, "user@domain", "授权码", "socks5://127.0.0.1:1080", 30);
        if (!imap) { console.log("连接失败"); return; }

        // 设置客户端ID (网易等强制)
        imap.setID("MyMailClient", "1.0.0");

        // 获取文件夹列表
        folders = imap.getDirList(120);
        imap.selectDir("INBOX");

        // 获取最近 10 封未读邮件 (按日期过滤)
        uids = imap.getMailList(1, 10, 0, "2026-07-01", "", "");

        // 遍历邮件 (只取头部, 不下载附件)
        for (id in uids) {
            mail = imap.getMailInfo(id, false, false);
            console.log(mail.Subject, mail.From[0].Name);
        }

        // 关闭
        imap.close();
    

版本演进

v2.4 (2026-08-01) — 优化流程结构，完善部分功能，提升稳定性。
v2.3 — 修复 3 处逻辑改进点 + 2 处潜在风险 (小问题，不影响核心)。
v2.2 — 全面小幅优化，提升性能。
v2.1 — 安全性优化，加强超时与错误处理。
v2.0 — 支持限制附件大小 (默认 5MB)。
v1.9 — 支持下载附件内容 (base64)。
v1.8 — 修复编码问题导致无法获取完整邮件信息的错误。

特别提醒： 网易 163/188 等服务器强制要求登录后调用 setID()，否则 selectDir() 会抛出 “SELECT Unsafe Login”。另外 getMailInfo() 的 loadAttach 参数建议按需开启，大附件场景使用 false 仅获取元数据，避免内存压力。