mailcue

A realistic email testing server in a single Docker container.

MailCue packages Postfix, Dovecot, OpenDKIM, OpenDMARC, SpamAssassin, a FastAPI REST API, and a React web UI into one Docker container managed by s6-overlay. It runs a full mail stack with IMAP/POP3 access, DKIM signing, DMARC verification, spam filtering, TLS, and GPG encryption, so you can test email the way it behaves in production. Set `MAILCUE_MODE=production` and the same container runs as a real mail server.

**Features · Quick start · Documentation · Contributing**

Features

Quick start

Docker Compose

git clone https://github.com/Olib-AI/mailcue.git
cd mailcue
docker compose up -d

Open http://localhost:8088 and log in with username `admin` and password `mailcue`.

Docker run

docker run -d \
  --name mailcue \
  -p 8088:80 \
  -p 25:25 \
  -p 587:587 \
  -p 143:143 \
  -p 993:993 \
  -v mailcue-data:/var/mail/vhosts \
  -v mailcue-db:/var/lib/mailcue \
  -e MAILCUE_DOMAIN=mailcue.local \
  -e MAILCUE_ADMIN_PASSWORD=mailcue \
  ghcr.io/olib-ai/mailcue

Check it works

curl http://localhost:8088/api/v1/health

Database choices

MailCue uses SQLite by default, which keeps local and small deployments simple.

Production installations with concurrent API, provider sandbox, HTTP-bin, or

email warmup traffic should use PostgreSQL. MailCue supports a managed

PostgreSQL database or a PostgreSQL container on the same private Docker

network. Connection pooling, production indexes, foreign keys, automatic schema

migrations, and an offline SQLite-to-PostgreSQL migration command are included.

See Production deployment

for Docker Compose examples and the migration procedure. See

Configuration for every

database environment variable.

Documentation

> 📖 Read the full, interactive guides on the **Official MailCue Documentation Website**.

The API is also served as interactive Swagger UI at `/api/docs`, with machine-readable specs in openapi.json and postman_collection.json. See the deliverability testing guide for scoring, visual testing, placement, providers, schedules, and CI policies.

The SDKs and MCP server have their own docs: Python SDK, Node SDK, and MCP server.

Contributing

Contributions are welcome. See Development and contributing for local setup, linting, type checks, tests, and the pull request process.

License

MIT. See LICENSE.

Star History

Links

• Olib AI: www.olib.ai
• GitHub: github.com/Olib-AI/mailcue
• Container registry: ghcr.io/olib-ai/mailcue
• API docs: available at `/api/docs` when running
• Issues: github.com/Olib-AI/mailcue/issues
• Discussions: github.com/Olib-AI/mailcue/discussions

If you find MailCue useful, please consider giving it a . It helps others discover the project.

Built by