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, and more.

If you are building an integration or admin panel, this is the service you talk to.

What It Does¶

• Centralized REST API on port 8083
• 20 route modules covering every management function
• MySQL and Redis backends
• Authentication via API key or admin password
• CORS support for web dashboard integration
• Global exception handling (no stack traces leak to clients)

Architecture¶

flowchart TB
    Client["Admin Panel /\nExternal Integration"] -->|"HTTP :8083"| API["FastAPI App"]

    subgraph Routes["Route Modules"]
        Orgs["/api/v1/organizations"]
        Domains["/api/v1/domains"]
        Mailboxes["/api/v1/mailboxes"]
        Aliases["/api/v1/aliases"]
        Analytics["/api/v1/analytics"]
        Monitoring["/api/v1/monitoring"]
        Queue["/api/v1/queue"]
        Webhooks["/api/v1/webhooks"]
        RateLimit["/api/v1/rate-limiter"]
        Storage["/api/v1/storage"]
        Tracking["/api/v1/tracking"]
        RAG["/api/v1/rag"]
        Filters["/api/v1/filters"]
        SharedMB["/api/v1/shared-mailboxes"]
        MsgTrace["/api/v1/message-trace"]
        Transport["/api/v1/transport-rules"]
        WhiteLabel["/api/v1/whitelabel"]
        Reseller["/api/v1/reseller"]
        Compliance["/api/v1/compliance"]
        Migration["/api/v1/migration"]
    end

    API --> Routes
    Routes --> MySQL[(MySQL)]
    Routes --> Redis[(Redis)]
    Routes -->|"HTTP"| Workers["Other Workers"]

API Endpoints¶

The API is versioned at /api/v1/. Here is what each route module provides:

Common Endpoints¶

GET  /         -- API info and version
GET  /health   -- Health check with database status

Authentication¶

The API supports two auth modes:

API Key¶

Pass the key in the X-API-Key header:

curl -H "X-API-Key: your-api-key-here" \
     http://localhost:8083/api/v1/organizations

Admin Password¶

For quick admin access, use Basic Auth with the admin password:

curl -u admin:your-admin-password \
     http://localhost:8083/api/v1/organizations

Auth logic lives in worker/api/utils/auth.py.

Database¶

The API reads from and writes to MySQL. The database connection utility is in worker/api/utils/database.py.

Key tables the API touches:

CORS Configuration¶

CORS is configured via the CORS_ALLOWED_ORIGINS environment variable:

allow_origins = os.getenv("CORS_ALLOWED_ORIGINS", "http://localhost:3000").split(",")

For production, set this to your dashboard URL(s).

Error Handling¶

The API has a global exception handler that catches unhandled errors and returns a clean JSON response instead of a stack trace:

{"status": "error", "message": "Internal server error"}

Actual error details are logged server-side for debugging.

Configuration¶

Docker Configuration¶

api:
  build: ./worker/api
  container_name: api
  ports:
    - "8083:8080"
  depends_on:
    - mysql
    - redis

Connections to Other Services¶

The API gateway acts as an orchestrator. It talks to other workers when it needs data or actions beyond its own scope:

• Tracking worker -- for tracking stats and injection config
• Webhooks worker -- for webhook endpoint management
• Rate limiter worker -- for rate limit status queries
• Queue manager -- for mail queue operations
• Monitoring -- for service health data
• RAG worker -- for semantic search queries
• Storage usage -- for disk usage reports

Gotchas¶