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
38// EmailSender sends outgoing email.
39type EmailSender interface {
40 SendEmail(ctx context.Context, msg *OutgoingEmail) error
41}
42
43// FolderManager lists folders/mailboxes.
44type FolderManager interface {
45 FetchFolders(ctx context.Context) ([]Folder, error)
46}
47
48// Notifier provides real-time notifications for new email.
49type Notifier interface {
50 Watch(ctx context.Context, folder string) (<-chan NotifyEvent, func(), error)
51}
52
53// CapabilityProvider optionally reports what a backend can do.
54type CapabilityProvider interface {
55 Capabilities() Capabilities
56}
57
58// Email represents a single email message.
59type Email struct {
60 UID uint32
61 From string
62 To []string
63 Subject string
64 Body string
65 Date time.Time
66 IsRead bool
67 MessageID string
68 References []string
69 Attachments []Attachment
70 AccountID string
71}
72
73// Attachment holds data for an email attachment.
74type Attachment struct {
75 Filename string
76 PartID string
77 Data []byte
78 Encoding string
79 MIMEType string
80 ContentID string
81 Inline bool
82 IsSMIMESignature bool
83 SMIMEVerified bool
84 IsSMIMEEncrypted bool
85 IsPGPSignature bool
86 PGPVerified bool
87 IsPGPEncrypted bool
88}
89
90// Folder represents a mailbox/folder.
91type Folder struct {
92 Name string
93 Delimiter string
94 Attributes []string
95}
96
97// OutgoingEmail contains everything needed to send an email.
98type OutgoingEmail struct {
99 To []string
100 Cc []string
101 Bcc []string
102 Subject string
103 PlainBody string
104 HTMLBody string
105 Images map[string][]byte
106 Attachments map[string][]byte
107 InReplyTo string
108 References []string
109 SignSMIME bool
110 EncryptSMIME bool
111 SignPGP bool
112 EncryptPGP bool
113}
114
115// NotifyType indicates the kind of notification event.
116type NotifyType int
117
118const (
119 NotifyNewEmail NotifyType = iota
120 NotifyExpunge
121 NotifyFlagChange
122)
123
124// NotifyEvent is emitted by Watch() when something changes in a mailbox.
125type NotifyEvent struct {
126 Type NotifyType
127 Folder string
128 AccountID string
129}
130
131// Capabilities describes what a backend supports.
132type Capabilities struct {
133 CanSend bool
134 CanMove bool
135 CanArchive bool
136 CanPush bool
137 CanSearchServer bool
138 CanFetchFolders bool
139 SupportsSMIME bool
140}