mailkit

type AccountConfig struct {
	ID                string          // ID 是应用定义的稳定账号标识。
	Endpoint          Endpoint        // Endpoint 是 IMAP 服务地址。
	Auth              Auth            // Auth 是 IMAP 认证信息。
	TLSConfig         *tls.Config     // TLSConfig 是可选的自定义 TLS 配置。
	DialContext       DialContextFunc // DialContext 是可选的自定义网络拨号函数。
	Mailbox           string          // Mailbox 是接收目录，空值使用 INBOX。
	Query             SearchQuery     // Query 是每轮接收都要应用的通用过滤条件。
	PreferIMAPIdle    bool            // PreferIMAPIdle 表示优先使用 IMAP IDLE。
	PollInterval      time.Duration   // PollInterval 是 IDLE 不可用或关闭时的轮询周期。
	IdleRefresh       time.Duration   // IdleRefresh 是主动重启 IDLE 命令的周期。
	ConnectTimeout    time.Duration   // ConnectTimeout 是 IMAP 建连超时。
	CommandTimeout    time.Duration   // CommandTimeout 是单次 IMAP 命令超时。
	BatchSize         int             // BatchSize 是每轮按 UID 获取的最大邮件数。
	ReplayHistory     bool            // ReplayHistory 表示首次上线或 UIDValidity 变化后回放已有邮件。
	RetryDelay        time.Duration   // RetryDelay 是业务要求重试同一封邮件前的等待时间。
	Reconnect         ReconnectPolicy // Reconnect 控制断线恢复退避。
	AllowInsecureAuth bool            // AllowInsecureAuth 允许在明文链路发送认证信息。
}

type AccountState string

type AccountStatus struct {
	AccountID       string       // AccountID 是邮箱账号标识。
	State           AccountState // State 是当前运行状态。
	Generation      uint64       // Generation 是当前会话代次。
	DesiredOnline   bool         // DesiredOnline 表示调用方是否要求账号在线。
	LastStateAt     time.Time    // LastStateAt 是最近状态变化时间。
	LastConnectedAt time.Time    // LastConnectedAt 是最近连接成功时间。
	LastMessageAt   time.Time    // LastMessageAt 是最近完成业务处理时间。
	LastError       string       // LastError 是最近错误文本，成功后会清空。
	Committed       uint64       // Committed 是成功处理数量。
	Skipped         uint64       // Skipped 是永久跳过数量。
	Retried         uint64       // Retried 是业务重试数量。
	Reconnects      uint64       // Reconnects 是断线重连次数。
	Cursor          Cursor       // Cursor 是最近已提交的处理进度。
}

type Address struct {
	Name  string // Name 是收发件人的显示名称。
	Email string // Email 是完整邮箱地址。
}

type Attachment struct {
	Filename    string           // Filename 是收件人看到的文件名称。
	ContentType string           // ContentType 是可选 MIME 类型。
	ContentID   string           // ContentID 用于 HTML 内嵌资源引用。
	Inline      bool             // Inline 标记附件是否为内嵌资源。
	Source      AttachmentSource // Source 为每次发送打开独立内容流。
}

type AttachmentSource func() (io.ReadCloser, error)

type Auth struct {
	// contains filtered or unexported fields
}

type AuthMode string

type BatchResult struct {
	Results   []SendResult // Results 与输入邮件顺序一致。
	Succeeded int          // Succeeded 是成功数量。
	Failed    int          // Failed 是失败数量。
}

type Cursor struct {
	Key         CursorKey // Key 是游标所属账号和邮箱目录。
	UIDValidity uint32    // UIDValidity 标识当前 UID 命名空间。
	LastUID     uint32    // LastUID 是最后已经提交的邮件 UID。
	UpdatedAt   time.Time // UpdatedAt 是游标更新时间。
}

type CursorKey struct {
	AccountID string // AccountID 是调用方定义的账号标识。
	Mailbox   string // Mailbox 是 IMAP 邮箱目录。
}

type CursorStore interface {
	// Load 读取指定账号和邮箱目录的游标。
	Load(ctx context.Context, key CursorKey) (Cursor, bool, error)
	// Save 保存游标，并拒绝同一 UIDValidity 下的倒退更新。
	Save(ctx context.Context, cursor Cursor) error
	// Delete 删除指定账号和邮箱目录的游标。
	Delete(ctx context.Context, key CursorKey) error
}

type DialContextFunc func(ctx context.Context, network, address string) (net.Conn, error)

type Endpoint struct {
	Host    string  // Host 是邮箱服务器域名或 IP。
	Port    int     // Port 是邮箱服务器端口。
	TLSMode TLSMode // TLSMode 是连接加密方式。
}

type Error struct {
	Op        string    // Op 记录失败的操作名称。
	Kind      ErrorKind // Kind 记录稳定错误分类。
	Temporary bool      // Temporary 标记错误是否适合稍后重试。
	Err       error     // Err 保存原始错误。
}

