olibakram/mailcue repository overview

⁠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 container managed by s6-overlay. Unlike simple SMTP catchers, MailCue provides a production-realistic mail stack — IMAP/POP3, DKIM signing, DMARC verification, spam filtering, TLS, GPG encryption, and a modern web interface.

⁠Quick Start

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 \
  olibakram/mailcue

Open http://localhost:8088⁠ — login with admin / mailcue.

⁠Docker Compose

services:
  mailcue:
    image: olibakram/mailcue
    ports:
      - "8088:80"
      - "25:25"
      - "587:587"
      - "143:143"
      - "993:993"
    volumes:
      - mailcue-data:/var/mail/vhosts
      - mailcue-db:/var/lib/mailcue
    environment:
      - MAILCUE_DOMAIN=mailcue.local
      - MAILCUE_ADMIN_PASSWORD=mailcue

volumes:
  mailcue-data:
  mailcue-db:

⁠Features

• Catch-all SMTP — accepts mail for any address on any domain
• Full IMAP & POP3 — read emails with any standard client
• Modern Web UI — React app with rich text editor, reply/forward, real-time updates, keyboard shortcuts
• REST API — send, receive, inject, search, and delete emails programmatically
• Email Injection — insert emails directly via IMAP APPEND for deterministic testing
• Realistic Headers — multi-hop Received chains, Authentication-Results, ARC headers, DKIM-Signature, threading headers (In-Reply-To, References)
• DKIM Signing — automatic key generation and signing via OpenDKIM
• DMARC Verification — OpenDMARC milter verifies DMARC alignment on inbound mail
• SPF Checking — inbound SPF verification via postfix-policyd-spf-python
• Spam Filtering — SpamAssassin scoring with Bayesian filtering and RBL checks
• MTA-STS & TLS-RPT — serves MTA-STS policy (RFC 8461) and TLS-RPT DNS record guidance
• TLS Everywhere — auto-generated certificates for all protocols
• GPG / PGP-MIME — generate keys, sign, encrypt, verify, and decrypt
• Real-time Events — SSE stream for instant notifications
• API Keys — X-API-Key authentication for CI/CD pipelines
• Domain Management — DNS verification for MX, SPF, DKIM, DMARC, MTA-STS, and TLS-RPT
• Smarthost Relay — optional outbound relay via SendGrid, Mailgun, AWS SES when port 25 is blocked
• Developer Tools — built-in connection info, API reference, code snippets, and email header analysis
• Admin Panel — manage mailboxes, inject emails, handle GPG keys, configure domains
• Encrypted Database — optional AES-256 encryption via SQLCipher

⁠Exposed Ports

⁠Environment Variables

⁠Volumes

⁠Supported Architectures

⁠Documentation

Full documentation, API reference, and source code: github.com/Olib-AI/mailcue⁠

⁠License

MIT — Olib AI⁠