Skip to main content

Swap your fake SMTP server for Buggregator on port 1025

Already send dev mail to a fake SMTP server on port 1025? Stop it and start Buggregator in its place. Buggregator's SMTP server listens on the same port 1025, so your apps keep their mail host and port, and nothing in their config changes. The emails show up in the Buggregator UI on port 8000, next to your errors, logs and dumps.

Steps

1. Stop the old server

Only one program can listen on port 1025. If it is still taken, the binary stops at start with failed to start TCP servers and address already in use, and docker run refuses with port is already allocated.

2. Start Buggregator on the same port

With Docker:

bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  ghcr.io/buggregator/server:latest

Or as one binary, without Docker:

bash
buggregator -http-addr 127.0.0.1:8000 -smtp-addr 127.0.0.1:1025

3. In Docker Compose, swap only the image

Keep the service's name, so your apps still reach it by the same host name. Change the image and the ports.

yaml
services:
  mail:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000 # UI
      - 127.0.0.1:1025:1025 # SMTP

Here the service is called mail; keep whatever name yours has. Your apps' MAIL_HOST=mail or MAILER_DSN=smtp://mail:1025 stays as it is.

4. Check the SMTP user name

Buggregator accepts any user name and password, or none. A user name picks the project the email lands in: with MAIL_USERNAME=shop, the email goes to the project shop. Without one, it goes to default.

5. Open the inbox

Send an email from your app and open http://127.0.0.1:8000. Each email shows its HTML preview with a desktop and mobile width switch, the plain text, addresses, attachments and raw source.

Why it works

Your app only knows a host and a port for SMTP. Buggregator answers on that same port 1025 and stores each email instead of delivering it, so the app cannot tell the difference. Its web UI and testing API run on port 8000, where tests can wait for an email with GET /api/smtp/messages/wait.

Checked on with Buggregator v2.13.0

Setup in 60 seconds

No registration. No account. Start it and point your app at it.

1

Start Buggregator

One file, installed with one command. The web UI opens on port 8000. Prefer containers? Use the Docker tab.

$ curl -fsSL https://raw.githubusercontent.com/buggregator/server/master/scripts/install.sh | sh
$ HTTP_ADDR=127.0.0.1:8000 \
  SMTP_ADDR=127.0.0.1:1025 \
  VAR_DUMPER_ADDR=127.0.0.1:9912 \
  MONOLOG_ADDR=127.0.0.1:9913 \
  PROXY_ADDR=127.0.0.1:8080 \
  ~/.local/bin/buggregator

The script picks the file for your CPU: Intel/AMD or ARM.

One file for Linux, macOS and Windows, about 40 MB. Nothing else to install.

This run line keeps it on this computer. Without the *_ADDR settings it listens on all network interfaces

Rather not run a script? Download the file yourself

Runs on Windows, macOS and Linux, on Intel/AMD and ARM.

Prefer not to do it yourself? Your AI agent can set Buggregator up for you