api

package
v0.11.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 51 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// Email errors
	ErrorCodeEmailNotFound      = "EMAIL_NOT_FOUND"
	ErrorCodeEmailFileNotFound  = "EMAIL_FILE_NOT_FOUND"
	ErrorCodeNoEmailsFound      = "NO_EMAILS_FOUND"
	ErrorCodeNoEmailsToExport   = "NO_EMAILS_TO_EXPORT"
	ErrorCodeInvalidEmailID     = "INVALID_EMAIL_ID"
	ErrorCodeNoEmailIDsProvided = "NO_EMAIL_IDS_PROVIDED"

	// Request errors
	ErrorCodeInvalidRequest      = "INVALID_REQUEST"
	ErrorCodeInvalidEmailAddress = "INVALID_EMAIL_ADDRESS"
	ErrorCodeHostRequired        = "HOST_REQUIRED"
	ErrorCodePortOutOfRange      = "PORT_OUT_OF_RANGE"
	ErrorCodeInvalidPort         = "INVALID_PORT"
	ErrorCodeConfigUpdateFailed  = "CONFIG_UPDATE_FAILED"

	// Relay errors
	ErrorCodeRelayFailed = "RELAY_FAILED"

	// Success messages (also use codes for consistency)
	SuccessCodeEmailDeleted         = "EMAIL_DELETED"
	SuccessCodeAllEmailsDeleted     = "ALL_EMAILS_DELETED"
	SuccessCodeEmailMarkedRead      = "EMAIL_MARKED_READ"
	SuccessCodeAllEmailsMarkedRead  = "ALL_EMAILS_MARKED_READ"
	SuccessCodeEmailRelayed         = "EMAIL_RELAYED"
	SuccessCodeMailsReloaded        = "MAILS_RELOADED"
	SuccessCodeBatchDeleteCompleted = "BATCH_DELETE_COMPLETED"
	SuccessCodeBatchReadCompleted   = "BATCH_READ_COMPLETED"
	SuccessCodeConfigUpdated        = "CONFIG_UPDATED"
)

API Error Codes These codes are returned to the frontend, which will translate them based on user's language preference

Variables

This section is empty.

Functions

This section is empty.

Types

type API

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

API represents the REST API server

func NewAPI

func NewAPI(mailServer *mailserver.MailServer, port int, host string) *API

NewAPI creates a new API server instance

func NewAPIWithAuth

func NewAPIWithAuth(mailServer *mailserver.MailServer, port int, host, user, password string) *API

NewAPIWithAuth creates a new API server instance with HTTP Basic Auth

func NewAPIWithHTTPS

func NewAPIWithHTTPS(mailServer *mailserver.MailServer, port int, host, user, password string, httpsEnabled bool, certFile, keyFile string) *API

NewAPIWithHTTPS creates a new API server instance with HTTP Basic Auth and HTTPS support

func NewAPIWithHTTPSDeferredRecovery

func NewAPIWithHTTPSDeferredRecovery(mailServer *mailserver.MailServer, port int, host, user, password string, httpsEnabled bool, certFile, keyFile string) *API

NewAPIWithHTTPSDeferredRecovery loads and protects durable relay jobs but leaves delivery recovery paused until StartRelayRecovery is called.

func (*API) MCPAllowedOrigins added in v0.10.0

func (api *API) MCPAllowedOrigins() []string

MCPAllowedOrigins returns the configured extra origins in the canonical form the guard compares against, which is also the form a browser sends. It is what an operator needs to read back when a request is refused; the values as written in configuration may be percent-encoded or spelled differently.

func (*API) SetBasePathname

func (api *API) SetBasePathname(basePathname string) error

SetBasePathname configures the browser-visible URL prefix and rebuilds the router before the server starts. Root is represented by an empty string.

func (*API) SetExternalScheme

func (api *API) SetExternalScheme(scheme string) error

SetExternalScheme configures the browser-visible scheme when TLS terminates at a reverse proxy. It must be called before the API server starts.

func (*API) SetMCPAllowedOrigins added in v0.10.0

func (api *API) SetMCPAllowedOrigins(origins []string) error

