Go go-imap 怎样用 UID 查询指定日期后的邮件

如果你要在 Go 中找出某个日期之后的邮件，并且希望后续读取时使用稳定的邮件标识，可以用 go-imap v2 的 Client.UIDSearch。它会发送 UID SEARCH，返回 SearchData；再调用 AllUIDs() 就能得到匹配邮件的 UID 集合。

官方文档：https://pkg.go.dev/github.com/emersion/go-imap/v2/imapclient

真正容易出错的地方不是方法名，而是日期语义：SearchCriteria.Since 只使用日期部分，表示“该日期及以后”的内部日期匹配。如果业务要求严格晚于某天，就把查询日期改成下一天，再把返回的 UID 交给 Fetch。

UIDSearch 和普通 Search 到底差在哪里

go-imap 的 Search 与 UIDSearch 都接收 *imap.SearchCriteria，区别在于返回结果所对应的编号类型。UIDSearch 发送的是 UID SEARCH，返回数据里的 AllUIDs() 可以转换出 UID；普通 Search 则使用序号。

序号会随着邮件被删除而重新排列，UID 更适合把“这批邮件”交给后续 Fetch。不过 UID 仍然只在特定邮箱和 UIDVALIDITY 范围内有意义，不要把它当成跨邮箱永久主键。

先连接并选中要查询的邮箱

SEARCH 作用于当前选中的邮箱，因此代码顺序应是建立连接、完成登录、选择邮箱，再创建搜索条件。下面只展示 API 组合方式，账号和服务器地址需要替换为你自己的配置。

package main

import (
    "fmt"
    "log"

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

func main() {
    // 使用 TLS 建立 IMAP 连接，避免把账号凭据放在明文连接中。
    client, err := imapclient.DialTLS("imap.example.com:993", nil)
    if err != nil {
        log.Fatalf("连接 IMAP 服务器失败: %v", err)
    }
    defer client.Close()

    // Login 返回异步命令，需要 Wait 等待服务器完成认证。
    if err := client.Login("user@example.com", "your-password").Wait(); err != nil {
        log.Fatalf("登录失败: %v", err)
    }

    // 先选中邮箱，后续 UID SEARCH 才有明确的搜索范围。
    if _, err := client.Select("INBOX", nil).Wait(); err != nil {
        log.Fatalf("选择 INBOX 失败: %v", err)
    }

    fmt.Println("邮箱已选中，可以开始 UID SEARCH")
}

Login、Select 和搜索命令都采用命令对象配合 Wait() 的模式。不要在还没有选中邮箱时就假定搜索结果属于 INBOX。

用 Since 表达“指定日期后”

SearchCriteria 的 Since、Before、SentSince 和 SentBefore 字段都只使用日期，时间和时区会被忽略。Since 针对邮件的内部日期；如果你要按邮件头里的发送日期筛选，应考虑 SentSince。

因此有两种常见口径：

下面示例按“严格晚于 2026-10-01”处理，所以把日期推进一天。这里的日期只用于解释边界，不代表某个真实邮箱已有对应邮件。

package main

import (
    "fmt"
    "log"
    "time"

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

func main() {
    // 连接、认证和选箱的错误处理保持在调用点，便于区分失败层次。
    client, err := imapclient.DialTLS("imap.example.com:993", nil)
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer client.Close()

    if err := client.Login("user@example.com", "your-password").Wait(); err != nil {
        log.Fatalf("登录失败: %v", err)
    }
    if _, err := client.Select("INBOX", nil).Wait(); err != nil {
        log.Fatalf("选中邮箱失败: %v", err)
    }

    // Since 只比较日期；严格晚于 10 月 1 日就从 10 月 2 日开始查。
    since := time.Date(2026, time.October, 2, 0, 0, 0, 0, time.UTC)
    criteria := &imap.SearchCriteria{Since: since}

    // UIDSearch 返回 UID SEARCH 的命令对象，Wait 才会取得服务器结果。
    data, err := client.UIDSearch(criteria, nil).Wait()
    if err != nil {
        log.Fatalf("UID SEARCH 失败: %v", err)
    }

    // AllUIDs 把协议结果转换成便于后续 Fetch 使用的 UID 列表。
    fmt.Printf("匹配到 %d 个 UID\n", len(data.AllUIDs()))
}

拿到 UID 后怎样继续读取邮件

UIDSearch 的结果不是邮件正文，而是一个 SearchData。其中的 All 保存协议层的编号集合，AllUIDs() 把它展开为 []imap.UID。你可以把这些 UID 放进 imap.UIDSet，再作为 UID 维度的 Fetch 输入。

// data 来自 client.UIDSearch(criteria, nil).Wait()。
uids := data.AllUIDs()
if len(uids) == 0 {
    // 空结果是正常业务结果，不应被当成命令失败。
    fmt.Println("没有找到符合日期条件的邮件")
    return
}

// UIDSetNum 将 UID 列表包装成 UID 维度的集合，供后续 Fetch 选择邮件。
uidSet := imap.UIDSetNum(uids...)
fetchOptions := &imap.FetchOptions{
    // 这里只请求 UID 和信封信息，避免一开始就读取整封正文。
    UID:     true,
    Envelope: true,
}
fetchCmd := client.Fetch(uidSet, fetchOptions)
defer fetchCmd.Close()

for {
    // Next 逐条取出结果；没有更多数据时返回 nil。
    message := fetchCmd.Next()
    if message == nil {
        break
    }
    fmt.Println("收到一封匹配邮件的 Fetch 结果")
}

上面的重点是把搜索和读取分成两层：第一层只负责“哪些 UID 符合条件”，第二层再决定要拿信封、标记还是正文。这样做能避免为了判断日期而立即下载大量内容。

日期和 UID 的几个兼容边界

• 不要把 Since 当成时间点过滤。它按日期工作，时分秒和时区不会参与比较；需要更细粒度时，应取得候选 UID 后在应用层继续判断。
• 区分内部日期和发送日期。用户说“收到”通常更接近内部日期，用户说“发出”则可能需要 SentSince，两者不能混用。
• UID 依赖邮箱上下文。查询前要先选中正确邮箱；如果邮箱的 UIDVALIDITY 发生变化，持久化的旧 UID 不能直接当作新结果使用。
• 空集合不是错误。Wait() 成功但 AllUIDs() 为空，表示没有匹配项；只有命令返回错误时才进入失败处理。
• 按服务器能力选择返回字段。SearchOptions 中部分返回项需要 IMAP4rev2、ESEARCH、CONDSTORE 或 SEARCHRES，基础 UID 查询不必为了这些扩展字段增加复杂度。

常见问题

UIDSearch 能直接按某个小时筛选吗？

不能只靠 Since 完成小时级过滤，因为官方结构说明它只使用日期。可以先得到日期范围内的 UID，再 Fetch 信封里的时间字段做应用层过滤。

为什么返回了 UID，却不能在另一个邮箱 Fetch？

UID 的解释范围是当前邮箱。切换邮箱后，即使数字看起来相同，也不能假定它指向同一封邮件；应在目标邮箱重新搜索。

怎样查询某天之前的邮件？

使用 Before。它同样按日期边界工作，组合 Since 与 Before 可以构造一个日期区间。

总结一下：先连接并选中邮箱，再用 imap.SearchCriteria{Since: ...} 表达日期边界，调用 client.UIDSearch(...).Wait()，最后用 AllUIDs() 取得 UID 集合。记住 Since 包含给定日期，严格“之后”要传下一天；UID 只在对应邮箱上下文中有效。