Skip to content

System - SMTP Settings

Purpose

Enables platform operators to configure, inspect, test, and maintain SMTP mail server credentials for outbound transactional emails (invitations, password resets, system alerts, and notification dispatches).

Users and permissions

Owner and Operator roles with smtp:manage can view masked configurations, update connection parameters, test server handshakes, and send test emails from the admin portal at /smtp-settings. That platform SMTP is what the system uses to email customers (invites, resets, notices). Support and customer-portal roles (including tenant owner) cannot open the screen. Password fields are never returned in cleartext. The API enforces the permission on every request.

Requirements

ID Priority Requirement
SMTP-01 Must The system reads SMTP connection parameters (host, port, secure, username, password, fromName, fromEmail) from environment variables or administrative overrides.
SMTP-02 Must The configuration endpoint (GET /api/admin/system/smtp) returns active parameters with the password masked (********) to prevent credential leakage. Requires a signed-in operator with smtp:manage.
SMTP-03 Must Operators with smtp:manage can update SMTP parameters via PUT /api/admin/system/smtp.
SMTP-04 Must The connection test endpoint (POST /api/admin/system/smtp/test-connection) verifies socket connection, EHLO greeting, TLS/STARTTLS handshake, and authentication without needing to send an actual message.
SMTP-05 Must The test email endpoint (POST /api/admin/system/smtp/send-test) dispatches a verification message to a specified recipient and returns delivery receipt metadata.
SMTP-06 Must The system provides reusable, standardized transactional email templates (libs/api/system/src/lib/email-templates) generating branded responsive HTML and plaintext alternatives for platform dispatches (SMTP test, operator invites, password resets, welcome messages, maintenance notices).
SMTP-07 Must The admin portal exposes an SMTP settings screen under Administration where Owner and Operator with smtp:manage can edit host, port, TLS options, credentials, from name/email, save, test the connection, and send a test email. Tenant owners have no access.

Business rules

  • Passwords are masked in responses; an empty password on update keeps the previously stored password.
  • Standard ports supported: 587 (STARTTLS), 465 (SSL/TLS direct), 25 (unencrypted relay).
  • Connection timeouts default to 10000ms to avoid blocking API worker processes.
  • Zero external package dependencies for the classic SMTP client: implemented using native Node.js socket and TLS libraries.
  • Optional Mailtrap Email API (local/test): when MAILTRAP_API_TOKEN is set, sendMail / send-test use the official mailtrap SDK instead of the socket SMTP client. Demo sender domains (e.g. hello@demomailtrap.co) only deliver to the Mailtrap account owner until a custom domain is verified. Production leaves MAILTRAP_* unset and uses SMTP_* with a verified sending domain configured at deploy time. See .env.example. Delivery logs: https://mailtrap.io/sending/email_logs
  • Email templates are decoupled in @bizos/api-system to allow reuse across API and background worker tasks.
  • Unauthenticated callers receive 401; Support and other roles without smtp:manage receive 403.

Acceptance criteria

  • SMTP-01: SMTP parameters load defaults from SMTP_* environment variables.
  • SMTP-02: GET /api/admin/system/smtp masks passwords and indicates whether a password is set.
  • SMTP-03: PUT /api/admin/system/smtp successfully updates parameters and updates modification timestamp.
  • SMTP-04: POST /api/admin/system/smtp/test-connection reports detailed handshake results and latency.
  • SMTP-05: POST /api/admin/system/smtp/send-test sends formatted verification emails.
  • SMTP-06: Email template system provides responsive layouts, XSS-safe escaping, and dual HTML/plain text outputs.
  • SMTP-07: Admin portal /smtp-settings loads the form, saves overrides, and offers test connection / send test actions.

Not yet implemented

  • Durable persistence of admin overrides across API restarts (current overrides live in process memory; restart falls back to SMTP_* env).
  • Audit log entries for SMTP configuration changes.

Out of scope

  • Per-tenant SMTP overrides (platform-wide settings only).
  • Incoming mail / IMAP.