If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/sj26/mailcatcher shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 91% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sj26/mailcatcher repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sj26/mailcatcher.

What it runs against: a local clone of sj26/mailcatcher — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in sj26/mailcatcher | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 745 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sj26/mailcatcher. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sj26/mailcatcher.git
#   cd mailcatcher
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of sj26/mailcatcher and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sj26/mailcatcher(\\.git)?\\b" \\
  && ok "origin remote is sj26/mailcatcher" \\
  || miss "origin remote is not sj26/mailcatcher (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/mailcatcher.rb" \\
  && ok "lib/mailcatcher.rb" \\
  || miss "missing critical file: lib/mailcatcher.rb"
test -f "lib/mail_catcher/smtp.rb" \\
  && ok "lib/mail_catcher/smtp.rb" \\
  || miss "missing critical file: lib/mail_catcher/smtp.rb"
test -f "lib/mail_catcher/web/application.rb" \\
  && ok "lib/mail_catcher/web/application.rb" \\
  || miss "missing critical file: lib/mail_catcher/web/application.rb"
test -f "lib/mail_catcher/mail.rb" \\
  && ok "lib/mail_catcher/mail.rb" \\
  || miss "missing critical file: lib/mail_catcher/mail.rb"
test -f "lib/mail_catcher/bus.rb" \\
  && ok "lib/mail_catcher/bus.rb" \\
  || miss "missing critical file: lib/mail_catcher/bus.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 745 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~715d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/sj26/mailcatcher"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MailCatcher is a lightweight SMTP server (listening on port 1025 by default) that intercepts all outgoing email and displays it in a web UI (port 1080) instead of actually delivering it. Built in Ruby with a Sinatra-based web interface and WebSocket support, it's specifically designed for development environments where you need to test email functionality without spamming real inboxes or configuring external SMTP providers. Monolithic single-purpose app: lib/mail_catcher/smtp.rb handles SMTP server logic, lib/mail_catcher/web/application.rb wraps the web UI (Sinatra-based), lib/mail_catcher/bus.rb manages WebSocket broadcasts, lib/mail_catcher/mail.rb models the in-memory message store. Frontend is CoffeeScript (assets/javascripts/mailcatcher.js.coffee) + Sass styling (assets/stylesheets/mailcatcher.css.sass). CLI entry point is bin/mailcatcher.

Developers and QA engineers testing email-sending features in their applications (Rails, PHP, Node.js, etc.) who need a zero-config local SMTP sink. Also used by teams testing transactional email templates and verifying email content before production deployment.

Moderately mature and production-stable for development use. The repo shows active Ruby codebase (42K lines) with CI/CD pipeline (.github/workflows/ci.yml), test suite (spec/ directory with multiple test files), and a Dockerfile for containerized deployment. However, visible commit recency cannot be confirmed from metadata alone; check GitHub for last update date.

Low risk for intended use case (dev-only tool), but consider: single active maintainer (sj26) means slower issue triage, dependency chain includes older gems like Thin (Ruby web server, see Rakefile), and WebSocket support depends on EventMachine (lib/mail_catcher/bus.rb). No apparent breaking changes in recent versions, but Ruby version constraints should be verified in Gemfile.

Unable to determine current active work from provided metadata. Check GitHub Issues, Pull Requests, and commit history for recent activity. The .github/workflows/ci.yml indicates automated testing is enabled.

gem install mailcatcher
mailcatcher
open http://127.0.0.1:1080

Daily commands:

bundle install
mailcatcher
# or with options:
mailcatcher --ip 127.0.0.1 --smtp-port 1025 --http-port 1080 --foreground
# or via Docker:
docker build -t mailcatcher .
docker run -p 1025:1025 -p 1080:1080 mailcatcher

• lib/mailcatcher.rb — Main entry point and orchestrator that initializes SMTP server, web server, and bus; every contributor must understand the application lifecycle here.
• lib/mail_catcher/smtp.rb — SMTP server implementation that catches incoming mail; critical to understand how messages are intercepted and stored.
• lib/mail_catcher/web/application.rb — Sinatra web application that serves the UI and API endpoints; essential for understanding request routing and message retrieval.
• lib/mail_catcher/mail.rb — Mail message model and storage abstraction; defines how caught emails are structured and persisted.
• lib/mail_catcher/bus.rb — Event bus for WebSocket communication between backend and frontend; critical for real-time message updates.
• bin/mailcatcher — CLI entry point with configuration parsing; required to understand command-line options and daemon behavior.
• views/index.erb — Main web UI template where the entire frontend is rendered; needed to understand the user-facing interface.

