1// Package backend defines the Provider interface for multi-protocol email support.
2package backend
3
4import (
5 "context"
6 "errors"
7 "time"
8)
9
10// ErrNotSupported is returned when a provider does not support an operation.
11var ErrNotSupported = errors.New("operation not supported by this provider")
12
13// Provider is the unified interface that all email backends must implement.
14type Provider interface {
15 EmailReader
16 EmailWriter
17 EmailSender
18 FolderManager
19 Notifier
20 Close() error
21}
22
23// EmailReader fetches emails and their content.
24type EmailReader interface {
25 FetchEmails(ctx context.Context, folder string, limit, offset uint32) ([]Email, error)
26 FetchEmailBody(ctx context.Context, folder string, uid uint32) (string, []Attachment, error)
27 FetchAttachment(ctx context.Context, folder string, uid uint32, partID, encoding string) ([]byte, error)
28}
29
30// EmailWriter modifies email state.
31type EmailWriter interface {
32 MarkAsRead(ctx context.Context, folder string, uid uint32) error
33 DeleteEmail(ctx context.Context, folder string, uid uint32) error
34 ArchiveEmail(ctx context.Context, folder string, uid uint32) error
35 MoveEmail(ctx context.Context, uid uint32, srcFolder, dstFolder string) error
36
37 // Batch operations
38 DeleteEmails(ctx context.Context, folder string, uids []uint32) error
39 ArchiveEmails(ctx context.Context, folder string, uids []uint32) error
40 MoveEmails(ctx context.Context, uids []uint32, srcFolder, dstFolder string) error
41}
42
43// EmailSender sends outgoing email.
44type EmailSender interface {
45 SendEmail(ctx context.Context, msg *OutgoingEmail) error
46}
47
48// FolderManager lists folders/mailboxes.
49type FolderManager interface {
50 FetchFolders(ctx context.Context) ([]Folder, error)
51}
52
53// Notifier provides real-time notifications for new email.
54type Notifier interface {
55 Watch(ctx context.Context, folder string) (<-chan NotifyEvent, func(), error)
56}
57
58// CapabilityProvider optionally reports what a backend can do.
59type CapabilityProvider interface {
60 Capabilities() Capabilities
61}
62
63// Email represents a single email message.
64type Email struct {
65 UID uint32
66 From string
67 To []string
68 Subject string
69 Body string
70 Date time.Time
71 IsRead bool
72 MessageID string
73 References []string
74 Attachments []Attachment
75 AccountID string
76}
77
78// Attachment holds data for an email attachment.
79type Attachment struct {
80 Filename string
81 PartID string
82 Data []byte
83 Encoding string
84 MIMEType string
85 ContentID string
86 Inline bool
87 IsSMIMESignature bool
88 SMIMEVerified bool
89 IsSMIMEEncrypted bool
90 IsPGPSignature bool
91 PGPVerified bool
92 IsPGPEncrypted bool
93}
94
95// Folder represents a mailbox/folder.
96type Folder struct {
97 Name string
98 Delimiter string
99 Attributes []string
100}
101
102// OutgoingEmail contains everything needed to send an email.
103type OutgoingEmail struct {
104 To []string
105 Cc []string
106 Bcc []string
107 Subject string
108 PlainBody string
109 HTMLBody string
110 Images map[string][]byte
111 Attachments map[string][]byte
112 InReplyTo string
113 References []string
114 SignSMIME bool
115 EncryptSMIME bool
116 SignPGP bool
117 EncryptPGP bool
118}
119
120// NotifyType indicates the kind of notification event.
121type NotifyType int
122
123const (
124 NotifyNewEmail NotifyType = iota
125 NotifyExpunge
126 NotifyFlagChange
127)
128
129// NotifyEvent is emitted by Watch() when something changes in a mailbox.
130type NotifyEvent struct {
131 Type NotifyType
132 Folder string
133 AccountID string
134}
135
136// Capabilities describes what a backend supports.
137type Capabilities struct {
138 CanSend bool
139 CanMove bool
140 CanArchive bool
141 CanPush bool
142 CanSearchServer bool
143 CanFetchFolders bool
144 SupportsSMIME bool
145}