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}
86
87// Folder represents a mailbox/folder.
88type Folder struct {
89 Name string
90 Delimiter string
91 Attributes []string
92}
93
94// OutgoingEmail contains everything needed to send an email.
95type OutgoingEmail struct {
96 To []string
97 Cc []string
98 Bcc []string
99 Subject string
100 PlainBody string
101 HTMLBody string
102 Images map[string][]byte
103 Attachments map[string][]byte
104 InReplyTo string
105 References []string
106 SignSMIME bool
107 EncryptSMIME bool
108}
109
110// NotifyType indicates the kind of notification event.
111type NotifyType int
112
113const (
114 NotifyNewEmail NotifyType = iota
115 NotifyExpunge
116 NotifyFlagChange
117)
118
119// NotifyEvent is emitted by Watch() when something changes in a mailbox.
120type NotifyEvent struct {
121 Type NotifyType
122 Folder string
123 AccountID string
124}
125
126// Capabilities describes what a backend supports.
127type Capabilities struct {
128 CanSend bool
129 CanMove bool
130 CanArchive bool
131 CanPush bool
132 CanSearchServer bool
133 CanFetchFolders bool
134 SupportsSMIME bool
135}