Skip to content

Development

Everything you need to build features, fix bugs, or extend Mailyte. Whether you're adding a new worker, writing tests, or shipping a release — start here.

In this section

  • Getting Started (Dev)

    Set up your local dev environment, run the stack, and make your first change.

    Dev setup

  • Adding Features

    How to add a new feature end to end — from database migration to API endpoint to worker.

    Adding features

  • Contributing

    PR process, branch naming, commit conventions, and code review guidelines.

    Contributing

  • Coding Standards

    Python style, naming conventions, file organization, and import ordering.

    Coding standards

  • Testing

    Running and writing tests — unit, integration, and end-to-end.

    Testing

  • Custom Workers

    Build a new background worker module with the standard worker template.

    Custom workers

  • Plugin Development

    Extend Mailyte with plugins — hooks, event handlers, and custom integrations.

    Plugin development

  • Monitoring Integration

    Add Prometheus metrics, Grafana dashboards, and health check endpoints.

    Monitoring integration

  • Release Process

    Versioning, changelog management, building images, and deploying.

    Release process

Repo Structure

Text Only
mailyte-email-server/
  alembic/              # Database migration scripts
  config/               # Service configuration files
    mailer/
      postfix/          # Postfix overrides
      dovecot/          # Dovecot overrides
      rspamd/           # Rspamd overrides
  database/
    migrations/sql/     # SQL bootstrap files
  deployment/           # Kubernetes, production configs
  docs/                 # This handbook (MkDocs)
  logs/                 # Service logs (git-ignored)
  mailer/               # Mail service Dockerfiles and configs
    postfix/
    dovecot/
    rspamd/
    cert_manager/
  monitoring/           # Prometheus, Grafana configs
  scripts/              # Utility scripts
  security/             # Security-related configs
  shared/               # Shared Python modules across workers
  storage/              # Mail data, certs, DKIM keys (git-ignored)
  tests/                # Test suite
  worker/               # Worker service modules
    api/                # REST API (FastAPI)
    tracking/           # Email tracking
    webhooks/           # Webhook delivery
    analytics/          # Analytics aggregation
    rate_limiter/       # Rate limiting
    queue_manager/      # Mail queue management
    storage_usage/      # Storage monitoring
    rag/                # AI-powered search
    monitoring/         # Health checks and metrics
    dashboard/          # Admin dashboard
    templates/          # Email templates
    encryption/         # Email encryption
    archiver/           # Email archiving
    activesync/         # ActiveSync protocol
    cloud_sync/         # Cloud backup sync
    delivery_optimizer/ # Delivery optimization
  docker-compose.yml    # Main compose file
  main.py               # Application entry point
  manage.py             # Management CLI
  pyproject.toml        # Python project config
  requirements.txt      # Python dependencies

Key directories

Most of your time will be spent in worker/ (business logic), shared/ (common utilities), tests/ (test suite), and alembic/ (database migrations). The mailer/ directory is for mail service configuration and rarely needs changes.

Tech Stack

Component Technology Version
Language Python 3.11+
API framework FastAPI Latest
Database MySQL 8.0
Cache Redis 7
Vector DB Qdrant Latest
SMTP Postfix 3.x
IMAP/POP3 Dovecot 2.3+
Spam filter Rspamd Latest
Containers Docker + Docker Compose v2+
Migrations Alembic Latest
Testing pytest Latest
Linting Black, isort, flake8 Latest
Docs MkDocs Material Latest

Development workflow

Here's the typical flow for making a change:

flowchart LR
    A["Fork & branch"] --> B["Write code"]
    B --> C["Write tests"]
    C --> D["Run linters"]
    D --> E["Run tests"]
    E --> F["Open PR"]
    F --> G["Code review"]
    G --> H["Merge"]
    style A fill:#4051b5,color:#fff
    style H fill:#2e7d32,color:#fff
Bash
git checkout -b feature/my-new-feature

Branch naming: feature/, fix/, docs/, refactor/, test/

Make your changes in the relevant worker/ module or shared/ library. If you need a database change, create an Alembic migration.

Bash
# Run all tests
pytest tests/

# Run tests for a specific module
pytest tests/test_tracking.py

# Run with coverage
pytest --cov=worker tests/
Bash
# Format code
black .
isort .

# Check for issues
flake8 .

Push your branch and open a pull request. Fill in the PR template with what changed, why, and how to test it.

Common development tasks

I want to... How
Run the full stack locally docker compose up -- see Dev Setup
Add a new API endpoint Add a route in worker/api/, see Adding Features
Create a database migration alembic revision --autogenerate -m "description"
Build a new worker Copy the worker template, see Custom Workers
Add Prometheus metrics See Metrics Implementation
Write a plugin See Plugin Development
Run the docs locally mkdocs serve from the repo root
Ship a release Follow the Release Process
Guide What it covers
Getting Started Dev environment setup, running locally
Adding Features How to add a new feature end to end
Contributing PR process, branch naming, code review
Coding Standards Python style, naming, file organization
Testing Running and writing tests
Custom Workers Building a new worker module
Plugin Development Extending with plugins
Monitoring Integration Adding Prometheus metrics
Metrics Implementation Counters, gauges, histograms
Release Process Versioning, changelog, deployment
  • Getting Started -- install and run Mailyte (not dev-specific)
  • Architecture -- understand the system you're building on
  • API Reference -- the API you'll be extending
  • Features -- understand existing features before adding new ones
  • Security -- security practices to follow in your code