Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(mail): serverkit-mail extension backend (Stalwart engine)

Juan Denis2f36fa4c927d
diff --git a/builtin-extensions/serverkit-mail/backend/__init__.py b/builtin-extensions/serverkit-mail/backend/__init__.py
new file mode 100644
index 00000000..4a3057cc
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/__init__.py
@@ -0,0 +1,4 @@
+"""ServerKit Mail Server extension backend package (Stalwart engine)."""
+from .mail import mail_bp
+
+__all__ = ['mail_bp']
diff --git a/builtin-extensions/serverkit-mail/backend/dns_mail_service.py b/builtin-extensions/serverkit-mail/backend/dns_mail_service.py
new file mode 100644
index 00000000..b3b2bede
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/dns_mail_service.py
@@ -0,0 +1,239 @@
+"""DKIM keygen + mail DNS record deployment (serverkit-mail extension).
+
+Owns the DNS side of standing up a deliverable domain:
+
+* :meth:`generate_dkim` — mint an RSA-2048 DKIM keypair (via ``cryptography``),
+ store the PEM private key + base64 DER public key on the :class:`MailDomain`
+ row, and expose the public half as a DKIM TXT value.
+* :meth:`build_records` — the **pure, testable** record builder: given a domain
+ row + optional server IP, return the exact list of records
+ (MX/SPF/DKIM/DMARC/A) the domain needs. No side effects.
+* :meth:`deploy_dns` — push those records through the core
+ :class:`DNSProviderService` (``source='mail'`` for the ownership ledger),
+ recording per-record results on the row. When no connected provider manages
+ the zone, degrade to manual instructions.
+* :meth:`dns_instructions` — the record list for the UI, provider or not.
+* :meth:`request_cert` — best-effort Let's Encrypt cert for the mail hostname.
+
+Best-effort throughout; the provider/SSL layers are imported lazily so a missing
+dependency never breaks import, and nothing here raises to the caller.
+"""
+import base64
+import json
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_SELECTOR = 'serverkit'
+DMARC_POLICY = 'quarantine'
+
+
+class DkimDnsService:
+ """Stateless DKIM + mail-DNS orchestration."""
+
+ # ---------- DKIM key generation ----------
+
+ @classmethod
+ def generate_dkim(cls, domain_row):
+ """Generate an RSA-2048 DKIM keypair and store it on *domain_row*.
+
+ Returns ``{success, selector, dkim_value}`` (or an error dict). The
+ private key is stored as PEM, the public key as base64 DER, and the
+ DKIM TXT value ``v=DKIM1; k=rsa; p=<b64>`` is returned for display.
+ """
+ try:
+ from cryptography.hazmat.primitives import serialization
+ from cryptography.hazmat.primitives.asymmetric import rsa
+ except ImportError as e:
+ return {'success': False, 'error': f'cryptography is required for DKIM: {e}'}
+ try:
+ key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+ private_pem = key.private_bytes(
+ encoding=serialization.Encoding.PEM,
+ format=serialization.PrivateFormat.TraditionalOpenSSL,
+ encryption_algorithm=serialization.NoEncryption(),
+ ).decode('ascii')
+ public_der = key.public_key().public_bytes(
+ encoding=serialization.Encoding.DER,
+ format=serialization.PublicFormat.SubjectPublicKeyInfo,
+ )
+ public_b64 = base64.b64encode(public_der).decode('ascii')
+ except Exception as e: # noqa: BLE001
+ return {'success': False, 'error': f'DKIM key generation failed: {e}'}
+
+ selector = domain_row.dkim_selector or DEFAULT_SELECTOR
+ try:
+ from app import db
+ domain_row.dkim_selector = selector
+ domain_row.dkim_private_key = private_pem
+ domain_row.dkim_public_key = public_b64
+ db.session.commit()
+ except Exception as e: # noqa: BLE001
+ try:
+ from app import db
+ db.session.rollback()
+ except Exception:
+ pass
+ return {'success': False, 'error': f'Could not store DKIM key: {e}'}
+
+ return {
+ 'success': True,
+ 'selector': selector,
+ 'dkim_value': cls._dkim_txt_value(public_b64),
+ }
+
+ @staticmethod
+ def _dkim_txt_value(public_b64):
+ return f'v=DKIM1; k=rsa; p={public_b64}'
+
+ # ---------- pure record builder (testable) ----------
+
+ @classmethod
+ def build_records(cls, domain_row, server_ip=None):
+ """Return the list of DNS records *domain_row* needs. Pure, no I/O.
+
+ Each record is ``{type, name, value}`` (plus ``priority`` for MX). The
+ DKIM record is included only once a key has been generated.
+ """
+ name = (domain_row.name or '').strip().lower().rstrip('.')
+ selector = domain_row.dkim_selector or DEFAULT_SELECTOR
+ mail_host = f'mail.{name}'
+ records = [
+ {'type': 'MX', 'name': name, 'value': f'10 {mail_host}', 'priority': 10},
+ {'type': 'TXT', 'name': name, 'value': 'v=spf1 mx a ~all'},
+ {'type': 'TXT', 'name': f'_dmarc.{name}',
+ 'value': f'v=DMARC1; p={DMARC_POLICY}; rua=mailto:postmaster@{name}'},
+ ]
+ if domain_row.dkim_public_key:
+ records.append({
+ 'type': 'TXT',
+ 'name': f'{selector}._domainkey.{name}',
+ 'value': cls._dkim_txt_value(domain_row.dkim_public_key),
+ })
+ if server_ip:
+ records.append({'type': 'A', 'name': mail_host, 'value': server_ip})
+ return records
+
+ # ---------- DNS deployment ----------
+
+ @classmethod
+ def deploy_dns(cls, domain_id, server_ip=None):
+ """Deploy the domain's mail records through a connected DNS provider.
+
+ Records the per-record result on ``MailDomain.dns_last_result`` and sets
+ ``dns_deployed``. When no connected provider manages the zone, returns
+ ``{success: True, deployed: False, manual: True, records: [...]}`` so the
+ caller can show manual instructions. Never raises.
+ """
+ try:
+ from app import db
+ from .models import MailDomain
+ except Exception as e: # noqa: BLE001
+ return {'success': False, 'error': f'Model import failed: {e}'}
+
+ domain_row = MailDomain.query.get(domain_id)
+ if not domain_row:
+ return {'success': False, 'error': 'Domain not found'}
+
+ records = cls.build_records(domain_row, server_ip=server_ip)
+
+ try:
+ from app.services.dns_provider_service import DNSProviderService
+ except Exception as e: # noqa: BLE001
+ return {'success': True, 'deployed': False, 'manual': True,
+ 'records': records, 'note': f'DNS provider layer unavailable: {e}'}
+
+ try:
+ config, zone = DNSProviderService.find_zone_for_domain(domain_row.name)
+ except Exception as e: # noqa: BLE001
+ return {'success': True, 'deployed': False, 'manual': True,
+ 'records': records, 'note': f'Provider lookup failed: {e}'}
+
+ if not config or not zone:
+ return {'success': True, 'deployed': False, 'manual': True,
+ 'records': records,
+ 'note': f'No connected DNS provider manages {domain_row.name}.'}
+
+ results = {}
+ all_ok = True
+ for rec in records:
+ key = f"{rec['type'].lower()}:{rec['name']}"
+ try:
+ res = DNSProviderService.set_record(
+ config.id, zone['id'], rec['type'], rec['name'], rec['value'],
+ priority=rec.get('priority'), source='mail')
+ except Exception as e: # noqa: BLE001
+ res = {'success': False, 'error': str(e)}
+ results[key] = {'success': bool(res.get('success')),
+ 'error': res.get('error'),
+ 'record': rec}
+ all_ok = all_ok and bool(res.get('success'))
+
+ payload = {'provider': config.name, 'zone': zone.get('name'),
+ 'results': results, 'all_ok': all_ok}
+ try:
+ domain_row.dns_last_result = json.dumps(payload)
+ domain_row.dns_deployed = all_ok
+ db.session.commit()
+ except Exception as e: # noqa: BLE001
+ try:
+ db.session.rollback()
+ except Exception:
+ pass
+ logger.warning('Could not persist DNS deploy result: %s', e)
+
+ cls._notify_deployed(domain_row.name, all_ok)
+ return {'success': all_ok, 'deployed': all_ok, 'manual': False,
+ 'provider': config.name, 'zone': zone.get('name'),
+ 'results': results, 'records': records}
+
+ @staticmethod
+ def _notify_deployed(domain, all_ok):
+ try:
+ from app.plugins_sdk import notify
+ notify.send('mail.dns_deployed', to='admins',
+ data={'domain': domain, 'all_ok': all_ok}, category='system')
+ except Exception as e: # noqa: BLE001
+ logger.debug('mail.dns_deployed notify failed: %s', e)
+
+ @classmethod
+ def dns_instructions(cls, domain_row, server_ip=None):
+ """Return the records the operator must publish (for the UI), plus the
+ current deployment status. Provider-independent."""
+ deployed = bool(getattr(domain_row, 'dns_deployed', False))
+ last_result = None
+ if getattr(domain_row, 'dns_last_result', None):
+ try:
+ last_result = json.loads(domain_row.dns_last_result)
+ except (ValueError, TypeError):
+ last_result = None
+ return {
+ 'domain': domain_row.name,
+ 'records': cls.build_records(domain_row, server_ip=server_ip),
+ 'dns_deployed': deployed,
+ 'dns_last_result': last_result,
+ 'dkim_configured': bool(getattr(domain_row, 'dkim_private_key', None)),
+ }
+
+ # ---------- TLS certificate ----------
+
+ @classmethod
+ def request_cert(cls, hostname):
+ """Best-effort Let's Encrypt cert for ``mail.<hostname>``. Linux-only."""
+ if os.name == 'nt':
+ return {'success': False, 'skipped': True,
+ 'error': 'Certificate issuance is not supported on this OS.'}
+ hostname = (hostname or '').strip().lower().rstrip('.')
+ if not hostname:
+ return {'success': False, 'error': 'A hostname is required'}
+ try:
+ from app.services.ssl_service import SSLService
+ except Exception as e: # noqa: BLE001
+ return {'success': False, 'error': f'SSL service unavailable: {e}'}
+ email = f'postmaster@{hostname.split(".", 1)[-1]}' if '.' in hostname else f'postmaster@{hostname}'
+ try:
+ result = SSLService.obtain_certificate([hostname], email, use_nginx=True)
+ except Exception as e: # noqa: BLE001
+ return {'success': False, 'error': f'Certificate request failed: {e}'}
+ return result
diff --git a/builtin-extensions/serverkit-mail/backend/jobs.py b/builtin-extensions/serverkit-mail/backend/jobs.py
new file mode 100644
index 00000000..c7df64f9
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/jobs.py
@@ -0,0 +1,70 @@
+"""Background job handlers (serverkit-mail extension).
+
+Registered via the manifest ``jobs`` block; each handler takes the ``job`` row
+and must never raise (a raised handler fails the job loudly — these are
+best-effort maintenance tasks).
+
+* ``mail.preflight.run`` (:func:`run_preflight`) — re-check deliverability for the
+ configured hostname on a daily schedule; notify admins if it regressed to
+ failing.
+* ``mail.queue.flush`` (:func:`flush_queue`) — ask Stalwart to retry its outbound
+ queue.
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+
+SLUG = 'serverkit-mail'
+
+
+def run_preflight(job):
+ """Re-run the deliverability preflight for the configured hostname.
+
+ Reads the hostname from the plugin config store, re-runs preflight, and —
+ when the verdict regressed from passing to failing — notifies admins. Never
+ raises.
+ """
+ try:
+ from app.plugins_sdk import config as plugin_config
+ from .preflight_service import PreflightService
+
+ cfg = plugin_config(SLUG)
+ hostname = cfg.get('hostname')
+ server_ip = cfg.get('server_ip')
+ if not hostname:
+ return {'skipped': True, 'reason': 'no hostname configured'}
+
+ previous = PreflightService.latest()
+ was_passing = bool(previous and previous.get('passed'))
+
+ result = PreflightService.run(hostname, server_ip=server_ip)
+ now_passing = bool(result and result.get('passed'))
+
+ if was_passing and not now_passing:
+ _notify_regression(hostname, result)
+
+ return {'hostname': hostname, 'passed': now_passing,
+ 'regressed': was_passing and not now_passing}
+ except Exception as e: # noqa: BLE001 — a maintenance job must not crash the loop
+ logger.warning('mail preflight job failed: %s', e)
+ return {'error': str(e)}
+
+
+def _notify_regression(hostname, result):
+ try:
+ from app.plugins_sdk import notify
+ notify.send('mail.preflight_failed', to='admins',
+ data={'hostname': hostname, 'result': result},
+ category='system')
+ except Exception as e: # noqa: BLE001
+ logger.debug('mail.preflight_failed notify failed: %s', e)
+
+
+def flush_queue(job):
+ """Best-effort flush of the Stalwart outbound queue. Never raises."""
+ try:
+ from .stalwart_service import StalwartService
+ return StalwartService.flush_queue()
+ except Exception as e: # noqa: BLE001
+ logger.warning('mail queue flush job failed: %s', e)
+ return {'error': str(e)}
diff --git a/builtin-extensions/serverkit-mail/backend/lifecycle.py b/builtin-extensions/serverkit-mail/backend/lifecycle.py
new file mode 100644
index 00000000..ad423ec2
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/lifecycle.py
@@ -0,0 +1,43 @@
+"""Install / uninstall lifecycle hooks (serverkit-mail extension).
+
+Contract (per the plugin SDK): a single positional arg — the InstalledPlugin
+row. ``on_uninstall`` also accepts a ``purge`` flag. Everything here is wrapped
+so a hook failure never blocks install/uninstall.
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def on_install(plugin):
+ """Register the extension's notification events. Best-effort."""
+ try:
+ from app.plugins_sdk import notify
+ notify.register_event(
+ 'mail.preflight_failed',
+ 'Mail deliverability preflight failed',
+ template='generic', severity='warning', category='system')
+ notify.register_event(
+ 'mail.dns_deployed',
+ 'Mail DNS records deployed',
+ template='generic', severity='success', category='system')
+ logger.info('serverkit-mail installed: notification events registered')
+ except Exception as e: # noqa: BLE001
+ logger.warning('serverkit-mail on_install hook error: %s', e)
+
+
+def on_uninstall(plugin, purge=False):
+ """Best-effort stop/remove the Stalwart container on uninstall.
+
+ On ``purge`` the mail data directory is deleted too; otherwise the container
+ is removed but the data is kept so a reinstall can pick it back up.
+ """
+ try:
+ from .stalwart_service import StalwartService
+ if StalwartService.is_installed():
+ result = StalwartService.uninstall(keep_data=not purge)
+ logger.info('serverkit-mail on_uninstall: %s', result)
+ else:
+ logger.info('serverkit-mail on_uninstall: container not present')
+ except Exception as e: # noqa: BLE001
+ logger.warning('serverkit-mail on_uninstall hook error: %s', e)
diff --git a/builtin-extensions/serverkit-mail/backend/mail.py b/builtin-extensions/serverkit-mail/backend/mail.py
new file mode 100644
index 00000000..e2200717
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/mail.py
@@ -0,0 +1,392 @@
+"""Mail Server API endpoints (serverkit-mail extension).
+
+Mounted under ``/api/v1/mail`` via the manifest's ``url_prefix``. Thin routing
+layer over the extension services — all Docker, Stalwart-API, DNS, and DKIM work
+happens in the services. Reads need viewer, mutations need admin (same split as
+the serverkit-dns-server extension).
+
+``_installed_or_error`` guards only the routes that genuinely need a running
+Stalwart engine (``/queue``, ``/service/<action>``). Domain/mailbox/forwarder
+CRUD writes to *our* DB and reconciles to Stalwart best-effort, so it works even
+before the engine is installed (operators can stage config first).
+"""
+from flask import Blueprint, jsonify, request
+
+from app.middleware.rbac import admin_required, viewer_required
+
+from .mail_service import MailService
+from .stalwart_service import StalwartService
+from .preflight_service import PreflightService
+from .dns_mail_service import DkimDnsService
+
+mail_bp = Blueprint('mail', __name__)
+
+_NOT_INSTALLED = (
+ 'The mail server is not installed. Install it from the Mail Server page '
+ '(admin only).'
+)
+
+
+def _installed_or_error():
+ """Return an error response tuple when the engine is absent, else None."""
+ if not StalwartService.is_installed():
+ return jsonify({'error': _NOT_INSTALLED}), 503
+ return None
+
+
+def _server_ip(data=None):
+ """Resolve the server public IP: explicit body value, else system settings."""
+ if data and data.get('server_ip'):
+ return str(data['server_ip']).strip()
+ try:
+ from app.services.site_domain_service import SiteDomainService
+ return SiteDomainService.server_ip()
+ except Exception: # noqa: BLE001
+ return None
+
+
+def _domain_or_404(domain_id):
+ from .models import MailDomain
+ return MailDomain.query.get(domain_id)
+
+
+# ── Status / lifecycle ──
+
+@mail_bp.route('/status', methods=['GET'])
+@viewer_required
+def get_status():
+ """Engine status + latest deliverability preflight."""
+ return jsonify(MailService.get_status()), 200
+
+
+@mail_bp.route('/install', methods=['POST'])
+@admin_required
+def install():
+ """Start the Stalwart container: {hostname}."""
+ data = request.get_json() or {}
+ hostname = (data.get('hostname') or '').strip()
+ if not hostname:
+ return jsonify({'error': 'hostname is required'}), 400
+ result = StalwartService.install(hostname)
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Install failed')}), 400
+ return jsonify(result), 201
+
+
+@mail_bp.route('/install', methods=['DELETE'])
+@admin_required
+def uninstall():
+ """Remove the container (?keep_data=true keeps the mail data)."""
+ keep_data = (request.args.get('keep_data', 'true').lower()
+ not in ('false', '0', 'no'))
+ result = StalwartService.uninstall(keep_data=keep_data)
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Uninstall failed')}), 400
+ return jsonify(result), 200
+
+
+@mail_bp.route('/service/<action>', methods=['POST'])
+@admin_required
+def control_service(action):
+ """Start / stop / restart the engine container."""
+ guard = _installed_or_error()
+ if guard:
+ return guard
+ if action not in ('start', 'stop', 'restart'):
+ return jsonify({'error': "action must be start, stop or restart"}), 400
+ result = StalwartService.control(action)
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Service control failed')}), 400
+ return jsonify(result), 200
+
+
+# ── Preflight ──
+
+@mail_bp.route('/preflight', methods=['GET'])
+@viewer_required
+def get_preflight():
+ """Latest persisted preflight result (or null)."""
+ return jsonify({'preflight': PreflightService.latest()}), 200
+
+
+@mail_bp.route('/preflight', methods=['POST'])
+@admin_required
+def run_preflight():
+ """Run and persist a deliverability preflight: {hostname, server_ip?}."""
+ data = request.get_json() or {}
+ hostname = (data.get('hostname') or '').strip()
+ if not hostname:
+ return jsonify({'error': 'hostname is required'}), 400
+ server_ip = _server_ip(data)
+ result = PreflightService.run(hostname, server_ip=server_ip)
+ return jsonify(result), 200
+
+
+# ── Domains ──
+
+@mail_bp.route('/domains', methods=['GET'])
+@viewer_required
+def list_domains():
+ return jsonify({'domains': MailService.list_domains()}), 200
+
+
+@mail_bp.route('/domains', methods=['POST'])
+@admin_required
+def add_domain():
+ """Add a mail domain: {name, catch_all_target?}."""
+ data = request.get_json() or {}
+ name = (data.get('name') or '').strip()
+ if not name:
+ return jsonify({'error': 'name is required'}), 400
+ result = MailService.add_domain(name, catch_all_target=data.get('catch_all_target'))
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Failed to add domain')}), 400
+ return jsonify(result), 201
+
+
+@mail_bp.route('/domains/<int:domain_id>', methods=['GET'])
+@viewer_required
+def get_domain(domain_id):
+ domain = MailService.get_domain(domain_id)
+ if not domain:
+ return jsonify({'error': 'Domain not found'}), 404
+ return jsonify(domain), 200
+
+
+@mail_bp.route('/domains/<int:domain_id>', methods=['PATCH'])
+@admin_required
+def update_domain(domain_id):
+ """Update a domain: {is_active?, catch_all_target?}. Activation is gated on a
+ passing preflight (or ?force=true)."""
+ data = request.get_json() or {}
+ force = (request.args.get('force', 'false').lower() in ('true', '1', 'yes')) \
+ or bool(data.get('force'))
+ is_active = data.get('is_active')
+ if is_active is not None:
+ result = MailService.set_domain_active(domain_id, bool(is_active), force=force)
+ else:
+ result = MailService.update_domain(
+ domain_id, catch_all_target=data.get('catch_all_target'))
+ if not result.get('success'):
+ code = 409 if result.get('code') == 'preflight_required' else 400
+ return jsonify({'error': result.get('error', 'Update failed'),
+ 'preflight': result.get('preflight')}), code
+ return jsonify(result), 200
+
+
+@mail_bp.route('/domains/<int:domain_id>', methods=['DELETE'])
+@admin_required
+def remove_domain(domain_id):
+ result = MailService.remove_domain(domain_id)
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Failed to remove domain')}), 400
+ return jsonify(result), 200
+
+
+# ── DKIM / DNS / cert ──
+
+@mail_bp.route('/domains/<int:domain_id>/dkim', methods=['POST'])
+@admin_required
+def generate_dkim(domain_id):
+ domain = _domain_or_404(domain_id)
+ if not domain:
+ return jsonify({'error': 'Domain not found'}), 404
+ result = DkimDnsService.generate_dkim(domain)
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'DKIM generation failed')}), 400
+ return jsonify(result), 200
+
+
+@mail_bp.route('/domains/<int:domain_id>/dns', methods=['GET'])
+@viewer_required
+def dns_instructions(domain_id):
+ domain = _domain_or_404(domain_id)
+ if not domain:
+ return jsonify({'error': 'Domain not found'}), 404
+ return jsonify(DkimDnsService.dns_instructions(domain, server_ip=_server_ip())), 200
+
+
+@mail_bp.route('/domains/<int:domain_id>/dns/deploy', methods=['POST'])
+@admin_required
+def deploy_dns(domain_id):
+ domain = _domain_or_404(domain_id)
+ if not domain:
+ return jsonify({'error': 'Domain not found'}), 404
+ data = request.get_json(silent=True) or {}
+ result = DkimDnsService.deploy_dns(domain_id, server_ip=_server_ip(data))
+ # A manual-instructions outcome is still a 200 (there's nothing to fix).
+ if not result.get('success') and not result.get('manual'):
+ return jsonify(result), 400
+ return jsonify(result), 200
+
+
+@mail_bp.route('/domains/<int:domain_id>/cert', methods=['POST'])
+@admin_required
+def request_cert(domain_id):
+ domain = _domain_or_404(domain_id)
+ if not domain:
+ return jsonify({'error': 'Domain not found'}), 404
+ result = DkimDnsService.request_cert(f'mail.{domain.name}')
+ if not result.get('success'):
+ return jsonify(result), 200 if result.get('skipped') else 400
+ return jsonify(result), 200
+
+
+# ── Mailboxes ──
+
+@mail_bp.route('/domains/<int:domain_id>/mailboxes', methods=['GET'])
+@viewer_required
+def list_mailboxes(domain_id):
+ if not _domain_or_404(domain_id):
+ return jsonify({'error': 'Domain not found'}), 404
+ return jsonify({'mailboxes': MailService.list_mailboxes(domain_id)}), 200
+
+
+@mail_bp.route('/domains/<int:domain_id>/mailboxes', methods=['POST'])
+@admin_required
+def add_mailbox(domain_id):
+ """Create a mailbox: {local_part, password, quota_mb?, display_name?}."""
+ data = request.get_json() or {}
+ local_part = (data.get('local_part') or '').strip()
+ password = data.get('password')
+ if not local_part:
+ return jsonify({'error': 'local_part is required'}), 400
+ if not password:
+ return jsonify({'error': 'password is required'}), 400
+ result = MailService.add_mailbox(
+ domain_id, local_part, password,
+ quota_mb=data.get('quota_mb', 0),
+ display_name=data.get('display_name'))
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Failed to create mailbox')}), 400
+ return jsonify(result), 201
+
+
+@mail_bp.route('/mailboxes/<int:mailbox_id>', methods=['PATCH'])
+@admin_required
+def update_mailbox(mailbox_id):
+ """Update a mailbox: {quota_mb?, is_active?, display_name?}."""
+ data = request.get_json() or {}
+ result = MailService.update_mailbox(
+ mailbox_id,
+ quota_mb=data.get('quota_mb'),
+ is_active=data.get('is_active'),
+ display_name=data.get('display_name'))
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Failed to update mailbox')}), 400
+ return jsonify(result), 200
+
+
+@mail_bp.route('/mailboxes/<int:mailbox_id>/password', methods=['POST'])
+@admin_required
+def set_mailbox_password(mailbox_id):
+ """Set a mailbox password: {password}."""
+ data = request.get_json() or {}
+ password = data.get('password')
+ if not password:
+ return jsonify({'error': 'password is required'}), 400
+ result = MailService.set_mailbox_password(mailbox_id, password)
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Failed to set password')}), 400
+ return jsonify(result), 200
+
+
+@mail_bp.route('/mailboxes/<int:mailbox_id>', methods=['DELETE'])
+@admin_required
+def remove_mailbox(mailbox_id):
+ result = MailService.remove_mailbox(mailbox_id)
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Failed to remove mailbox')}), 400
+ return jsonify(result), 200
+
+
+# ── Autoresponder ──
+
+@mail_bp.route('/mailboxes/<int:mailbox_id>/autoresponder', methods=['GET'])
+@viewer_required
+def get_autoresponder(mailbox_id):
+ result = MailService.get_autoresponder(mailbox_id)
+ if result is None:
+ return jsonify({'error': 'Mailbox not found'}), 404
+ return jsonify({'autoresponder': result}), 200
+
+
+@mail_bp.route('/mailboxes/<int:mailbox_id>/autoresponder', methods=['PUT'])
+@admin_required
+def set_autoresponder(mailbox_id):
+ """Set the autoresponder: {enabled, subject, body, start_at?, end_at?}."""
+ data = request.get_json() or {}
+ result = MailService.set_autoresponder(
+ mailbox_id,
+ enabled=data.get('enabled'),
+ subject=data.get('subject'),
+ body=data.get('body'),
+ start_at=data.get('start_at'),
+ end_at=data.get('end_at'))
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Failed to save autoresponder')}), 400
+ return jsonify(result), 200
+
+
+# ── Forwarders ──
+
+@mail_bp.route('/domains/<int:domain_id>/forwarders', methods=['GET'])
+@viewer_required
+def list_forwarders(domain_id):
+ if not _domain_or_404(domain_id):
+ return jsonify({'error': 'Domain not found'}), 404
+ return jsonify({'forwarders': MailService.list_forwarders(domain_id)}), 200
+
+
+@mail_bp.route('/domains/<int:domain_id>/forwarders', methods=['POST'])
+@admin_required
+def add_forwarder(domain_id):
+ """Create a forwarder: {source_local_part, destination, keep_copy?}."""
+ data = request.get_json() or {}
+ source = (data.get('source_local_part') or '').strip()
+ destination = (data.get('destination') or '').strip()
+ if not source:
+ return jsonify({'error': 'source_local_part is required'}), 400
+ if not destination:
+ return jsonify({'error': 'destination is required'}), 400
+ result = MailService.add_forwarder(
+ domain_id, source, destination, keep_copy=bool(data.get('keep_copy')))
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Failed to create forwarder')}), 400
+ return jsonify(result), 201
+
+
+@mail_bp.route('/forwarders/<int:forwarder_id>', methods=['DELETE'])
+@admin_required
+def remove_forwarder(forwarder_id):
+ result = MailService.remove_forwarder(forwarder_id)
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Failed to remove forwarder')}), 400
+ return jsonify(result), 200
+
+
+# ── Queue ──
+
+@mail_bp.route('/queue', methods=['GET'])
+@viewer_required
+def get_queue():
+ """Outbound queue messages from the Stalwart admin API (best-effort)."""
+ guard = _installed_or_error()
+ if guard:
+ return guard
+ result = StalwartService.list_queue()
+ return jsonify({'messages': result.get('messages', []),
+ 'note': result.get('note')}), 200
+
+
+@mail_bp.route('/queue/flush', methods=['POST'])
+@admin_required
+def flush_queue():
+ """Ask Stalwart to retry/flush the outbound queue (best-effort)."""
+ guard = _installed_or_error()
+ if guard:
+ return guard
+ result = StalwartService.flush_queue()
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Queue flush failed')}), 400
+ return jsonify(result), 200
diff --git a/builtin-extensions/serverkit-mail/backend/mail_backup.py b/builtin-extensions/serverkit-mail/backend/mail_backup.py
new file mode 100644
index 00000000..73cc0bdb
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/mail_backup.py
@@ -0,0 +1,58 @@
+"""Register the mail data directory as a backup policy (serverkit-mail extension).
+
+Thin, best-effort binder over the core :class:`BackupPolicyService`: a mail
+domain's maildir lives under the Stalwart data dir, so we register that path as a
+``files`` backup target with a daily schedule. Everything is wrapped so a missing
+BackupPolicyService (or a dev shell without the job bus) is non-fatal.
+"""
+import logging
+
+from .stalwart_service import DATA_DIR
+
+logger = logging.getLogger(__name__)
+
+
+def register_backup_policy(domain_row):
+ """Register/enable a daily files backup of the mail data dir for *domain_row*.
+
+ Best-effort: returns ``{success, ...}`` and never raises.
+ """
+ try:
+ from app.services.backup_policy_service import BackupPolicyService
+ except Exception as e: # noqa: BLE001
+ logger.debug('BackupPolicyService unavailable, skipping mail backup: %s', e)
+ return {'success': False, 'skipped': True, 'error': str(e)}
+ try:
+ policy = BackupPolicyService.get_or_create_policy(
+ target_type='files',
+ target_id=domain_row.id,
+ target_subtype='pathlist',
+ target_meta={'label': f'mail:{domain_row.name}', 'paths': [DATA_DIR]},
+ )
+ BackupPolicyService.update_policy(policy, {
+ 'enabled': True,
+ 'schedule_cron': '0 3 * * *', # daily at 03:00
+ })
+ return {'success': True, 'policy_id': policy.id}
+ except Exception as e: # noqa: BLE001
+ logger.warning('Could not register mail backup policy for %s: %s',
+ getattr(domain_row, 'name', '?'), e)
+ return {'success': False, 'error': str(e)}
+
+
+def unregister_backup_policy(domain_row):
+ """Disable the mail backup policy for *domain_row*. Best-effort; never raises.
+
+ The policy row (and its history) is intentionally left in place — only the
+ schedule is disabled — so a re-added domain keeps its backup lineage.
+ """
+ try:
+ from app.services.backup_policy_service import BackupPolicyService
+ policy = BackupPolicyService.get_policy('files', domain_row.id)
+ if not policy:
+ return {'success': True, 'skipped': True}
+ BackupPolicyService.update_policy(policy, {'enabled': False})
+ return {'success': True, 'policy_id': policy.id}
+ except Exception as e: # noqa: BLE001
+ logger.debug('Could not unregister mail backup policy: %s', e)
+ return {'success': False, 'error': str(e)}
diff --git a/builtin-extensions/serverkit-mail/backend/mail_jail_service.py b/builtin-extensions/serverkit-mail/backend/mail_jail_service.py
new file mode 100644
index 00000000..84b43c5a
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/mail_jail_service.py
@@ -0,0 +1,165 @@
+"""Fail2ban brute-force jails for the mail server (serverkit-mail extension).
+
+Mirrors the core :class:`Fail2banJailService` write-half pattern: ServerKit-owned
+``serverkit-mail-*`` jail files under ``/etc/fail2ban/jail.d``, written with
+privilege (``sudo tee``), reloaded via ``fail2ban-client reload``.
+
+The auth jail watches the mail auth log for repeated SMTP/IMAP login failures and
+bans the offending IP. Best-effort and Linux-only: on Windows (dev) or when
+fail2ban is absent, every mutating call returns a ``skipped`` descriptor instead
+of raising, so mail setup degrades gracefully.
+"""
+import logging
+import os
+
+from app.utils.system import run_privileged, is_command_available, ServiceControl
+
+logger = logging.getLogger(__name__)
+
+
+class MailJailService:
+ JAIL_DIR = '/etc/fail2ban/jail.d'
+ JAIL_PREFIX = 'serverkit-mail-'
+ AUTH_JAIL = 'serverkit-mail-auth'
+
+ # 5 auth failures within 10 min -> 1 hour ban.
+ MAXRETRY = 5
+ FINDTIME = 600
+ BANTIME = 3600
+
+ # Stalwart writes its log inside the container data dir bind-mounted to the
+ # host; fall back to the common dovecot/postfix filters if present. The jail
+ # uses the stock filters so it works without a custom filter file.
+ LOG_PATH = '/var/serverkit/mail/logs/stalwart.log'
+
+ JAIL_TEMPLATE = '''# ServerKit-managed mail brute-force jail.
+# Generated by MailJailService - do not edit by hand (regenerated on change).
+[{jail}]
+enabled = true
+filter = {filter}
+port = smtp,submission,smtps,imap,imaps,pop3,pop3s
+logpath = {logpath}
+maxretry = {maxretry}
+findtime = {findtime}
+bantime = {bantime}
+'''
+
+ # ---------- availability ----------
+
+ @classmethod
+ def available(cls):
+ """True only on a Linux host where the fail2ban client is installed."""
+ if os.name == 'nt':
+ return False
+ return is_command_available('fail2ban-client')
+
+ @staticmethod
+ def _unavailable():
+ return {
+ 'success': True, 'skipped': True, 'available': False, 'reason': 'unavailable',
+ 'message': 'fail2ban is not available on this host; mail brute-force '
+ 'protection is inactive.',
+ }
+
+ # ---------- file helpers ----------
+
+ @classmethod
+ def _jail_path(cls):
+ filename = f'{cls.AUTH_JAIL}.conf'
+ if (not filename.startswith(cls.JAIL_PREFIX)
+ or '/' in filename or '\\' in filename or '..' in filename):
+ raise ValueError(f'refusing to target non-ServerKit jail file: {filename!r}')
+ return os.path.join(cls.JAIL_DIR, filename)
+
+ @staticmethod
+ def _write_file(path, content):
+ """Write *content* to *path* with privilege (sudo tee)."""
+ try:
+ proc = run_privileged(['tee', path], input=content)
+ if getattr(proc, 'returncode', 1) != 0:
+ return {'success': False, 'error': (getattr(proc, 'stderr', '') or 'write failed').strip()}
+ return {'success': True, 'path': path}
+ except Exception as e: # noqa: BLE001
+ return {'success': False, 'error': str(e)}
+
+ @classmethod
+ def _render_jail(cls):
+ return cls.JAIL_TEMPLATE.format(
+ jail=cls.AUTH_JAIL,
+ filter='postfix-sasl', # stock filter; broadly present on Debian/RHEL
+ logpath=cls.LOG_PATH,
+ maxretry=cls.MAXRETRY,
+ findtime=cls.FINDTIME,
+ bantime=cls.BANTIME,
+ )
+
+ # ---------- jail lifecycle ----------
+
+ @classmethod
+ def enable_auth_jail(cls):
+ """Create/refresh the mail auth brute-force jail and reload fail2ban."""
+ if not cls.available():
+ return cls._unavailable()
+ try:
+ path = cls._jail_path()
+ except ValueError as e:
+ return {'success': False, 'error': str(e)}
+ written = cls._write_file(path, cls._render_jail())
+ if not written.get('success'):
+ return written
+ reloaded = cls.reload()
+ return {'success': True, 'enabled': True, 'jail': cls.AUTH_JAIL,
+ 'path': path, 'reloaded': reloaded.get('success')}
+
+ @classmethod
+ def disable_auth_jail(cls):
+ """Remove the mail auth jail file and reload fail2ban. No-op when absent."""
+ if not cls.available():
+ return cls._unavailable()
+ try:
+ path = cls._jail_path()
+ except ValueError as e:
+ return {'success': False, 'error': str(e)}
+ if not os.path.exists(path):
+ return {'success': True, 'removed': False, 'message': 'no jail to remove'}
+ try:
+ proc = run_privileged(['rm', '-f', path])
+ if getattr(proc, 'returncode', 1) != 0:
+ return {'success': False, 'error': (getattr(proc, 'stderr', '') or 'remove failed').strip()}
+ except Exception as e: # noqa: BLE001
+ return {'success': False, 'error': str(e)}
+ reloaded = cls.reload()
+ return {'success': True, 'removed': True, 'jail': cls.AUTH_JAIL,
+ 'reloaded': reloaded.get('success')}
+
+ @classmethod
+ def reload(cls):
+ """``fail2ban-client reload`` (keeps existing bans), falling back to a
+ service restart if the client call fails. Never raises."""
+ if not cls.available():
+ return cls._unavailable()
+ try:
+ proc = run_privileged(['fail2ban-client', 'reload'], timeout=30)
+ if getattr(proc, 'returncode', 1) == 0:
+ return {'success': True, 'message': 'fail2ban reloaded'}
+ except Exception:
+ pass
+ try:
+ res = ServiceControl.restart('fail2ban', timeout=30)
+ return {'success': getattr(res, 'returncode', 1) == 0,
+ 'message': 'fail2ban restarted' if getattr(res, 'returncode', 1) == 0
+ else (getattr(res, 'stderr', '') or 'reload failed')}
+ except Exception as e: # noqa: BLE001
+ return {'success': False, 'error': str(e)}
+
+ @classmethod
+ def status(cls):
+ """Availability + whether the auth jail file exists."""
+ info = {'available': cls.available(), 'enabled': False, 'jail': cls.AUTH_JAIL}
+ if not cls.available():
+ return info
+ try:
+ info['enabled'] = os.path.exists(cls._jail_path())
+ except ValueError:
+ info['enabled'] = False
+ return info
diff --git a/builtin-extensions/serverkit-mail/backend/mail_service.py b/builtin-extensions/serverkit-mail/backend/mail_service.py
new file mode 100644
index 00000000..dc0bc4a7
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/mail_service.py
@@ -0,0 +1,442 @@
+"""DB <-> Stalwart orchestration (serverkit-mail extension).
+
+The panel's tables (:mod:`.models`) are the source of truth for what mail objects
+*should* exist; this service is the reconcile layer. Every mutation:
+
+1. Writes the panel DB (this always succeeds, or returns a clean 400).
+2. Best-effort reconciles the change to Stalwart via :class:`StalwartService`.
+3. Records the outcome on the row's ``sync_state`` / ``sync_error``.
+
+A Stalwart failure therefore never loses panel state: the row exists with
+``sync_state='error'`` and the call returns ``{success: True, sync_state:
+'error', ...}`` so the panel can surface and later re-sync the drift. Everything
+is wrapped so a missing Stalwart/Docker (dev) never raises.
+
+Activation gate: :meth:`set_domain_active` refuses to activate a domain (which
+enables outbound sending) unless the latest :class:`PreflightResult` passed, or an
+explicit ``force=True`` override is passed (which is audit-logged).
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class MailService:
+ """Stateless DB/Stalwart reconcile orchestration."""
+
+ # ---------- helpers ----------
+
+ @staticmethod
+ def _db():
+ from app import db
+ return db
+
+ @staticmethod
+ def _models():
+ from . import models
+ return models
+
+ @staticmethod
+ def _stalwart():
+ from .stalwart_service import StalwartService
+ return StalwartService
+
+ @classmethod
+ def _apply_sync(cls, row, result):
+ """Fold a StalwartService reconcile *result* into a row's sync state."""
+ if result.get('success'):
+ row.sync_state = 'synced'
+ row.sync_error = None
+ else:
+ row.sync_state = 'error'
+ row.sync_error = result.get('error') or 'Stalwart sync failed'
+ return row
+
+ @staticmethod
+ def _norm(value):
+ return (value or '').strip().lower().rstrip('.')
+
+ # ---------- status ----------
+
+ @classmethod
+ def get_status(cls):
+ """Engine status merged with the latest deliverability preflight."""
+ status = cls._stalwart().get_status()
+ try:
+ from .preflight_service import PreflightService
+ status['preflight'] = PreflightService.latest()
+ except Exception as e: # noqa: BLE001
+ logger.debug('preflight latest failed: %s', e)
+ status['preflight'] = None
+ try:
+ from .models import MailDomain
+ status['domains_count'] = MailDomain.query.count()
+ except Exception: # noqa: BLE001
+ status['domains_count'] = 0
+ return status
+
+ # ---------- domains ----------
+
+ @classmethod
+ def list_domains(cls):
+ MailDomain = cls._models().MailDomain
+ return [d.to_dict() for d in MailDomain.query.order_by(MailDomain.name).all()]
+
+ @classmethod
+ def get_domain(cls, domain_id):
+ MailDomain = cls._models().MailDomain
+ row = MailDomain.query.get(domain_id)
+ return row.to_dict() if row else None
+
+ @classmethod
+ def add_domain(cls, name, catch_all_target=None):
+ db = cls._db()
+ MailDomain = cls._models().MailDomain
+ name = cls._norm(name)
+ if not name or '.' not in name:
+ return {'success': False, 'error': f'Invalid domain name: {name!r}'}
+ if MailDomain.query.filter_by(name=name).first():
+ return {'success': False, 'error': f'Domain {name} already exists'}
+ row = MailDomain(name=name,
+ catch_all_target=(catch_all_target or '').strip() or None,
+ is_active=False, sync_state='pending')
+ try:
+ db.session.add(row)
+ db.session.commit()
+ except Exception as e: # noqa: BLE001
+ db.session.rollback()
+ return {'success': False, 'error': str(e)}
+
+ result = cls._safe(lambda: cls._stalwart().upsert_domain(name))
+ cls._apply_sync(row, result)
+ db.session.commit()
+ return {'success': True, 'domain': row.to_dict(),
+ 'sync_state': row.sync_state, 'sync_error': row.sync_error}
+
+ @classmethod
+ def update_domain(cls, domain_id, is_active=None, catch_all_target=None):
+ """Update mutable domain fields (catch-all + activation).
+
+ Activation is delegated to :meth:`set_domain_active` so the preflight
+ gate cannot be bypassed here.
+ """
+ db = cls._db()
+ MailDomain = cls._models().MailDomain
+ row = MailDomain.query.get(domain_id)
+ if not row:
+ return {'success': False, 'error': 'Domain not found'}
+
+ if catch_all_target is not None:
+ row.catch_all_target = (catch_all_target or '').strip() or None
+ db.session.commit()
+
+ if is_active is not None:
+ return cls.set_domain_active(domain_id, bool(is_active))
+
+ return {'success': True, 'domain': row.to_dict()}
+
+ @classmethod
+ def set_domain_active(cls, domain_id, active, force=False):
+ """Activate/deactivate a domain. Activation enables outbound sending and
+ is **gated** on the latest preflight passing, unless ``force=True`` (which
+ is audit-logged)."""
+ db = cls._db()
+ MailDomain = cls._models().MailDomain
+ row = MailDomain.query.get(domain_id)
+ if not row:
+ return {'success': False, 'error': 'Domain not found'}
+
+ if active:
+ from .preflight_service import PreflightService
+ latest = None
+ try:
+ latest = PreflightService.latest()
+ except Exception as e: # noqa: BLE001
+ logger.debug('preflight check failed during activation: %s', e)
+ passed = bool(latest and latest.get('passed'))
+ if not passed and not force:
+ return {'success': False, 'code': 'preflight_required',
+ 'error': 'Deliverability preflight has not passed. Run '
+ 'preflight and resolve any failures, or activate '
+ 'with force to override.',
+ 'preflight': latest}
+ if not passed and force:
+ cls._audit('mail.domain.activate_forced', row.id, {
+ 'domain': row.name,
+ 'preflight_passed': passed,
+ })
+
+ row.is_active = bool(active)
+ db.session.commit()
+
+ # Reconcile: ensure the domain principal exists when activating.
+ if active:
+ result = cls._safe(lambda: cls._stalwart().upsert_domain(row.name))
+ cls._apply_sync(row, result)
+ db.session.commit()
+
+ return {'success': True, 'domain': row.to_dict(),
+ 'sync_state': row.sync_state, 'sync_error': row.sync_error}
+
+ @classmethod
+ def remove_domain(cls, domain_id):
+ db = cls._db()
+ MailDomain = cls._models().MailDomain
+ row = MailDomain.query.get(domain_id)
+ if not row:
+ return {'success': False, 'error': 'Domain not found'}
+ name = row.name
+ # Best-effort Stalwart cleanup before the DB delete (cascade removes
+ # mailboxes/forwarders/autoresponders panel-side).
+ cls._safe(lambda: cls._stalwart().delete_domain(name))
+ try:
+ from .mail_backup import unregister_backup_policy
+ unregister_backup_policy(row)
+ except Exception as e: # noqa: BLE001
+ logger.debug('backup unregister failed: %s', e)
+ try:
+ db.session.delete(row)
+ db.session.commit()
+ except Exception as e: # noqa: BLE001
+ db.session.rollback()
+ return {'success': False, 'error': str(e)}
+ return {'success': True, 'message': f'Domain {name} removed'}
+
+ # ---------- mailboxes ----------
+
+ @classmethod
+ def list_mailboxes(cls, domain_id):
+ Mailbox = cls._models().Mailbox
+ rows = Mailbox.query.filter_by(domain_id=domain_id).order_by(Mailbox.local_part).all()
+ return [m.to_dict() for m in rows]
+
+ @classmethod
+ def get_mailbox(cls, mailbox_id):
+ Mailbox = cls._models().Mailbox
+ row = Mailbox.query.get(mailbox_id)
+ return row.to_dict() if row else None
+
+ @classmethod
+ def add_mailbox(cls, domain_id, local_part, password, quota_mb=0, display_name=None):
+ """Create a mailbox. ``password`` is required (set on Stalwart only) and is
+ NEVER persisted panel-side."""
+ db = cls._db()
+ models = cls._models()
+ MailDomain, Mailbox = models.MailDomain, models.Mailbox
+ domain = MailDomain.query.get(domain_id)
+ if not domain:
+ return {'success': False, 'error': 'Domain not found'}
+ local_part = (local_part or '').strip().lower()
+ if not local_part or '@' in local_part:
+ return {'success': False, 'error': f'Invalid local part: {local_part!r}'}
+ if not password:
+ return {'success': False, 'error': 'A password is required'}
+ if Mailbox.query.filter_by(domain_id=domain_id, local_part=local_part).first():
+ return {'success': False,
+ 'error': f'Mailbox {local_part}@{domain.name} already exists'}
+
+ row = Mailbox(domain_id=domain_id, local_part=local_part,
+ quota_mb=int(quota_mb or 0),
+ display_name=(display_name or '').strip() or None,
+ is_active=True, sync_state='pending')
+ try:
+ db.session.add(row)
+ db.session.commit()
+ except Exception as e: # noqa: BLE001
+ db.session.rollback()
+ return {'success': False, 'error': str(e)}
+
+ email = f'{local_part}@{domain.name}'
+ result = cls._safe(lambda: cls._stalwart().upsert_account(
+ email, password=password, quota_mb=row.quota_mb, display_name=row.display_name))
+ cls._apply_sync(row, result)
+ db.session.commit()
+ # password intentionally discarded here — never stored.
+ return {'success': True, 'mailbox': row.to_dict(),
+ 'sync_state': row.sync_state, 'sync_error': row.sync_error}
+
+ @classmethod
+ def update_mailbox(cls, mailbox_id, quota_mb=None, is_active=None, display_name=None):
+ db = cls._db()
+ Mailbox = cls._models().Mailbox
+ row = Mailbox.query.get(mailbox_id)
+ if not row:
+ return {'success': False, 'error': 'Mailbox not found'}
+ if quota_mb is not None:
+ row.quota_mb = int(quota_mb)
+ if display_name is not None:
+ row.display_name = (display_name or '').strip() or None
+ if is_active is not None:
+ row.is_active = bool(is_active)
+ db.session.commit()
+
+ result = cls._safe(lambda: cls._stalwart().upsert_account(
+ row.email, quota_mb=row.quota_mb, display_name=row.display_name))
+ cls._apply_sync(row, result)
+ db.session.commit()
+ return {'success': True, 'mailbox': row.to_dict(),
+ 'sync_state': row.sync_state, 'sync_error': row.sync_error}
+
+ @classmethod
+ def set_mailbox_password(cls, mailbox_id, password):
+ db = cls._db()
+ Mailbox = cls._models().Mailbox
+ row = Mailbox.query.get(mailbox_id)
+ if not row:
+ return {'success': False, 'error': 'Mailbox not found'}
+ if not password:
+ return {'success': False, 'error': 'A password is required'}
+ result = cls._safe(lambda: cls._stalwart().set_password(row.email, password))
+ cls._apply_sync(row, result)
+ db.session.commit()
+ return {'success': True, 'sync_state': row.sync_state,
+ 'sync_error': row.sync_error}
+
+ @classmethod
+ def remove_mailbox(cls, mailbox_id):
+ db = cls._db()
+ Mailbox = cls._models().Mailbox
+ row = Mailbox.query.get(mailbox_id)
+ if not row:
+ return {'success': False, 'error': 'Mailbox not found'}
+ email = row.email
+ cls._safe(lambda: cls._stalwart().delete_account(email))
+ try:
+ db.session.delete(row)
+ db.session.commit()
+ except Exception as e: # noqa: BLE001
+ db.session.rollback()
+ return {'success': False, 'error': str(e)}
+ return {'success': True, 'message': f'Mailbox {email} removed'}
+
+ # ---------- autoresponder ----------
+
+ @classmethod
+ def get_autoresponder(cls, mailbox_id):
+ models = cls._models()
+ Mailbox, Autoresponder = models.Mailbox, models.Autoresponder
+ if not Mailbox.query.get(mailbox_id):
+ return None
+ row = Autoresponder.query.filter_by(mailbox_id=mailbox_id).first()
+ if row:
+ return row.to_dict()
+ # A not-yet-configured autoresponder reads as a disabled shell.
+ return {'mailbox_id': mailbox_id, 'enabled': False, 'subject': None,
+ 'body': None, 'start_at': None, 'end_at': None}
+
+ @classmethod
+ def set_autoresponder(cls, mailbox_id, enabled=None, subject=None, body=None,
+ start_at=None, end_at=None):
+ db = cls._db()
+ models = cls._models()
+ Mailbox, Autoresponder = models.Mailbox, models.Autoresponder
+ if not Mailbox.query.get(mailbox_id):
+ return {'success': False, 'error': 'Mailbox not found'}
+ row = Autoresponder.query.filter_by(mailbox_id=mailbox_id).first()
+ if not row:
+ row = Autoresponder(mailbox_id=mailbox_id)
+ db.session.add(row)
+ if enabled is not None:
+ row.enabled = bool(enabled)
+ if subject is not None:
+ row.subject = subject
+ if body is not None:
+ row.body = body
+ if start_at is not None:
+ row.start_at = cls._parse_dt(start_at)
+ if end_at is not None:
+ row.end_at = cls._parse_dt(end_at)
+ try:
+ db.session.commit()
+ except Exception as e: # noqa: BLE001
+ db.session.rollback()
+ return {'success': False, 'error': str(e)}
+ return {'success': True, 'autoresponder': row.to_dict()}
+
+ @staticmethod
+ def _parse_dt(value):
+ if not value:
+ return None
+ if hasattr(value, 'isoformat'):
+ return value
+ from datetime import datetime
+ try:
+ return datetime.fromisoformat(str(value).replace('Z', '+00:00'))
+ except (ValueError, TypeError):
+ return None
+
+ # ---------- forwarders ----------
+
+ @classmethod
+ def list_forwarders(cls, domain_id):
+ Forwarder = cls._models().Forwarder
+ rows = Forwarder.query.filter_by(domain_id=domain_id).order_by(
+ Forwarder.source_local_part).all()
+ return [f.to_dict() for f in rows]
+
+ @classmethod
+ def add_forwarder(cls, domain_id, source_local_part, destination, keep_copy=False):
+ db = cls._db()
+ models = cls._models()
+ MailDomain, Forwarder = models.MailDomain, models.Forwarder
+ domain = MailDomain.query.get(domain_id)
+ if not domain:
+ return {'success': False, 'error': 'Domain not found'}
+ source_local_part = (source_local_part or '').strip().lower()
+ destination = (destination or '').strip()
+ if not source_local_part or '@' in source_local_part:
+ return {'success': False, 'error': f'Invalid source: {source_local_part!r}'}
+ if not destination:
+ return {'success': False, 'error': 'A destination is required'}
+ row = Forwarder(domain_id=domain_id, source_local_part=source_local_part,
+ destination=destination, keep_copy=bool(keep_copy),
+ is_active=True, sync_state='pending')
+ try:
+ db.session.add(row)
+ db.session.commit()
+ except Exception as e: # noqa: BLE001
+ db.session.rollback()
+ return {'success': False, 'error': str(e)}
+
+ # Forwarders map to an aliased principal on Stalwart; reconcile best-effort.
+ email = f'{source_local_part}@{domain.name}'
+ result = cls._safe(lambda: cls._stalwart().upsert_account(email))
+ cls._apply_sync(row, result)
+ db.session.commit()
+ return {'success': True, 'forwarder': row.to_dict(),
+ 'sync_state': row.sync_state, 'sync_error': row.sync_error}
+
+ @classmethod
+ def remove_forwarder(cls, forwarder_id):
+ db = cls._db()
+ Forwarder = cls._models().Forwarder
+ row = Forwarder.query.get(forwarder_id)
+ if not row:
+ return {'success': False, 'error': 'Forwarder not found'}
+ try:
+ db.session.delete(row)
+ db.session.commit()
+ except Exception as e: # noqa: BLE001
+ db.session.rollback()
+ return {'success': False, 'error': str(e)}
+ return {'success': True, 'message': 'Forwarder removed'}
+
+ # ---------- internals ----------
+
+ @staticmethod
+ def _safe(fn):
+ """Run a best-effort Stalwart reconcile call; never raise."""
+ try:
+ result = fn()
+ return result if isinstance(result, dict) else {'success': bool(result)}
+ except Exception as e: # noqa: BLE001
+ logger.debug('Stalwart reconcile call failed: %s', e)
+ return {'success': False, 'error': str(e)}
+
+ @staticmethod
+ def _audit(action, target_id, details):
+ try:
+ from app.plugins_sdk import audit
+ audit(action, 'mail_domain', target_id=target_id, details=details)
+ except Exception as e: # noqa: BLE001
+ logger.debug('audit %s failed: %s', action, e)
diff --git a/builtin-extensions/serverkit-mail/backend/models.py b/builtin-extensions/serverkit-mail/backend/models.py
new file mode 100644
index 00000000..f03cbb87
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/models.py
@@ -0,0 +1,269 @@
+"""Data models for the serverkit-mail extension.
+
+These tables are the panel-side **source of truth** for what mail objects
+*should* exist; :class:`StalwartService` reconciles them to the running Stalwart
+engine best-effort and each row records its own ``sync_state`` / ``sync_error``
+so a Stalwart API failure never corrupts panel state (the row simply reports
+drift).
+
+Tables are namespaced ``ext_serverkit_mail_*`` (dash → underscore) per the
+extension convention, so ``purge_models`` on uninstall drops exactly these.
+
+Registration: importing this module defines the tables on the shared metadata as
+a side effect; the manifest's ``models: "models:register"`` then calls
+:func:`register` (a no-op passthrough) and the platform runs ``db.create_all()``.
+
+Security: mailbox passwords are **never** persisted here — they live only on the
+Stalwart engine. There is no password column on :class:`Mailbox`.
+"""
+from datetime import datetime
+
+from app import db
+
+
+class MailDomain(db.Model):
+ __tablename__ = 'ext_serverkit_mail_domains'
+
+ id = db.Column(db.Integer, primary_key=True)
+ name = db.Column(db.String(255), unique=True, nullable=False, index=True)
+ is_active = db.Column(db.Boolean, default=False)
+ catch_all_target = db.Column(db.String(255), nullable=True)
+
+ # DKIM
+ dkim_selector = db.Column(db.String(63), default='serverkit')
+ dkim_private_key = db.Column(db.Text, nullable=True)
+ dkim_public_key = db.Column(db.Text, nullable=True)
+
+ # DNS deployment ledger
+ dns_deployed = db.Column(db.Boolean, default=False)
+ dns_last_result = db.Column(db.Text, nullable=True) # JSON string
+
+ # Reconcile state against the Stalwart engine
+ sync_state = db.Column(db.String(20), default='pending') # pending|synced|error
+ sync_error = db.Column(db.Text, nullable=True)
+
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+ mailboxes = db.relationship('Mailbox', backref='domain', lazy=True,
+ cascade='all, delete-orphan')
+ forwarders = db.relationship('Forwarder', backref='domain', lazy=True,
+ cascade='all, delete-orphan')
+
+ def to_dict(self):
+ import json
+ dns_result = None
+ if self.dns_last_result:
+ try:
+ dns_result = json.loads(self.dns_last_result)
+ except (ValueError, TypeError):
+ dns_result = None
+ return {
+ 'id': self.id,
+ 'name': self.name,
+ 'is_active': bool(self.is_active),
+ 'catch_all_target': self.catch_all_target,
+ 'dkim_selector': self.dkim_selector,
+ 'dkim_public_key': self.dkim_public_key,
+ 'dkim_configured': bool(self.dkim_private_key),
+ 'dns_deployed': bool(self.dns_deployed),
+ 'dns_last_result': dns_result,
+ 'sync_state': self.sync_state,
+ 'sync_error': self.sync_error,
+ 'mailboxes_count': len(self.mailboxes) if self.mailboxes else 0,
+ 'forwarders_count': len(self.forwarders) if self.forwarders else 0,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ }
+
+ def __repr__(self):
+ return f'<MailDomain {self.name}>'
+
+
+class Mailbox(db.Model):
+ __tablename__ = 'ext_serverkit_mail_mailboxes'
+ __table_args__ = (
+ db.UniqueConstraint('domain_id', 'local_part', name='uq_mail_mailbox_local'),
+ )
+
+ id = db.Column(db.Integer, primary_key=True)
+ domain_id = db.Column(db.Integer,
+ db.ForeignKey('ext_serverkit_mail_domains.id'),
+ nullable=False, index=True)
+ local_part = db.Column(db.String(255), nullable=False)
+ quota_mb = db.Column(db.Integer, default=0) # 0 == unlimited
+ is_active = db.Column(db.Boolean, default=True)
+ display_name = db.Column(db.String(255), nullable=True)
+
+ # NO password column — passwords live only on Stalwart, never persisted.
+ sync_state = db.Column(db.String(20), default='pending')
+ sync_error = db.Column(db.Text, nullable=True)
+
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+ autoresponder = db.relationship('Autoresponder', backref='mailbox', uselist=False,
+ lazy=True, cascade='all, delete-orphan')
+
+ @property
+ def email(self):
+ return f'{self.local_part}@{self.domain.name}' if self.domain else self.local_part
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'domain_id': self.domain_id,
+ 'domain_name': self.domain.name if self.domain else None,
+ 'local_part': self.local_part,
+ 'email': self.email,
+ 'quota_mb': self.quota_mb,
+ 'is_active': bool(self.is_active),
+ 'display_name': self.display_name,
+ 'sync_state': self.sync_state,
+ 'sync_error': self.sync_error,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ }
+
+ def __repr__(self):
+ return f'<Mailbox {self.email}>'
+
+
+class Forwarder(db.Model):
+ __tablename__ = 'ext_serverkit_mail_forwarders'
+
+ id = db.Column(db.Integer, primary_key=True)
+ domain_id = db.Column(db.Integer,
+ db.ForeignKey('ext_serverkit_mail_domains.id'),
+ nullable=False, index=True)
+ source_local_part = db.Column(db.String(255), nullable=False)
+ destination = db.Column(db.Text, nullable=False) # may be an external address
+ keep_copy = db.Column(db.Boolean, default=False)
+ is_active = db.Column(db.Boolean, default=True)
+
+ sync_state = db.Column(db.String(20), default='pending')
+ sync_error = db.Column(db.Text, nullable=True)
+
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+ @property
+ def source(self):
+ return f'{self.source_local_part}@{self.domain.name}' if self.domain else self.source_local_part
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'domain_id': self.domain_id,
+ 'domain_name': self.domain.name if self.domain else None,
+ 'source_local_part': self.source_local_part,
+ 'source': self.source,
+ 'destination': self.destination,
+ 'keep_copy': bool(self.keep_copy),
+ 'is_active': bool(self.is_active),
+ 'sync_state': self.sync_state,
+ 'sync_error': self.sync_error,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ }
+
+ def __repr__(self):
+ return f'<Forwarder {self.source} -> {self.destination}>'
+
+
+class Autoresponder(db.Model):
+ __tablename__ = 'ext_serverkit_mail_autoresponders'
+
+ id = db.Column(db.Integer, primary_key=True)
+ mailbox_id = db.Column(db.Integer,
+ db.ForeignKey('ext_serverkit_mail_mailboxes.id'),
+ nullable=False, unique=True, index=True)
+ enabled = db.Column(db.Boolean, default=False)
+ subject = db.Column(db.String(500), nullable=True)
+ body = db.Column(db.Text, nullable=True)
+ start_at = db.Column(db.DateTime, nullable=True)
+ end_at = db.Column(db.DateTime, nullable=True)
+
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'mailbox_id': self.mailbox_id,
+ 'enabled': bool(self.enabled),
+ 'subject': self.subject,
+ 'body': self.body,
+ 'start_at': self.start_at.isoformat() if self.start_at else None,
+ 'end_at': self.end_at.isoformat() if self.end_at else None,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ }
+
+ def __repr__(self):
+ return f'<Autoresponder mailbox={self.mailbox_id} enabled={self.enabled}>'
+
+
+class PreflightResult(db.Model):
+ __tablename__ = 'ext_serverkit_mail_preflight'
+
+ id = db.Column(db.Integer, primary_key=True)
+ hostname = db.Column(db.String(255), nullable=True, index=True)
+ server_ip = db.Column(db.String(64), nullable=True)
+
+ ptr_ok = db.Column(db.Boolean, default=False)
+ ptr_value = db.Column(db.String(255), nullable=True)
+ port25_ok = db.Column(db.Boolean, default=False)
+ rbl_ok = db.Column(db.Boolean, default=False)
+ rbl_hits = db.Column(db.Text, nullable=True) # JSON list
+ ports_ok = db.Column(db.Boolean, default=False)
+
+ passed = db.Column(db.Boolean, default=False)
+ detail = db.Column(db.Text, nullable=True) # JSON object
+
+ checked_at = db.Column(db.DateTime, default=datetime.utcnow, index=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+ def to_dict(self):
+ import json
+ rbl_hits = []
+ if self.rbl_hits:
+ try:
+ rbl_hits = json.loads(self.rbl_hits)
+ except (ValueError, TypeError):
+ rbl_hits = []
+ detail = None
+ if self.detail:
+ try:
+ detail = json.loads(self.detail)
+ except (ValueError, TypeError):
+ detail = None
+ return {
+ 'id': self.id,
+ 'hostname': self.hostname,
+ 'server_ip': self.server_ip,
+ 'ptr_ok': bool(self.ptr_ok),
+ 'ptr_value': self.ptr_value,
+ 'port25_ok': bool(self.port25_ok),
+ 'rbl_ok': bool(self.rbl_ok),
+ 'rbl_hits': rbl_hits,
+ 'ports_ok': bool(self.ports_ok),
+ 'passed': bool(self.passed),
+ 'detail': detail,
+ 'checked_at': self.checked_at.isoformat() if self.checked_at else None,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ }
+
+ def __repr__(self):
+ return f'<PreflightResult {self.hostname} passed={self.passed}>'
+
+
+def register(db): # noqa: A002 — signature dictated by the platform (fn(db))
+ """No-op passthrough required by the manifest ``models: "models:register"``.
+
+ Importing this module already registered the tables on the metadata; the
+ platform calls this then runs ``db.create_all()``. Returns ``None``.
+ """
+ return None
diff --git a/builtin-extensions/serverkit-mail/backend/preflight_service.py b/builtin-extensions/serverkit-mail/backend/preflight_service.py
new file mode 100644
index 00000000..037cd23e
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/preflight_service.py
@@ -0,0 +1,236 @@
+"""Deliverability preflight checks (serverkit-mail extension).
+
+Running a mail server that the world will *accept* mail from has hard host
+prerequisites that a panel cannot fix for you. This service checks them and
+persists the verdict; :class:`MailService` refuses to activate outbound sending
+for a domain until the latest preflight ``passed`` (or an explicit force
+override is logged).
+
+Checks (all best-effort, individually monkeypatchable for tests):
+
+* **PTR / reverse DNS** — the server IP's PTR record must resolve back to the
+ mail hostname (``socket.gethostbyaddr``). Mismatched PTR is the #1 reason big
+ providers reject mail.
+* **Port-25 egress** — many VPS providers block outbound TCP :25. We try to open
+ a connection to a public MX on :25 with a short timeout.
+* **RBL / DNSBL** — query a couple of well-known blocklists for the reversed
+ server IP; any hit means the IP is listed.
+* **Local listening ports** — best-effort check that the mail ports are open
+ locally.
+
+On Windows / dev, every host-dependent check returns ``skipped`` and the overall
+verdict is ``passed=False`` with a clear note. Nothing here ever raises.
+"""
+import json
+import logging
+import os
+import socket
+
+logger = logging.getLogger(__name__)
+
+# A public MX we can dial on :25 to prove outbound egress is not blocked.
+PORT25_PROBE_HOST = 'gmail-smtp-in.l.google.com'
+PORT25_PROBE_PORT = 25
+PORT25_TIMEOUT = 6
+
+# DNSBLs queried for the reversed server IP.
+RBL_ZONES = ('zen.spamhaus.org', 'bl.spamcop.net')
+
+# Mail ports we expect to be listening locally once Stalwart is up.
+LOCAL_PORTS = (25, 465, 587, 993)
+
+
+class PreflightService:
+ """Stateless deliverability preflight runner."""
+
+ # ---------- individual checks (monkeypatchable) ----------
+
+ @staticmethod
+ def _check_ptr(hostname, server_ip):
+ """Reverse-DNS: does the server IP's PTR match *hostname*?
+
+ Returns ``(ok, ptr_value, note)``.
+ """
+ if os.name == 'nt':
+ return None, None, 'skipped (not supported on this OS)'
+ if not server_ip:
+ return None, None, 'skipped (no server IP provided)'
+ try:
+ ptr_value = socket.gethostbyaddr(server_ip)[0]
+ except (OSError, socket.herror) as e:
+ return False, None, f'PTR lookup failed: {e}'
+ ptr_norm = (ptr_value or '').strip().lower().rstrip('.')
+ host_norm = (hostname or '').strip().lower().rstrip('.')
+ ok = bool(host_norm) and ptr_norm == host_norm
+ note = None if ok else f'PTR {ptr_norm!r} does not match hostname {host_norm!r}'
+ return ok, ptr_value, note
+
+ @staticmethod
+ def _check_port25():
+ """Outbound TCP :25 egress test against a public MX.
+
+ Returns ``(ok, note)``.
+ """
+ if os.name == 'nt':
+ return None, 'skipped (not supported on this OS)'
+ try:
+ conn = socket.create_connection(
+ (PORT25_PROBE_HOST, PORT25_PROBE_PORT), timeout=PORT25_TIMEOUT)
+ conn.close()
+ return True, None
+ except OSError as e:
+ return False, (f'Could not open outbound :25 to {PORT25_PROBE_HOST} '
+ f'({e}) — your provider likely blocks port 25.')
+
+ @staticmethod
+ def _reverse_ip(server_ip):
+ """Return the reversed dotted-quad of an IPv4 address, or None."""
+ parts = (server_ip or '').split('.')
+ if len(parts) != 4 or not all(p.isdigit() and 0 <= int(p) <= 255 for p in parts):
+ return None
+ return '.'.join(reversed(parts))
+
+ @classmethod
+ def _check_rbl(cls, server_ip):
+ """Query the DNSBLs for the reversed server IP.
+
+ Returns ``(ok, hits, note)`` — ``ok`` is True when the IP is on no list.
+ """
+ if os.name == 'nt':
+ return None, [], 'skipped (not supported on this OS)'
+ if not server_ip:
+ return None, [], 'skipped (no server IP provided)'
+ reversed_ip = cls._reverse_ip(server_ip)
+ if not reversed_ip:
+ return None, [], 'skipped (non-IPv4 address)'
+ hits = []
+ checked = 0
+ for zone in RBL_ZONES:
+ query = f'{reversed_ip}.{zone}'
+ try:
+ socket.gethostbyname(query)
+ hits.append(zone) # a resolvable A record == listed
+ checked += 1
+ except socket.gaierror:
+ checked += 1 # NXDOMAIN == not listed (the good case)
+ except OSError:
+ continue # transient resolver error — don't count it
+ if checked == 0:
+ return None, [], 'skipped (RBL resolvers unreachable)'
+ ok = not hits
+ note = None if ok else f'Listed on: {", ".join(hits)}'
+ return ok, hits, note
+
+ @staticmethod
+ def _check_local_ports():
+ """Best-effort: are the mail ports listening on localhost?
+
+ Returns ``(ok, note)``. This is advisory only — a fresh install may not
+ be running yet — so it never drives the pass/fail verdict on its own.
+ """
+ if os.name == 'nt':
+ return None, 'skipped (not supported on this OS)'
+ open_ports = []
+ for port in LOCAL_PORTS:
+ try:
+ conn = socket.create_connection(('127.0.0.1', port), timeout=2)
+ conn.close()
+ open_ports.append(port)
+ except OSError:
+ continue
+ ok = bool(open_ports)
+ note = None if ok else 'No mail ports are listening locally yet.'
+ return ok, note
+
+ # ---------- orchestration ----------
+
+ @classmethod
+ def run(cls, hostname, server_ip=None):
+ """Run all checks, persist a :class:`PreflightResult`, and return its dict.
+
+ ``passed`` requires the *critical* checks (PTR, port-25 egress, RBL) to
+ pass. Skipped checks (Windows/dev, missing IP) count as not-passed so a
+ dev box never green-lights sending. Never raises.
+ """
+ hostname = (hostname or '').strip().lower().rstrip('.')
+
+ ptr_ok, ptr_value, ptr_note = cls._check_ptr(hostname, server_ip)
+ port25_ok, port25_note = cls._check_port25()
+ rbl_ok, rbl_hits, rbl_note = cls._check_rbl(server_ip)
+ ports_ok, ports_note = cls._check_local_ports()
+
+ # Critical checks must be explicitly True (None/skipped => not passed).
+ critical = [ptr_ok, port25_ok, rbl_ok]
+ passed = all(c is True for c in critical)
+
+ detail = {
+ 'ptr': {'ok': ptr_ok, 'value': ptr_value, 'note': ptr_note},
+ 'port25': {'ok': port25_ok, 'note': port25_note},
+ 'rbl': {'ok': rbl_ok, 'hits': rbl_hits, 'note': rbl_note},
+ 'ports': {'ok': ports_ok, 'note': ports_note},
+ 'critical_checks': ['ptr', 'port25', 'rbl'],
+ }
+ if os.name == 'nt':
+ detail['dev_note'] = ('Host-dependent checks are skipped on this OS; '
+ 'run preflight on the target server before sending.')
+
+ result = {
+ 'hostname': hostname,
+ 'server_ip': server_ip,
+ 'ptr_ok': bool(ptr_ok),
+ 'ptr_value': ptr_value,
+ 'port25_ok': bool(port25_ok),
+ 'rbl_ok': bool(rbl_ok),
+ 'rbl_hits': rbl_hits,
+ 'ports_ok': bool(ports_ok),
+ 'passed': passed,
+ 'detail': detail,
+ }
+ cls._persist(result)
+ # Return the freshly persisted row's dict (falls back to the raw result).
+ latest = cls.latest()
+ return latest or {**result, 'rbl_hits': rbl_hits, 'detail': detail}
+
+ @classmethod
+ def _persist(cls, result):
+ """Store a PreflightResult row. Best-effort; never raises."""
+ try:
+ from app import db
+ from .models import PreflightResult
+ row = PreflightResult(
+ hostname=result.get('hostname'),
+ server_ip=result.get('server_ip'),
+ ptr_ok=result.get('ptr_ok'),
+ ptr_value=result.get('ptr_value'),
+ port25_ok=result.get('port25_ok'),
+ rbl_ok=result.get('rbl_ok'),
+ rbl_hits=json.dumps(result.get('rbl_hits') or []),
+ ports_ok=result.get('ports_ok'),
+ passed=result.get('passed'),
+ detail=json.dumps(result.get('detail') or {}),
+ )
+ db.session.add(row)
+ db.session.commit()
+ return row
+ except Exception as e: # noqa: BLE001 — persistence is best-effort
+ logger.warning('Preflight result could not be persisted: %s', e)
+ try:
+ from app import db
+ db.session.rollback()
+ except Exception:
+ pass
+ return None
+
+ @classmethod
+ def latest(cls):
+ """Most recent PreflightResult as a dict, or None."""
+ try:
+ from .models import PreflightResult
+ row = (PreflightResult.query
+ .order_by(PreflightResult.checked_at.desc(),
+ PreflightResult.id.desc())
+ .first())
+ return row.to_dict() if row else None
+ except Exception as e: # noqa: BLE001
+ logger.debug('Could not load latest preflight: %s', e)
+ return None
diff --git a/builtin-extensions/serverkit-mail/backend/stalwart_service.py b/builtin-extensions/serverkit-mail/backend/stalwart_service.py
new file mode 100644
index 00000000..7436a7f2
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/backend/stalwart_service.py
@@ -0,0 +1,409 @@
+"""Stalwart mail-server engine service (serverkit-mail extension).
+
+Runs the Stalwart all-in-one mail server (SMTP/IMAP/JMAP/Sieve) in a managed
+Docker container so a ServerKit box can host mailboxes for its domains. Driven
+entirely through Stalwart's HTTP **admin API**, published on loopback only.
+
+Design mirrors the serverkit-dns-server extension exactly:
+
+* **Two choke-points** — every Docker invocation goes through :meth:`_docker`
+ (privilege escalation, timeouts, error shaping) and every admin-API call goes
+ through :meth:`_api` (HTTP Basic auth, JSON, error shaping). Nothing else
+ shells out or talks HTTP.
+* **Best-effort, Linux-only** — on Windows (dev) or when Docker is absent, calls
+ return a clean error dict instead of raising.
+* **Panel DB is the source of truth** — our tables describe what *should* exist;
+ the thin reconcile methods (:meth:`upsert_account`, :meth:`upsert_domain`, …)
+ push best-effort to Stalwart and **degrade gracefully**: a 404 / shape change
+ in the version-sensitive admin API returns ``{success: False, error}`` and
+ never raises, so :class:`MailService` can still record a row with
+ ``sync_state='error'``.
+* **Secrets in the config store** — the generated admin password lives in the
+ plugin config store (``plugins_sdk.config`` + the ``_save_config`` pattern),
+ used as HTTP Basic auth to the admin API.
+
+Version note: the Stalwart admin API is version-sensitive. All endpoint paths are
+centralized as module constants below and each reconcile call is wrapped so a
+future API change degrades to a reported drift rather than a crash.
+"""
+import logging
+import os
+import secrets
+import subprocess
+
+import requests
+
+from app.utils.system import run_privileged, is_command_available
+
+logger = logging.getLogger(__name__)
+
+SLUG = 'serverkit-mail'
+
+# Official Stalwart all-in-one mail server image.
+IMAGE = 'stalwartlabs/mail-server:latest'
+CONTAINER_NAME = 'serverkit-mail'
+DATA_DIR = '/var/serverkit/mail'
+# Bind-mount target inside the container (Stalwart's data/config root).
+CONTAINER_DATA_DIR = '/opt/stalwart-mail'
+
+# Admin HTTP API — published on 127.0.0.1 only, never reachable off-host.
+API_HOST = '127.0.0.1'
+API_PORT = 8080
+API_BASE = f'http://{API_HOST}:{API_PORT}/api'
+API_TIMEOUT = 10
+DOCKER_TIMEOUT = 180
+
+# Default admin account Stalwart provisions on first start.
+ADMIN_USER = 'admin'
+
+# Mail ports published on the host (SMTP / submission / IMAP / Sieve).
+MAIL_PORTS = ('25', '465', '587', '993', '143', '4190')
+
+DOCS_URL = 'https://stalw.art/docs/'
+
+# ── Admin-API endpoint paths (version-sensitive; centralized on purpose) ──
+# Each reconcile method wraps these so a 404 / shape change degrades gracefully.
+EP_PRINCIPAL = '/principal' # accounts / mailboxes / domains (CRUD)
+EP_DKIM = '/dkim' # DKIM signature management
+EP_QUEUE = '/queue/messages' # outbound queue introspection
+EP_RECONFIG = '/reload' # ask Stalwart to reload config
+
+
+class StalwartService:
+ """Stateless wrapper around Docker + the Stalwart admin HTTP API."""
+
+ # ---------- config (plugin config store) ----------
+
+ @classmethod
+ def _config(cls):
+ """Saved extension settings from the plugin config store."""
+ from app.plugins_sdk import config as plugin_config
+ return plugin_config(SLUG)
+
+ @classmethod
+ def _save_config(cls, updates):
+ """Merge *updates* into the plugin's stored config.
+
+ The SDK ``config()`` helper is read-only (the panel owns writes), so the
+ generated admin password is persisted through the InstalledPlugin row
+ directly. Returns False when the plugin row is absent (dev shells).
+ """
+ from app import db
+ from app.models.plugin import InstalledPlugin
+ row = InstalledPlugin.query.filter_by(slug=SLUG).first()
+ if not row:
+ logger.warning('%s: no InstalledPlugin row; config not persisted', SLUG)
+ return False
+ merged = dict(row.config or {})
+ merged.update(updates)
+ row.config = merged
+ db.session.commit()
+ return True
+
+ # ---------- docker choke-point ----------
+
+ @classmethod
+ def _docker(cls, args, timeout=DOCKER_TIMEOUT):
+ """Run ``docker <args>`` and return a normalized result dict."""
+ if os.name == 'nt':
+ return {'success': False,
+ 'error': 'The mail server extension is not supported on Windows.'}
+ if not is_command_available('docker'):
+ return {'success': False, 'not_installed': True,
+ 'error': 'Docker is not installed on this host.'}
+ cmd = ['docker'] + list(args)
+ try:
+ result = run_privileged(cmd, timeout=timeout)
+ except subprocess.TimeoutExpired:
+ return {'success': False, 'error': f'docker timed out after {timeout}s'}
+ except (OSError, subprocess.SubprocessError) as e:
+ return {'success': False, 'error': f'Failed to run docker: {e}'}
+ out = {
+ 'success': result.returncode == 0,
+ 'returncode': result.returncode,
+ 'stdout': result.stdout or '',
+ 'stderr': result.stderr or '',
+ }
+ if not out['success']:
+ out['error'] = (out['stderr'] or out['stdout'] or 'docker failed').strip()
+ return out
+
+ # ---------- Stalwart admin-API choke-point ----------
+
+ @classmethod
+ def _api(cls, method, path, payload=None):
+ """Call the container's Stalwart admin HTTP API (loopback only).
+
+ Returns ``{'success': True, 'data': <json-or-None>}`` or an error dict.
+ Auth is HTTP Basic with the generated admin password. The API is
+ published on 127.0.0.1 exclusively, so this never leaves the host.
+ Never raises.
+ """
+ if os.name == 'nt':
+ return {'success': False,
+ 'error': 'The mail server extension is not supported on Windows.'}
+ password = cls._config().get('admin_password')
+ if not password:
+ return {'success': False,
+ 'error': 'Stalwart admin password is not configured. Reinstall the mail server.'}
+ try:
+ resp = requests.request(
+ method, API_BASE + path,
+ auth=(ADMIN_USER, password),
+ json=payload,
+ timeout=API_TIMEOUT,
+ )
+ except requests.RequestException as e:
+ return {'success': False,
+ 'error': f'Stalwart admin API is unreachable: {e}'}
+ if resp.status_code >= 400:
+ try:
+ body = resp.json()
+ detail = body.get('error') or body.get('details') or resp.text
+ except ValueError:
+ detail = resp.text
+ return {'success': False, 'status_code': resp.status_code,
+ 'error': f'Stalwart admin API error ({resp.status_code}): {detail}'.strip()}
+ if not resp.content:
+ return {'success': True, 'data': None}
+ try:
+ return {'success': True, 'data': resp.json()}
+ except ValueError:
+ return {'success': True, 'data': resp.text}
+
+ # ---------- container lifecycle ----------
+
+ @classmethod
+ def is_installed(cls):
+ """True when the managed container exists (running or not)."""
+ if os.name == 'nt':
+ return False
+ res = cls._docker(['inspect', '--format', '{{.State.Running}}',
+ CONTAINER_NAME], timeout=20)
+ return bool(res.get('success'))
+
+ @classmethod
+ def get_status(cls):
+ """Installed / running / version / ports summary, best-effort."""
+ status = {
+ 'installed': False,
+ 'running': False,
+ 'version': None,
+ 'engine': 'stalwart',
+ 'image': IMAGE,
+ 'container': CONTAINER_NAME,
+ 'ports': list(MAIL_PORTS),
+ 'admin_api': f'{API_HOST}:{API_PORT}',
+ 'hostname': cls._config().get('hostname') if os.name != 'nt' else None,
+ 'docs_url': DOCS_URL,
+ }
+ if os.name == 'nt':
+ return status
+ res = cls._docker(['inspect', '--format', '{{.State.Running}}',
+ CONTAINER_NAME], timeout=20)
+ if not res.get('success'):
+ return status
+ status['installed'] = True
+ status['running'] = res.get('stdout', '').strip() == 'true'
+ if status['running']:
+ info = cls._api('GET', EP_RECONFIG)
+ # Version is best-effort; a shape change must not break status.
+ if info.get('success') and isinstance(info.get('data'), dict):
+ status['version'] = info['data'].get('version')
+ return status
+
+ @classmethod
+ def install(cls, hostname):
+ """Create and start the Stalwart container.
+
+ * Data + config bind-mounted at ``DATA_DIR`` (Stalwart bootstraps on
+ first start).
+ * Mail ports published on the host so the box can send/receive mail.
+ * Admin HTTP API published on **127.0.0.1 only** with a generated
+ password persisted to the plugin config store.
+ """
+ if os.name == 'nt':
+ return {'success': False,
+ 'error': 'The mail server extension is not supported on Windows.'}
+ hostname = (hostname or '').strip().lower().rstrip('.')
+ if not hostname:
+ return {'success': False, 'error': 'A mail server hostname is required'}
+ if cls.is_installed():
+ return {'success': False,
+ 'error': 'The mail server container already exists. Uninstall it first.'}
+
+ dir_res = run_privileged(['mkdir', '-p', DATA_DIR])
+ if getattr(dir_res, 'returncode', 1) != 0:
+ return {'success': False,
+ 'error': f'Could not create data directory {DATA_DIR}: '
+ f'{(getattr(dir_res, "stderr", "") or "").strip()}'}
+
+ admin_password = secrets.token_urlsafe(24)
+ run_args = [
+ 'run', '-d',
+ '--name', CONTAINER_NAME,
+ '--restart', 'unless-stopped',
+ '--hostname', hostname,
+ ]
+ for port in MAIL_PORTS:
+ run_args += ['-p', f'{port}:{port}']
+ # Admin API bound to loopback on the host — never reachable off-box.
+ run_args += ['-p', f'{API_HOST}:{API_PORT}:{API_PORT}']
+ run_args += ['-v', f'{DATA_DIR}:{CONTAINER_DATA_DIR}']
+ # Seed the fallback admin credentials Stalwart reads on first boot.
+ run_args += [
+ '-e', f'FALLBACK_ADMIN_USER={ADMIN_USER}',
+ '-e', f'FALLBACK_ADMIN_SECRET={admin_password}',
+ IMAGE,
+ ]
+ res = cls._docker(run_args)
+ if not res.get('success'):
+ return {'success': False,
+ 'error': res.get('error', 'Failed to start the Stalwart container')}
+
+ persisted = cls._save_config({
+ 'admin_password': admin_password,
+ 'hostname': hostname,
+ })
+ result = {'success': True,
+ 'message': 'Stalwart mail server installed',
+ 'container': CONTAINER_NAME,
+ 'hostname': hostname}
+ if not persisted:
+ result['warning'] = ('Container started but the admin password could not '
+ 'be persisted to the plugin config store.')
+ return result
+
+ @classmethod
+ def uninstall(cls, keep_data=True):
+ """Remove the container; optionally delete the mail data directory."""
+ if os.name == 'nt':
+ return {'success': False,
+ 'error': 'The mail server extension is not supported on Windows.'}
+ res = cls._docker(['rm', '-f', CONTAINER_NAME])
+ if not res.get('success'):
+ return {'success': False,
+ 'error': res.get('error', 'Failed to remove the Stalwart container')}
+ if not keep_data:
+ rm = run_privileged(['rm', '-rf', DATA_DIR])
+ if getattr(rm, 'returncode', 1) != 0:
+ return {'success': True,
+ 'warning': f'Container removed but mail data at {DATA_DIR} '
+ f'could not be deleted: {(getattr(rm, "stderr", "") or "").strip()}'}
+ cls._save_config({'admin_password': None})
+ return {'success': True,
+ 'message': 'Mail server removed'
+ + ('' if keep_data else ' (mail data deleted)')}
+
+ @classmethod
+ def control(cls, action):
+ """Start / stop / restart the managed container."""
+ if action not in ('start', 'stop', 'restart'):
+ return {'success': False, 'error': f'Invalid action: {action!r}'}
+ if not cls.is_installed():
+ return {'success': False, 'error': 'The mail server is not installed.'}
+ res = cls._docker([action, CONTAINER_NAME], timeout=60)
+ if not res.get('success'):
+ return {'success': False, 'error': res.get('error', f'docker {action} failed')}
+ return {'success': True, 'message': f'Mail server {action}ed', 'action': action}
+
+ # ---------- thin reconcile methods (best-effort, never raise) ----------
+ #
+ # Each of these pushes the panel's intent to Stalwart via the version-
+ # sensitive admin API and returns {success, ...}. On any error they report
+ # {success: False, error} so MailService can flag the row's sync_state.
+
+ @classmethod
+ def _principal_payload(cls, ptype, name, **extra):
+ payload = {'type': ptype, 'name': name}
+ payload.update({k: v for k, v in extra.items() if v is not None})
+ return payload
+
+ @classmethod
+ def upsert_account(cls, email, password=None, quota_mb=0, display_name=None):
+ """Create/update a mailbox account principal on Stalwart. Best-effort."""
+ if not cls.is_installed():
+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}
+ extra = {}
+ if password:
+ extra['secrets'] = [password]
+ if display_name:
+ extra['description'] = display_name
+ if quota_mb:
+ extra['quota'] = int(quota_mb) * 1024 * 1024 # bytes
+ payload = cls._principal_payload('individual', email, **extra)
+ res = cls._api('POST', EP_PRINCIPAL, payload)
+ if res.get('success'):
+ return {'success': True, 'email': email}
+ return {'success': False, 'error': res.get('error', 'Stalwart account upsert failed')}
+
+ @classmethod
+ def delete_account(cls, email):
+ """Delete a mailbox account principal on Stalwart. Best-effort."""
+ if not cls.is_installed():
+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}
+ res = cls._api('DELETE', f'{EP_PRINCIPAL}/{email}')
+ if res.get('success') or res.get('status_code') == 404:
+ return {'success': True, 'email': email}
+ return {'success': False, 'error': res.get('error', 'Stalwart account delete failed')}
+
+ @classmethod
+ def set_password(cls, email, password):
+ """Set a mailbox account's password on Stalwart. Best-effort."""
+ if not cls.is_installed():
+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}
+ if not password:
+ return {'success': False, 'error': 'A password is required'}
+ res = cls._api('PATCH', f'{EP_PRINCIPAL}/{email}', {'secrets': [password]})
+ if res.get('success'):
+ return {'success': True, 'email': email}
+ # Fall back to a full upsert if PATCH is unsupported in this version.
+ return cls.upsert_account(email, password=password)
+
+ @classmethod
+ def upsert_domain(cls, name):
+ """Register a domain principal on Stalwart. Best-effort."""
+ if not cls.is_installed():
+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}
+ payload = cls._principal_payload('domain', name)
+ res = cls._api('POST', EP_PRINCIPAL, payload)
+ if res.get('success'):
+ return {'success': True, 'domain': name}
+ return {'success': False, 'error': res.get('error', 'Stalwart domain upsert failed')}
+
+ @classmethod
+ def delete_domain(cls, name):
+ """Remove a domain principal from Stalwart. Best-effort."""
+ if not cls.is_installed():
+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}
+ res = cls._api('DELETE', f'{EP_PRINCIPAL}/{name}')
+ if res.get('success') or res.get('status_code') == 404:
+ return {'success': True, 'domain': name}
+ return {'success': False, 'error': res.get('error', 'Stalwart domain delete failed')}
+
+ @classmethod
+ def list_queue(cls):
+ """List outbound queue messages from the admin API. ``[]`` when down."""
+ if not cls.is_installed():
+ return {'success': True, 'messages': []}
+ res = cls._api('GET', EP_QUEUE)
+ if not res.get('success'):
+ return {'success': True, 'messages': [], 'note': res.get('error')}
+ data = res.get('data')
+ if isinstance(data, list):
+ messages = data
+ elif isinstance(data, dict):
+ messages = data.get('items', [])
+ else:
+ messages = []
+ return {'success': True, 'messages': messages}
+
+ @classmethod
+ def flush_queue(cls):
+ """Ask Stalwart to retry/flush the outbound queue. Best-effort."""
+ if not cls.is_installed():
+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}
+ res = cls._api('PATCH', EP_QUEUE, {'action': 'retry'})
+ if res.get('success'):
+ return {'success': True, 'message': 'Queue flush requested'}
+ return {'success': False, 'error': res.get('error', 'Queue flush failed')}
diff --git a/builtin-extensions/serverkit-mail/plugin.json b/builtin-extensions/serverkit-mail/plugin.json
new file mode 100644
index 00000000..e99b6271
--- /dev/null
+++ b/builtin-extensions/serverkit-mail/plugin.json
@@ -0,0 +1,53 @@
+{
+ "name": "serverkit-mail",
+ "display_name": "Mail Server",
+ "version": "1.0.0",
+ "description": "Self-hosted mail server powered by Stalwart in a managed Docker container — domains, mailboxes, forwarders, and autoresponders, with automatic DKIM/SPF/DMARC/MX record deployment, a deliverability preflight (PTR, port-25 egress, RBL) that gates outbound sending, brute-force jails, and maildir backups. Most panels never run a mail server, so it ships as an opt-in extension.",
+ "author": "ServerKit",
+ "license": "MIT",
+ "category": "integration",
+ "homepage": "https://github.com/jhd3197/ServerKit",
+ "permissions": ["shell", "filesystem", "network", "docker"],
+ "min_panel_version": "1.7.0",
+ "entry_point": "mail:mail_bp",
+ "url_prefix": "/api/v1/mail",
+ "models": "models:register",
+ "lifecycle": {
+ "on_install": "lifecycle:on_install",
+ "on_uninstall": "lifecycle:on_uninstall"
+ },
+ "jobs": [
+ { "kind": "mail.preflight.run", "handler": "jobs:run_preflight" },
+ { "kind": "mail.queue.flush", "handler": "jobs:flush_queue" }
+ ],
+ "schedules": [
+ { "name": "mail-preflight-daily", "kind": "mail.preflight.run", "cron": "0 6 * * *" }
+ ],
+ "icon": "<rect x=\"2\" y=\"4\" width=\"20\" height=\"16\" rx=\"2\"/><path d=\"m22 7-8.97 5.7a1.94 1.94 0 0 1-2.06 0L2 7\"/>",
+ "contributions": {
+ "nav": [
+ {
+ "id": "mail",
+ "label": "Mail Server",
+ "route": "/mail",
+ "category": "operations",
+ "icon": "<rect x=\"2\" y=\"4\" width=\"20\" height=\"16\" rx=\"2\"/><path d=\"m22 7-8.97 5.7a1.94 1.94 0 0 1-2.06 0L2 7\"/>"
+ }
+ ],
+ "routes": [
+ { "path": "mail", "component": "MailPage" },
+ { "path": "mail/:tab", "component": "MailPage" }
+ ],
+ "page_titles": {
+ "/mail": "Mail Server"
+ },
+ "command_palette": [
+ {
+ "label": "Mail Server",
+ "path": "/mail",
+ "category": "Pages",
+ "keywords": "mail smtp imap stalwart mailbox domain dkim spf dmarc mx deliverability forwarder autoresponder queue"
+ }
+ ]
+ }
+}