postal

Postal is a complete, self-hosted mail server designed for websites and web servers that need full control over their email infrastructure. It offers everything you’d find in commercial services like SendGrid, Mailgun, or Postmark — including SMTP delivery, inbound routing, API access, real-time analytics, and webhooks — without recurring per-email fees or third-party data exposure.

Built in Ruby on Rails and packaged as a Docker image, Postal supports multi-tenant deployments with isolated mail servers per organization. Each server gets its own credentials, domain configuration, DKIM/SPF validation, IP pool assignments, and suppression list management — making it suitable for agencies or SaaS platforms running email infrastructure on behalf of multiple clients.

Postal’s architecture separates inbound from outbound mail flows, includes a built-in spam scoring integration (SpamAssassin, Rspamd, ClamAV), and ships with a full-featured admin dashboard built in Haml. Webhooks deliver real-time delivery event notifications (delivered, bounced, held, clicked) to downstream applications, and an HTTP-based legacy API maintains compatibility with existing integrations.

Deployed through Docker Compose or a Kubernetes Helm chart, Postal is actively maintained with regular releases, OIDC single sign-on support, Prometheus metrics endpoints, and a growing community of contributors on Discord and GitHub Discussions.

What You Get

• Full SMTP Server - Send authenticated outbound email over SMTP using custom domains, TLS, and configurable relay chains with automatic MX record resolution.
• Inbound Mail Routing - Route incoming email to HTTP endpoints, SMTP servers, or address forwarding rules — enabling webhook-driven inbox processing for web applications.
• DKIM, SPF, and Return-Path Verification - Built-in DNS checking and per-domain DKIM signing (RFC 6376 compliant) to improve email deliverability and prevent spoofing.
• Spam and Virus Filtering - Integration with SpamAssassin, Rspamd, and ClamAV to score and block malicious or low-quality inbound messages before routing.
• IP Pool Management - Assign multiple IP addresses to named pools, set priority weights, and apply per-server or per-domain IP pool routing rules for deliverability warm-up.
• Real-time Webhooks and Events - Receive HTTP POST notifications for every delivery event (delivered, bounced, held, clicked, complained) directly to your application endpoints.
• Multi-Tenant Organizations - Isolate multiple mail servers under separate organizations with independent credentials, domain configurations, and send limits.
• Prometheus Metrics and Health Endpoints - Expose operational metrics and a health check HTTP server for integration with monitoring stacks like Grafana.

Common Use Cases

• Transactional email for SaaS products - A product team runs Postal on their own VPS to send password resets, welcome emails, and billing receipts without paying per-email fees to SendGrid or Postmark.
• Agency email infrastructure - A digital agency creates one Postal instance with multiple organizations — one per client — managing branded domains, DKIM signing, and send quotas independently for each.
• Inbound email processing for web apps - A help-desk application configures Postal inbound routes to receive support@ emails and POST the raw message to a webhook, where the app parses and creates tickets.
• Email deliverability warm-up - An e-commerce platform configures IP pools and priority weights in Postal to gradually warm up new sending IPs before migrating bulk promotional campaigns from a third-party ESP.
• GDPR-compliant data sovereignty - A European company hosts Postal on EU infrastructure to keep all email metadata — opens, clicks, bounce records — under their direct control and jurisdiction.
• Development and staging email testing - A DevOps team runs Postal in Development mode to test transactional email flows locally without risking delivery to real recipients.

Under The Hood

Architecture Postal is a layered Rails 7.1 monolith where responsibilities are divided across controllers, ActiveRecord models, a parallel set of SMTP/HTTP server processes, and background worker roles. The web application handles configuration, analytics, and API access while dedicated long-running processes (SMTP server, message dequeuer, worker roles, scheduled tasks) handle the operational email pipeline. A notable design choice is the per-organization message database: each mail server gets its own MySQL database with dedicated migrations, separating message storage from the control plane and enabling multi-tenant data isolation at the schema level. Scheduled task abstractions, Procfile-based process separation, and explicit worker role registration give the system predictable operational boundaries, though tight coupling between ActiveRecord models and DNS resolution logic (via the HasDNSChecks concern) blurs the separation between data access and domain behavior in places.

