Mail

Stack

Same mail stack on every node. Domains, mailboxes, aliases, routes are replicated rows; Postfix and Dovecot read them live. No reloads.

• StorageMaildir ~/mail/<domain>/<localpart> in the tenant home, shared storage. No mount, no mail services; senders retry.
• ClusterDKIM keys, counters, greylist, Bayes shared. Every node in the MX set by default.
• AuthHashed password · up to 5 app passwords (user+tag@example.com) · access tokens (XOAUTH2, OAUTHBEARER) · sender must own the From.
• Login throttlePer client IP: delay after 5, refuse after 20, 10 min window.
• Suspended tenantNo send, no receive. Mail kept.

Mail domains

POST /mail/domains {"domain":"example.com"}          # selector, DKIM key, DNS, SNI, webmail opt-in
POST /mail/domains/example.com/mailboxes {"localpart":"user","quota_mb":2048}

GET/PUT /mail/domains/{domain}/settings (PUT merges). Disable: DELETE /mail/domains/{domain}, mail kept.

Routing

Aliases, forwarders, lists, catch-all

POST /mail/domains/example.com/aliases {"source":"sales","destinations":["user@example.com","other@example.net"]}

• sourceLocal part, full address, or @ for catch-all (explicit only).
• destinationsSeveral = distribution list. Local mailbox = delivery; other = external forward.
• LimitPlan mail_aliases, per source.
• Not availableMailing lists (subscribe, archive, moderation).

External forwarding

Off by default. Needs plan feature external_forwarding (operator) and the tenant switch PUT /mail/account/forwarding {"enabled":true,"default_mailbox_id":N}.

Relays

POST /mail/domains/example.com/relays {"name":"smarthost","nexthop":"[smtp.example.net]:587",
  "auth_enabled":true,"username":"user@example.net","password":"…","tls_level":"encrypt"}

Platform relays: operator, /mail/relays. Tenant relays: own domains; may also use platform relays.

Routes

Order: mailbox → domain → relayhost → direct. Destination route beats transport. Most specific relay login wins. GET /mail/domains/{d}/routing.

Journaling

BCC to an archive. Domain: PUT /mail/domains/{d}/journal {"direction":"in|out|both","address","label"}. Platform: PUT /mail/journal. One address per scope.

Sending limits

• AccountPlan email_per_hour, email_per_day; cluster-wide counter.
• Domainrate_hourly/rate_daily. Per mailbox: not available.
• CountedExternal recipients only, after acceptance.
• Over4.7.1 sending limit reached; counter down 4.3.0. Both temporary; sender notified.
• Outbound limitsCluster-wide; GET /mail/ratelimits.
• LockedRelay lock (/postfix/relay/lock): submission only, sendmail root-only, PHP mail() off. Tenant outbound 25/465/587 denied. Outbound scan: mark 10, reject 15.
• Sieve mailPUT /mail/sieve-route {"enabled":true}: redirects and vacation counted, From checked. Off by default.

Import and sync

mbsync from any IMAP. Gmail and Outlook folders handled. Tenant (/mail/migrations) and mailbox owner (/mail/me/migrations).

POST /mail/migrations {"dest_domain":"example.com","dest_localpart":"user",
  "source_host":"imap.example.net","source_port":993,"source_user":"user@example.net",
  "source_password":"…","mode":"pull","interval_minutes":15,"scan_spam":true}

• ControlPATCH /mail/migrations/{id} · POST …/action pause | resume | run | cancel · DELETE keeps copied mail.
• BehaviourCert verified, password encrypted. Backoff to 6 h, pause after 10 failures. 3 per node. Resumes on another node.
• Moving a domain inEnable mail, create mailboxes (new passwords), aliases, rules, pull syncs, publish new DKIM, switch MX, cancel syncs.
• Not availablecPanel, Virtualmin or other panel importers.

Mail backup jobs

POST /mail/backups {"name":"nightly","kind":"backup","scope":"domain","target":"example.com",
  "dest_path":"/var/backups/ozpanel/mail","schedule":"0 3 * * *","active":true}
ozpanel mail-backup-run --job 3

Operator. kind backup (maildir copy) | sync (remote). scope all | domain | mailbox. Cron or @daily etc. Status ok · partial · failed.

Spam and malware

• QuarantineSpam held. Release (?learn=ham) or delete (?learn=spam) by tenant (/mail/quarantine) or owner (/mail/me/quarantine).
• DigestPOST /mail/quarantine/digest/schedule {"hour":7}; send now …/digest.
• LearningMove in or out of Junk in any client trains (IMAPSieve). /mail/junk-learning.

Deliverability

One-call DNS

POST /mail/domains/{domain}/dns publishes, into the cluster's zone:

Missing MX, host, SPF, DMARC republished every pass; custom values left alone. Autoconfig/autodiscover XML endpoint: not available (DNS only).

Scorecard

GET /mail/domains/{d}/deliverability · /mail/me/deliverability. Grade: good · improvable · action needed.

Checks: MX · SPF (exactly one) · DKIM published and signed · DMARC policy · DNSSEC · MTA-STS · TLS-RPT · TLSA · mail certificate (14 days) · PTR · HELO · Spamhaus ZEN.

Mailboxes and client servicing

• Own passwordMailbox and panel login stay in sync. Reset by email link (/auth/password/reset-request).
• QuotasPer mailbox (Dovecot, at delivery) and tenant total (mail_quota_mb, at allocation).
• FiltersOne Sieve script per mailbox, shared by panel, Roundcube, SOGo.
• Self-diagnosticsGET /mail/me/diagnostics: health, storage, counts, size and send limits.
• Apple MailProfile per access token: GET /tokens/me/{jti}/apple-mail.

Failover

• InboundAll nodes in the mail host's A set; dead node withdrawn; never emptied. Senders retry.
• QueuePer node; a stopped node delivers on return.
• MailboxesShared storage; any node serves them. Dovecot replication not used.

Troubleshooting

CLI: ozpanel mail-backup-run --job N · ozpanel mail-digest · ozpanel mailgw (unit only).

Previous: Apps and containers Next: Webmail, webapp and push