README
¶
backend
The backend package defines a unified Provider interface for multi-protocol email support and provides three protocol implementations: IMAP, JMAP, and POP3.
Architecture
This package acts as an abstraction layer, allowing the rest of the application to interact with mail servers through a consistent interface regardless of the underlying protocol. Implementations self-register at init time via RegisterBackend, and the factory function New() creates the right provider based on the account's Protocol field (defaults to "imap").
Provider interface
The Provider interface composes five sub-interfaces:
| Interface | Methods | Purpose |
|---|---|---|
EmailReader |
FetchEmails, FetchEmailBody, FetchAttachment |
Retrieve email lists, bodies, and raw attachments |
EmailWriter |
MarkAsRead, DeleteEmail, ArchiveEmail, MoveEmail |
Modify email state and location |
EmailSender |
SendEmail |
Send outgoing mail |
FolderManager |
FetchFolders |
List available mailboxes |
Notifier |
Watch |
Real-time push notifications for mailbox changes |
Backends that don't support an operation return ErrNotSupported.
Protocols
IMAP (backend/imap)
Wraps the existing fetcher and sender packages behind the Provider interface. IMAP IDLE is handled externally in main.go, so Watch() returns ErrNotSupported.
JMAP (backend/jmap)
Native JMAP implementation (RFC 8620 / RFC 8621) using go-jmap. Supports OAuth2 and Basic Auth, real-time push via JMAP EventSource, and full mailbox operations including send (via EmailSubmission). JMAP string IDs are hashed to uint32 UIDs for interface compatibility.
POP3 (backend/pop3)
POP3 + SMTP implementation. Inherently limited to a single INBOX folder, no read flags, no move/archive, and no push notifications. Uses the sender package for outgoing mail.
Files
| File | Description |
|---|---|
backend.go |
Core interfaces and data types (Provider, Email, Attachment, Folder, OutgoingEmail, NotifyEvent, Capabilities) |
factory.go |
Protocol registry and New() factory function |
imap/imap.go |
IMAP provider — adapter over fetcher and sender packages |
jmap/jmap.go |
JMAP provider — native implementation with session management and mailbox caching |
pop3/pop3.go |
POP3 provider — per-connection model with UIDL-based UID hashing |
Documentation
¶
Overview ¶
Package backend defines the Provider interface for multi-protocol email support.
Index ¶
- Variables
- func RegisterBackend(protocol string, fn NewFunc)
- type Attachment
- type Capabilities
- type CapabilityProvider
- type Email
- type EmailReader
- type EmailSender
- type EmailWriter
- type Folder
- type FolderManager
- type NewFunc
- type Notifier
- type NotifyEvent
- type NotifyType
- type OutgoingEmail
- type Provider
Constants ¶
This section is empty.
Variables ¶
var ErrNotSupported = errors.New("operation not supported by this provider")
ErrNotSupported is returned when a provider does not support an operation.
Functions ¶
func RegisterBackend ¶
RegisterBackend registers a backend constructor for a protocol name.
Types ¶
type Attachment ¶
type Attachment struct {
Filename string
PartID string
Data []byte
Encoding string
MIMEType string
ContentID string
Inline bool
IsSMIMESignature bool
SMIMEVerified bool
IsSMIMEEncrypted bool
IsPGPSignature bool
PGPVerified bool
IsPGPEncrypted bool
}
Attachment holds data for an email attachment.
type Capabilities ¶
type Capabilities struct {
CanSend bool
CanMove bool
CanArchive bool
CanPush bool
CanSearchServer bool
CanFetchFolders bool
SupportsSMIME bool
}
Capabilities describes what a backend supports.
type CapabilityProvider ¶
type CapabilityProvider interface {
Capabilities() Capabilities
}
CapabilityProvider optionally reports what a backend can do.
type Email ¶
type Email struct {
UID uint32
From string
To []string
Subject string
Body string
Date time.Time
IsRead bool
MessageID string
References []string
Attachments []Attachment
AccountID string
}
Email represents a single email message.
type EmailReader ¶
type EmailReader interface {
FetchEmails(ctx context.Context, folder string, limit, offset uint32) ([]Email, error)
FetchEmailBody(ctx context.Context, folder string, uid uint32) (string, []Attachment, error)
FetchAttachment(ctx context.Context, folder string, uid uint32, partID, encoding string) ([]byte, error)
}
EmailReader fetches emails and their content.
type EmailSender ¶
type EmailSender interface {
SendEmail(ctx context.Context, msg *OutgoingEmail) error
}
EmailSender sends outgoing email.
type EmailWriter ¶
type EmailWriter interface {
MarkAsRead(ctx context.Context, folder string, uid uint32) error
DeleteEmail(ctx context.Context, folder string, uid uint32) error
ArchiveEmail(ctx context.Context, folder string, uid uint32) error
MoveEmail(ctx context.Context, uid uint32, srcFolder, dstFolder string) error
}
EmailWriter modifies email state.
type FolderManager ¶
FolderManager lists folders/mailboxes.
type Notifier ¶
type Notifier interface {
Watch(ctx context.Context, folder string) (<-chan NotifyEvent, func(), error)
}
Notifier provides real-time notifications for new email.
type NotifyEvent ¶
type NotifyEvent struct {
Type NotifyType
Folder string
AccountID string
}
NotifyEvent is emitted by Watch() when something changes in a mailbox.
type NotifyType ¶
type NotifyType int
NotifyType indicates the kind of notification event.
const ( NotifyNewEmail NotifyType = iota NotifyExpunge NotifyFlagChange )
type OutgoingEmail ¶
type OutgoingEmail struct {
To []string
Cc []string
Bcc []string
Subject string
PlainBody string
HTMLBody string
Images map[string][]byte
Attachments map[string][]byte
InReplyTo string
References []string
SignSMIME bool
EncryptSMIME bool
SignPGP bool
EncryptPGP bool
}
OutgoingEmail contains everything needed to send an email.
type Provider ¶
type Provider interface {
EmailReader
EmailWriter
EmailSender
FolderManager
Notifier
Close() error
}
Provider is the unified interface that all email backends must implement.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package imap implements the backend.Provider interface by delegating to the existing fetcher and sender packages.
|
Package imap implements the backend.Provider interface by delegating to the existing fetcher and sender packages. |
|
Package jmap implements the backend.Provider interface using the JMAP protocol (RFC 8620 Core + RFC 8621 Mail).
|
Package jmap implements the backend.Provider interface using the JMAP protocol (RFC 8620 Core + RFC 8621 Mail). |
|
Package pop3 implements the backend.Provider interface using POP3 for reading email and SMTP for sending.
|
Package pop3 implements the backend.Provider interface using POP3 for reading email and SMTP for sending. |