Skip to main content

Python smtplib mail to a local inbox

To test a Python script that sends email, point smtplib.SMTP at 127.0.0.1, port 1025, where Buggregator listens. Every message then lands in a local inbox with the HTML preview, headers and attachments. Nothing reaches a real address.

Steps

1. Start Buggregator

Run the container. Port 8000 is the web UI, port 1025 is the SMTP server.

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

2. Send with smtplib

Build the message with email.message.EmailMessage and send it with send_message. It takes the sender and the recipients from the headers.

python
import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["Subject"] = "Your order"
msg["From"] = "shop@example.com"
msg["To"] = "alice@example.com"
msg.set_content("Thanks for your order.")
msg.add_alternative("<h1>Thanks for your order.</h1>", subtype="html")

with smtplib.SMTP("127.0.0.1", 1025) as smtp:
    smtp.send_message(msg)

3. Leave out starttls() and login()

Buggregator's SMTP server offers no TLS, so smtp.starttls() fails with SMTPNotSupportedError. Skip it locally, for example behind a setting. You need no login() either. If you call it anyway, since server v2.5.0 the user name picks the project, and any password works.

4. Open the inbox

Run the script and open http://127.0.0.1:8000. You see the HTML part, the plain text part, the addresses and the raw MIME source. In Docker Compose, use the Buggregator service name, for example buggregator, instead of 127.0.0.1.

Why it works

smtplib talks plain SMTP to whatever host and port you give it. Buggregator listens on port 1025, needs no authentication, and stores each email for the UI instead of delivering it. Only the host and port change; the code that builds your email stays the same.

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