Documentation
¶
Index ¶
- Constants
- type API
- func NewAPI(mailServer *mailserver.MailServer, port int, host string) *API
- func NewAPIWithAuth(mailServer *mailserver.MailServer, port int, host, user, password string) *API
- func NewAPIWithHTTPS(mailServer *mailserver.MailServer, port int, host, user, password string, ...) *API
- func NewAPIWithHTTPSDeferredRecovery(mailServer *mailserver.MailServer, port int, host, user, password string, ...) *API
- func (api *API) MCPAllowedOrigins() []string
- func (api *API) SetBasePathname(basePathname string) error
- func (api *API) SetExternalScheme(scheme string) error
- func (api *API) SetMCPAllowedOrigins(origins []string) error
- func (api *API) SetMCPHandler(handler http.Handler) error
- func (api *API) SetMailCatcherRESTCompat(enabled bool)
- func (api *API) SetMailDevRESTCompat(enabled bool)
- func (api *API) SetMetricsEnabled(enabled bool)
- func (api *API) SetWebAllowedOrigins(origins []string) error
- func (api *API) SetWebhookService(service *webhook.Service)
- func (api *API) Start() error
- func (api *API) StartRelayRecovery()
- func (api *API) StartWithCertificateReady(ready func([][]byte) error) error
- func (api *API) StartWithReady(ready func()) error
- func (api *API) WebAllowedOrigins() []string
- type APIResponse
- type EmailPreview
- type RelayRecoveryInspection
Constants ¶
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
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 ¶
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 ¶
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
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 ¶
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 ¶
SetMailCatcherRESTCompat enables or disables the opt-in MailCatcher facade.
func (*API) SetMailDevRESTCompat ¶
SetMailDevRESTCompat enables or disables the opt-in MailDev REST facade. It must be called before the API server starts.
func (*API) SetMetricsEnabled ¶
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
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
SetWebhookService connects delivery diagnostics before the API starts serving.
func (*API) StartRelayRecovery ¶
func (api *API) StartRelayRecovery()
StartRelayRecovery starts queued durable work at most once.
func (*API) StartWithCertificateReady ¶ added in v0.11.0
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 ¶
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
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.
Source Files
¶
- api.go
- api_config.go
- api_delivery_wait.go
- api_email_checks.go
- api_emails.go
- api_mailcatcher_compat.go
- api_maildev_compat.go
- api_mcp_origin.go
- api_middleware.go
- api_openapi.go
- api_origin.go
- api_relay.go
- api_utils.go
- api_web_origin.go
- api_websocket.go
- api_workflows.go
- error_codes.go
- mcp_http.go
- metrics.go
- relay_job_readiness.go
- relay_jobs.go
- relay_jobs_persistence.go
- relay_recovery_diagnostics.go