smtp4dev

Last reviewed Sep 13, 2026 · 730 words

The single most common smtp4dev support question is "why does mail never arrive", and the answer is that it is doing its job. smtp4dev is a sink, not a relay: it accepts every message on port 25, stores it, and shows it in a web inbox. Nothing leaves. Point your staging Nextcloud or your half-built app at it and you get a safe place to see exactly what your software sends, complete with headers and HTML rendering, without ever spamming a real address.

Where it sits in a homelab

Two uses earn it a permanent container. The first is development: any app with an SMTP setting gets smtp4dev:25 while you are building, and you check the web inbox instead of a real mailbox. The second is quieter and more useful for self-hosters: every service in your stack that sends notifications (Vaultwarden invites, Nextcloud shares, Uptime Kuma alerts) can be pointed at smtp4dev first, so you can confirm the templates and recipients before switching the setting to your real provider. I have caught more than one service that would have emailed the wrong list on day one this way.

The Compose file, and the three ports that matter

services:
  smtp4dev:
    image: rnwood/smtp4dev:latest
    ports:
      - "5000:80"      # web inbox
      - "2525:25"      # SMTP in
      - "143:143"      # IMAP out
    volumes:
      - ./smtp4dev-data:/smtp4dev
    restart: unless-stopped

Inside the container the web UI listens on 80, SMTP on 25 and IMAP on 143; map them to whatever your host has free. Other containers on the same Compose network reach it as smtp4dev on port 25 directly, so the host port mapping for SMTP only matters for things running outside Docker. If an app insists on STARTTLS, smtp4dev can generate a self-signed certificate on first start, though switching the app's TLS setting off for a test host is usually simpler. The volume holds the SQLite message store; without it, every restart empties the inbox, which is sometimes exactly what you want on a build agent.

IMAP turns it into a real inbox

The IMAP listener is the feature I did not expect to care about. Add smtp4dev as an IMAP account in Thunderbird with any username and password (it does not check them by default) and the caught mail shows up like a normal mailbox, which is far better than a browser tab for reviewing 200 test messages from a bulk-send job. The REST API does the same for scripts: an integration test can send a password reset, then query the API for the message and pull the link out of the body.

Relay rules are for staging, not production

smtp4dev can forward specific messages to a real SMTP server, filtered by recipient. That is how you let a staging environment reach your own team's addresses while every customer-shaped address stays trapped. It is a convenience for a test box, not a mail architecture; if you are reading this looking for a way to actually deliver email from a homelab, that is a different and much harder problem, covered honestly in the self-hosted email post.

Mailpit is lighter, smtp4dev has more knobs

The obvious rival is Mailpit, a single Go binary that does the same catch-and-view job on a fraction of the memory. smtp4dev is a .NET application and wants about 128 MB, versus tens of megabytes for Mailpit. In exchange you get IMAP, the relay rules, and a web UI that has been polished for 10 years. If you only ever look at the last five messages, Mailpit wins on weight. If you use the IMAP path or the relay filters, smtp4dev is the one with the feature. MailHog, the older option, is effectively unmaintained and I would not start a new setup on it. The wider email category covers the real servers.

What I'd do

One smtp4dev container on the Docker network your other services share, persistent volume on, port 25 not published to the host. Every new service gets pointed at it before it gets pointed at a real provider. Thunderbird on IMAP for anything more than a glance. When the stack is stable and you are only doing occasional checks, swap to Mailpit to save the RAM; until then, the extra features are worth the 100 MB.