Local Mailtrap-like SMTP Catcher

A lightweight local SMTP catcher with a simple web UI to view emails and download attachments. Great for development/testing without sending real emails.

• SMTP server: 127.0.0.1:2525
• Web UI: http://127.0.0.1:3000
• Stores messages under mailtrap/data/messages/
• Supports HTML/text body, attachments, CC/BCC (BCC inferred from SMTP envelope)

Requirements

• Node.js 18+ and npm
• Windows, macOS, or Linux

Setup

# Install dependencies
npm install

# Start (production mode)
npm run start

# Or start in dev mode with auto-reload
npm run dev

Usage

• Configure your application to send SMTP to 127.0.0.1 on port 2525.
• Open http://127.0.0.1:3000 to see incoming emails. You can view HTML or text, see CC/BCC, and download attachments.
• Use “Clear All” to delete all emails, or “Delete” on a single message.

Laravel configuration (.env)

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

Apply and test:

php artisan config:clear
php artisan tinker
>>> Mail::raw('Hello from local trap', fn($m) => $m->to('[email protected]')->subject('Trap test'));

API

• GET /api/messages → list messages (newest first)
• GET /api/messages/:id → message details (includes from, to, cc, bcc, subject, date, text, html, attachments)
• GET /api/messages/:id/attachment/:filename → download an attachment
• DELETE /api/messages/:id → delete one message
• DELETE /api/messages → delete all messages

Data layout

Messages are stored under {location}/data/messages/<id>/:

• metadata.json — message metadata (from, to, cc, bcc, subject, date, attachments, snippet)
• text.txt — plain text body (if present)
• html.html — HTML body (if present)
• attachments/ — files saved with their filenames

Notes

• Intended for local development only. SMTP auth is optional and STARTTLS is disabled.
• BCC: If not present in headers, the server infers BCC by subtracting To/Cc/Bcc header recipients from the SMTP envelope recipients.
• If port 2525 or 3000 are in use, set environment variables before starting:
  • HOST=127.0.0.1 SMTP_PORT=2526 WEB_PORT=3001 npm run start

Scripts

• npm run start — start web UI and SMTP server
• npm run dev — start in dev mode with nodemon

Troubleshooting

• If npm install fails with a mailparser version error, ensure mailparser is at ^3.7.4 in package.json.
• On Windows PowerShell 5, avoid &&; run commands separately.