backend

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 EmailSearcher
• type EmailSender
• type EmailWriter
• type Folder
• type FolderManager
• type NewFunc
• type Notifier
• type NotifyEvent
• type NotifyType
• type OutgoingEmail
• type Provider
  • func New(account *config.Account) (Provider, error)
• type SearchQuery
  • func ParseSearchQuery(s string) SearchQuery

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

func RegisterBackend(protocol string, fn NewFunc)

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
	ReplyTo     []string
	Subject     string
	Body        string
	Date        time.Time
	IsRead      bool
	MessageID   string
	InReplyTo   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 returns the chosen body, its MIME type ("text/html" or
	// "text/plain"; empty when unknown), parsed attachments, and any error.
	FetchEmailBody(ctx context.Context, folder string, uid uint32) (string, string, []Attachment, error)
	FetchAttachment(ctx context.Context, folder string, uid uint32, partID, encoding string) ([]byte, error)
}

EmailReader fetches emails and their content.

type EmailSearcher

type EmailSearcher interface {
	Search(ctx context.Context, folder string, query SearchQuery) ([]Email, error)
}

EmailSearcher searches emails server-side.

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
	MarkAsUnread(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

	// Batch operations
	DeleteEmails(ctx context.Context, folder string, uids []uint32) error
	ArchiveEmails(ctx context.Context, folder string, uids []uint32) error
	MoveEmails(ctx context.Context, uids []uint32, srcFolder, dstFolder string) error
}

EmailWriter modifies email state.

type Folder

type Folder struct {
	Name       string
	Delimiter  string
	Attributes []string
	Unread     uint32
}

Folder represents a mailbox/folder.

type FolderManager

type FolderManager interface {
	FetchFolders(ctx context.Context) ([]Folder, error)
}

FolderManager lists folders/mailboxes.

type NewFunc

type NewFunc func(account *config.Account) (Provider, error)

NewFunc is the constructor signature for backend providers.

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
	EmailSearcher
	FolderManager
	Notifier
	Close() error
}

Provider is the unified interface that all email backends must implement.

func New

func New(account *config.Account) (Provider, error)

New creates a Provider for the given account based on its Protocol field. An empty protocol defaults to "imap".

type SearchQuery

type SearchQuery struct {
	Raw        string
	From       string
	To         string
	Subject    string
	Body       string
	Since      time.Time
	Before     time.Time
	LargerThan int
	Limit      uint32
}

SearchQuery is the parsed form of a user query string.

func ParseSearchQuery

func ParseSearchQuery(s string) SearchQuery

ParseSearchQuery parses a compact search DSL into a SearchQuery.