• SMTP Server (Ruby Socket, MIME parsing (Mail gem)) — Accepts SMTP connections, parses MIME messages, stores in mail collection, triggers bus notifications
  • Failure mode: If SMTP crashes, incoming mail is rejected; already-stored mail remains viewable
• Mail Store (Ruby Hash, Mail gem parsing) — In-memory collection of parsed emails indexed by ID; provides query/retrieval/deletion
  • Failure mode: Process restart loses all stored mail; no data corruption risk since read-heavy
• Web API (Sinatra) (Sinatra, JSON serialization) — RESTful endpoints for listing, fetching, deleting, and searching caught emails
  • Failure mode: If web server crashes, UI becomes unreachable; SMTP continues storing mail
• Event Bus (EventMachine, WebSocket) — Broadcasts new mail notifications to connected WebSocket clients in real-time
  • Failure mode: If bus fails, clients fall back to polling every 30 seconds; no mail loss
• Frontend UI (CoffeeScript, jQuery, Embedded JS/CSS in ERB template) — Single-page app rendering mail list, message viewer, and attachment downloader
  • Failure mode: If JavaScript fails, user cannot interact; static HTML still renders

• Email Client (SMTP) → SMTP Server — Raw SMTP traffic (MAIL FROM, RCPT TO, DATA) containing message body and headers
• SMTP Server → Mail Store — Parsed Mail objects (from, to, subject, body, attachments, raw MIME)
• SMTP Server → Event Bus — Notification event with message ID and basic metadata
• Event Bus → Web Browser — WebSocket push with new message ID and metadata (fallback: browser polls GET /messages.json every 30s)
• Web Browser → Web API — HTTP GET requests for mail list, single message, and attachment downloads
• undefined → undefined — undefined

Add a new HTTP API endpoint to view or manipulate mail

1. Define a new route in the Sinatra application (lib/mail_catcher/web/application.rb)
2. If the route needs mail model logic, add a class method to (lib/mail_catcher/mail.rb)
3. If the endpoint should trigger real-time updates, publish to the bus (lib/mail_catcher/bus.rb)
4. Update client-side JavaScript to call the new endpoint (assets/javascripts/mailcatcher.js.coffee)

Add a new UI feature or view in the web interface

1. Add HTML markup and structure to the template (views/index.erb)
2. Add CoffeeScript event handlers and DOM manipulation logic (assets/javascripts/mailcatcher.js.coffee)
3. Add styles for the new UI elements (assets/stylesheets/mailcatcher.css.sass)
4. If needed, add a corresponding API endpoint (lib/mail_catcher/web/application.rb)

Add a new command-line option

1. Parse the option in the CLI binary (bin/mailcatcher)
2. Pass the option to the MailCatcher orchestrator (lib/mailcatcher.rb)
3. Apply the option when initializing SMTP or web servers (lib/mail_catcher/smtp.rb)

• Ruby + Sinatra — Simple, lightweight web framework ideal for a single-purpose tool; minimal dependencies
• SMTP server (custom implementation) — Allows MailCatcher to intercept raw SMTP traffic without external dependencies; full control over message handling
• WebSocket (EventMachine-based bus) — Enables real-time push of new messages to browser without polling; graceful fallback to 30s polling for older browsers
• CoffeeScript + jQuery — Lightweight frontend dependencies; single-page app avoids server-side rendering overhead
• Mail gem (Ruby) — Standard library for parsing MIME emails; handles complex multipart/attachments robustly

• In-memory mail storage (no database)

  • Why: Simplicity and zero configuration; MailCatcher is a development tool, not production email
  • Consequence: Mails are lost on restart; suitable only for development/testing workflows

• Single-process daemon

  • Why: Minimal resource footprint; runs on developer machines without overhead
  • Consequence: Not horizontally scalable; not suitable for high-volume or multi-user scenarios

• HTML rewriting to display inline images

  • Why: Allows viewing rich email exactly as it would appear in a mail client
  • Consequence: Adds parsing complexity and potential XSS attack surface (mitigated by Nokogiri sanitization)

• No authentication or multi-user isolation

  • Why: Development tool; localhost-only by default
  • Consequence: Any user on the machine can view all caught emails; unsuitable for shared environments

• Does not forward or relay emails to external servers
• Does not persist emails across process restarts
• Does not provide authentication or multi-tenancy
• Does not support TLS/SSL for SMTP (development-only tool)
• Does not scale horizontally or support clustering
• Does not implement full RFC 5321/5322 SMTP compliance (intentionally loose for development)