SetMCPAllowedOrigins records extra browser origins accepted on the MCP endpoint, in addition to OwlMail's own browser-visible origins. A single "*" entry disables origin validation entirely and is an explicit, documented opt-out. It must be called before the API server starts.

func (*API) SetMCPHandler

func (api *API) SetMCPHandler(handler http.Handler) error

SetMCPHandler enables the optional MCP endpoint using the same listener, HTTPS configuration, base pathname, and Basic Auth middleware as the Web API.

func (*API) SetMailCatcherRESTCompat

func (api *API) SetMailCatcherRESTCompat(enabled bool)

SetMailCatcherRESTCompat enables or disables the opt-in MailCatcher facade.

func (*API) SetMailDevRESTCompat

func (api *API) SetMailDevRESTCompat(enabled bool)

SetMailDevRESTCompat enables or disables the opt-in MailDev REST facade. It must be called before the API server starts.

func (*API) SetMetricsEnabled

func (api *API) SetMetricsEnabled(enabled bool)

SetMetricsEnabled controls the opt-in Prometheus endpoint. The endpoint follows the configured base pathname and existing HTTP Basic Auth policy.

func (*API) SetWebAllowedOrigins added in v0.10.0

func (api *API) SetWebAllowedOrigins(origins []string) error

SetWebAllowedOrigins records extra browser origins accepted on the Web UI and REST API, in addition to OwlMail's own browser-visible origins. A single "*" entry disables origin validation entirely and is an explicit, documented opt-out. It must be called before the API server starts.

func (*API) SetWebhookService added in v0.11.0

func (api *API) SetWebhookService(service *webhook.Service)

SetWebhookService connects delivery diagnostics before the API starts serving.

func (*API) Start

func (api *API) Start() error

Start starts the API server

func (*API) StartRelayRecovery

func (api *API) StartRelayRecovery()

StartRelayRecovery starts queued durable work at most once.

func (*API) StartWithCertificateReady added in v0.11.0

func (api *API) StartWithCertificateReady(ready func([][]byte) error) error

StartWithCertificateReady exposes a copy of the public certificate chain actually loaded by the listener. An initialization error closes the bound listener before serving; private keys never leave the listener configuration.

func (*API) StartWithReady

func (api *API) StartWithReady(ready func()) error

StartWithReady binds the API listener, then calls ready immediately before serving. A bind or TLS configuration failure is returned without calling it.

func (*API) WebAllowedOrigins added in v0.10.0

func (api *API) WebAllowedOrigins() []string

WebAllowedOrigins returns the configured extra origins in the canonical form the guard compares against, which is also the form a browser sends. It is what an operator needs to read back when a request is refused; the values as written in configuration may be percent-encoded or spelled differently.

type APIResponse

type APIResponse struct {
	Code    string      `json:"code,omitempty"`    // Error or success code
	Message string      `json:"message,omitempty"` // Optional: English message for backward compatibility
	Data    interface{} `json:"data,omitempty"`    // Response data
	Error   string      `json:"error,omitempty"`   // Error code (for error responses)
}

APIResponse represents a standardized API response

func ErrorResponse

func ErrorResponse(code string, message string) APIResponse

ErrorResponse creates an error response with code

func SuccessResponse

func SuccessResponse(code string, message string, data interface{}) APIResponse

SuccessResponse creates a success response with code

type EmailPreview

type EmailPreview = mailserver.EmailPreview

EmailPreview represents a lightweight email preview.

type RelayRecoveryInspection added in v0.11.0

type RelayRecoveryInspection struct {
	Pending          int `json:"pending"`
	Completed        int `json:"completed"`
	MissingSources   int `json:"missing_sources"`
	DuplicateSources int `json:"duplicate_sources"`
}

RelayRecoveryInspection is an offline inventory; no records are changed or delivered.

func InspectRelayRecovery added in v0.11.0

func InspectRelayRecovery(mailDirectory string) (RelayRecoveryInspection, error)

InspectRelayRecovery validates persisted records with the normal loader's reader. It never creates directories, prunes expired jobs, acquires leases, or starts workers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL