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 ReplyTo []string
69 Subject string
70 Body string
71 Date time.Time
72 IsRead bool
73 MessageID string
74 References []string
75 Attachments []Attachment
76 AccountID string
77}
78
79// Attachment holds data for an email attachment.
80type Attachment struct {
81 Filename string
82 PartID string
83 Data []byte
84 Encoding string
85 MIMEType string
86 ContentID string
87 Inline bool
88 IsSMIMESignature bool
89 SMIMEVerified bool
90 IsSMIMEEncrypted bool
91 IsPGPSignature bool
92 PGPVerified bool
93 IsPGPEncrypted bool
94}
95
96// Folder represents a mailbox/folder.
97type Folder struct {
98 Name string
99 Delimiter string
100 Attributes []string
101}
102
103// OutgoingEmail contains everything needed to send an email.
104type OutgoingEmail struct {
105 To []string
106 Cc []string
107 Bcc []string
108 Subject string
109 PlainBody string
110 HTMLBody string
111 Images map[string][]byte
112 Attachments map[string][]byte
113 InReplyTo string
114 References []string
115 SignSMIME bool
116 EncryptSMIME bool
117 SignPGP bool
118 EncryptPGP bool
119}
120
121// NotifyType indicates the kind of notification event.
122type NotifyType int
123
124const (
125 NotifyNewEmail NotifyType = iota
126 NotifyExpunge
127 NotifyFlagChange
128)
129
130// NotifyEvent is emitted by Watch() when something changes in a mailbox.
131type NotifyEvent struct {
132 Type NotifyType
133 Folder string
134 AccountID string
135}
136
137// Capabilities describes what a backend supports.
138type Capabilities struct {
139 CanSend bool
140 CanMove bool
141 CanArchive bool
142 CanPush bool
143 CanSearchServer bool
144 CanFetchFolders bool
145 SupportsSMIME bool
146}