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 NewMultiuserAPIWithHTTPS(server *mailserver.MailServer, port int, host string, httpsEnabled bool, ...) (*API, error)
- func (api *API) BoundAddress() (mailserver.ListenerAddress, bool)
- func (api *API) Close() error
- func (api *API) GetPort() int
- 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 MultiuserOptions
- 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 NewMultiuserAPIWithHTTPS ¶ added in v0.14.0
func NewMultiuserAPIWithHTTPS(server *mailserver.MailServer, port int, host string, httpsEnabled bool, certFile, keyFile string, options MultiuserOptions) (*API, error)
NewMultiuserAPIWithHTTPS constructs an isolated whitelist router. It never registers legacy/global routes, WebSocket listeners, or an MCP handler.
func (*API) BoundAddress ¶ added in v0.12.0
func (api *API) BoundAddress() (mailserver.ListenerAddress, bool)
BoundAddress reports the actual HTTP(S) address between successful binding and listener shutdown. It is safe to read concurrently with startup.
func (*API) Close ¶ added in v0.12.0
Close stops the HTTP listener, including a bound listener not yet passed to Fiber. Shutdown is bounded so a slow HTTP client cannot block process exit.
func (*API) GetPort ¶ added in v0.12.0
GetPort returns the actual bound HTTP(S) port, or the requested port before binding.
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 MultiuserOptions ¶ added in v0.14.0
type RelayRecoveryInspection ¶ added in v0.11.0
type RelayRecoveryInspection = relay.RelayRecoveryInspection
func InspectRelayRecovery ¶ added in v0.11.0
func InspectRelayRecovery(directory string) (RelayRecoveryInspection, error)
InspectRelayRecovery inspects persisted tasks without changing or dispatching them.
Source Files
¶
- address.go
- 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_multiuser.go
- api_multiuser_status.go
- api_openapi.go
- api_origin.go
- api_relay.go
- api_utils.go
- api_web_origin.go
- api_websocket.go
- api_workflows.go
- claim_cache.go
- error_codes.go
- mcp_http.go
- metrics.go
- relay_jobs.go
- relay_recovery_diagnostics.go