type ErrorKind string

type Event struct {
	Type       EventType    // Type 是事件类型。
	AccountID  string       // AccountID 是邮箱账号标识。
	State      AccountState // State 是事件发生时的账号状态。
	UID        uint32       // UID 是相关邮件 UID。
	MessageID  string       // MessageID 是相关邮件头标识。
	Err        error        // Err 是相关错误或跳过原因。
	OccurredAt time.Time    // OccurredAt 是事件发生时间。
}

type EventType string

type FetchOptions struct {
	IncludeBody        bool  // IncludeBody 控制是否解析文本和 HTML 正文。
	IncludeAttachments bool  // IncludeAttachments 控制是否读取附件内容。
	MaxMessageBytes    int64 // MaxMessageBytes 限制单封原始邮件大小，零使用默认值。
	MaxAttachmentBytes int64 // MaxAttachmentBytes 限制单个附件大小，零使用默认值。
}

type Hub struct {
	// contains filtered or unexported fields
}

type HubConfig struct {
	Handler     MessageHandler // Handler 处理按账号和 UID 排序的邮件。
	CursorStore CursorStore    // CursorStore 保存已经提交的邮件进度。
	EventBuffer int            // EventBuffer 是运行观测副本的通道容量，不参与邮件交付。
}

type Mailbox interface {
	// Search 查询并返回标准化邮件，结果按 UID 升序排列。
	Search(ctx context.Context, query SearchQuery) (SearchResult, error)
	// Close 关闭当前 IMAP 会话。
	Close(ctx context.Context) error
}

type MailboxConfig struct {
	AccountID         string          // AccountID 是调用方定义的稳定账号标识。
	Endpoint          Endpoint        // Endpoint 是 IMAP 服务地址。
	Auth              Auth            // Auth 是 IMAP 认证信息。
	TLSConfig         *tls.Config     // TLSConfig 是可选的自定义 TLS 配置。
	DialContext       DialContextFunc // DialContext 是可选的自定义网络拨号函数。
	Mailbox           string          // Mailbox 是默认邮箱目录，空值使用 INBOX。
	ConnectTimeout    time.Duration   // ConnectTimeout 是建连超时。
	CommandTimeout    time.Duration   // CommandTimeout 是单次 IMAP 命令超时。
	AllowInsecureAuth bool            // AllowInsecureAuth 允许在明文链路发送认证信息。
}

type MemoryCursorStore struct {
	// contains filtered or unexported fields
}

type MessageHandler interface {
	// Handle 处理一封邮件，并明确返回提交、重试或跳过决策。
	Handle(ctx context.Context, message ReceivedMessage) ProcessResult
}

type MessageHandlerFunc func(ctx context.Context, message ReceivedMessage) ProcessResult

type OutgoingMessage struct {
	MessageID   string              // MessageID 是可选的邮件唯一标识。
	From        Address             // From 是发件人。
	To          []Address           // To 是主收件人列表。
	CC          []Address           // CC 是抄送人列表。
	BCC         []Address           // BCC 是密送人列表。
	ReplyTo     []Address           // ReplyTo 是回复地址列表。
	Subject     string              // Subject 是邮件主题。
	Text        string              // Text 是纯文本正文。
	HTML        string              // HTML 是 HTML 正文。
	Headers     map[string][]string // Headers 保存调用方自定义邮件头。
	Attachments []Attachment        // Attachments 是附件和内嵌资源列表。
}

type ProcessAction string

type ProcessResult struct {
	Action ProcessAction // Action 决定当前邮件是否推进游标。
	Err    error         // Err 保存业务失败或跳过原因。
}

type ProviderName string

type ProviderProfile struct {
	Name           string     // Name 是服务商配置名称。
	SMTP           Endpoint   // SMTP 是邮件发送端点。
	IMAP           Endpoint   // IMAP 是邮件接收端点。
	AuthModes      []AuthMode // AuthModes 是服务商支持的认证方式。
	PreferIMAPIdle bool       // PreferIMAPIdle 表示优先使用 IMAP IDLE。
}

type ReceivedAttachment struct {
	Filename    string // Filename 是附件名称。
	ContentType string // ContentType 是附件 MIME 类型。
	ContentID   string // ContentID 是内嵌资源标识。
	Inline      bool   // Inline 标记是否为内嵌资源。
	Size        int64  // Size 是原始附件字节数。
	Data        []byte // Data 是按 FetchOptions 限制读取的附件内容。
}

