Skip to content

Getting Started

Everything you need to go from zero to a running Mailyte email server — install it, configure it, and send your first email in under 15 minutes.

What is Mailyte?

Mailyte is a self-hosted email platform. It bundles Postfix (SMTP), Dovecot (IMAP/POP3), Rspamd (spam filtering), a FastAPI REST API, and a collection of worker services into a single Docker Compose stack. You bring a server, a domain, and DNS access. Mailyte handles the rest.

flowchart LR
    You["You 🧑‍💻"] -->|"docker compose up"| Stack["Mailyte Stack"]
    Stack --> SMTP["Send Email<br>Postfix"]
    Stack --> IMAP["Read Email<br>Dovecot"]
    Stack --> API["Control Plane<br>FastAPI REST API"]
    Stack --> Spam["Spam Filter<br>Rspamd"]
    style Stack fill:#4051b5,color:#fff

In this section

  • Installation

    Clone the repo, configure .env, run docker compose up, and verify every container is healthy.

    Installation guide

  • Configuration

    Understand the environment variables that control database connections, mail routing, security, feature flags, and worker behaviour.

    Configuration reference

  • First Steps

    Create an organization, add a domain, provision a mailbox, and send a test email through the API.

    First steps walkthrough

  • Troubleshooting

    Diagnostic commands, common pitfalls, log locations, and the fastest way to figure out what went wrong.

    Troubleshooting guide

Quick-start checklist

Use this as a high-level roadmap. Each step links to its own page with full details.

What you will end up with

After completing this section you will have:

  1. Every container running and healthy.
  2. An organization and domain registered through the API.
  3. A working mailbox that can send and receive mail.
  4. Familiarity with the logs and health checks you will use day-to-day.

Prerequisites at a glance

Requirement Minimum Recommended
OS Linux (Ubuntu 20.04+ or similar) Ubuntu 22.04 LTS
Docker 20.10+ Latest stable
Docker Compose v2.0+ v2.20+
RAM 4 GB 8 GB+
Disk 50 GB 100 GB+ SSD
Domain One domain with DNS control --
Ports open 25, 143, 465, 587, 993 All mail + API ports

Port 25 matters

Many cloud providers block outbound port 25 by default. Check with your hosting provider before you start — you may need to request that the block be lifted. Without port 25, your server can receive email but cannot deliver it to other servers.

The Installation page covers prerequisites in full.

Architecture at a glance

Mailyte is made up of three layers:

Postfix handles SMTP (ports 25, 587, 465). Dovecot handles IMAP/POP3 (ports 143, 993, 110, 995). Rspamd sits between them filtering spam.

A FastAPI application on port 5000 is the control plane. Worker services handle tracking, webhooks, rate limiting, analytics, RAG/AI search, queue management, storage, backup, and cloud sync.

MySQL stores configuration and metadata. Redis provides caching and pub/sub for the workers. Qdrant stores vector embeddings for AI-powered email search.

Don't worry about memorizing all of this

The Architecture section covers every service in detail. Right now, you just need to get the stack running.

Capabilities overview

Capability What you get
Send & receive email Full SMTP, IMAP, and POP3 support via Postfix and Dovecot
REST API Manage everything programmatically — orgs, domains, mailboxes, aliases
Spam filtering ML-based spam detection, Bayesian filtering, ClamAV antivirus
Multi-tenant Host multiple organizations with fully isolated data and quotas
Email tracking Open tracking, click tracking, bounce and complaint logging
Webhooks Real-time event delivery with retry and HMAC signing
AI search Semantic search over email content with Qdrant vector DB
Auto-healing Health monitor detects failed services and restarts them
Backups Automated database and filesystem backups with S3/Azure sync

Where to go next

Start here

Head to the Installation guide. It takes about ten minutes if you already have Docker installed.

Related sections:

  • Architecture -- understand how the system is put together
  • API Reference -- explore the REST API once your server is running
  • Features -- see everything Mailyte can do
  • Security -- harden your deployment before going live