feat(mail): IMAP client — select, fetch headers/full, search

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-21 23:55:30 +01:00
parent 7df0c95339
commit 83bf3019c5
4 changed files with 273 additions and 2 deletions
@@ -2,16 +2,21 @@ module git.dcglab.co.uk/steve/emcli

 go 1.25.0

-require modernc.org/sqlite v1.53.0
+require (
+	github.com/emersion/go-imap v1.2.1
+	github.com/emersion/go-message v0.18.2
+	modernc.org/sqlite v1.53.0
+)

 require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
-	github.com/emersion/go-message v0.18.2 // indirect
+	github.com/emersion/go-sasl v0.0.0-20200509203442-7bfe0ed36a21 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	golang.org/x/sys v0.44.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
 	modernc.org/libc v1.73.4 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect
@@ -1,7 +1,13 @@
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/emersion/go-imap v1.2.1 h1:+s9ZjMEjOB8NzZMVTM3cCenz2JrQIGGo5j1df19WjTA=
+github.com/emersion/go-imap v1.2.1/go.mod h1:Qlx1FSx2FTxjnjWpIlVNEuX+ylerZQNFE5NsmKFSejY=
+github.com/emersion/go-message v0.15.0/go.mod h1:wQUEfE+38+7EW8p8aZ96ptg6bAb1iwdgej19uXASlE4=
 github.com/emersion/go-message v0.18.2 h1:rl55SQdjd9oJcIoQNhubD2Acs1E6IzlZISRTK7x/Lpg=
 github.com/emersion/go-message v0.18.2/go.mod h1:XpJyL70LwRvq2a8rVbHXikPgKj8+aI0kGdHlg16ibYA=
+github.com/emersion/go-sasl v0.0.0-20200509203442-7bfe0ed36a21 h1:OJyUGMJTzHTd1XQp98QTaHernxMYzRaOasRir9hUlFQ=
+github.com/emersion/go-sasl v0.0.0-20200509203442-7bfe0ed36a21/go.mod h1:iL2twTeMvZnrg54ZoPDNfJaJaqy0xIQFuBdrLsmspwQ=
+github.com/emersion/go-textwrapper v0.0.0-20200911093747-65d896831594/go.mod h1:aqO8z8wPrjkscevZJFVE1wXJrLpC5LtJG7fqLOsPb2U=
 github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
 github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -44,8 +50,10 @@ golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuX
 golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
+golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
@@ -0,0 +1,199 @@
+package mail
+
+import (
+	"fmt"
+	"io"
+	"sort"
+	"time"
+
+	"github.com/emersion/go-imap"
+	"github.com/emersion/go-imap/client"
+)
+
+type IMAPConfig struct {
+	Host     string
+	Port     int
+	Security string // tls | starttls
+	Username string
+	Password string
+}
+
+type Client struct {
+	c *client.Client
+}
+
+func Dial(cfg IMAPConfig) (*Client, error) {
+	addr := fmt.Sprintf("%s:%d", cfg.Host, cfg.Port)
+	var (
+		ic  *client.Client
+		err error
+	)
+	switch cfg.Security {
+	case "tls":
+		ic, err = client.DialTLS(addr, nil)
+	case "starttls":
+		ic, err = client.Dial(addr)
+		if err == nil {
+			err = ic.StartTLS(nil)
+		}
+	default:
+		return nil, fmt.Errorf("unknown imap security %q", cfg.Security)
+	}
+	if err != nil {
+		return nil, err
+	}
+	if err := ic.Login(cfg.Username, cfg.Password); err != nil {
+		ic.Logout()
+		return nil, err
+	}
+	return &Client{c: ic}, nil
+}
+
+func (c *Client) Logout() error { return c.c.Logout() }
+
+func (c *Client) SelectFolder(folder string) (uint32, uint32, error) {
+	mbox, err := c.c.Select(folder, true) // read-only select
+	if err != nil {
+		return 0, 0, err
+	}
+	var maxUID uint32
+	if mbox.Messages > 0 {
+		// UIDNext-1 is an upper bound for the highest existing UID.
+		if mbox.UidNext > 0 {
+			maxUID = mbox.UidNext - 1
+		}
+	}
+	return mbox.UidValidity, maxUID, nil
+}
+
+func (c *Client) fetchByUIDSet(folder string, set *imap.SeqSet, full bool) ([]Message, error) {
+	if _, err := c.c.Select(folder, true); err != nil {
+		return nil, err
+	}
+	section := &imap.BodySectionName{Peek: true} // entire message, no \Seen side-effect
+	items := []imap.FetchItem{imap.FetchUid, section.FetchItem()}
+
+	msgCh := make(chan *imap.Message, 16)
+	done := make(chan error, 1)
+	go func() { done <- c.c.UidFetch(set, items, msgCh) }()
+
+	var out []Message
+	for m := range msgCh {
+		r := m.GetBody(section)
+		if r == nil {
+			continue
+		}
+		raw, _ := io.ReadAll(r)
+		parsed, err := ParseMessage(m.Uid, raw)
+		if err != nil {
+			return nil, err
+		}
+		if !full {
+			parsed.Attachments = nil
+			parsed.BodyText = ""
+		}
+		out = append(out, parsed)
+	}
+	if err := <-done; err != nil {
+		return nil, err
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Header.UID > out[j].Header.UID })
+	return out, nil
+}
+
+func (c *Client) FetchHeaders(folder string, uids []uint32) ([]Header, error) {
+	set := new(imap.SeqSet)
+	if len(uids) == 0 {
+		set.AddRange(1, 0) // 1:* — all
+	} else {
+		for _, u := range uids {
+			set.AddNum(u)
+		}
+	}
+	msgs, err := c.fetchByUIDSet(folder, set, false)
+	if err != nil {
+		return nil, err
+	}
+	return headersOf(msgs), nil
+}
+
+func (c *Client) FetchHeadersRange(folder string, sinceUID, beforeUID uint32, limit int) ([]Header, error) {
+	set := new(imap.SeqSet)
+	lo := sinceUID + 1
+	if sinceUID == 0 {
+		lo = 1
+	}
+	hi := uint32(0) // '*'
+	if beforeUID > 1 {
+		hi = beforeUID - 1
+	}
+	set.AddRange(lo, hi)
+	msgs, err := c.fetchByUIDSet(folder, set, false)
+	if err != nil {
+		return nil, err
+	}
+	h := headersOf(msgs)
+	if limit > 0 && len(h) > limit {
+		h = h[:limit]
+	}
+	return h, nil
+}
+
+func (c *Client) FetchFull(folder string, uid uint32) (Message, error) {
+	set := new(imap.SeqSet)
+	set.AddNum(uid)
+	msgs, err := c.fetchByUIDSet(folder, set, true)
+	if err != nil {
+		return Message{}, err
+	}
+	if len(msgs) == 0 {
+		return Message{}, fmt.Errorf("uid %d not found in %s", uid, folder)
+	}
+	return msgs[0], nil
+}
+
+type SearchCriteria struct {
+	From            string
+	SubjectContains string
+	Text            string
+	Since           time.Time
+	Before          time.Time
+}
+
+func (c *Client) Search(folder string, sc SearchCriteria, limit int) ([]Header, error) {
+	if _, err := c.c.Select(folder, true); err != nil {
+		return nil, err
+	}
+	crit := imap.NewSearchCriteria()
+	if sc.From != "" {
+		crit.Header.Add("From", sc.From)
+	}
+	if sc.SubjectContains != "" {
+		crit.Header.Add("Subject", sc.SubjectContains)
+	}
+	if sc.Text != "" {
+		crit.Text = []string{sc.Text}
+	}
+	if !sc.Since.IsZero() {
+		crit.Since = sc.Since
+	}
+	if !sc.Before.IsZero() {
+		crit.Before = sc.Before
+	}
+	uids, err := c.c.UidSearch(crit)
+	if err != nil {
+		return nil, err
+	}
+	if len(uids) == 0 {
+		return nil, nil
+	}
+	return c.FetchHeaders(folder, uids)
+}
+
+func headersOf(msgs []Message) []Header {
+	out := make([]Header, 0, len(msgs))
+	for _, m := range msgs {
+		out = append(out, m.Header)
+	}
+	return out
+}
@@ -0,0 +1,59 @@
+//go:build integration
+
+package mail
+
+import (
+	"os"
+	"strconv"
+	"testing"
+)
+
+// These tests require a GreenMail server reachable via env vars:
+//
+//	EMCLI_TEST_IMAP_HOST, EMCLI_TEST_IMAP_PORT, EMCLI_TEST_USER, EMCLI_TEST_PASS
+//
+// Run: go test -tags=integration ./internal/mail/
+func testCfg(t *testing.T) IMAPConfig {
+	t.Helper()
+	host := os.Getenv("EMCLI_TEST_IMAP_HOST")
+	if host == "" {
+		t.Skip("EMCLI_TEST_IMAP_HOST not set; skipping IMAP integration test")
+	}
+	return IMAPConfig{
+		Host:     host,
+		Port:     atoiEnv(t, "EMCLI_TEST_IMAP_PORT"),
+		Security: "starttls",
+		Username: os.Getenv("EMCLI_TEST_USER"),
+		Password: os.Getenv("EMCLI_TEST_PASS"),
+	}
+}
+
+func TestSelectAndFetch(t *testing.T) {
+	c, err := Dial(testCfg(t))
+	if err != nil {
+		t.Fatalf("Dial: %v", err)
+	}
+	defer c.Logout()
+
+	uidv, maxUID, err := c.SelectFolder("INBOX")
+	if err != nil {
+		t.Fatalf("SelectFolder: %v", err)
+	}
+	if uidv == 0 {
+		t.Fatal("uidvalidity should be non-zero")
+	}
+	headers, err := c.FetchHeaders("INBOX", nil)
+	if err != nil {
+		t.Fatalf("FetchHeaders: %v", err)
+	}
+	t.Logf("inbox has %d messages, maxUID=%d", len(headers), maxUID)
+}
+
+func atoiEnv(t *testing.T, k string) int {
+	t.Helper()
+	n, err := strconv.Atoi(os.Getenv(k))
+	if err != nil {
+		t.Fatalf("bad int env %s: %v", k, err)
+	}
+	return n
+}