README.md
1# go-imap
2
3[![GoDoc](https://godoc.org/github.com/emersion/go-imap?status.svg)](https://godoc.org/github.com/emersion/go-imap)
4[![builds.sr.ht status](https://builds.sr.ht/~emersion/go-imap.svg)](https://builds.sr.ht/~emersion/go-imap?)
5[![Codecov](https://codecov.io/gh/emersion/go-imap/branch/master/graph/badge.svg)](https://codecov.io/gh/emersion/go-imap)
6
7An [IMAP4rev1](https://tools.ietf.org/html/rfc3501) library written in Go. It
8can be used to build a client and/or a server.
9
10```shell
11go get github.com/emersion/go-imap/...
12```
13
14## Usage
15
16### Client [![GoDoc](https://godoc.org/github.com/emersion/go-imap/client?status.svg)](https://godoc.org/github.com/emersion/go-imap/client)
17
18```go
19package main
20
21import (
22 "log"
23
24 "github.com/emersion/go-imap/client"
25 "github.com/emersion/go-imap"
26)
27
28func main() {
29 log.Println("Connecting to server...")
30
31 // Connect to server
32 c, err := client.DialTLS("mail.example.org:993", nil)
33 if err != nil {
34 log.Fatal(err)
35 }
36 log.Println("Connected")
37
38 // Don't forget to logout
39 defer c.Logout()
40
41 // Login
42 if err := c.Login("username", "password"); err != nil {
43 log.Fatal(err)
44 }
45 log.Println("Logged in")
46
47 // List mailboxes
48 mailboxes := make(chan *imap.MailboxInfo, 10)
49 done := make(chan error, 1)
50 go func () {
51 done <- c.List("", "*", mailboxes)
52 }()
53
54 log.Println("Mailboxes:")
55 for m := range mailboxes {
56 log.Println("* " + m.Name)
57 }
58
59 if err := <-done; err != nil {
60 log.Fatal(err)
61 }
62
63 // Select INBOX
64 mbox, err := c.Select("INBOX", false)
65 if err != nil {
66 log.Fatal(err)
67 }
68 log.Println("Flags for INBOX:", mbox.Flags)
69
70 // Get the last 4 messages
71 from := uint32(1)
72 to := mbox.Messages
73 if mbox.Messages > 3 {
74 // We're using unsigned integers here, only substract if the result is > 0
75 from = mbox.Messages - 3
76 }
77 seqset := new(imap.SeqSet)
78 seqset.AddRange(from, to)
79
80 messages := make(chan *imap.Message, 10)
81 done = make(chan error, 1)
82 go func() {
83 done <- c.Fetch(seqset, []imap.FetchItem{imap.FetchEnvelope}, messages)
84 }()
85
86 log.Println("Last 4 messages:")
87 for msg := range messages {
88 log.Println("* " + msg.Envelope.Subject)
89 }
90
91 if err := <-done; err != nil {
92 log.Fatal(err)
93 }
94
95 log.Println("Done!")
96}
97```
98
99### Server [![GoDoc](https://godoc.org/github.com/emersion/go-imap/server?status.svg)](https://godoc.org/github.com/emersion/go-imap/server)
100
101```go
102package main
103
104import (
105 "log"
106
107 "github.com/emersion/go-imap/server"
108 "github.com/emersion/go-imap/backend/memory"
109)
110
111func main() {
112 // Create a memory backend
113 be := memory.New()
114
115 // Create a new server
116 s := server.New(be)
117 s.Addr = ":1143"
118 // Since we will use this server for testing only, we can allow plain text
119 // authentication over unencrypted connections
120 s.AllowInsecureAuth = true
121
122 log.Println("Starting IMAP server at localhost:1143")
123 if err := s.ListenAndServe(); err != nil {
124 log.Fatal(err)
125 }
126}
127```
128
129You can now use `telnet localhost 1143` to manually connect to the server.
130
131## Extending go-imap
132
133### Extensions
134
135Commands defined in IMAP extensions are available in other packages. See [the
136wiki](https://github.com/emersion/go-imap/wiki/Using-extensions#using-client-extensions)
137to learn how to use them.
138
139* [APPENDLIMIT](https://github.com/emersion/go-imap-appendlimit)
140* [COMPRESS](https://github.com/emersion/go-imap-compress)
141* [ENABLE](https://github.com/emersion/go-imap-enable)
142* [ID](https://github.com/ProtonMail/go-imap-id)
143* [IDLE](https://github.com/emersion/go-imap-idle)
144* [METADATA](https://github.com/emersion/go-imap-metadata)
145* [MOVE](https://github.com/emersion/go-imap-move)
146* [QUOTA](https://github.com/emersion/go-imap-quota)
147* [SORT and THREAD](https://github.com/emersion/go-imap-sortthread)
148* [SPECIAL-USE](https://github.com/emersion/go-imap-specialuse)
149* [UNSELECT](https://github.com/emersion/go-imap-unselect)
150* [UIDPLUS](https://github.com/emersion/go-imap-uidplus)
151
152### Server backends
153
154* [Memory](https://github.com/emersion/go-imap/tree/master/backend/memory) (for testing)
155* [Multi](https://github.com/emersion/go-imap-multi)
156* [PGP](https://github.com/emersion/go-imap-pgp)
157* [Proxy](https://github.com/emersion/go-imap-proxy)
158
159### Related projects
160
161* [go-message](https://github.com/emersion/go-message) - parsing and formatting MIME and mail messages
162* [go-msgauth](https://github.com/emersion/go-msgauth) - handle DKIM, DMARC and Authentication-Results
163* [go-pgpmail](https://github.com/emersion/go-pgpmail) - decrypting and encrypting mails with OpenPGP
164* [go-sasl](https://github.com/emersion/go-sasl) - sending and receiving SASL authentications
165* [go-smtp](https://github.com/emersion/go-smtp) - building SMTP clients and servers
166
167## License
168
169MIT
170