Skip to content

Mailyte Mail Server Handbook

Run your own mail server: SMTP, IMAP, spam filtering, webmail and an admin console, driven by a REST API. This handbook covers both editions — pages describing something only the Enterprise Edition has are marked with a badge. See what each includes.

  • Getting Started

    Check your server can actually send mail — outbound port 25 and reverse DNS stop more installs than anything else — then install, configure and send.

    Jump in

  • Architecture

    How all the pieces fit together — services, data flows, database design, and multi-tenant isolation.

    See the big picture

  • API Reference

    Every REST endpoint documented with parameters, response schemas, and copy-paste examples in 4 languages.

    Explore the API

  • Configuration

    Fine-tune Postfix, Dovecot, Rspamd, SSL certificates, DNS records, and performance knobs.

    Configure it

  • Security

    Authentication, encryption at every layer, intrusion detection, and a pre-launch hardening checklist.

    Lock it down

  • Development

    Set up your dev environment, build custom workers, write tests, and ship releases.

    Start building

What is Mailyte Email Server?

It's a complete, production-ready email system that runs inside Docker containers. It handles the entire lifecycle of an email — from the moment someone clicks "Send" to delivery, spam filtering, tracking, and storage.

Here's what you get out of the box:

Capability What it does Powered by
Send & receive email SMTP inbound/outbound with database-driven virtual domains Postfix
Email client access IMAP, POP3, JMAP, ManageSieve — plus client auto-configuration (autoconfig/autodiscover/MTA-STS) Dovecot, jmap worker, autoconfig worker
Spam filtering & DKIM Machine-learning spam detection inbound, per-domain DKIM signing outbound Rspamd (ClamAV optional, not deployed by default)
REST API Manage everything programmatically — orgs, domains, mailboxes, SMTP credentials FastAPI gateway (34 route modules)
SMTP credentials Per-mailbox API keys for sending, revocable with immediate effect SMTP credentials module + Dovecot doveadm
Email tracking Open pixels, click-through link rewrites, engagement analytics Tracking worker + Postfix content filter
Email logs Per-message delivery records and delivery-event feed log_ingestor (tails Postfix's log)
AI-powered search Semantic email search using vector embeddings Qdrant + RAG worker
Real-time webhooks Signed, retried callbacks for mail, tracking, storage, and security events Shared webhook dispatcher + webhooks worker
Auto SSL certificates Let's Encrypt with auto-renewal, per-domain SNI, and Traefik integration cert_manager
Monitoring Prometheus metrics, Grafana dashboards, health checks, auto-restart Monitoring stack + monitoring worker
Multi-tenant Full data isolation per organization with quota management Built into every layer
Mail archiving Every message archived, age-encrypted, to S3-compatible storage Archiver worker
Rate limiting Per-sender, per-org, and per-key abuse prevention, enforced inside Postfix Rate limiter + Redis

The Architecture at a Glance

The server is organized in three layers, all running as Docker containers:

graph TB
    subgraph "<b>API Layer</b>"
        API["FastAPI Gateway<br/><small>:8080 &bull; api.&lt;domain&gt; via Traefik</small>"]
    end

    subgraph "<b>Mail Infrastructure</b>"
        POSTFIX["Postfix<br/><small>:25 :587 :465</small>"]
        DOVECOT["Dovecot<br/><small>:143 :993 :110 :995</small>"]
        RSPAMD["Rspamd<br/><small>milter :11332</small>"]
        INGEST["log_ingestor"]
    end

    subgraph "<b>Background Workers</b>"
        TRACKING["Tracking"]
        WEBHOOKS["Webhooks"]
        RATELIMIT["Rate Limiter"]
        ANALYTICS["Analytics"]
        RAG["AI Search"]
        QUEUE["Queue Mgr"]
        STORAGE["Storage Usage"]
        ARCHIVER["Archiver"]
    end

    subgraph "<b>Data Stores</b>"
        MYSQL[("MySQL")]
        REDIS[("Redis")]
        QDRANT[("Qdrant")]
        S3[("S3 storage")]
    end

    API -->|"SMTP :10587"| POSTFIX
    API --> DOVECOT
    POSTFIX -->|"milter: scan + DKIM sign"| RSPAMD
    POSTFIX -->|"LMTP"| DOVECOT
    POSTFIX --> TRACKING & RATELIMIT
    INGEST --> MYSQL

    TRACKING --> MYSQL
    WEBHOOKS --> MYSQL
    RATELIMIT --> REDIS
    ANALYTICS --> MYSQL
    RAG --> QDRANT
    QUEUE --> POSTFIX
    STORAGE --> DOVECOT
    ARCHIVER --> S3

The 30-second version

Postfix sends and receives email. Dovecot lets email clients read it. Rspamd blocks spam coming in and DKIM-signs mail going out. The FastAPI gateway manages everything and serves the webmail. Workers handle tracking, webhooks, analytics, archiving, and more; log_ingestor turns Postfix's log into queryable email logs. MySQL stores the data, Redis caches it, Qdrant powers AI search, and S3 holds the encrypted archive.

System Requirements

Resource Minimum Recommended High Volume
CPU 2 cores 4 cores 8+ cores
RAM 4 GB 8 GB 16+ GB
Disk 50 GB SSD 200 GB SSD 1 TB+ NVMe
Network 100 Mbps 1 Gbps 10+ Gbps
Docker 24.0+ Latest Latest
Docker Compose v2.20+ Latest Latest

Where to Start

Head to the Installation Guide for a step-by-step walkthrough. You'll have a working server in about 15 minutes.

Start with the Architecture Overview to see the big picture, then dive into How Data Flows to follow an email through the system.

The API Reference has every endpoint documented. Check the Quickstart for ready-to-use snippets in curl, Python, JavaScript, and PHP.

The Development Guide covers your dev environment setup, and Building Custom Workers shows you how to extend the system.

Jump to Troubleshooting for the most common issues, or check Health Checks to diagnose service problems.

Built with :material-heart: by the Mailyte engineering team at TechiesAfrica