API Gateway¶

The API gateway is the single entry point for managing the entire Mailyte mail server. It is a FastAPI application that exposes REST endpoints for organizations, domains, mailboxes, aliases, analytics, webhooks, tracking, RAG search, storage, compliance, migration, SMTP credentials, platform (console) operations, and the webmail's mailbox surface.

If you are building an integration, the console, or the webmail, this is the service you talk to.

What It Does¶

• Centralized REST API -- container port 8080, published as 8083 in dev; in production reached only through Traefik at api.${DOMAIN} (and the bare domain serves the same landing page)
• 32 route modules, loaded dynamically at startup (route_modules in app.py)
• MySQL and Redis backends; S3 for object storage
• Auth: tenant API keys, tenant browser sessions, and operator (console) sessions -- one permission model, three credential types
• Proxies to sibling workers (monitoring, queue, storage, rag, analytics, tracking, rate limiter, delivery optimizer) with org scoping enforced at the gateway
• Global exception handling (no stack traces leak to clients)

Route Modules¶

All mounted under /api/v1/ (from route_modules in worker/api/app.py):

Top-Level Endpoints¶

GET /               -- Landing page (HTML)
GET /features       -- Features page (HTML)
GET /health         -- Health check with database status
GET /metrics        -- Prometheus metrics
GET /api-reference  -- ReDoc API reference
GET /api-docs       -- Swagger UI (docs_url is customized; /docs is NOT served)

Authentication¶

Three credential types resolve to one permission model (worker/api/utils/auth.py):

• Tenant API keys -- X-API-Key header; route handlers guard with Depends(require_api_key('read'|'write'))
• Tenant browser sessions -- mailyte_session cookie (used by web UIs so no long-lived key sits in the browser); a thin layer over the same permission checks
• Operator sessions -- mailyte_operator_session cookie, separate table and shorter lifetime (ADR-002); operator MFA is verified through the TOTP security service (TOTP_SERVICE_URL)

The webmail authenticates mailbox holders via /api/v1/mailbox-auth -- credentials are verified against Dovecot over IMAP (not a stored copy), and mail is sent through Postfix's internal submission listener.

Mail Submission¶

Messages sent through the API/webmail are submitted to Postfix on the internal submission listener postfix:10587 (MAIL_SUBMIT_HOST/MAIL_SUBMIT_PORT), not port 25. That listener carries the tracking content filter; port 25 deliberately does not, because it also receives all inbound mail. Sending on 25 is why no webmail message was ever tracked before 2026-08.

Configuration¶

The compose file is the reference; the load-bearing variables:

Docker Configuration¶

api:
  build: ./worker/api
  container_name: api
  ports:
    - "8083:8080"
  volumes:
    - ./worker/api:/app
    - ./shared:/app/shared
    - ./database:/app/database
    - ./storage/api_data:/app/data          # writable data dir (uid 10001)
    - ./secrets/encryption_kek:/run/secrets/encryption_kek:ro

In production (docker-compose.prod.yml) the service runs with replicas: 2: container_name and the host port are reset (fixed names/ports cannot be shared between replicas), and Traefik load-balances api.${DOMAIN} across the replicas. The bare ${DOMAIN} router serves the same landing page.

Gotchas¶