MAILIX Documentation

Introduction

This documentation describes MAILIX — a developer-focused, self-hostable email infrastructure platform. It covers the architecture, installation, providers, projects, domains, API keys, templates, the delivery queue, security, the CLI, and releases.

What is MAILIX?

MAILIX is a developer-focused email infrastructure platform for sending, managing, templating, and monitoring transactional email.

It provides APIs and dashboard tools for projects, templates, domains, API keys, email delivery, logs, analytics, verification emails, OTP emails, password-reset emails, CLI tooling, and provider integrations.

• MAILIX is not primarily an email inbox or client
• MAILIX is email infrastructure — built to make transactional email easier to deploy and operate
• One line: Build and operate transactional email infrastructure with MAILIX.

Features

• Transactional email sending (verification, OTP, password reset, welcome, notifications)
• Templates & template management, with the MAILIX Studio editor
• Project isolation with per-project domains and API keys
• Email logs and dashboard analytics
• Background email queue with retry handling
• Provider integrations: Local, SMTP, Amazon SES, Resend
• Local development email simulation
• Authentication, role-based authorization, rate limiting, request validation
• Secure logging, production error handling, sensitive-field redaction
• CLI and cross-platform release tooling with a bundled Node.js runtime

Architecture

The primary backend is Node.js + Express. The API is versioned under /api/v1/* and covers routes for authentication, projects, emails, templates, Studio, domains, API keys, logs, analytics, and other operational resources.

Major areas

• Express API with centralized error handling and request-ID tracking
• Authentication layer and role-based authorization
• Project isolation and scoping
• Custom JSON document database (atomic writes, concurrent-write safety)
• Email queue and worker processing
• Provider abstraction over Local / SMTP / SES / Resend
• Template system and Studio API
• Dashboard frontend, CLI, runtime bundling, release pipeline

Installation

The release bundles its own Node.js runtime — end users do not need to install Node.js separately. The launcher prefers the bundled runtime automatically.

# 1. Get a release from GitHub (installer, ZIP, checksums)
https://github.com/Viyan852/mailix/releases

# 2. Install or extract following the release notes

# 3. Launch MAILIX
mlx-run

Build from source

git clone https://github.com/Viyan852/mailix.git
cd mailix
npm install
npm test

Quick Start

1. Launch MAILIX with mlx-run
2. Open the dashboard at http://localhost:7345
3. Sign in and create a project
4. Configure a domain for the project
5. Generate an API key (shown once, then stored hashed)
6. Pick a template — duplicate a system template into your project and customize it in Studio
7. Start with the Local provider to simulate delivery, then switch to SMTP, Amazon SES, or Resend for real email

Dashboard

The web dashboard exposes the major platform functionality: projects, emails, templates, Studio, domains, API keys, logs, analytics, and settings.

• Communicates with /api/v1/*
• A centralized apiFetch wrapper handles authenticated API communication
• Operates within the selected project context

Projects

Projects provide logical isolation. A project owns its email activity, templates, API keys, domains, logs, configuration, and statistics.

• Cross-project access is prevented
• Isolation is enforced server-side — frontend restrictions are not security boundaries
• A user cannot access another user's project data

API Keys

API keys authenticate programmatic requests to your MAILIX instance.

• Keys are not stored in plaintext — the database keeps a SHA-256 hash
• Generated securely, associated with the correct project, revocable, validated securely
• Never appear in normal logs; hashed fields are redacted
• Never hardcoded into release artifacts

Email Providers

MAILIX sends through a provider abstraction, so the rest of the system never needs provider-specific logic everywhere. Provider failures are normalized; retryable errors may be retried, permanent errors never enter infinite retry loops.

Local

Development, demo, and testing provider. No real external delivery — emails are captured in a simulated local inbox.

SMTP

Standard email server delivery. Configuration includes host, port, username, password, and TLS settings. SMTP credentials are sensitive and never logged.

Amazon SES

AWS SES integration for real delivery. AWS credentials must remain secret.

Resend

Resend integration for real delivery. Resend API credentials must remain secret.

Queue & Reliability

Outgoing emails flow through a background queue with worker processing.

• Queues jobs, processes them, and limits concurrency
• In-flight tracking prevents duplicate processing and duplicate sends
• Retries failed delivery — transient failures retried, permanent failures not retried endlessly, retry limits respected
• Graceful shutdown on SIGTERM / SIGINT — workers stop accepting and processing work appropriately
• Preserves useful error information without leaking secrets into retry logs

Templates & Studio

Templates are reusable email content — subject, HTML, text, and variables. System templates are bundled with MAILIX from the template catalog; duplicating one creates a project-scoped custom template you can edit freely. Templates are validated before use.

MAILIX Studio

Studio is the integrated template management and editing experience:

• Browse and categorize the system template catalog
• Preview templates
• Duplicate system templates into your project
• Visual editing and raw HTML editing
• Communicates with dedicated Studio/template APIs

Domains

Domains are associated with projects and used as part of email infrastructure configuration and verification. Domain management respects project ownership and authorization.

Email Logs

MAILIX logs requests, request IDs, execution timing, operational events, and errors. The logs UI can filter by all types, project, and event/type categories, with search controls.

• Sensitive fields — passwords, API keys, hashes, tokens, provider secrets — are redacted
• Logs help debugging without becoming a source of credential leakage
• The frontend never bypasses project isolation — backend security is authoritative

Analytics

Analytics displays backend-derived statistics through dashboard charts:

backend statistics → API → authenticated frontend request
→ dashboard data → Chart.js → rendered analytics

• Supports loading states, empty states, errors, and refresh/re-render
• Always correctly project-scoped
• The frontend never relies on fake production statistics

Security

• scrypt password hashing — passwords never returned by APIs, never logged
• API-key hashing (SHA-256) with sensitive-field redaction
• JWT/session-based authentication + role-based authorization, enforced server-side
• Request validation (express-validator) — required fields, types, formats, lengths, allowed values
• Rate limiting — a global limit, stricter limits on authentication operations
• Helmet security headers, request IDs, sanitized production errors

Secrets handling

Passwords, API keys and hashes, JWT/session secrets, SMTP passwords, provider API keys, AWS credentials, OTP values, and reset tokens must never be logged or exposed unnecessarily. When showing configuration examples, always use placeholders:

YOUR_API_KEY
YOUR_SMTP_PASSWORD
YOUR_RESEND_KEY

CLI

MAILIX includes a command-line interface managed through the mlx-run launcher concept. CLI responsibilities cover starting, stopping, and checking MAILIX status, viewing logs, configuration, help, and version information — the exact command set follows the current CLI implementation.

$ mlx-run
→ MAILIX dashboard running
→ http://localhost:7345

Releases

The release system can generate a Windows installer, a ZIP distribution, checksums, and other platform artifacts supported by the current pipeline. Targeted platforms are Windows, Linux, and macOS with x64/arm64 variants — only claim a platform as supported when the release pipeline actually builds and verifies it.

• The release bundles a Node.js runtime (zero-node distribution)
• CI/CD via GitHub Actions — tests, builds, security scanning, artifacts, checksums, GitHub releases; CI fails when critical tests fail
• Release artifacts must never contain .env secrets, API keys, passwords, provider credentials, test secrets, or machine-specific paths

Uninstall — data safety

The uninstaller stops the running service, waits for shutdown if necessary, removes application files, and preserves user data: data/, logs/, and config/ survive. It never performs an unsafe recursive deletion of the whole installation directory.

View Releases

MAILIX Assistant

Troubleshooting

Email not sending

1. Check provider configuration, credentials, and availability
2. Check MAILIX logs, queue status, and retry/error information
3. Check domain/provider requirements, the selected provider, and the request itself
4. Verify credentials locally — never expose them while troubleshooting

Authentication failing

1. Check credentials and session/token validity
2. Check account/project access and rate limiting
3. Check server logs safely — never request secrets in chat

Frequently asked

GitHub and Support

MAILIX is developed in public. Everything — source, releases, issues, and license — lives on GitHub.

• Repository — source code and project history
• Releases — installers, archives, checksums
• Issues — bugs and feature requests
• README — the canonical guide
• License — terms of use