Tech Stack The core is Ruby 3.4 on Rails 7.1, with Puma serving both the web interface and the health check endpoint. MariaDB/MySQL underpins the primary control-plane data and every tenant’s isolated message database, accessed through ActiveRecord and direct Mysql2 connections. The SMTP server is implemented with NIO4R for event-driven I/O, enabling high-throughput concurrent connections without threading overhead. Spam and virus scanning integrates with SpamAssassin, Rspamd, and ClamAV as external processes. Frontend assets are compiled through the Rails asset pipeline using CoffeeScript, Sass, Haml templates, and Uglifier. OpenID Connect SSO is available as an optional gem group. Prometheus metrics are emitted from the SMTP server and worker processes for external monitoring.

Code Quality The test suite is substantial, with RSpec covering models, service objects, the SMTP sender, and webhook delivery in detail. The smtp_sender_spec.rb file alone contains extensive scenario coverage including relay fallback, connection error handling, TLS negotiation, and message size limits. Factory-based test data via FactoryBot keeps fixtures readable and composable. RuboCop with rubocop-rails enforces style consistency, and CI runs automated checks through GitHub Actions. Error handling in the delivery pipeline is intentionally explicit — delivery results are modeled as typed objects with retry flags and error details rather than raised exceptions, improving observability of failure paths. Domain logic is concentrated in service objects (WebhookDeliveryService) and sender classes rather than scattered across controllers, even if the models still carry some DNS resolution side effects.

What Makes It Unique Postal’s defining capability is its per-tenant message database design: each mail server provisioned through the UI gets its own isolated MySQL database with independent schema migrations, preventing data bleed between organizations while enabling fine-grained retention policies per server. The IP pool system with priority-weighted rules for selecting sending IPs — applicable at the organization, server, or domain level — is unusually sophisticated for open-source mail platforms and directly addresses the deliverability warm-up and reputation management needs of high-volume senders. The built-in DKIM signing implementation follows RFC 6376 precisely, handling header normalization and body canonicalization internally rather than delegating to external libraries, ensuring correctness and reducing runtime dependencies.

Self-Hosting

Postal is released under the MIT License, which is one of the most permissive open-source licenses available. You are free to use it commercially, modify the source code, distribute it, and run it on your own infrastructure with no royalty obligations. There are no copyleft requirements — modifications do not need to be released back to the public. The only obligation is to retain the copyright notice in distributions. This makes Postal suitable for organizations with legal or procurement restrictions around copyleft licenses like GPL.

Running Postal yourself means owning the full operational stack. You will need a Linux server or Kubernetes cluster, a MySQL or MariaDB instance with permissions to create databases (one per provisioned mail server), and either Docker Compose or Helm for deployment. Postal also requires a dedicated IP address (or pool of IPs) that have not been blocklisted, correct PTR/rDNS records, and DNS configuration for SPF, DKIM, and return-path on every sending domain. Maintaining IP reputation, handling bounce processing, managing TLS certificates, and applying security updates are all your responsibility. The ops burden is moderate to high — comparable to running any stateful, multi-process Ruby application — and scales with the number of organizations and message volume you support.

There is no official managed cloud version of Postal itself, which means there is no hosted tier with an SLA, managed upgrades, or professional support contract available from the project. If you want dedicated support, you are reliant on the community Discord, GitHub Discussions, and third-party managed hosting providers who may offer Postal as part of their email infrastructure services. What you trade away compared to a service like Mailgun or Sendgrid is the abstraction of IP reputation management, deliverability monitoring, and 24/7 incident response — all of which become your problem. What you gain is complete data ownership, no per-email cost at scale, and the ability to customize delivery behavior in ways that hosted APIs simply don’t expose.