1. EventMachine reactor: SMTP and WebSocket logic run in EM reactor thread; long-running code in routes will block all clients. 2. In-memory only: all messages lost on restart; no persistence. 3. No auth: anyone with network access to ports 1025/1080 can read/delete messages; not suitable for untrusted networks. 4. CoffeeScript compilation: frontend changes require CoffeeScript→JavaScript transpilation (check Rakefile for build task). 5. Ruby version: Thin and EventMachine have known issues with newer Rubies (3.x); test against target Ruby version. 6. Port conflicts: default ports 1025 (SMTP) and 1080 (HTTP) must be available; may clash with existing services.

• SMTP (Simple Mail Transfer Protocol) — MailCatcher's core function is implementing a minimal SMTP server; understanding SMTP verbs (HELO, MAIL FROM, RCPT TO, DATA) is essential to reading lib/mail_catcher/smtp.rb
• EventMachine (async I/O reactor) — SMTP and WebSocket handling are built on EventMachine's non-blocking reactor pattern; essential to understanding concurrency model in lib/mail_catcher/bus.rb and lib/mail_catcher/smtp.rb
• WebSockets — Real-time message push to web UI depends on WebSocket connections (fallback to 30-second polling); see assets/javascripts/mailcatcher.js.coffee and lib/mail_catcher/bus.rb
• MIME and RFC 2822 Email Format — Email parsing and display (HTML vs. plain text extraction, attachment handling) relies on Mail gem's RFC 2822 compliance; needed to understand lib/mail_catcher/mail.rb rendering logic
• CoffeeScript — All frontend logic is written in CoffeeScript (assets/javascripts/mailcatcher.js.coffee), not vanilla JavaScript; requires understanding CoffeeScript syntax or transpilation workflow
• Sinatra (Ruby microframework) — Web API and HTML rendering use Sinatra routes and ERB templates; understanding lib/mail_catcher/web/application.rb requires basic Sinatra knowledge
• Server-Sent Events (SSE) — Fallback to WebSocket for real-time updates; MailCatcher uses EventMachine for both WebSocket and Server-Sent Events; check lib/mail_catcher/bus.rb for SSE implementation

• mailhog/MailHog — Direct alternative: Go-based SMTP catcher with similar UI and features, faster performance, and better Windows support
• sj26/mailcatcher-rails — Official Rails integration gem simplifying MailCatcher setup in Rails apps
• localhero/localmail — Similar lightweight SMTP interceptor for Rails with focus on simplicity and zero configuration
• ethereal-email/ethereal — Cloud-based alternative (free tier) if you need persistent inbox across restarts and team sharing
• nodemailer/smtp-server — Lower-level Node.js SMTP server library; reference for understanding SMTP protocol implementation details

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add WebSocket connection tests to spec/

The README mentions WebSocket support for instant mail updates ('Mail appears instantly if your browser supports [WebSockets]'), but there are no tests in spec/ validating WebSocket functionality. spec/delivery_spec.rb tests SMTP delivery, but lacks tests for the real-time update mechanism. This is critical for ensuring the core feature works reliably.

• [ ] Create spec/websocket_spec.rb to test WebSocket connections from lib/mail_catcher/web/application.rb
• [ ] Add tests verifying WebSocket messages are sent when new mail arrives via lib/mail_catcher/bus.rb
• [ ] Test WebSocket disconnection and reconnection scenarios
• [ ] Verify the bus pubsub mechanism correctly broadcasts to connected WebSocket clients

Add attachment handling tests to spec/

The README explicitly mentions 'Lists attachments and allows separate downloading of parts' as a key feature, and the examples/ folder includes multipart test cases (examples/multipartmail, examples/multipartmail-with-utf8, examples/attachment), yet spec/ has no dedicated attachment parsing or download tests. Current spec files don't validate attachment extraction.

• [ ] Create spec/attachment_spec.rb to test attachment parsing from lib/mail_catcher/mail.rb
• [ ] Add tests for examples/attachment and examples/multipartmail files to verify correct parsing
• [ ] Test attachment download routes in lib/mail_catcher/web/application.rb
• [ ] Verify UTF-8 attachment names are handled correctly (examples/multipartmail-with-utf8)

Add integration tests for HTML rewriting feature in spec/

The README states 'Rewrites HTML enabling display of embedded, inline images/etc and opens links in a new window' as a core feature. The examples/ folder has HTML test cases (examples/htmlmail, examples/xhtmlmail, examples/quoted_printable_htmlmail), but spec/ contains no tests validating this HTML transformation logic that should exist in lib/mail_catcher/mail.rb or lib/mail_catcher/web/application.rb.

