Skip to content

Postfix SMTP Server (F4.1) ​

1. Overview ​

Postfix SMTP Server provides enterprise-grade outgoing email transport (MTA) and mail submission for all domains managed in Vexlyx.

In production, port 587 presents the publicly trusted Let's Encrypt certificate for VEXLYX_MAIL_HOSTNAME. Traefik obtains and renews it, while system/scripts/install/sync-mail-tls.sh extracts the matching key pair from acme.json, installs it atomically in docker/mail-data/certs, and restarts Postfix and Dovecot only when the pair changes. A systemd timer runs that sync every 12 hours. The self-signed certificate generated by the container remains a development-only fallback.

The mail hostname must resolve to the Vexlyx server and ports 80/443 must be reachable for the initial HTTP-01 challenge. To retry after correcting DNS:

bash
sudo /usr/local/sbin/vexlyx-sync-mail-tls

Inbound delivery also requires an MX record at VEXLYX_MAIL_DOMAIN targeting VEXLYX_MAIL_HOSTNAME with priority 10. Both values are independently configurable; code and operator guidance must not assume they are always mail.$VEXLYX_DOMAIN and $VEXLYX_DOMAIN. PTR/reverse DNS is configured at the hosting provider, not by Vexlyx. Public mail operation also requires inbound TCP ports 25, 587 and 993, while outbound TCP/25 may require provider approval.

