Test Email with Mailpit, Docker & ngrok

Real inbox sends are slow and noisy when you only need to verify MIME headers, From/To/Subject, and HTML rendering. A professional QA loop uses Mailpit in Docker as a catch-all SMTP + API inbox, exposes it with ngrok, then Email Viewer's Send test email action to deliver the current preview HTML into that inbox — without Tools Viewer servers and without polluting a real mailbox.

What you will set up

Install Docker Desktop (or Docker Engine).
Run the official axllent/mailpit image with CORS enabled so the browser can call Mailpit's HTTP API.
Expose Mailpit with ngrok (HTTPS) and paste that URL into Send test → Base URL.
Open Email Viewer → Send test, confirm From / To / Subject, and send.
Review the message in Mailpit's UI and in Email Viewer Check email → Headers.

1. Download Docker

Mailpit runs as a small container. Install Docker for your platform:

Get Docker — official installers for macOS, Windows, and Linux
Docker Desktop — the usual choice on Mac and Windows

After install, confirm the daemon is running (docker version should show a Server section):

Confirm Docker

docker version

docker version

2. Download / run Mailpit

Mailpit is an open-source email testing tool with a web UI, SMTP on port 1025, and a REST API on port 8025. Docs and releases:

Recommended Docker run (with CORS)

Email Viewer calls Mailpit from your browser. Enable CORS so the Send API accepts those requests:

bash

docker run -d \
  --name=mailpit \
  --restart unless-stopped \
  -p 8025:8025 \
  -p 1025:1025 \
  -e MP_API_CORS="*" \
  axllent/mailpit

docker run -d \
  --name=mailpit \
  --restart unless-stopped \
  -p 8025:8025 \
  -p 1025:1025 \
  -e MP_API_CORS="*" \
  axllent/mailpit

For a tighter allow-list, set MP_API_CORS="www.toolsviewer.com" instead of *.

Docker Compose example

docker-compose.yml

services:
  mailpit:
    image: axllent/mailpit
    container_name: mailpit
    restart: unless-stopped
    ports:
      - "8025:8025"
      - "1025:1025"
    environment:
      MP_API_CORS: "*"
      MP_MAX_MESSAGES: 5000
      MP_SMTP_AUTH_ACCEPT_ANY: 1
      MP_SMTP_AUTH_ALLOW_INSECURE: 1

services:
  mailpit:
    image: axllent/mailpit
    container_name: mailpit
    restart: unless-stopped
    ports:
      - "8025:8025"
      - "1025:1025"
    environment:
      MP_API_CORS: "*"
      MP_MAX_MESSAGES: 5000
      MP_SMTP_AUTH_ACCEPT_ANY: 1
      MP_SMTP_AUTH_ALLOW_INSECURE: 1

Then docker compose up -d. Confirm the container is running in Docker Desktop (ports 8025 and 1025).

Mailpit web UI inbox showing a captured test email — Mailpit web UI — messages captured for QA on your machine

3. Connect with ngrok

Tools Viewer needs an HTTPS Mailpit URL. Use ngrok to create a tunnel to Mailpit's API port (8025), then paste that HTTPS URL into Send test → Base URL.

Install ngrok from the download page and sign in (free tier is enough for QA).
With Mailpit already running, start a tunnel:
bash
```
ngrok http 8025
```
```
ngrok http 8025
```
Copy the HTTPS forwarding URL (for example https://abc123.ngrok-free.app).
In Email Viewer → Send test, set Base URL to that HTTPS address (no trailing path), then click Test connection.

Keep the ngrok process running while you send tests. Stop the tunnel when you are done so the temporary URL is no longer reachable. Do not leave an open Mailpit tunnel on a shared or untrusted network without authentication.

Email Viewer sends the ngrok-skip-browser-warning header automatically so free-tier interstitial pages do not break the API.

4. Send a test from Email Viewer

Open Email Viewer and load your HTML or MJML template.
Click Send test in the toolbar.
Paste your ngrok HTTPS URL as the Mailpit Base URL. Confirm From, To, and Subject. Use Test connection for a quick health check.
Click Send to Mailpit. Email Viewer posts to your Mailpit endpoint only — not to Tools Viewer servers.

Email Viewer Send test email dialog with From, To, Subject, and Mailpit URL — Send test email — professional From / To / Subject dialog for Mailpit

5. Inspect headers in Check email

After a successful send, Email Viewer opens Check email → Headers with the MIME headers returned by Mailpit (Date, From, To, Subject, Message-Id, and more). You can also open the message in Mailpit's UI from that tab.

Email Viewer Check email Headers tab showing MIME headers from Mailpit — Check email → Headers — MIME header table after a Mailpit test send

Why this approach

No ESP required for day-to-day header and HTML smoke tests.
Honest privacy — Tools Viewer does not receive the message; only your Mailpit endpoint does.
Same workflow as production-minded QA — verify subject encoding, From display, multipart HTML/text, then run the local QA / HTML Check tabs before a real ESP send.

Client simulations in Email Viewer are still not native inboxes. Use Mailpit for transport/header confidence, then litmus-style or ESP previews when a campaign is critical.

Mailpit FAQ

Does Tools Viewer host Mailpit for me?

No. You run Mailpit yourself (usually Docker). Email Viewer only calls the HTTPS Base URL you enter — typically from ngrok.

Why do I need CORS (MP_API_CORS)?

The browser blocks cross-origin API calls unless Mailpit allows them. Set MP_API_CORS to * while testing, or list www.toolsviewer.com.

What Base URL should I use in Send test?

Your ngrok HTTPS URL that forwards to Mailpit (for example https://abc123.ngrok-free.app). Paste it into Send test → Base URL, then Test connection.

Is ngrok required?

Yes for Send test from Tools Viewer. Mailpit runs on your machine; ngrok gives Email Viewer a reachable HTTPS endpoint.

Can I still use SMTP port 1025?

Yes. Apps and CLIs can SMTP to Mailpit on port 1025. Email Viewer uses the HTTP send API on port 8025 (via your ngrok URL) because browsers cannot speak SMTP.

Is this safe for production email?

Mailpit is for development and QA capture — not a production mail server. Stop ngrok when you finish, and do not expose Mailpit publicly without authentication.