• [ ] Create spec/html_rewriting_spec.rb to test HTML transformation logic
• [ ] Add tests parsing examples/htmlmail and examples/xhtmlmail to verify link rewriting (target=_blank)
• [ ] Test embedded image URL rewriting for inline display
• [ ] Test quoted-printable HTML parsing with examples/quoted_printable_htmlmail
• [ ] Verify HTML sanitization doesn't break the display functionality

• Add test coverage for lib/mail_catcher/mail.rb—the Mail model class has no corresponding spec file in spec/, despite being core to message storage and querying.
• Document the WebSocket message protocol in README or code comments—lib/mail_catcher/bus.rb broadcasts events but the event schema and client reconnection logic are undocumented.
• Create example integration for Docker Compose (docker-compose.yml in examples/) showing how to run MailCatcher alongside a sample Rails/Node app, filling the gap between Dockerfile and actual usage patterns.

• High · Exposed Web Interface Without Authentication — lib/mail_catcher/web/application.rb, Dockerfile (EXPOSE 1080). MailCatcher exposes a web interface on port 1080 without any authentication mechanism. This allows anyone with network access to view all captured emails, which may contain sensitive information including password reset tokens, sensitive business communications, or personal data. Fix: Implement authentication (e.g., API key, basic auth, OAuth) for the web interface. Alternatively, bind to localhost only by default and document security implications. Consider adding optional password protection via command-line flags.
• High · SMTP Server Exposed Without Authentication — lib/mail_catcher/smtp.rb, Dockerfile (EXPOSE 1025, CMD --ip 0.0.0.0). The SMTP server runs on port 1025 without authentication. In Docker, it's bound to 0.0.0.0, making it accessible from any network interface. This allows unauthorized users to send emails through the service, potentially for spam or abuse. Fix: By default, bind SMTP to localhost only (127.0.0.1). If network exposure is needed, document the security risks clearly. Consider requiring a token or API key for SMTP submissions. Add rate limiting to prevent abuse.
• High · Potential XSS via HTML Email Display — lib/mail_catcher/web/application.rb, assets/javascripts/mailcatcher.js.coffee, views/index.erb. MailCatcher displays HTML emails in the web interface with the note that it 'rewrites HTML enabling display of embedded, inline images'. If the HTML rewriting is not comprehensive, malicious scripts embedded in emails could execute in the context of the web application, affecting other users viewing emails. Fix: Ensure strict Content Security Policy (CSP) headers are implemented. Use a robust HTML sanitization library (e.g., Sanitize, Loofah) for email content. Sandbox email display in an iframe with restricted permissions. Validate that HTML rewriting removes all script tags and event handlers.
• Medium · No HTTPS Support by Default — lib/mail_catcher/web/application.rb. The application serves the web interface over HTTP only, with no built-in HTTPS support. Sensitive email content is transmitted in plaintext, vulnerable to man-in-the-middle attacks on the network. Fix: Add optional HTTPS support via command-line flags. Document that in production environments, MailCatcher should be deployed behind a reverse proxy (nginx, Apache) that handles TLS termination. Add a security warning in documentation about using MailCatcher only in development/testing environments.
• Medium · No SQLi Validation Visible — lib/mail_catcher/mail.rb. The codebase uses SQLite3 for storage. While the file structure doesn't explicitly show raw SQL queries in the provided list, database access in lib/mail_catcher/mail.rb should be reviewed for parameterized queries. Fix: Ensure all database queries use parameterized statements or ORM methods that prevent SQL injection. Review lib/mail_catcher/mail.rb for any string concatenation in SQL queries. Use Rails/Sequel ORM methods rather than raw SQL when possible.
• Medium · Missing Security Headers — lib/mail_catcher/web/application.rb. The web application likely lacks important security headers like X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Strict-Transport-Security, and Content-Security-Policy, increasing vulnerability to various attacks. Fix: Add security headers middleware to set: X-Frame-Options: DENY, X-Content-Type-Options: nosniff, X-XSS-Protection: 1; mode=block, Referrer-Policy: strict-origin-when-cross-origin, and a restrictive Content-Security-Policy header.
• Medium · Outdated Ruby Version Considerations — Dockerfile (FROM ruby:3.3-alpine). While Ruby 3.3 is recent, the Dockerfile uses Alpine Linux which may have fewer security updates and smaller attack surface, but the base image should be regularly rebuilt and scanned for CVEs. Fix: Implement regular image rebuilds and vulnerability scanning. Use a vulnerability scanner like Trivy or Clair. Keep Ruby and Alpine base images updated. Consider using a supported LTS Ruby version for production deployments.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.