MailCue

Product Introduction

1. Definition: MailCue is a production-grade, all-in-one email testing server and mock SMTP infrastructure delivered as a single, lightweight Docker container. It functions as a comprehensive mail stack that integrates industry-standard components—including Postfix for SMTP, Dovecot for IMAP/POP3, and SpamAssassin for content filtering—into a unified environment for local development and automated testing.

2. Core Value Proposition: MailCue exists to bridge the gap between development environments and production email delivery. While traditional "catch-all" SMTP tools only capture outgoing mail, MailCue allows developers to test the entire lifecycle of an email, including DKIM/DMARC authentication, spam scoring, GPG encryption, and multi-protocol access (IMAP/POP3). It eliminates the need for expensive third-party sandbox services and complex local mail server configurations, providing a "mail server in a box" that ensures transactional emails actually deliver and render correctly before deployment.

Main Features

1. Production-Grade Infrastructure Stack: Unlike simple mock servers, MailCue utilizes a robust backend featuring Postfix for SMTP (supporting ports 25 and 587) and Dovecot for IMAP, POP3, and LMTP. This stack is managed by the s6-overlay process supervisor, ensuring high availability within the container. By using actual production software instead of simulated scripts, MailCue provides 100% parity with how real-world mail servers handle protocols, STARTTLS, and implicit TLS.

2. Automated Authentication & Security (DKIM/DMARC/GPG): MailCue integrates OpenDKIM for automatic outbound message signing and OpenDMARC for inbound verification. This allows developers to test complex authentication flows and ensure their DNS records are properly configured. Furthermore, it offers full RFC 3156 support for PGP/MIME, allowing users to generate, import, and manage GPG keys to test signed and encrypted email workflows directly through a REST API or the Web UI.

3. Programmable API & Real-time Event Streaming: The system is built on a Python 3.12 FastAPI backend, exposing a comprehensive OpenAPI 3.1-compliant REST API. This API facilitates the programmatic injection, retrieval, and searching of emails, which is essential for CI/CD pipelines and automated end-to-end testing. Additionally, MailCue utilizes Server-Sent Events (SSE) to stream real-time events such as email.received or mailbox.created, allowing external testing scripts to react instantly to incoming mail without polling.

4. Integrated Spam Analysis & Content Filtering: Every inbound message is processed through SpamAssassin. The server provides detailed spam scores, Bayesian filtering results, and RBL (Real-time Blackhole List) check simulations. This feature is critical for developers who need to ensure their transactional templates do not trigger production spam filters due to formatting, header issues, or keyword triggers.

5. Modern React-Based Management UI: The frontend is built with React 19, TypeScript, and Tailwind CSS 4, providing a high-performance, desktop-class mail client experience. It includes a rich-text Tiptap editor for composing/injecting emails, a folder navigation sidebar, and a detailed email viewer that renders HTML, attachments, and raw headers for deep inspection.

Problems Solved

1. Pain Point: Inaccurate Local Email Testing: Developers often use simple SMTP sinks that do not support IMAP or authentication protocols, leading to "works on my machine" bugs where emails fail in production due to DKIM mismatches or spam filtering. MailCue solves this by providing a full, local mail stack that behaves exactly like a production relay.

2. Target Audience:

• Full-Stack Developers: Needing to verify user registration and password reset flows.
• DevOps & Site Reliability Engineers (SRE): Setting up hermetic testing environments for CI/CD pipelines.
• QA Automation Engineers: Writing scripts that need to "log in" via IMAP to verify email content.
• Security Researchers: Testing PGP/GPG encryption implementations and email header security.

3. Use Cases:

• CI/CD Pipeline Validation: Automatically verifying that a web application sends a correctly formatted "Welcome" email during a headless test run.
• Local UI/UX Design: Using the React UI to preview how responsive HTML email templates render across different viewports.
• Integration Testing: Using standard mail clients like Thunderbird or Mutt to connect via IMAP/POP3 to the local Docker container to verify multi-device synchronization.

Unique Advantages

1. Differentiation: Zero-Dependency Portability: Most advanced mail testing tools require external databases (like PostgreSQL or MySQL) or message brokers (like Redis). MailCue is entirely self-contained, utilizing SQLite with optional AES-256 encryption for data persistence. This "single container" philosophy makes it significantly easier to share across dev teams and deploy in ephemeral environments like GitHub Actions or GitLab CI.

2. Key Innovation: Converged Protocol Support: MailCue is unique in its ability to combine high-level API access with low-level protocol support (SMTP/IMAP/POP3). While competitors usually choose one or the other, MailCue allows a developer to inject an email via a REST POST request and then immediately fetch it using a standard IMAP library, providing a unified bridge between modern web development and legacy email infrastructure.

Frequently Asked Questions (FAQ)

1. How does MailCue differ from tools like MailHog or Mailtrap? While MailHog and Mailtrap act as simple SMTP "black holes" for capturing outgoing mail, MailCue is a complete mail server. It includes IMAP/POP3 access, SpamAssassin scoring, and DKIM/DMARC verification—features typically missing from basic mock SMTP tools. This allows for more complex testing, such as verifying how a real mail client interacts with the server.

2. Can MailCue be used for automated testing in CI/CD pipelines? Yes. MailCue is designed specifically for automation. It offers a REST API for injecting and retrieving emails and a Server-Sent Events (SSE) stream for real-time notifications. Because it is packaged as a single Docker container with no external dependencies, it can be spun up in seconds as a service container in GitHub Actions, Jenkins, or CircleCI.

3. Does MailCue support PGP and GPG encryption testing? Yes. MailCue provides full support for PGP/MIME (RFC 3156). Users can generate or import GPG keys via the API or Web UI to sign, encrypt, and decrypt emails. This is a rare feature in email testing tools and is essential for developers working on secure communication platforms or sensitive transactional notifications.