How modalsource/postal works
Project type and purpose
• Postal is a self-hosted, open-source mail server (like SendGrid/Mailgun) built on Ruby on Rails.
• It provides a web-based admin UI, HTTP/SMTP APIs for sending and receiving mail, background workers, message storage, spam inspection, webhooks, MTA-STS/TLS-RPT support, and health/metrics endpoints.
Main components
a. Web Application (Rails MVC)
• app/controllers + app/views + app/assets → HTML UI & REST/legacy JSON API
• config/routes.rb → maps HTTP(S) endpoints
b. Primary Configuration Database
• ActiveRecord models (app/models) + config/database.yml → stores users, domains, credentials, routes, settings
c. SMTP Ingress Server
• lib/smtp_server → listens on port 25/587, accepts incoming mail, enqueues messages
d. Message Dequeuer & Processor
• app/lib/message_dequeuer pipeline → pulls queued messages, runs spam checks, applies routing, writes to message store
e. Message Database (Message DB)
• lib/postal/message_db → separate optimized store for message bodies, deliveries, stats, webhooks
f. SMTP Egress Client / Sender
• lib/smtp_client & app/senders → delivers outgoing mail to external SMTP servers
g. Background Workers & Scheduled Tasks
• app/lib/worker/jobs + app/scheduled_tasks → retention, DNS checks, webhook retries, notification jobs
h. Webhook Delivery Service
• app/services/webhook_delivery_service → posts events to customer-configured HTTP endpoints
i. Spam Inspection Modules
• lib/postal/message_inspectors → integrators for ClamAV, SpamAssassin, Rspamd, Truemail
j. DNS Resolver & MTA-STS/TLS-RPT Endpoints
• lib/dns_resolver + app/controllers/mta_sts_controller → publishes TXT/HTTPS policies
k. Health & Metrics
• app/util/health_server → Prometheus-style metrics endpoint
l. CLI & Scripts
• bin/*, script/* → tooling for setup, migration, signing, testing
Relationships & data flows
• Browser/API client → HTTPS → Rails Web App → Primary DB (config, UI state).
• Incoming SMTP → SMTP Server → QueuedMessage (Primary DB) → Message Dequeuer →
• Spam inspectors → Message DB → Webhook queue or routing decision.
• Outgoing Submission (HTTP API/Web UI) → OutgoingMessagePrototype → Worker picks up → SMTP Client → external SMTP servers → Message DB for logging.
• Scheduled tasks (cron or Clock process) → invoke ScheduledTask classes → maintenance jobs (cleanup, DNS checks, stats).
• WebhookDeliveryService → polls Message DB for events → HTTP POST to external webhooks.
• Health Server runs alongside Workers → exposes /health and /metrics.
Architectural patterns & design principles
• MVC for the management console and HTTP APIs
• Asynchronous, event-driven processing for mail pipelines
• Separation of concerns: config/state in Primary DB vs high-volume message data in Message DB
• Modular “inspector” and “sender” plugins for extensibility
• Scheduled tasks for periodic maintenance
• Clear boundary between sync (UI/API) and async (workers)
Showing interactions
• Cron or scheduler triggers on scheduled tasks.
Essential details to capture
• Dual-database architecture (config vs message store)
• Dual API: Legacy JSON API vs RESTful API vs Web UI
• SMTP ingress vs egress pipelines
• Spam inspection and webhook delivery as modular services
• Scheduled tasks separate from real-time processing
• Health/metrics endpoint for Prometheus
• Deployment artifacts: Docker containers, Procfile.dev, Puma config