Configuration

MailCue is configured through environment variables and exposes a fixed set of network ports.

Environment variables

All settings are configured via environment variables prefixed with MAILCUE_. A .env file is also supported.

Database configuration

SQLite is the default and requires no database settings. Use it for local development, CI, and smaller installations. Use PostgreSQL for production installations that handle sustained concurrent requests or large metadata and sandbox datasets.

Configure PostgreSQL with individual environment variables:

MAILCUE_DATABASE_BACKEND=postgresql
MAILCUE_DATABASE_HOST=postgres
MAILCUE_DATABASE_PORT=5432
MAILCUE_DATABASE_USER=mailcue
MAILCUE_DATABASE_PASSWORD=replace-me
MAILCUE_DATABASE_NAME=mailcue
MAILCUE_DATABASE_SSLMODE=disable
MAILCUE_DATABASE_ALLOW_INSECURE_PRIVATE_NETWORK=true

MAILCUE_DATABASE_HOST also selects PostgreSQL when MAILCUE_DATABASE_BACKEND is not set. Setting the backend explicitly is recommended because it makes deployment intent clear.

Alternatively, provide one SQLAlchemy URL. The URL takes precedence over all individual connection settings:

MAILCUE_DATABASE_URL=postgresql+psycopg://mailcue:replace-me@postgres:5432/mailcue?sslmode=disable

Percent-encode special characters in usernames or passwords used in a URL. The individual variables do not require URL encoding. Use verify-full for managed or remote PostgreSQL with a trusted TLS certificate. Use disable only for a PostgreSQL service on a trusted private Docker network or another protected local network, and set MAILCUE_DATABASE_ALLOW_INSECURE_PRIVATE_NETWORK=true to acknowledge that exception. Never use this exception for a remote host.

Pool limits apply per MailCue application process. With multiple replicas, the maximum normal connection count is approximately replicas * pool size, plus temporary overflow connections. Size the PostgreSQL connection limit with this total in mind.

MailCue runs Alembic migrations automatically before the API starts. PostgreSQL migrations use an advisory lock, which prevents multiple MailCue replicas from changing the schema at the same time. Set MAILCUE_MIGRATION_DATABASE_URL to a DDL-capable role and use a separate, lower-privilege MAILCUE_DATABASE_URL for the running API. Existing SQLite installations require the offline copy procedure in Production deployment.

Exposed ports