type ReceivedMessage struct {
	AccountID   string               // AccountID 是 MailKit 邮箱账号标识。
	Mailbox     string               // Mailbox 是邮件所在邮箱目录。
	UIDValidity uint32               // UIDValidity 标识当前 UID 命名空间。
	UID         uint32               // UID 是当前邮箱目录中的稳定邮件编号。
	MessageID   string               // MessageID 是邮件头中的 Message-ID。
	InReplyTo   string               // InReplyTo 是被回复邮件的 Message-ID。
	From        []Address            // From 是发件人列表。
	To          []Address            // To 是主收件人列表。
	CC          []Address            // CC 是抄送人列表。
	ReplyTo     []Address            // ReplyTo 是回复地址列表。
	Subject     string               // Subject 是邮件主题。
	Date        time.Time            // Date 是邮件头声明的发送时间。
	ReceivedAt  time.Time            // ReceivedAt 是 IMAP 服务器内部接收时间。
	Flags       []string             // Flags 是 IMAP 邮件标记。
	Headers     map[string][]string  // Headers 保存标准化后的邮件头。
	Text        string               // Text 是纯文本正文。
	HTML        string               // HTML 是 HTML 正文。
	Attachments []ReceivedAttachment // Attachments 是附件和内嵌资源。
	Size        uint32               // Size 是服务端报告的整封邮件大小。
	ParseError  error                // ParseError 是单封邮件的 MIME 解析错误。
}

type ReconnectPolicy struct {
	InitialDelay   time.Duration // InitialDelay 是第一次重连等待时间。
	MaxDelay       time.Duration // MaxDelay 是重连等待上限。
	Multiplier     float64       // Multiplier 是每次失败后的退避倍数。
	JitterFraction float64       // JitterFraction 是用于错开多账号重连的抖动比例。
}

type RetryPolicy struct {
	MaxAttempts int           // MaxAttempts 是包含首次发送的最大尝试次数。
	Backoff     time.Duration // Backoff 是两次发送尝试之间的固定等待时间。
}

type SearchQuery struct {
	Mailbox      string            // Mailbox 是待查询的邮箱目录，空值使用 INBOX。
	AfterUID     uint32            // AfterUID 只查询 UID 大于该值的邮件。
	Since        time.Time         // Since 按 IMAP 日期粒度查询该日期及之后的邮件。
	Before       time.Time         // Before 按 IMAP 日期粒度查询该日期之前的邮件。
	From         string            // From 按发件地址或名称匹配。
	To           string            // To 按收件地址或名称匹配。
	Subject      string            // Subject 按主题文本匹配。
	Text         string            // Text 按服务端全文搜索能力匹配。
	Headers      map[string]string // Headers 按指定邮件头匹配。
	WithFlags    []string          // WithFlags 要求邮件包含这些标记。
	WithoutFlags []string          // WithoutFlags 要求邮件不包含这些标记。
	Limit        int               // Limit 限制最终返回数量，零表示不额外限制。
	Fetch        FetchOptions      // Fetch 控制邮件内容读取范围。
}

type SearchResult struct {
	Mailbox     string            // Mailbox 是本次查询的邮箱目录。
	UIDValidity uint32            // UIDValidity 标识当前 UID 命名空间。
	Messages    []ReceivedMessage // Messages 按 UID 升序排列。
}

type SendResult struct {
	Index     int    // Index 是邮件在输入切片中的位置。
	MessageID string // MessageID 是调用方提供的邮件标识。
	Attempts  int    // Attempts 是实际发送尝试次数。
	Err       error  // Err 是最终错误，成功时为空。
}

type Sender interface {
	// Send 发送一封邮件。
	Send(ctx context.Context, message OutgoingMessage) error
	// SendBatch 并发发送多封邮件，并按输入顺序返回结果。
	SendBatch(ctx context.Context, messages []OutgoingMessage) BatchResult
	// Stats 返回当前运行状态快照。
	Stats() SenderStats
	// Close 停止接收新任务，并等待进行中的发送完成。
	Close(ctx context.Context) error
}

type SenderConfig struct {
	Endpoint              Endpoint        // Endpoint 是 SMTP 服务地址。
	Auth                  Auth            // Auth 是 SMTP 认证信息。
	TLSConfig             *tls.Config     // TLSConfig 是可选的自定义 TLS 配置。
	DialContext           DialContextFunc // DialContext 是可选的自定义网络拨号函数。
	Timeout               time.Duration   // Timeout 是 SMTP 建连和命令超时。
	MaxConnections        int             // MaxConnections 是并发 SMTP 连接上限。
	ConnectionMaxLifetime time.Duration   // ConnectionMaxLifetime 是连接最大复用时间。
	Retry                 RetryPolicy     // Retry 控制临时错误重试。
	AllowInsecureAuth     bool            // AllowInsecureAuth 允许在明文链路发送认证信息。
}

type SenderStats struct {
	Sent           uint64 // Sent 是发送成功数量。
	Failed         uint64 // Failed 是最终发送失败数量。
	Retried        uint64 // Retried 是额外重试次数。
	InFlight       int64  // InFlight 是当前正在发送的数量。
	MaxConnections int    // MaxConnections 是配置的最大并发连接数。
	Closed         bool   // Closed 表示 Sender 是否已经关闭。
}

type TLSMode string

type TokenSource interface {
	Token(ctx context.Context) (string, error)
}

type TokenSourceFunc func(ctx context.Context) (string, error)