mail/README.md

@go/mail

极致精简的高性能邮件客户端，支持 SMTP 发送与 IMAP 接收，集成 starter.Service 支持后台自动监听，并提供多实例管理。

设计哲学

• 统一性: 与 apigo.cc/go 基础设施深度集成（Log, Config, Cast, Safe, Starter）。
• 服务化: 支持作为 starter.Service 运行，通过规则过滤实现多实例后台自动处理。
• 多实例: 支持通过 Get(name) 管理多个邮箱账号。
• 安全性: 强制使用 safe.SafeBuf 保护内存中的密码。
• 高性能: 利用 imapclient v2 实现流式处理。

配置示例 (env.yml)

mail:
  mailbox:
    default:
      smtpHost: smtp.126.com
      smtpPort: 465
      imapHost: imap.126.com
      imapPort: 993
      username: user@126.com
      password: your_password
      senderName: 测试工程师
      pollInterval: 1m

API 参考

多实例管理

import "apigo.cc/go/mail"

// 获取默认实例并注册回调
mbox := mail.GetMailbox("default") 
mbox.On(&mail.RecvOption{Unseen: true}, func(m mail.Mail) {
    fmt.Println("收到新邮件:", m.Subject)
})

// 注册为后台服务 starter.Register("mail-default", mbox, 1, 0, 0)

### 发送富媒体邮件 (HTML + 附件 + 内嵌图片)
```go
mbox.Send([]string{"target@example.com"}, "报表", "<h1>见附件</h1><img src='cid:chart'>", &mail.SendOption{
    HTML: true,
    Attachments: []mail.Attachment{
        {Name: "data.xlsx", Path: "./data.xlsx"},
    },
    Embeds: []mail.Attachment{
        {Name: "chart.png", Path: "./chart.png", ContentID: "chart"},
    },
})

接收邮件与解析

// 手动接收
res, _ := mbox.Recv(&mail.RecvOption{Limit: 1})
for _, m := range res.List {
    fmt.Println(m.Subject)
    fmt.Println(m.Text)      // 纯文本正文
    fmt.Println(m.HTML)      // HTML 正文
    fmt.Println(m.Headers)   // 原始请求头 map[string][]string

    // 遍历附件
    for _, a := range m.Attachments {
        fmt.Println("附件:", a.Name, len(a.Data))
    }
}

规则过滤说明

RecvOption 支持丰富的过滤条件：

• Unseen: 仅未读
• Subject, From, To, Body: 关键字包含过滤
• Since, Before: 日期过滤
• Not: 排除关键字
• MarkAsRead: 处理后标记为已读