Go go-imap 怎样把本地邮件追加到指定邮箱

Go 项目需要把备份目录里的 .eml 文件导回 IMAP 邮箱时，核心不是调用发送邮件的 SMTP，而是调用 go-imap v2 的 imapclient.Client.Append。它把完整 RFC 822 邮件作为字节流追加到目标邮箱：先用文件大小创建命令，再写入文件，最后依次执行 Close 和 Wait。只有最后的 Wait 没有错误，才可以把这次导入记为成功。

本地邮件要作为完整字节流追加

APPEND 的输入不是一个主题字符串，也不是只有正文的文本。一个可导入的 .eml 文件通常至少要有 From、To、Date、Subject 等邮件头，头部与正文之间用空行分隔。文件内容会原样交给 IMAP 服务器解析，因此不要在读取后随意改变换行或编码。

连接、登录和权限检查属于前置步骤。下面的函数假定 client 已经完成 TLS 连接与认证，只聚焦“从本地文件追加到指定邮箱”这一件事。

最小配方：Stat、Append、Write、Close、Wait

package mailimport

import (
    "fmt"
    "io"
    "os"

    "github.com/emersion/go-imap/v2"
    "github.com/emersion/go-imap/v2/imapclient"
)

func appendEML(client *imapclient.Client, mailbox, path string) error {
    file, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("打开邮件文件失败: %w", err)
    }
    defer file.Close() // 文件只负责提供 APPEND 的输入字节流

    info, err := file.Stat()
    if err != nil {
        return fmt.Errorf("读取邮件文件大小失败: %w", err)
    }

    // size 必须等于后续写入的完整邮件字节数，不能填正文长度。
    options := &imap.AppendOptions{
        Flags: []imap.Flag{imap.FlagSeen},
    }
    appendCmd := client.Append(mailbox, info.Size(), options)

    // AppendCommand 实现了 Writer；io.Copy 可避免一次性把大附件读进内存。
    if _, err := io.Copy(appendCmd, file); err != nil {
        _ = appendCmd.Close() // 写入失败时尽量结束当前命令，避免连接卡住
        return fmt.Errorf("写入 IMAP 邮件内容失败: %w", err)
    }
    if err := appendCmd.Close(); err != nil {
        return fmt.Errorf("结束 APPEND 内容失败: %w", err)
    }
    if err := appendCmd.Wait(); err != nil {
        return fmt.Errorf("服务器拒绝 APPEND: %w", err)
    }
    return nil
}

这段配方里，info.Size() 是关键参数；它描述即将发送的完整邮件字节数。AppendOptions 可以省略，设置 FlagSeen 只是示例：如果导入后仍希望邮件显示为未读，就传入空 options 或不包含该 flag 的配置。

为什么 Close 和 Wait 不能合并

写入文件成功只说明客户端把字节交给了命令对象，并不等于服务器已经接受邮件。Close 结束 literal 内容，让客户端发送 APPEND 的收尾部分；Wait 再等待服务器返回最终状态。服务器可能在最后一步因为邮箱不存在、没有写入权限、邮箱超出 APPENDLIMIT 或配额不足而返回错误。

变体：设置内部日期和草稿标记

imap.AppendOptions 还包含 Time 和 Flags。如果备份恢复需要保留内部日期，可以传入原邮件对应的时间；如果要导入为草稿，则使用 imap.FlagDraft。这两个字段描述的是 IMAP 邮箱中的消息属性，不会替你修改邮件头里的 Date。

options := &imap.AppendOptions{
    Time:  originalInternalDate, // 保留邮箱内部日期，按业务时区准备好时间值
    Flags: []imap.Flag{imap.FlagDraft}, // 恢复为草稿时再设置，普通归档不要误加
}
appendCmd := client.Append("Archive/2026", fileSize, options)

常见坑与完整检查清单

• 目标邮箱名必须使用服务器实际接受的层级和编码；必要时先用 List 确认名称。
• 导入任务应记录文件哈希或稳定的 Message-ID，否则网络超时后重试可能产生重复邮件。
• 大邮件先关注服务器的 APPENDLIMIT 和账号配额；本地流式复制只减少客户端内存，不会绕过服务端限制。
• 不要只判断 io.Copy；至少要把 Close 与 Wait 的错误都写进任务结果。

相关问题

追加邮件前必须 Select 目标邮箱吗？

不一定。APPEND 的目标邮箱由参数指定，代码重点是已认证连接、正确邮箱名和服务器权限；是否需要先 Select 应按你的其他业务操作安排。

Append 返回的 UID 在哪里读取？

Wait 返回 AppendData。服务器支持 UIDPLUS 或 IMAP4rev2 时，其中的 UID 和 UIDValidity 才有意义；不支持时不要把零值当成可追踪 UID。

Write 成功后服务器一定保存了吗？

不一定。Write 只完成内容传输，Close 收尾，Wait 才取得最终 APPEND 结果。生产导入应以 Wait 无错误作为成功条件。

把“文件大小、内容写入、命令收尾、服务器确认”拆开后，go-imap 的本地邮件导入就很清晰：先验证输入，再流式写入，最后只依据服务器最终响应更新进度。