Drawing from modern cloud-native standards (Mailcow, Plesk, CloudPanel, Resend), Vexlyx decouples outgoing mail into:

  1. RFC 6409 Port Separation: Clear segregation between port 25 (server-to-server relay/delivery with strict open relay denial) and port 587 (authenticated client submission with mandatory TLS encryption).
  2. Cryptographic DKIM Signing via OpenDKIM: Automated 2048-bit RSA key pair generation per domain, auto-configuring KeyTable, SigningTable, and TrustedHosts, with direct integration into Vexlyx CoreDNS (F3.3) for instant one-click DNS TXT record deployment.
  3. Decoupled Virtual Domain Sync: Virtual domain tables (/etc/postfix/virtual_domains, virtual_mailbox_maps) synchronized as flat hash maps via postfix_manager.py, isolating mail delivery from runtime database schema changes. Pipelining (#158): Postfix 3.9 defaults smtpd_forbid_unauth_pipelining to yes (an SMTP smuggling mitigation), so a client that sends EHLO and QUIT in one packet gets 554 5.5.0 SMTP protocol synchronization. Mail clients do exactly that when probing a new account (Thunderbird), so the submission service in docker/postfix/master.cf sets -o smtpd_forbid_unauth_pipelining=no. That service only talks to clients that negotiate TLS and then authenticate; port 25, the one exposed to arbitrary senders, keeps the strict default. tests/test_postfix_submission_pipelining.py builds the image and sends a pipelined probe to both ports.
  4. Hybrid Dev & Production Parity: Full containerized development environment in docker-compose.yml (vexlyx-postfix) exposing ports 25 and 587, alongside a dedicated bare-metal production installer (system/scripts/setup-postfix.sh).
  5. Interactive Diagnostic Sandbox: Real-time SMTP handshake testing and open relay verification directly within the Vexlyx dashboard.

2. Architecture & Data Flow ​

┌─────────────────────────────────────────────────────────────┐
│                    Next.js Dashboard UI                     │
│  - /mail (Global Mail & Outgoing SMTP hub)                  │
│  - Daemon status & Port 25 / 587 health badges              │
│  - Virtual domains accordion with DKIM DNS TXT copy helpers │
│  - Interactive SMTP Test Email & Anti-Relay Probe modals    │
└──────────────────────────────┬──────────────────────────────┘
                               │ HTTP / JSON
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                     Fastify API Server                      │
│  - GET  /api/mail/status       (Daemon & port status)       │
│  - GET  /api/mail/domains      (List domains & DKIM state)  │
│  - POST /api/mail/sync         (Sync virtual domains)       │
│  - POST /api/mail/dkim/:id     (Generate DKIM / add to DNS) │
│  - POST /api/mail/test-send    (Live SMTP test delivery)    │
│  - GET  /api/mail/test-relay   (Probe open relay defense)   │
└───────────────┬──────────────────────────────┬──────────────┘
                │                              │
                ▼                              ▼
┌───────────────────────────────┐ ┌───────────────────────────┐
│      PostgreSQL (Prisma)      │ │  system/python/           │
│  - model Domain               │ │  postfix_manager.py       │
│  - model DnsRecord            │ │  - 2048-bit RSA DKIM keys │
│  - model Mailbox              │ │  - sync virtual maps      │
└───────────────────────────────┘ │  - handshake probing      │
                                  └─────────────┬─────────────┘
                                                │ Configures
                                                ▼
                                  ┌───────────────────────────┐
                                  │ Postfix & OpenDKIM Engine │
                                  │ - Port 25 (SMTP MTA)      │
                                  │ - Port 587 (Submission)   │
                                  │ - Port 8891 (Milter)      │
                                  │ - Strict Anti-Open-Relay  │
                                  └───────────────────────────┘

3. Configuration Specifications ​

Postfix main.cf (docker/postfix/main.cf) ​

text
# Identity
myhostname = mail.vexlyx.local
mydomain = vexlyx.local
myorigin = $mydomain
mydestination = localhost.$mydomain, localhost
inet_interfaces = all
inet_protocols = ipv4

# Virtual Domains & Mailboxes
virtual_mailbox_domains = /etc/postfix/virtual_domains
virtual_mailbox_maps = hash:/etc/postfix/virtual_mailbox_maps
virtual_alias_maps = hash:/etc/postfix/virtual_alias_maps

# Relay Security (No Open Relay)
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16
smtpd_relay_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination

# TLS Encryption
smtpd_tls_security_level = may
smtpd_tls_cert_file = /etc/postfix/certs/cert.pem
smtpd_tls_key_file = /etc/postfix/certs/key.pem
smtpd_tls_protocols = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1
smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1

# OpenDKIM Milter
smtpd_milters = inet:127.0.0.1:8891
non_smtpd_milters = $smtpd_milters
milter_default_action = accept
milter_protocol = 6

Postfix master.cf (docker/postfix/master.cf) ​

text
# Standard SMTP MTA
smtp      inet  n       -       n       -       -       smtpd

# Submission Port 587 (RFC 6409)
submission inet n       -       n       -       -       smtpd
  -o syslog_name=postfix/submission
  -o smtpd_tls_security_level=encrypt
  -o smtpd_sasl_auth_enable=yes
  -o smtpd_reject_unlisted_recipient=no
  -o smtpd_client_restrictions=permit_sasl_authenticated,permit_mynetworks,reject
  -o smtpd_relay_restrictions=permit_sasl_authenticated,permit_mynetworks,reject
  -o milter_macro_daemon_name=ORIGINATING

Lookup map rebuilds (virtual_mailbox_maps, virtual_alias_maps) — failures are reported (#51) ​

Postfix reads the compiled .lmdb files, not the plain-text sources, so every mailbox/alias change must be recompiled with postmap. A failed rebuild leaves the previous map in place (recipients rejected with 550, mail routed to old destinations), so it is never swallowed:

WhereBehaviour on a failed rebuild
postfix_manager.py _compile_lmdb_map()Checks the exit status (the script saves the postmap/mv/chmod chain's status before the cleanup rm, which would otherwise always report success), and raises PostfixMapError with the map name and the command's stderr. Timeouts and a missing docker binary are errors too.
sync_virtual_domains / sync_virtual_aliasesThe error propagates, no reload is attempted, and the script prints { "error", "code": "POSTFIX_MAP_COMPILE_FAILED" } with exit 1.
MailService.syncVirtualDomains / syncVirtualAliasesReject with MailError POSTFIX_MAP_COMPILE_FAILED (502) instead of treating the error payload as a result.
POST /api/mail/syncReturns that error.
Mailbox create / reset password / quota / deleteThe database change is already committed, so a failed sync is not an error response (creation would otherwise lose the one-time password, and a saved change would look like a failure). The call succeeds and the response carries warnings: ["The change was saved, but the mail server could not be updated: … Use Mail → Sync to retry."] (DELETE returns 200 { success, warnings } instead of 204 only in this case). Creation is audited and the domain's first-mailbox SPF/DKIM/DMARC/MX setup still runs. The dashboard shows each warning as a toast.
Container entrypoint.sh compile_mapA missing source file is still the quiet first-boot case. A compile failure logs ERROR: failed to compile <map>; a map whose source exists but whose .lmdb is missing afterwards, or that cannot be made world-readable, is logged as an error too, plus a startup warning. None of these abort startup.

Tests: tests/test_postfix_map_rebuild.py, apps/api/src/modules/mail/sync.test.ts, apps/api/src/modules/mailboxes/service.test.ts.


4. OpenDKIM & DNS TXT Auto-Configuration ​

  1. Key Generation: 2048-bit RSA private keys are stored in /etc/opendkim/keys/{domain}/{selector}.private.
  2. OpenDKIM Configuration:
    • KeyTable: default._domainkey.domain.com domain.com:default:/etc/opendkim/keys/domain.com/default.private
    • SigningTable: *@domain.com default._domainkey.domain.com
    • TrustedHosts: Local subnets and domain names.
  3. RFC 6376 DNS TXT Record:
    • Record Name: default._domainkey.domain.com
    • Record Value: v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCA...
    • Auto-inserted into model DnsRecord zone when CoreDNS (F3.3) is active.

5. Testing & Verification ​

Run the dedicated test suite:

bash
python tests/test_postfix_smtp.py

Covered tests:

  • test_01_generate_dkim_keys_and_dns_record: Verifies 2048-bit key generation and v=DKIM1; k=rsa; p=... format.
  • test_02_opendkim_tables_updated: Verifies KeyTable, SigningTable, and TrustedHosts.
  • test_03_get_dkim_existing: Checks retrieving existing DKIM keys from disk.
  • test_04_sync_virtual_domains: Verifies flat map creation for virtual domains and mailboxes.
  • test_05_status_inspection: Verifies service status structure.
  • test_01_main_cf_security_parameters: Checks main.cf parameters.
  • test_02_master_cf_submission_service: Checks port 587 submission parameters.
  • test_03_opendkim_conf_parameters: Checks opendkim.conf.
  • test_04_host_setup_script_exists: Validates VPS installation script.
  • test_01_unauthenticated_requests_return_401: Enforces security on all mail endpoints.

6. How to Extend ​

  • F4.2 Dovecot IMAP Server (🟢 COMPLETED): Postfix is configured with smtpd_sasl_type = dovecot and smtpd_sasl_path = inet:dovecot:12345 (a TCP auth listener, not a shared unix socket — Postfix and Dovecot run in separate containers). See docs/dev/email/dovecot.md.
  • F4.3 Mailbox Management UI: The virtual mailbox map structure (/etc/postfix/virtual_mailbox_maps) is ready for per-user quota and address provisioning.
  • F4.5 SPF & DMARC Auto-Configuration: The DKIM public keys generated in F4.1 directly populate the DMARC and SPF alignment policies.

Released under the MIT license.